2. 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.

2.1 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 anEnvironmentwhich 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, by default.

The bootstrap context uses a different convention for locating external configuration than the main application context, so instead ofapplication.yml(or.properties) you usebootstrap.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 thespring.application.name(inbootstrap.ymlorapplication.yml) if your application needs any application-specific configuration from the server.

You can disable the bootstrap process completely by settingspring.cloud.bootstrap.enabled=false(e.g. in System properties).

2.2 Application Context Hierarchies

If you build an application context fromSpringApplicationorSpringApplicationBuilder, 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 CompositePropertySourceappears with high priority if any PropertySourceLocatorsare 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 abootstrap.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 the application.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 frombootstrap.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 anyApplicationContextyou create, e.g. using its own interface, or with theSpringApplicationBuilderconvenience methods (parent(),child()andsibling()). 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 differentspring.application.nameand 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 theSpringApplicationBuilderallows you to share anEnvironmentamongst 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.

2.3 Changing the Location of Bootstrap Properties

Thebootstrap.yml(or.properties) location can be specified usingspring.cloud.bootstrap.name(default "bootstrap") orspring.cloud.bootstrap.location(default empty), e.g. in System properties. Those properties behave like thespring.config.*variants with the same name, in fact they are used to set up the bootstrapApplicationContextby setting those properties in itsEnvironment. If there is an active profile (fromspring.profiles.activeor through theEnvironmentAPI 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. frombootstrap-development.propertiesfor a "development" profile.

2.4 Overriding the Values of Remote Properties

The property sources that are added to you application by the bootstrap context are often "remote" (e.g. from a Config Server), and by default they cannot be overridden locally, except on the command line. If you want to allow your applications to override the remote properties with their own System properties or config files, the remote property source has to grant it permission by settingspring.cloud.config.allowOverride=true(it doesn’t work to set this locally). Once that flag is set there are some finer grained settings to control the location of the remote properties in relation to System properties and the application’s local configuration:spring.cloud.config.overrideNone=trueto override with any local property source, andspring.cloud.config.overrideSystemProperties=falseif only System properties and env vars should override the remote settings, but not the local config files.

2.5 Customizing the Bootstrap Configuration

The bootstrap context can be trained to do anything you like by adding entries to/META-INF/spring.factoriesunder the keyorg.springframework.cloud.bootstrap.BootstrapConfiguration. This is a comma-separated list of Spring@Configurationclasses 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@Beansof typeApplicationContextInitializer. Classes can be marked with an@Orderif you want to control the startup sequence (the default order is "last").

Be careful when adding customBootstrapConfigurationthat the classes you add are not@ComponentScannedby 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@ComponentScanor@SpringBootApplicationannotated configuration classes.

The bootstrap process ends by injecting initializers into the mainSpringApplicationinstance (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 inspring.factoriesand then all@Beansof typeApplicationContextInitializerare added to the mainSpringApplicationbefore it is started.

2.6 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 typePropertySourceLocatorto the bootstrap context (viaspring.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"));
    }

}

TheEnvironmentthat is passed in is the one for theApplicationContextabout 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 thisEnvironment(e.g. by keying it on thespring.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 aMETA-INF/spring.factoriescontaining:

org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator

then the "customProperty"PropertySourcewill show up in any application that includes that jar on its classpath.

2.7 Environment Changes

The application will listen for anEnvironmentChangeEventand react to the change in a couple of standard ways (additionalApplicationListenerscan be added as@Beansby the user in the normal way). When anEnvironmentChangeEventis observed it will have a list of key values that have changed, and the application will use those to:

Re-bind any@ConfigurationPropertiesbeans in the context
Set the logger levels for any properties inlogging.level.*

Note that the Config Client does not by default poll for changes in theEnvironment, and generally we would not recommend that approach for detecting changes (although you could set it up with a@Scheduledannotation). If you have a scaled-out client application then it is better to broadcast theEnvironmentChangeEventto all the instances instead of having them polling for changes (e.g. using theSpring Cloud Bus).

TheEnvironmentChangeEventcovers a large class of refresh use cases, as long as you can actually make a change to theEnvironmentand publish the event (those APIs are public and part of core Spring). You can verify the changes are bound to@ConfigurationPropertiesbeans by visiting the/configpropsendpoint (normal Spring Boot Actuator feature). For instance aDataSourcecan have itsmaxPoolSizechanged at runtime (the defaultDataSourcecreated by Spring Boot is an@ConfigurationPropertiesbean) and grow capacity dynamically. Re-binding@ConfigurationPropertiesdoes 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 wholeApplicationContext. To address those concerns we have@RefreshScope.

2.8 Refresh Scope

A Spring@Beanthat is marked as@RefreshScopewill 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 aDataSourcehas open connections when the database URL is changed via theEnvironment, 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.

TheRefreshScopeis a bean in the context and it has a public methodrefreshAll()to refresh all beans in the scope by clearing the target cache. There is also arefresh(String)method to refresh an individual bean by name. This functionality is exposed in the/refreshendpoint (over HTTP or JMX).

@RefreshScopeworks (technically) on an@Configurationclass, but it might lead to surprising behaviour: e.g. it does not mean that all the@Beansdefined 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).

2.9 Encryption and Decryption

Spring Cloud has anEnvironmentpre-processor for decrypting property values locally. It follows the same rules as the Config Server, and has the same external configuration viaencrypt.*. 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 theEnvironment. To use the encryption features in an application 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.

If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:

Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).

2.10 Endpoints

For a Spring Boot Actuator application there are some additional management endpoints:

POST to/envto update theEnvironmentand rebind@ConfigurationPropertiesand log levels
/refreshfor re-loading the boot strap context and refreshing the@RefreshScopebeans
/restartfor closing theApplicationContextand restarting it (disabled by default)
/pauseand/resumefor calling theLifecyclemethods (stop()andstart()on theApplicationContext)

2. Spring Cloud Context: Application Context Services