<simpara><linkxl:href="http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook">Cloud Native</link> is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building <linkxl:href="http://12factor.net/">12-factor Apps</link> in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required.</simpara>
<simpara>Many of those features are covered by <linkxl:href="http://projects.spring.io/spring-boot">Spring Boot</link>, which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the <literal>ApplicationContext</literal> of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).</simpara>
<simpara>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:</simpara>
<simpara>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</simpara>
<note>
<simpara>Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <linkxl:href="https://github.com/spring-cloud/spring-cloud-commons/tree/master/docs/src/main/asciidoc">github</link>.</simpara>
<simpara>then the "customProperty" <literal>PropertySource</literal> will show up in any
application that includes that jar on its classpath.</simpara>
</section>
<sectionxml:id="_environment_changes">
<title>Environment Changes</title>
<simpara>The application will listen for an <literal>EnvironmentChangeEvent</literal> and react
to the change in a couple of standard ways (additional
<literal>ApplicationListeners</literal> can be added as <literal>@Beans</literal> by the user in the
normal way). When an <literal>EnvironmentChangeEvent</literal> is observed it will
have a list of key values that have changed, and the application will
use those to:</simpara>
<itemizedlist>
<listitem>
<simpara>Re-bind any <literal>@ConfigurationProperties</literal> beans in the context</simpara>
</listitem>
<listitem>
<simpara>Set the logger levels for any properties in <literal>logging.level.*</literal></simpara>
</listitem>
</itemizedlist>
<simpara>Note that the Config Client does not by default poll for changes in
the <literal>Environment</literal>, and generally we would not recommend that approach
for detecting changes (although you could set it up with a
<literal>@Scheduled</literal> annotation). If you have a scaled-out client application
then it is better to broadcast the <literal>EnvironmentChangeEvent</literal> to all
the instances instead of having them polling for changes (e.g. using
the <linkxl:href="https://github.com/spring-cloud/spring-cloud-bus">Spring Cloud
Bus</link>).</simpara>
<simpara>The <literal>EnvironmentChangeEvent</literal> covers a large class of refresh use
cases, as long as you can actually make a change to the <literal>Environment</literal>
and publish the event (those APIs are public and part of core
Spring). You can verify the changes are bound to
<literal>@ConfigurationProperties</literal> beans by visiting the <literal>/configprops</literal>
endpoint (normal Spring Boot Actuator feature). For instance a
<literal>DataSource</literal> can have its <literal>maxPoolSize</literal> changed at runtime (the
default <literal>DataSource</literal> created by Spring Boot is an
<literal>@ConfigurationProperties</literal> bean) and grow capacity
dynamically. Re-binding <literal>@ConfigurationProperties</literal> 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
<literal>ApplicationContext</literal>. To address those concerns we have
<literal>@RefreshScope</literal>.</simpara>
</section>
<sectionxml:id="_refresh_scope">
<title>Refresh Scope</title>
<simpara>A Spring <literal>@Bean</literal> that is marked as <literal>@RefreshScope</literal> 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 <literal>DataSource</literal> has open
connections when the database URL is changed via the <literal>Environment</literal>, 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.</simpara>
<simpara>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.</simpara>
<simpara>The <literal>RefreshScope</literal> is a bean in the context and it has a public method
<literal>refreshAll()</literal> to refresh all beans in the scope by clearing the
target cache. There is also a <literal>refresh(String)</literal> method to refresh an
individual bean by name. This functionality is exposed in the
<literal>/refresh</literal> endpoint (over HTTP or JMX).</simpara>
<note>
<simpara><literal>@RefreshScope</literal> works (technically) on an <literal>@Configuration</literal>
class, but it might lead to surprising behaviour: e.g. it does <emphasisrole="strong">not</emphasis>
mean that all the <literal>@Beans</literal> defined in that class are themselves
<literal>@RefreshScope</literal>. Specifically, anything that depends on those beans
cannot rely on them being updated when a refresh is initiated, unless
it is itself in <literal>@RefreshScope</literal> (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 <literal>@Configuration</literal>).</simpara>
</note>
</section>
<sectionxml:id="_encryption_and_decryption">
<title>Encryption and Decryption</title>
<simpara>Spring Cloud has an <literal>Environment</literal> pre-processor for decrypting
property values locally. It follows the same rules as the Config
Server, and has the same external configuration via <literal>encrypt.*</literal>. Thus
you can use encrypted values in the form <literal>{cipher}*</literal> and as long as
there is a valid key then they will be decrypted before the main
application context gets the <literal>Environment</literal>. 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.</simpara>
<simpara>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:</simpara>
<simpara>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</simpara>
</section>
<sectionxml:id="_endpoints">
<title>Endpoints</title>
<simpara>For a Spring Boot Actuator application there are some additional management endpoints:</simpara>
<itemizedlist>
<listitem>
<simpara>POST to <literal>/env</literal> to update the <literal>Environment</literal> and rebind <literal>@ConfigurationProperties</literal> and log levels</simpara>
</listitem>
<listitem>
<simpara><literal>/refresh</literal> for re-loading the boot strap context and refreshing the <literal>@RefreshScope</literal> beans</simpara>
</listitem>
<listitem>
<simpara><literal>/restart</literal> for closing the <literal>ApplicationContext</literal> and restarting it (disabled by default)</simpara>
</listitem>
<listitem>
<simpara><literal>/pause</literal> and <literal>/resume</literal> for calling the <literal>Lifecycle</literal> methods (<literal>stop()</literal> and <literal>start()</literal> on the <literal>ApplicationContext</literal>)</simpara>
<title>Spring Cloud Commons: Common Abstractions</title>
<simpara>Patterns such as service discovery, load balancing and circuit breakers lend themselves to a common abstraction layer that can be consumed by all Spring Cloud clients, independent of the implementation (e.g. discovery via Eureka or Consul).</simpara>
<sectionxml:id="__enablediscoveryclient">
<title>@EnableDiscoveryClient</title>
<simpara>Commons provides the <literal>@EnableDiscoveryClient</literal> annotation. This looks for implementations of the <literal>DiscoveryClient</literal> interface via <literal>META-INF/spring.factories</literal>. Implementations of Discovery Client will add a configuration class to <literal>spring.factories</literal> under the <literal>org.springframework.cloud.client.discovery.EnableDiscoveryClient</literal> key. Examples of <literal>DiscoveryClient</literal> implementations: are <linkxl:href="http://cloud.spring.io/spring-cloud-netflix/">Spring Cloud Netflix Eureka</link>, <linkxl:href="http://cloud.spring.io/spring-cloud-consul/">Spring Cloud Consul Discovery</link> and <linkxl:href="http://cloud.spring.io/spring-cloud-zookeeper/">Spring Cloud Zookeeper Discovery</link>.</simpara>
<simpara>By default, implementations of <literal>DiscoveryClient</literal> will auto-register the local Spring Boot server with the remote discovery server. This can be disabled by setting <literal>autoRegister=false</literal> in <literal>@EnableDiscoveryClient</literal>.</simpara>
</section>
<sectionxml:id="_serviceregistry">
<title>ServiceRegistry</title>
<simpara>Commons now provides a <literal>ServiceRegistry</literal> interface which provides methods like <literal>register(Registration)</literal> and <literal>deregister(Registration)</literal> which allow you to provide custom registered services. <literal>Registration</literal> is a marker interface.</simpara>
<simpara>By default, the <literal>ServiceRegistry</literal> implementation will auto-register the running service. To disable that behavior, there are two methods. You can set <literal>@EnableDiscoveryClient(autoRegister=false)</literal> to permanently disable auto-registration. You can also set <literal>spring.cloud.service-registry.auto-registration.enabled=false</literal> to disable the behavior via configuration.</simpara>
<simpara>A <literal>/service-registry</literal> actuator endpoint is provided by Commons. This endpoint relys on a <literal>Registration</literal> bean in the Spring Application Context. Calling <literal>/service-registry/instance-status</literal> via a GET will return the status of the <literal>Registration</literal>. A POST to the same endpoint with a <literal>String</literal> body will change the status of the current <literal>Registration</literal> to the new value. Please see the documentation of the <literal>ServiceRegistry</literal> implementation you are using for the allowed values for updating the status and the values retured for the status.</simpara>
<title>Spring RestTemplate as a Load Balancer Client</title>
<simpara><literal>RestTemplate</literal> can be automatically configured to use ribbon. To create a load balanced <literal>RestTemplate</literal> create a <literal>RestTemplate</literal><literal>@Bean</literal> and use the <literal>@LoadBalanced</literal> qualifier.</simpara>
<warning>
<simpara>A <literal>RestTemplate</literal> bean is no longer created via auto configuration. It must be created by individual applications.</simpara>
for details of how the <literal>RestTemplate</literal> is set up.</simpara>
<sectionxml:id="_retrying_failed_requests">
<title>Retrying Failed Requests</title>
<simpara>A load balanced <literal>RestTemplate</literal> can be configured to retry failed requests.
By default this logic is disabled, you can enable it by adding <linkxl:href="https://github.com/spring-projects/spring-retry">Spring Retry</link> to your application’s classpath. The load balanced <literal>RestTemplate</literal> will
honor some of the Ribbon configuration values related to retrying failed requests. If
you would like to disable the retry logic with Spring Retry on the classpath
you can set <literal>spring.cloud.loadbalancer.retry.enabled=false</literal>.
The properties you can use are <literal>client.ribbon.MaxAutoRetries</literal>,
<literal>client.ribbon.MaxAutoRetriesNextServer</literal>, and <literal>client.ribbon.OkToRetryOnAllOperations</literal>.
See the <linkxl:href="https://github.com/Netflix/ribbon/wiki/Getting-Started#the-properties-file-sample-clientproperties">Ribbon documentation</link>
for a description of what there properties do.</simpara>
<note>
<simpara><literal>client</literal> in the above examples should be replaced with your Ribbon client’s
name.</simpara>
</note>
</section>
</section>
<sectionxml:id="_multiple_resttemplate_objects">
<title>Multiple RestTemplate objects</title>
<simpara>If you want a <literal>RestTemplate</literal> that is not load balanced, create a <literal>RestTemplate</literal>
bean and inject it as normal. To access the load balanced <literal>RestTemplate</literal> use
the <literal>@LoadBalanced</literal> qualifier when you create your <literal>@Bean</literal>.</simpara>
<important>
<simpara>Notice the <literal>@Primary</literal> annotation on the plain <literal>RestTemplate</literal> declaration in the example below, to disambiguate the unqualified <literal>@Autowired</literal> injection.</simpara>
<simpara>If you see errors like <literal>java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</literal> try injecting <literal>RestOperations</literal> instead or setting <literal>spring.aop.proxyTargetClass=true</literal>.</simpara>
</tip>
</section>
<sectionxml:id="ignore-network-interfaces">
<title>Ignore Network Interfaces</title>
<simpara>Sometimes it is useful to ignore certain named network interfaces so they can be excluded from Service Discovery registration (eg. running in a Docker container). A list of regular expressions can be set that will cause the desired network interfaces to be ignored. The following configuration will ignore the "docker0" interface and all interfaces that start with "veth".</simpara>
<formalpara>
<title>application.yml</title>
<para>
<screen>spring:
cloud:
inetutils:
ignoredInterfaces:
- docker0
- veth.*</screen>
</para>
</formalpara>
<simpara>You can also force to use only specified network addresses using list of regular expressions:</simpara>
<formalpara>
<title>application.yml</title>
<para>
<screen>spring:
cloud:
inetutils:
preferredNetworks:
- 192.168
- 10.0</screen>
</para>
</formalpara>
<simpara>You can also force to use only site local addresses. See <linkxl:href="https://docs.oracle.com/javase/8/docs/api/java/net/Inet4Address.html#isSiteLocalAddress--">Inet4Address.html.isSiteLocalAddress()</link> for more details what is site local address.</simpara>
