From 1e284961d503731504ee5dbc53fa26fcca44db1f Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Mon, 21 Dec 2015 14:46:58 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- spring-cloud.html | 210 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 145 insertions(+), 65 deletions(-) diff --git a/spring-cloud.html b/spring-cloud.html index 7860570..5c1198f 100644 --- a/spring-cloud.html +++ b/spring-cloud.html @@ -640,21 +640,30 @@ and extensibility mechanism to cover others.

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

-
-

https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc

+
+ + + + + +
+
Note
+		 +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 {githubmaster}/docs/src/main/asciidoc[github]. +
@@ -988,7 +997,23 @@ classpath (Maven co-ordinates the full strength JCE extensions in your JVM.

-

include::jce.adoc

+

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

@@ -1043,7 +1068,7 @@ when RestTemplate is on the classpath and a LoadBalancerClient bean

The URI needs to use a virtual host name (ie. service name, not a host name). The Ribbon client is used to create a full physical address. See -{github-code}/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java[RibbonAutoConfiguration] +RibbonAutoConfiguration for details of how the RestTemplate is set up.

@@ -1111,7 +1136,7 @@ IDE instead if you prefer (the main class is

The default strategy for locating property sources is to clone a git -repository (at "spring.cloud.config.server.git.uri") and use it to +repository (at spring.cloud.config.server.git.uri) and use it to initialize a mini SpringApplication. The mini-application’s Environment is used to enumerate property sources and publish them via a JSON endpoint.

@@ -1129,7 +1154,7 @@ via a JSON endpoint.

-

where the "application" is injected as the "spring.config.name" in the +

where the "application" is injected as the spring.config.name in the SpringApplication (i.e. what is normally "application" in a regular Spring Boot app), "profile" is an active profile (or comma-separated list of properties), and "label" is an optional git label (defaults to @@ -1146,12 +1171,12 @@ from a git repository (which must be provided):

-
spring:
+
spring:
   cloud:
     config:
-	  server:
-	    git:
-	      uri: https://github.com/spring-cloud-samples/config-repo

+      server:
+        git:
+          uri: https://github.com/spring-cloud-samples/config-repo
@@ -1217,8 +1242,7 @@ users. Example Maven configuration:

-
@Configuration
-@EnableAutoConfiguration
+
@SpringBootApplication
 @RestController
 public class Application {
 
@@ -1323,6 +1347,19 @@ spring.cloud.config.server.git.uri: file://${user.home}/config-repo

 
where ${user.home}/config-repo is a git repository containing
 YAML and properties files.
+
+ + + + + +
+
Note
+		 +in Windows you need an extra "/" in the file URL if it is +absolute with a drive prefix, e.g. file:///${user.home}/config-repo. +
+
@@ -1401,11 +1438,11 @@ one wins (like adding entries to a Map).

bootstrap.yml
-
spring:
+
spring:
   application:
     name: foo
   profiles:
-    active: dev,mysql

+    active: dev,mysql
@@ -1464,12 +1501,12 @@ using (for example):

-
spring:
+
spring:
   cloud:
     config:
       server:
         git:
-          uri: https://github.com/myorg/{application}

+          uri: https://github.com/myorg/{application}
@@ -1488,7 +1525,7 @@ quoted). Example:

-
spring:
+
spring:
   cloud:
     config:
       server:
@@ -1501,7 +1538,7 @@ quoted). Example:

               uri: https://github.com/special/config-repo
             local:
               pattern: local*
-              uri: file:/home/configsvc/config-repo

+              uri: file:/home/configsvc/config-repo
@@ -1537,7 +1574,7 @@ to run apps with multiple profiles. Example:

-
spring:
+
spring:
   cloud:
     config:
       server:
@@ -1553,7 +1590,7 @@ to run apps with multiple profiles. Example:

               pattern:
                 - */qa
                 - */production
-              uri: https://github.com/staging/config-repo

+              uri: https://github.com/staging/config-repo
@@ -1580,13 +1617,13 @@ specified as searchPaths. For example at the top level:

-
spring:
+
spring:
   cloud:
     config:
       server:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
-          searchPaths: foo,bar*

+          searchPaths: foo,bar*
@@ -1601,7 +1638,7 @@ at startup. For example at the top level:

-
spring:
+
spring:
   cloud:
     config:
       server:
@@ -1618,7 +1655,7 @@ at startup. For example at the top level:

                 uri: http://git/team-b/config-repo.git
             team-c:
                 pattern: team-c-*
-                uri: http://git/team-a/config-repo.git

+                uri: http://git/team-a/config-repo.git
@@ -1633,14 +1670,14 @@ e.g.

-
spring:
+
spring:
   cloud:
     config:
       server:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
           username: trolley
-          password: strongpassword

+          password: strongpassword
@@ -1661,10 +1698,26 @@ system properties (-Dhttps.proxyHost and -Dhttps.proxyPortThere is also a "native" profile in the Config Server that doesn’t use Git, but just loads the config files from the local classpath or file system (any static URL you want to point to with -"spring.cloud.config.server.native.searchLocations"). To use the native -profile just launch the Config Server with +"spring.cloud.config.server.native.searchLocations"). To use the +native profile just launch the Config Server with "spring.profiles.active=native".

+
+
+ + + + +
+
Note
+		 +Remember to use the file: prefix for file resources (the +default without a prefix is usually the classpath). Just as with any +Spring Boot configuration you can embed ${}-style environment +placeholders, but remember that absolute paths in Windows require an +extra "/", e.g. file:///${user.home}/config-repo +
+
@@ -1758,11 +1811,11 @@ hooks. To declare overrides just add a map of name-value pairs to
-
spring:
+
spring:
   cloud:
     config:
       server:
-        foo: bar

+        foo: bar
@@ -1781,10 +1834,10 @@ they are Spring Cloud Config clients.)

Normal, Spring environment placeholders with "${}" can be escaped (and resolved on the client) by using backslash ("\") to escape the -"$", e.g. \${app.foo:bar} resolves to "bar" unless the app provides -its own "app.foo". Note that in YAML you don’t need to escape the -backslash itself, but in properties files you do, when you configure -the overrides on the server. +"$" or the "{", e.g. \${app.foo:bar} resolves to "bar" unless the +app provides its own "app.foo". Note that in YAML you don’t need to +escape the backslash itself, but in properties files you do, when you +configure the overrides on the server.
@@ -1810,7 +1863,7 @@ along with custom profiles and custom labels, e.g.

-
spring:
+
spring:
   cloud:
     config:
       server:
@@ -1820,7 +1873,7 @@ along with custom profiles and custom labels, e.g.

               label: mylabel
             myservice-dev:
               name: myservice
-              profiles: development

+              profiles: development
@@ -1864,7 +1917,7 @@ in the JRE lib/security directory with the ones that you downloaded).
-

If the remote property sources contain encryted content +

If the remote property sources contain encrypted content (values starting with {cipher}) they will be decrypted before sending to clients over HTTP. The main advantage of this set up is that the property values don’t have to be in plain text when they are @@ -1880,10 +1933,10 @@ instance:

application.yml
-
spring:
+
spring:
   datasource:
     username: dbuser
-    password: '{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'

+    password: '{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'
@@ -1940,10 +1993,13 @@ are special characters ('+' is particularly tricky).

Take the encrypted value and add the {cipher} prefix before you put it in the YAML or properties file, and before you commit and push it -to a remote, potentially insecure store. The /encrypt and /decrypt -endpoints also both accept paths of the form /*/{name}/{profiles} -which can be used to control cryptography per application (name) -and profile when clients call into the main Environment resource.

+to a remote, potentially insecure store.

+
+
+

The /encrypt and /decrypt endpoints also both accept paths of the +form /*/{name}/{profiles} which can be used to control cryptography +per application (name) and profile when clients call into the main +Environment resource.

@@ -1955,7 +2011,7 @@ and profile when clients call into the main Environment resource.

to control the cryptography in this granular way you must also provide a @Bean of type TextEncryptorLocator that creates a different encryptor per name and profiles. The one that is provided -by default does not do this. +by default does not do this (so all encryptions use the same key).
@@ -2049,12 +2105,12 @@ your application.yml for the Config Server:

-
encrypt:
+
encrypt:
   keyStore:
     location: classpath:/server.jks
     password: letmein
     alias: mytestkey
-    secret: changeme

+    secret: changeme
@@ -2072,8 +2128,8 @@ i.e. with a cipher text like this:

-
foo:
-  bar: `{cipher}{key:testkey}...`
+
foo:
+  bar: `{cipher}{key:testkey}...`
@@ -2214,18 +2270,42 @@ to logback.xml).

The Config Server runs best as a standalone application, but if you need to you can embed it in another application. Just use the -@EnableConfigServer annotation and (optionally) set -spring.cloud.config.server.prefix to a path prefix, e.g. "/config", -to serve the resources under a prefix. The prefix should start but not -end with a "/". It is applied to the @RequestMappings in the Config -Server (i.e. underneath the Spring Boot prefixes server.servletPath -and server.contextPath). Another optional property that can be +@EnableConfigServer annotation. An optional property that can be useful in this case is spring.cloud.config.server.bootstrap which is a flag to indicate that the server should configure itself from its own remote repository. The flag is off by default because it can delay startup, but when embedded in another application it makes sense to initialize the same way as any other application.

+
+ + + + + +
+
Note
+		 +It should be obvious, but remember that if you use the bootstrap +flag the config server will need to have its name and repository URI +configured in bootstrap.yml. +
+
+
+

To change the location of the server endpoints you can (optionally) +set spring.cloud.config.server.prefix, e.g. "/config", to serve the +resources under a prefix. The prefix should start but not end with a +"/". It is applied to the @RequestMappings in the Config Server +(i.e. underneath the Spring Boot prefixes server.servletPath and +server.contextPath).

+
+
+

If you want to read the configuration for an application directly from +the backend repository (instead of from the config server) that’s +basically an embedded config server with no endpoints. You can switch +off the endpoints entirely if you don’t use the @EnableConfigServer +annotation (just set spring.cloud.config.server.bootstrap=true).

+
@@ -2359,7 +2439,7 @@ to set spring.cloud.config.failFast=true, and then you need to add spring-retry and spring-boot-starter-aop to your classpath. The default behaviour is to retry 6 times with an initial backoff interval of 1000ms and an exponential multiplier of 1.1 for subsequent backoffs. You can configure these -properties (and others) using spring.config.retry.* configuration properties.

+properties (and others) using spring.cloud.config.retry.* configuration properties.

@@ -2417,10 +2497,10 @@ properties, e.g.

bootstrap.yml
-
spring:
+
spring:
   cloud:
     config:
-     uri: https://user:secret@myconfig.mycompany.com

+     uri: https://user:secret@myconfig.mycompany.com
@@ -2429,12 +2509,12 @@ properties, e.g.

bootstrap.yml
-
spring:
+
spring:
   cloud:
     config:
      uri: https://myconfig.mycompany.com
      username: user
-     password: secret

+     password: secret
@@ -2451,10 +2531,10 @@ works locally and for a user-provided service on Cloud Foundry named
bootstrap.yml
-
spring:
+
spring:
   cloud:
     config:
-     uri: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:8888}

+     uri: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:8888}
@@ -4814,7 +4894,7 @@ AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...