undefined## Spring Cloud Context: Application Context Services {#spring-cloud-context-application-context-services}
Spring Boot has an opinionated view of how to build an application with Spring: for instance it has conventional locations for common configuration file, and endpoints for common management and monitoring tasks. Spring Cloud builds on top of that and adds a few features that probably all components in a system would use or occasionally need.
The Bootstrap Application Context
A Spring Cloud application operates by creating a "bootstrap" context, which is a parent context for the main application. Out of the box it is responsible for loading configuration properties from the external sources, and also decrypting properties in the local external configuration files. The two contexts share an Environment
which is the source of external properties for any Spring application. Bootstrap properties are added with high precedence, so they cannot be overridden by local configuration.
The bootstrap context uses a different convention for locating external configuration than the main application context, so instead of application.yml
(or .properties
) you use bootstrap.yml
, keeping the external configuration for bootstrap and main context nicely separate. Example:
bootstrap.yml
spring: application: name: foo cloud: config: uri: ${SPRING_CONFIG_URI:http://localhost:8888}
It is a good idea to set the spring.application.name
(in bootstrap.yml
or application.yml
) if your application needs any application-specific configuration from the server.
You can disable the bootstrap process completely by setting spring.cloud.bootstrap.enabled=false
(e.g. in System properties).
Application Context Hierarchies
If you build an application context from SpringApplication
or SpringApplicationBuilder
, then the Bootstrap context is added as a parent to that context. It is a feature of Spring that child contexts inherit property sources and profiles from their parent, so the "main" application context will contain additional property sources, compared to building the same context without Spring Cloud Config. The additional property sources are:
"bootstrap": an optional
CompositePropertySource
appears with high priority if anyPropertySourceLocators
are found in the Bootstrap context, and they have non-empty properties. An example would be properties from the Spring Cloud Config Server. See below for instructions on how to customize the contents of this property source."applicationConfig: [classpath:bootstrap.yml]" (and friends if Spring profiles are active). If you have a
bootstrap.yml
(or properties) then those properties are used to configure the Bootstrap context, and then they get added to the child context when its parent is set. They have lower precedence than theapplication.yml
(or properties) and any other property sources that are added to the child as a normal part of the process of creating a Spring Boot application. See below for instructions on how to customize the contents of these property sources.
Because of the ordering rules of property sources the "bootstrap" entries take precedence, but note that these do not contain any data from bootstrap.yml
, which has very low precedence, but can be used to set defaults.
You can extend the context hierarchy by simply setting the parent context of any ApplicationContext
you create, e.g. using its own interface, or with the SpringApplicationBuilder
convenience methods (parent()
, child()
and sibling()
). The bootstrap context will be the parent of the most senior ancestor that you create yourself. Every context in the hierarchy will have its own "bootstrap" property source (possibly empty) to avoid promoting values inadvertently from parents down to their descendants. Every context in the hierarchy can also (in principle) have a different spring.application.name
and hence a different remote property source if there is a Config Server. Normal Spring application context behaviour rules apply to property resolution: properties from a child context override those in the parent, by name and also by property source name (if the child has a property source with the same name as the parent, the one from the parent is not included in the child).
Note that the SpringApplicationBuilder
allows you to share an Environment
amongst the whole hierarchy, but that is not the default. Thus, sibling contexts in particular do not need to have the same profiles or property sources, even though they will share common things with their parent.
Changing the Location of Bootstrap Properties
The bootstrap.yml
(or .properties) location can be specified using
spring.cloud.bootstrap.name(default "bootstrap") or
spring.cloud.bootstrap.location(default empty), e.g. in System properties. Those properties behave like the
spring.config.*variants with the same name, in fact they are used to set up the bootstrap
ApplicationContextby setting those properties in its
Environment. If there is an active profile (from
spring.profiles.activeor through the
EnvironmentAPI in the context you are building) then properties in that profile will be loaded as well, just like in a regular Spring Boot app, e.g. from
bootstrap-development.properties` for a "development" profile.
Customizing the Bootstrap Configuration
The bootstrap context can be trained to do anything you like by adding entries to /META-INF/spring.factories
under the key org.springframework.cloud.bootstrap.BootstrapConfiguration
. This is a comma-separated list of Spring @Configuration
classes which will be used to create the context. Any beans that you want to be available to the main application context for autowiring can be created here, and also there is a special contract for @Beans
of type ApplicationContextInitializer
. Classes can be marked with an @Order
if you want to control the startup sequence (the default order is "last").
Warning | Be careful when adding custom BootstrapConfiguration that the classes you add are not @ComponentScanned by mistake into your "main" application context, where they might not be needed. Use a separate package name for boot configuration classes that is not already covered by your @ComponentScan or @SpringBootApplication annotated configuration classes. |
---|---|
The bootstrap process ends by injecting initializers into the main SpringApplication
instance (i.e. the normal Spring Boot startup sequence, whether it is running as a standalone app or deployed in an application server). First a bootstrap context is created from the classes found in spring.factories
and then all @Beans
of type ApplicationContextInitializer
are added to the main SpringApplication
before it is started.
Customizing the Bootstrap Property Sources
The default property source for external configuration added by the bootstrap process is the Config Server, but you can add additional sources by adding beans of type PropertySourceLocator
to the bootstrap context (via spring.factories
). You could use this to insert additional properties from a different server, or from a database, for instance.
As an example, consider the following trivial custom locator:
@Configuration
public class CustomPropertySourceLocator implements PropertySourceLocator {
@Override
public PropertySource<?> locate(Environment environment) {
return new MapPropertySource("customProperty",
Collections.<String, Object>singletonMap("property.from.sample.custom.source", "worked as intended"));
}
}
The Environment
that is passed in is the one for the ApplicationContext
about to be created, i.e. the one that we are supplying additional property sources for. It will already have its normal Spring Boot-provided property sources, so you can use those to locate a property source specific to this Environment
(e.g. by keying it on the spring.application.name
, as is done in the default Config Server property source locator).
If you create a jar with this class in it and then add a META-INF/spring.factories
containing:
org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator
then the "customProperty" PropertySource
will show up in any application that includes that jar on its classpath.
Environment Changes
The application will listen for an EnvironmentChangedEvent
and react to the change in a couple of standard ways (additional ApplicationListeners
can be added as @Beans
by the user in the normal way). When an EnvironmentChangedEvent
is observed it will have a list of key values that have changed, and the application will use those to:
Re-bind any
@ConfigurationProperties
beans in the contextSet the logger levels for any properties in
logging.level.*
Note that the Config Client does not by default poll for changes in the Environment
, and generally we would not recommend that approach for detecting changes (although you could set it up with a @Scheduled
annotation). If you have a scaled-out client application then it is better to broadcast the EnvironmentChangedEvent
to all the instances instead of having them polling for changes (e.g. using the Spring Cloud Bus).
The EnvironmentChangedEvent
covers a large class of refresh use cases, as long as you can actually make a change to the Environment
and publish the event (those APIs are public and part of core Spring). You can verify the changes are bound to @ConfigurationProperties
beans by visiting the /configprops
endpoint (normal Spring Boot Actuator feature). For instance a DataSource
can have its maxPoolSize
changed at runtime (the default DataSource
created by Spring Boot is an @ConfigurationProperties
bean) and grow capacity dynamically. Re-binding @ConfigurationProperties
does not cover another large class of use cases, where you need more control over the refresh, and where you need a change to be atomic over the whole ApplicationContext
. To address those concerns we have @RefreshScope
.
Refresh Scope
A Spring @Bean
that is marked as @RefreshScope
will get special treatment when there is a configuration change. This addresses the problem of stateful beans that only get their configuration injected when they are initialized. For instance if a DataSource
has open connections when the database URL is changed via the Environment
, we probably want the holders of those connections to be able to complete what they are doing. Then the next time someone borrows a connection from the pool he gets one with the new URL.
Refresh scope beans are lazy proxies that initialize when they are used (i.e. when a method is called), and the scope acts as a cache of initialized values. To force a bean to re-initialize on the next method call you just need to invalidate its cache entry.
The RefreshScope
is a bean in the context and it has a public method refreshAll()
to refresh all beans in the scope by clearing the target cache. There is also a refresh(String)
method to refresh an individual bean by name. This functionality is exposed in the /refresh
endpoint (over HTTP or JMX).
Note | @RefreshScope works (technically) on an @Configuration class, but it might lead to surprising behaviour: e.g. it does not mean that all the @Beans defined in that class are themselves @RefreshScope . Specifically, anything that depends on those beans cannot rely on them being updated when a refresh is initiated, unless it is itself in @RefreshScope (in which it will be rebuilt on a refresh and its dependencies re-injected, at which point they will be re-initialized from the refreshed @Configuration ). |
---|---|
Encryption and Decryption
The Config Client has an Environment
pre-processor for decrypting property values locally. It follows the same rules as the Config Server, and has the same external configuration via encrypt.*
. Thus you can use encrypted values in the form {cipher}*
and as long as there is a valid key then they will be decrypted before the main application context gets the Environment
. To use the encryption features in a client you need to include Spring Security RSA in your classpath (Maven co-ordinates "org.springframework.security:spring-security-rsa") and you also need the full strength JCE extensions in your JVM.
include::jce.adoc
Endpoints
For a Spring Boot Actuator application there are some additional management endpoints:
POST to
/env
to update theEnvironment
and rebind@ConfigurationProperties
and log levels/refresh
for re-loading the boot strap context and refreshing the@RefreshScope
beans/restart
for closing theApplicationContext
and restarting it (disabled by default)/pause
and/resume
for calling theLifecycle
methods (stop()
andstart()
on theApplicationContext
)