From 3f490c7126aefbf63e95c47833bd90fe03c26a0a Mon Sep 17 00:00:00 2001 From: buildmaster Date: Wed, 11 Apr 2018 01:42:06 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__spring_cloud_config_server.html | 33 +++++++++--------- multi/multi_spring-cloud-config.html | 2 +- single/spring-cloud-config.html | 35 ++++++++++---------- spring-cloud-config.xml | 5 ++- 4 files changed, 38 insertions(+), 37 deletions(-) diff --git a/multi/multi__spring_cloud_config_server.html b/multi/multi__spring_cloud_config_server.html index f2198e02..8c575522 100644 --- a/multi/multi__spring_cloud_config_server.html +++ b/multi/multi__spring_cloud_config_server.html @@ -39,7 +39,8 @@ Precedence rules for profiles are also the same as in a regular Spring Boot appl If the YAML files have documents inside them that point to Spring profiles, those are applied with higher precedence (in order of the profiles listed). If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults. Higher precedence translates to a PropertySource listed earlier in the Environment. -(These same rules apply in a standalone Spring Boot application.)

2.1.1 Git Backend

The default implementation of EnvironmentRepository uses a Git backend, which is very convenient for managing upgrades and physical +(These same rules apply in a standalone Spring Boot application.)

You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true. +==== Git Backend

The default implementation of EnvironmentRepository uses a Git backend, which is very convenient for managing upgrades and physical environments and for auditing changes. To change the location of the repository, you can set the spring.cloud.config.server.git.uri configuration property in the Config Server (for example in application.yml). If you set it with a file: prefix, it should work from a local repository so that you can get started quickly and easily without a server. However, in that case, the server operates directly on the local repository without cloning it (it does not matter if it is not bare because the Config Server never makes changes to the "remote" repository). @@ -49,7 +50,7 @@ If the git branch or tag name contains a slash (/), For example, if the label is foo/bar, replacing the slash would result in the following label: foo($$_$$)bar. The inclusion of the special string ($$_$$) can also be applied to the {application} parameter. If you use a command-line client such as curl, be careful with the brackets in the URL — you should -escape them from the shell with single quotes ('').

Placeholders in Git URI

Spring Cloud Config Server supports a git repository URL with placeholders for the {application} and {profile} (and {label} if you need it, but remember that the label is applied as a git label anyway). +escape them from the shell with single quotes ('').

2.1.1 Placeholders in Git URI

Spring Cloud Config Server supports a git repository URL with placeholders for the {application} and {profile} (and {label} if you need it, but remember that the label is applied as a git label anyway). So you can support a “one repository per application” policy by using a structure similar to the following:

spring:
   cloud:
     config:
@@ -62,7 +63,7 @@ organizations, as shown in the following example:
    config:
       server:
         git:
-          uri: https://github.com/{application}
where {application} is provided at request time in the following format: organization($$_$$)application.

Pattern Matching and Multiple Repositories

Spring Cloud Config also includes support for more complex requirements with pattern + uri: https://github.com/{application}

where {application} is provided at request time in the following format: organization($$_$$)application.

2.1.2 Pattern Matching and Multiple Repositories

Spring Cloud Config also includes support for more complex requirements with pattern matching on the application and profile name. The pattern format is a comma-separated list of {application}/{profile} names with wildcards (note that a pattern beginning with a wildcard may need to be quoted), as shown in the following example:

spring:
   cloud:
@@ -126,7 +127,7 @@ The server can be configured to clone the repositories at startup, as shown in t
                 uri: http://git/team-a/config-repo.git

In the preceding example, the server clones team-a’s config-repo on startup, before it accepts any requests. All other repositories are not cloned until configuration from the repository is requested.

[Note]Note

Setting a repository to be cloned when the Config Server starts up can help to identify a misconfigured configuration source (such as an invalid repository URI) quickly, while the Config Server is starting up. -With cloneOnStart not enabled for a configuration source, the Config Server may start successfully with a misconfigured or invalid configuration source and not detect an error until an application requests configuration from that configuration source.

Authentication

To use HTTP basic authentication on the remote repository, add the username and password properties separately (not in the URL), as shown in the following example:

spring:
+With cloneOnStart not enabled for a configuration source, the Config Server may start successfully with a misconfigured or invalid configuration source and not detect an error until an application requests configuration from that configuration source.

2.1.3 Authentication

To use HTTP basic authentication on the remote repository, add the username and password properties separately (not in the URL), as shown in the following example:

spring:
   cloud:
     config:
       server:
@@ -140,13 +141,13 @@ To avoid surprises, you should ensure that only one entry is present in the known_hosts file.
 The repository is accessed by using JGit, so any documentation you find on that should be applicable.
 HTTPS proxy settings can be set in ~/.git/config or (in the same way as for any other JVM process) with
-system properties (-Dhttps.proxyHost and -Dhttps.proxyPort).
[Tip]Tip
If you do not know where your ~/.git directory is, use git config --global to manipulate the settings (for example, git config --global http.sslVerify false).

Authentication with AWS CodeCommit

Spring Cloud Config Server also supports AWS CodeCommit authentication. +system properties (-Dhttps.proxyHost and -Dhttps.proxyPort).

[Tip]Tip

If you do not know where your ~/.git directory is, use git config --global to manipulate the settings (for example, git config --global http.sslVerify false).

2.1.4 Authentication with AWS CodeCommit

Spring Cloud Config Server also supports AWS CodeCommit authentication. AWS CodeCommit uses an authentication helper when using Git from the command line. This helper is not used with the JGit library, so a JGit CredentialProvider for AWS CodeCommit is created if the Git URI matches the AWS CodeCommit pattern. AWS CodeCommit URIs follow this pattern://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}.

If you provide a username and password with an AWS CodeCommit URI, they must be the AWS accessKeyId and secretAccessKey that provide access to the repository. If you do not specify a username and password, the accessKeyId and secretAccessKey are retrieved by using the AWS Default Credential Provider Chain.

If your Git URI matches the CodeCommit URI pattern (shown earlier), you must provide valid AWS credentials in the username and password or in one of the locations supported by the default credential provider chain. AWS EC2 instances may use IAM Roles for EC2 Instances.

[Note]Note

The aws-java-sdk-core jar is an optional dependency. -If the aws-java-sdk-core jar is not on your classpath, the AWS Code Commit credential provider is not created, regardless of the git server URI.

Git SSH configuration using properties

By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as ~/.ssh/known_hosts and /etc/ssh/ssh_config when connecting to Git repositories by using an SSH URI. +If the aws-java-sdk-core jar is not on your classpath, the AWS Code Commit credential provider is not created, regardless of the git server URI.

2.1.5 Git SSH configuration using properties

By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as ~/.ssh/known_hosts and /etc/ssh/ssh_config when connecting to Git repositories by using an SSH URI. In cloud environments such as Cloud Foundry, the local filesystem may be ephemeral or not easily accessible. For those cases, SSH configuration can be set by using Java properties. In order to activate property-based SSH configuration, the spring.cloud.config.server.git.ignoreLocalSshSettings property must be set to true, as shown in the following example:

  spring:
@@ -185,7 +186,7 @@ In order to activate property-based SSH configuration, the 69pcVH/4rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
-                         -----END RSA PRIVATE KEY-----

The following table describes the SSH configuration properties.

Table 2.1. SSH Configuration Properties

Property NameRemarks

ignoreLocalSshSettings

If true, use property-based instead of file-based SSH config. Must be set at as spring.cloud.config.server.git.ignoreLocalSshSettings, not inside a repository definition.

privateKey

Valid SSH private key. Must be set if ignoreLocalSshSettings is true and Git URI is SSH format.

hostKey

Valid SSH host key. Must be set if hostKeyAlgorithm is also set.

hostKeyAlgorithm

One of ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Must be set if hostKey is also set.

strictHostKeyChecking

true or false. If false, ignore errors with host key.

knownHostsFile

Location of custom .known_hosts file.

preferredAuthentications

Override server authentication method order. This should allow for evading login prompts if server has keyboard-interactive authentication before the publickey method.


Placeholders in Git Search Paths

Spring Cloud Config Server also supports a search path with placeholders for the {application} and {profile} (and {label} if + -----END RSA PRIVATE KEY-----

The following table describes the SSH configuration properties.

Table 2.1. SSH Configuration Properties

Property NameRemarks

ignoreLocalSshSettings

If true, use property-based instead of file-based SSH config. Must be set at as spring.cloud.config.server.git.ignoreLocalSshSettings, not inside a repository definition.

privateKey

Valid SSH private key. Must be set if ignoreLocalSshSettings is true and Git URI is SSH format.

hostKey

Valid SSH host key. Must be set if hostKeyAlgorithm is also set.

hostKeyAlgorithm

One of ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Must be set if hostKey is also set.

strictHostKeyChecking

true or false. If false, ignore errors with host key.

knownHostsFile

Location of custom .known_hosts file.

preferredAuthentications

Override server authentication method order. This should allow for evading login prompts if server has keyboard-interactive authentication before the publickey method.


2.1.6 Placeholders in Git Search Paths

Spring Cloud Config Server also supports a search path with placeholders for the {application} and {profile} (and {label} if you need it), as shown in the following example:

spring:
   cloud:
     config:
@@ -193,7 +194,7 @@ you need it), as shown in the following example:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
           searchPaths: '{application}'
The preceding listing causes a search of the repository for files in the same name as the directory (as well as the top level).
-Wildcards are also valid in a search path with placeholders (any matching directory is included in the search).

Force pull in Git Repositories

As mentioned earlier, Spring Cloud Config Server makes a clone of the remote git repository in case the local copy gets dirty (for example, +Wildcards are also valid in a search path with placeholders (any matching directory is included in the search).

2.1.7 Force pull in Git Repositories

As mentioned earlier, Spring Cloud Config Server makes a clone of the remote git repository in case the local copy gets dirty (for example, folder content changes by an OS process) such that Spring Cloud Config Server cannot update the local copy from remote repository.

To solve this issue, there is a force-pull property that makes Spring Cloud Config Server force pull from the remote repository if the local copy is dirty, as shown in the following example:

spring:
   cloud:
     config:
@@ -218,7 +219,7 @@ folder content changes by an OS process) such that Spring Cloud Config Server ca
                 force-pull: true
             team-c:
                 pattern: team-c-*
-                uri: http://git/team-a/config-repo.git
[Note]Note

The default value for force-pull property is false.

Deleting untracked branches in Git Repositories

As Spring Cloud Config Server has a clone of the remote git repository + uri: http://git/team-a/config-repo.git

[Note]Note

The default value for force-pull property is false.

2.1.8 Deleting untracked branches in Git Repositories

As Spring Cloud Config Server has a clone of the remote git repository after check-outing branch to local repo (e.g fetching properties by label) it will keep this branch forever or till the next server restart (which creates new local repo). So there could be a case when remote branch is deleted but local copy of it is still available for fetching. @@ -231,12 +232,12 @@ Example:

      server:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
-          deleteUntrackedBranches: true
[Note]Note

The default value for deleteUntrackedBranches property is false.

2.1.2 Version Control Backend Filesystem Use

[Warning]Warning

With VCS-based backends (git, svn), files are checked out or cloned to the local filesystem. + deleteUntrackedBranches: true

[Note]Note

The default value for deleteUntrackedBranches property is false.

2.1.9 Version Control Backend Filesystem Use

[Warning]Warning

With VCS-based backends (git, svn), files are checked out or cloned to the local filesystem. By default, they are put in the system temporary directory with a prefix of config-repo-. On linux, for example, it could be /tmp/config-repo-<randomid>. Some operating systems routinely clean out temporary directories. This can lead to unexpected behavior, such as missing properties. -To avoid this problem, change the directory that Config Server uses by setting spring.cloud.config.server.git.basedir or spring.cloud.config.server.svn.basedir to a directory that does not reside in the system temp structure.

2.1.3 File System Backend

There is also a “native” profile in the Config Server that does not use Git but 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 avoid this problem, change the directory that Config Server uses by setting spring.cloud.config.server.git.basedir or spring.cloud.config.server.svn.basedir to a directory that does not reside in the system temp structure.

2.1.10 File System Backend

There is also a “native” profile in the Config Server that does not use Git but 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, launch the Config Server with spring.profiles.active=native.

[Note]Note

Remember to use the file: prefix for file resources (the default without a prefix is usually the classpath). As with any Spring Boot configuration, you can embed ${}-style environment placeholders, but remember that absolute paths in Windows require an extra / (for example, file:///${user.home}/config-repo).

[Warning]Warning

The default value of the searchLocations is identical to a local Spring Boot application (that is, [classpath:/, classpath:/config, file:./, file:./config]). @@ -245,7 +246,7 @@ To use it in production, you need to be sure that the file system is reliable an In this way, you can segregate the directories in the path and choose a strategy that makes sense for you (such as subdirectory per application or subdirectory per profile).

If you do not use placeholders in the search locations, this repository also appends the {label} parameter of the HTTP resource to a suffix on the search path, so properties files are loaded from each search location and a subdirectory with the same name as the label (the labelled properties take precedence in the Spring Environment). Thus, the default behaviour with no placeholders is the same as adding a search location ending with /{label}/. For example, file:/tmp/config is the same as file:/tmp/config,file:/tmp/config/{label}. -This behavior can be disabled by setting spring.cloud.config.server.native.addLabelLocations=false.

2.1.4 Vault Backend

Spring Cloud Config Server also supports Vault as a backend.

Vault is a tool for securely accessing secrets. +This behavior can be disabled by setting spring.cloud.config.server.native.addLabelLocations=false.

2.1.11 Vault Backend

Spring Cloud Config Server also supports Vault as a backend.

Vault is a tool for securely accessing secrets. A secret is anything that to which you want to tightly control access, such as API keys, passwords, certificates, and other sensitive information. Vault provides a unified interface to any secret while providing tight access control and recording a detailed audit log.

For more information on Vault, see the Vault quick start guide.

To enable the config server to use a Vault backend, you can run your config server with the vault profile. For example, in your config server’s application.properties, you can add spring.profiles.active=vault.

By default, the config server assumes that your Vault server runs at http://127.0.0.1:8200. It also assumes that the name of backend is secret and the key is application. @@ -282,15 +283,15 @@ secret/myApp secret/application,dev secret/application

Properties written to secret/application are available to all applications using the Config Server. An application with the name, myApp, would have any properties written to secret/myApp and secret/application available to it. -When myApp has the dev profile enabled, properties written to all of the above paths would be available to it, with properties in the first path in the list taking priority over the others.

2.1.5 Sharing Configuration With All Applications

Sharing configuration between all applications varies according to which approach you take, as described in the following topics:

File Based Repositories

With file-based (git, svn, and native) repositories, resources with file names in application* (application.properties, application.yml, application-*.properties, and so on) are shared between all client applications. +When myApp has the dev profile enabled, properties written to all of the above paths would be available to it, with properties in the first path in the list taking priority over the others.

2.1.12 Sharing Configuration With All Applications

Sharing configuration between all applications varies according to which approach you take, as described in the following topics:

File Based Repositories

With file-based (git, svn, and native) repositories, resources with file names in application* (application.properties, application.yml, application-*.properties, and so on) are shared between all client applications. You can use resources with these file names to configure global defaults and have them be overridden by application-specific files as necessary.

The #_property_overrides[property overrides] feature can also be used for setting global defaults, with placeholders applications allowed to override them locally.

[Tip]Tip

With the “native” profile (a local file system backend) , you should use an explicit search location that is not part of the server’s own configuration. Otherwise, the application* resources in the default search locations get removed because they are part of the server.

Vault Server

When using Vault as a backend, you can share configuration with all applications by placing configuration in secret/application. -For example, if you run the following Vault command, all applications using the config server will have the properties foo and baz available to them:

$ vault write secret/application foo=bar baz=bam

2.1.6 JDBC Backend

Spring Cloud Config Server supports JDBC (relational database) as a backend for configuration properties. +For example, if you run the following Vault command, all applications using the config server will have the properties foo and baz available to them:

$ vault write secret/application foo=bar baz=bam

2.1.13 JDBC Backend

Spring Cloud Config Server supports JDBC (relational database) as a backend for configuration properties. You can enable this feature by adding spring-jdbc to the classpath and using the jdbc profile or by adding a bean of type JdbcEnvironmentRepository. If you include the right dependencies on the classpath (see the user guide for more details on that), Spring Boot configures a data source.

The database needs to have a table called PROPERTIES with columns called APPLICATION, PROFILE, and LABEL (with the usual Environment meaning), plus KEY and VALUE for the key and value pairs in Properties style. All fields are of type String in Java, so you can make them VARCHAR of whatever length you need. -Property values behave in the same way as they would if they came from Spring Boot properties files named {application}-{profile}.properties, including all the encryption and decryption, which will be applied as post-processing steps (that is, not in the repository implementation directly).

2.1.7 Composite Environment Repositories

In some scenarios, you may wish to pull configuration data from multiple environment repositories. +Property values behave in the same way as they would if they came from Spring Boot properties files named {application}-{profile}.properties, including all the encryption and decryption, which will be applied as post-processing steps (that is, not in the repository implementation directly).

2.1.14 Composite Environment Repositories

In some scenarios, you may wish to pull configuration data from multiple environment repositories. To do so, you can enable multiple profiles in your config server’s application properties or YAML file. If, for example, you want to pull configuration data from a Git repository as well as an SVN repository, you can set the following properties for your configuration server:

spring:
   profiles:
@@ -310,7 +311,7 @@ The priority order of a repository helps resolve any potential conflicts between
 If you have an environment similar to the one in the preceding example and you request configuration data with the master label but the SVN repository does not contain a branch called master, the entire request fails.

Custom Composite Environment Repositories

In addition to using one of the environment repositories from Spring Cloud, you can also provide your own EnvironmentRepository bean to be included as part of a composite environment. To do so, your bean must implement the EnvironmentRepository interface. If you want to control the priority of your custom EnvironmentRepository within the composite environment, you should also implement the Ordered interface and override the getOrdered method. -If you do not implement the Ordered interface, your EnvironmentRepository is given the lowest priority.

2.1.8 Property Overrides

The Config Server has an “overrides” feature that lets the operator provide configuration properties to all applications. +If you do not implement the Ordered interface, your EnvironmentRepository is given the lowest priority.

2.1.15 Property Overrides

The Config Server has an “overrides” feature that lets the operator provide configuration properties to all applications. The overridden properties cannot be accidentally changed by the application with the normal Spring Boot hooks. To declare overrides, add a map of name-value pairs to spring.cloud.config.server.overrides, as shown in the following example:

spring:
   cloud:
diff --git a/multi/multi_spring-cloud-config.html b/multi/multi_spring-cloud-config.html
index 596c842f..6f3d976e 100644
--- a/multi/multi_spring-cloud-config.html
+++ b/multi/multi_spring-cloud-config.html
@@ -1,3 +1,3 @@
 
       
-   Spring Cloud Config
Spring Cloud Config
   Next
Spring Cloud Config
Table of Contents
1. Quick Start
1.1. Client Side Usage
2. Spring Cloud Config Server
2.1. Environment Repository
2.1.1. Git Backend
Placeholders in Git URI
Pattern Matching and Multiple Repositories
Authentication
Authentication with AWS CodeCommit
Git SSH configuration using properties
Placeholders in Git Search Paths
Force pull in Git Repositories
Deleting untracked branches in Git Repositories
2.1.2. Version Control Backend Filesystem Use
2.1.3. File System Backend
2.1.4. Vault Backend
Multiple Properties Sources
2.1.5. Sharing Configuration With All Applications
File Based Repositories
Vault Server
2.1.6. JDBC Backend
2.1.7. Composite Environment Repositories
Custom Composite Environment Repositories
2.1.8. Property Overrides
2.2. Health Indicator
2.3. Security
2.4. Encryption and Decryption
2.5. Key Management
2.6. Creating a Key Store for Testing
2.7. Using Multiple Keys and Key Rotation
2.8. Serving Encrypted Properties
3. Serving Alternative Formats
4. Serving Plain Text
5. Embedding the Config Server
6. Push Notifications and Spring Cloud Bus
7. Spring Cloud Config Client
7.1. Config First Bootstrap
7.2. Discovery First Bootstrap
7.3. Config Client Fail Fast
7.4. Config Client Retry
7.5. Locating Remote Configuration Resources
7.6. Security
7.6.1. Health Indicator
7.6.2. Providing A Custom RestTemplate
7.6.3. Vault
7.7. Nested Keys In Vault
   Next
   

\ No newline at end of file
+   Spring Cloud Config
Spring Cloud Config
   Next
Spring Cloud Config
Table of Contents
1. Quick Start
1.1. Client Side Usage
2. Spring Cloud Config Server
2.1. Environment Repository
2.1.1. Placeholders in Git URI
2.1.2. Pattern Matching and Multiple Repositories
2.1.3. Authentication
2.1.4. Authentication with AWS CodeCommit
2.1.5. Git SSH configuration using properties
2.1.6. Placeholders in Git Search Paths
2.1.7. Force pull in Git Repositories
2.1.8. Deleting untracked branches in Git Repositories
2.1.9. Version Control Backend Filesystem Use
2.1.10. File System Backend
2.1.11. Vault Backend
Multiple Properties Sources
2.1.12. Sharing Configuration With All Applications
File Based Repositories
Vault Server
2.1.13. JDBC Backend
2.1.14. Composite Environment Repositories
Custom Composite Environment Repositories
2.1.15. Property Overrides
2.2. Health Indicator
2.3. Security
2.4. Encryption and Decryption
2.5. Key Management
2.6. Creating a Key Store for Testing
2.7. Using Multiple Keys and Key Rotation
2.8. Serving Encrypted Properties
3. Serving Alternative Formats
4. Serving Plain Text
5. Embedding the Config Server
6. Push Notifications and Spring Cloud Bus
7. Spring Cloud Config Client
7.1. Config First Bootstrap
7.2. Discovery First Bootstrap
7.3. Config Client Fail Fast
7.4. Config Client Retry
7.5. Locating Remote Configuration Resources
7.6. Security
7.6.1. Health Indicator
7.6.2. Providing A Custom RestTemplate
7.6.3. Vault
7.7. Nested Keys In Vault
   Next
   

\ No newline at end of file
diff --git a/single/spring-cloud-config.html b/single/spring-cloud-config.html
index 81ff758b..708a708d 100644
--- a/single/spring-cloud-config.html
+++ b/single/spring-cloud-config.html
@@ -1,6 +1,6 @@
 
       
-   Spring Cloud Config
Spring Cloud Config
Table of Contents
1. Quick Start
1.1. Client Side Usage
2. Spring Cloud Config Server
2.1. Environment Repository
2.1.1. Git Backend
Placeholders in Git URI
Pattern Matching and Multiple Repositories
Authentication
Authentication with AWS CodeCommit
Git SSH configuration using properties
Placeholders in Git Search Paths
Force pull in Git Repositories
Deleting untracked branches in Git Repositories
2.1.2. Version Control Backend Filesystem Use
2.1.3. File System Backend
2.1.4. Vault Backend
Multiple Properties Sources
2.1.5. Sharing Configuration With All Applications
File Based Repositories
Vault Server
2.1.6. JDBC Backend
2.1.7. Composite Environment Repositories
Custom Composite Environment Repositories
2.1.8. Property Overrides
2.2. Health Indicator
2.3. Security
2.4. Encryption and Decryption
2.5. Key Management
2.6. Creating a Key Store for Testing
2.7. Using Multiple Keys and Key Rotation
2.8. Serving Encrypted Properties
3. Serving Alternative Formats
4. Serving Plain Text
5. Embedding the Config Server
6. Push Notifications and Spring Cloud Bus
7. Spring Cloud Config Client
7.1. Config First Bootstrap
7.2. Discovery First Bootstrap
7.3. Config Client Fail Fast
7.4. Config Client Retry
7.5. Locating Remote Configuration Resources
7.6. Security
7.6.1. Health Indicator
7.6.2. Providing A Custom RestTemplate
7.6.3. Vault
7.7. Nested Keys In Vault
2.0.0.BUILD-SNAPSHOT
Spring Cloud Config provides server-side and client-side support for externalized configuration in a distributed system. With the Config Server, you have a central place to manage external properties for applications across all environments.
+   Spring Cloud Config
Spring Cloud Config
Table of Contents
1. Quick Start
1.1. Client Side Usage
2. Spring Cloud Config Server
2.1. Environment Repository
2.1.1. Placeholders in Git URI
2.1.2. Pattern Matching and Multiple Repositories
2.1.3. Authentication
2.1.4. Authentication with AWS CodeCommit
2.1.5. Git SSH configuration using properties
2.1.6. Placeholders in Git Search Paths
2.1.7. Force pull in Git Repositories
2.1.8. Deleting untracked branches in Git Repositories
2.1.9. Version Control Backend Filesystem Use
2.1.10. File System Backend
2.1.11. Vault Backend
Multiple Properties Sources
2.1.12. Sharing Configuration With All Applications
File Based Repositories
Vault Server
2.1.13. JDBC Backend
2.1.14. Composite Environment Repositories
Custom Composite Environment Repositories
2.1.15. Property Overrides
2.2. Health Indicator
2.3. Security
2.4. Encryption and Decryption
2.5. Key Management
2.6. Creating a Key Store for Testing
2.7. Using Multiple Keys and Key Rotation
2.8. Serving Encrypted Properties
3. Serving Alternative Formats
4. Serving Plain Text
5. Embedding the Config Server
6. Push Notifications and Spring Cloud Bus
7. Spring Cloud Config Client
7.1. Config First Bootstrap
7.2. Discovery First Bootstrap
7.3. Config Client Fail Fast
7.4. Config Client Retry
7.5. Locating Remote Configuration Resources
7.6. Security
7.6.1. Health Indicator
7.6.2. Providing A Custom RestTemplate
7.6.3. Vault
7.7. Nested Keys In Vault
2.0.0.BUILD-SNAPSHOT
Spring Cloud Config provides server-side and client-side support for externalized configuration in a distributed system. With the Config Server, you have a central place to manage external properties for applications across all environments.
 The concepts on both client and server map identically to the Spring Environment and PropertySource abstractions, so they fit very well with Spring applications but can be used with any application running in any language.
 As an application moves through the deployment pipeline from dev to test and into production, you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate.
 The default implementation of the server storage backend uses git, so it easily supports labelled versions of configuration environments as well as being accessible to a wide range of tooling for managing the content.
@@ -123,7 +123,8 @@ Precedence rules for profiles are also the same as in a regular Spring Boot appl
 If the YAML files have documents inside them that point to Spring profiles, those are applied with higher precedence (in order of the profiles listed).
 If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults.
 Higher precedence translates to a PropertySource listed earlier in the Environment.
-(These same rules apply in a standalone Spring Boot application.)
2.1.1 Git Backend
The default implementation of EnvironmentRepository uses a Git backend, which is very convenient for managing upgrades and physical
+(These same rules apply in a standalone Spring Boot application.)
You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true.
+==== Git Backend
The default implementation of EnvironmentRepository uses a Git backend, which is very convenient for managing upgrades and physical
 environments and for auditing changes.
 To change the location of the repository, you can set the spring.cloud.config.server.git.uri configuration property in the Config Server (for example in application.yml).
 If you set it with a file: prefix, it should work from a local repository so that you can get started quickly and easily without a server. However, in that case, the server operates directly on the local repository without cloning it (it does not matter if it is not bare because the Config Server never makes changes to the "remote" repository).
@@ -133,7 +134,7 @@ If the git branch or tag name contains a slash (/),
 For example, if the label is foo/bar, replacing the slash would result in the following label: foo($$_$$)bar.
 The inclusion of the special string ($$_$$) can also be applied to the {application} parameter.
 If you use a command-line client such as curl, be careful with the brackets in the URL — you should
-escape them from the shell with single quotes ('').
Placeholders in Git URI
Spring Cloud Config Server supports a git repository URL with placeholders for the {application} and {profile} (and {label} if you need it, but remember that the label is applied as a git label anyway).
+escape them from the shell with single quotes ('').
2.1.1 Placeholders in Git URI
Spring Cloud Config Server supports a git repository URL with placeholders for the {application} and {profile} (and {label} if you need it, but remember that the label is applied as a git label anyway).
 So you can support a “one repository per application” policy by using a structure similar to the following:
spring:
   cloud:
     config:
@@ -146,7 +147,7 @@ organizations, as shown in the following example:
    config:
       server:
         git:
-          uri: https://github.com/{application}
where {application} is provided at request time in the following format: organization($$_$$)application.
Pattern Matching and Multiple Repositories
Spring Cloud Config also includes support for more complex requirements with pattern
+          uri: https://github.com/{application}

where {application} is provided at request time in the following format: organization($$_$$)application.

2.1.2 Pattern Matching and Multiple Repositories

Spring Cloud Config also includes support for more complex requirements with pattern matching on the application and profile name. The pattern format is a comma-separated list of {application}/{profile} names with wildcards (note that a pattern beginning with a wildcard may need to be quoted), as shown in the following example:

spring:
   cloud:
@@ -210,7 +211,7 @@ The server can be configured to clone the repositories at startup, as shown in t
                 uri: http://git/team-a/config-repo.git

In the preceding example, the server clones team-a’s config-repo on startup, before it accepts any requests. All other repositories are not cloned until configuration from the repository is requested.

[Note]Note

Setting a repository to be cloned when the Config Server starts up can help to identify a misconfigured configuration source (such as an invalid repository URI) quickly, while the Config Server is starting up. -With cloneOnStart not enabled for a configuration source, the Config Server may start successfully with a misconfigured or invalid configuration source and not detect an error until an application requests configuration from that configuration source.

Authentication

To use HTTP basic authentication on the remote repository, add the username and password properties separately (not in the URL), as shown in the following example:

spring:
+With cloneOnStart not enabled for a configuration source, the Config Server may start successfully with a misconfigured or invalid configuration source and not detect an error until an application requests configuration from that configuration source.

2.1.3 Authentication

To use HTTP basic authentication on the remote repository, add the username and password properties separately (not in the URL), as shown in the following example:

spring:
   cloud:
     config:
       server:
@@ -224,13 +225,13 @@ To avoid surprises, you should ensure that only one entry is present in the known_hosts file.
 The repository is accessed by using JGit, so any documentation you find on that should be applicable.
 HTTPS proxy settings can be set in ~/.git/config or (in the same way as for any other JVM process) with
-system properties (-Dhttps.proxyHost and -Dhttps.proxyPort).
[Tip]Tip
If you do not know where your ~/.git directory is, use git config --global to manipulate the settings (for example, git config --global http.sslVerify false).

Authentication with AWS CodeCommit

Spring Cloud Config Server also supports AWS CodeCommit authentication. +system properties (-Dhttps.proxyHost and -Dhttps.proxyPort).

[Tip]Tip

If you do not know where your ~/.git directory is, use git config --global to manipulate the settings (for example, git config --global http.sslVerify false).

2.1.4 Authentication with AWS CodeCommit

Spring Cloud Config Server also supports AWS CodeCommit authentication. AWS CodeCommit uses an authentication helper when using Git from the command line. This helper is not used with the JGit library, so a JGit CredentialProvider for AWS CodeCommit is created if the Git URI matches the AWS CodeCommit pattern. AWS CodeCommit URIs follow this pattern://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}.

If you provide a username and password with an AWS CodeCommit URI, they must be the AWS accessKeyId and secretAccessKey that provide access to the repository. If you do not specify a username and password, the accessKeyId and secretAccessKey are retrieved by using the AWS Default Credential Provider Chain.

If your Git URI matches the CodeCommit URI pattern (shown earlier), you must provide valid AWS credentials in the username and password or in one of the locations supported by the default credential provider chain. AWS EC2 instances may use IAM Roles for EC2 Instances.

[Note]Note

The aws-java-sdk-core jar is an optional dependency. -If the aws-java-sdk-core jar is not on your classpath, the AWS Code Commit credential provider is not created, regardless of the git server URI.

Git SSH configuration using properties

By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as ~/.ssh/known_hosts and /etc/ssh/ssh_config when connecting to Git repositories by using an SSH URI. +If the aws-java-sdk-core jar is not on your classpath, the AWS Code Commit credential provider is not created, regardless of the git server URI.

2.1.5 Git SSH configuration using properties

By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as ~/.ssh/known_hosts and /etc/ssh/ssh_config when connecting to Git repositories by using an SSH URI. In cloud environments such as Cloud Foundry, the local filesystem may be ephemeral or not easily accessible. For those cases, SSH configuration can be set by using Java properties. In order to activate property-based SSH configuration, the spring.cloud.config.server.git.ignoreLocalSshSettings property must be set to true, as shown in the following example:

  spring:
@@ -269,7 +270,7 @@ In order to activate property-based SSH configuration, the 69pcVH/4rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
-                         -----END RSA PRIVATE KEY-----

The following table describes the SSH configuration properties.

Table 2.1. SSH Configuration Properties

Property NameRemarks

ignoreLocalSshSettings

If true, use property-based instead of file-based SSH config. Must be set at as spring.cloud.config.server.git.ignoreLocalSshSettings, not inside a repository definition.

privateKey

Valid SSH private key. Must be set if ignoreLocalSshSettings is true and Git URI is SSH format.

hostKey

Valid SSH host key. Must be set if hostKeyAlgorithm is also set.

hostKeyAlgorithm

One of ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Must be set if hostKey is also set.

strictHostKeyChecking

true or false. If false, ignore errors with host key.

knownHostsFile

Location of custom .known_hosts file.

preferredAuthentications

Override server authentication method order. This should allow for evading login prompts if server has keyboard-interactive authentication before the publickey method.


Placeholders in Git Search Paths

Spring Cloud Config Server also supports a search path with placeholders for the {application} and {profile} (and {label} if + -----END RSA PRIVATE KEY-----

The following table describes the SSH configuration properties.

Table 2.1. SSH Configuration Properties

Property NameRemarks

ignoreLocalSshSettings

If true, use property-based instead of file-based SSH config. Must be set at as spring.cloud.config.server.git.ignoreLocalSshSettings, not inside a repository definition.

privateKey

Valid SSH private key. Must be set if ignoreLocalSshSettings is true and Git URI is SSH format.

hostKey

Valid SSH host key. Must be set if hostKeyAlgorithm is also set.

hostKeyAlgorithm

One of ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Must be set if hostKey is also set.

strictHostKeyChecking

true or false. If false, ignore errors with host key.

knownHostsFile

Location of custom .known_hosts file.

preferredAuthentications

Override server authentication method order. This should allow for evading login prompts if server has keyboard-interactive authentication before the publickey method.


2.1.6 Placeholders in Git Search Paths

Spring Cloud Config Server also supports a search path with placeholders for the {application} and {profile} (and {label} if you need it), as shown in the following example:

spring:
   cloud:
     config:
@@ -277,7 +278,7 @@ you need it), as shown in the following example:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
           searchPaths: '{application}'
The preceding listing causes a search of the repository for files in the same name as the directory (as well as the top level).
-Wildcards are also valid in a search path with placeholders (any matching directory is included in the search).

Force pull in Git Repositories

As mentioned earlier, Spring Cloud Config Server makes a clone of the remote git repository in case the local copy gets dirty (for example, +Wildcards are also valid in a search path with placeholders (any matching directory is included in the search).

2.1.7 Force pull in Git Repositories

As mentioned earlier, Spring Cloud Config Server makes a clone of the remote git repository in case the local copy gets dirty (for example, folder content changes by an OS process) such that Spring Cloud Config Server cannot update the local copy from remote repository.

To solve this issue, there is a force-pull property that makes Spring Cloud Config Server force pull from the remote repository if the local copy is dirty, as shown in the following example:

spring:
   cloud:
     config:
@@ -302,7 +303,7 @@ folder content changes by an OS process) such that Spring Cloud Config Server ca
                 force-pull: true
             team-c:
                 pattern: team-c-*
-                uri: http://git/team-a/config-repo.git
[Note]Note

The default value for force-pull property is false.

Deleting untracked branches in Git Repositories

As Spring Cloud Config Server has a clone of the remote git repository + uri: http://git/team-a/config-repo.git

[Note]Note

The default value for force-pull property is false.

2.1.8 Deleting untracked branches in Git Repositories

As Spring Cloud Config Server has a clone of the remote git repository after check-outing branch to local repo (e.g fetching properties by label) it will keep this branch forever or till the next server restart (which creates new local repo). So there could be a case when remote branch is deleted but local copy of it is still available for fetching. @@ -315,12 +316,12 @@ Example:

      server:
         git:
           uri: https://github.com/spring-cloud-samples/config-repo
-          deleteUntrackedBranches: true
[Note]Note

The default value for deleteUntrackedBranches property is false.

2.1.2 Version Control Backend Filesystem Use

[Warning]Warning

With VCS-based backends (git, svn), files are checked out or cloned to the local filesystem. + deleteUntrackedBranches: true

[Note]Note

The default value for deleteUntrackedBranches property is false.

2.1.9 Version Control Backend Filesystem Use

[Warning]Warning

With VCS-based backends (git, svn), files are checked out or cloned to the local filesystem. By default, they are put in the system temporary directory with a prefix of config-repo-. On linux, for example, it could be /tmp/config-repo-<randomid>. Some operating systems routinely clean out temporary directories. This can lead to unexpected behavior, such as missing properties. -To avoid this problem, change the directory that Config Server uses by setting spring.cloud.config.server.git.basedir or spring.cloud.config.server.svn.basedir to a directory that does not reside in the system temp structure.

2.1.3 File System Backend

There is also a “native” profile in the Config Server that does not use Git but 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 avoid this problem, change the directory that Config Server uses by setting spring.cloud.config.server.git.basedir or spring.cloud.config.server.svn.basedir to a directory that does not reside in the system temp structure.

2.1.10 File System Backend

There is also a “native” profile in the Config Server that does not use Git but 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, launch the Config Server with spring.profiles.active=native.

[Note]Note

Remember to use the file: prefix for file resources (the default without a prefix is usually the classpath). As with any Spring Boot configuration, you can embed ${}-style environment placeholders, but remember that absolute paths in Windows require an extra / (for example, file:///${user.home}/config-repo).

[Warning]Warning

The default value of the searchLocations is identical to a local Spring Boot application (that is, [classpath:/, classpath:/config, file:./, file:./config]). @@ -329,7 +330,7 @@ To use it in production, you need to be sure that the file system is reliable an In this way, you can segregate the directories in the path and choose a strategy that makes sense for you (such as subdirectory per application or subdirectory per profile).

If you do not use placeholders in the search locations, this repository also appends the {label} parameter of the HTTP resource to a suffix on the search path, so properties files are loaded from each search location and a subdirectory with the same name as the label (the labelled properties take precedence in the Spring Environment). Thus, the default behaviour with no placeholders is the same as adding a search location ending with /{label}/. For example, file:/tmp/config is the same as file:/tmp/config,file:/tmp/config/{label}. -This behavior can be disabled by setting spring.cloud.config.server.native.addLabelLocations=false.

2.1.4 Vault Backend

Spring Cloud Config Server also supports Vault as a backend.

Vault is a tool for securely accessing secrets. +This behavior can be disabled by setting spring.cloud.config.server.native.addLabelLocations=false.

2.1.11 Vault Backend

Spring Cloud Config Server also supports Vault as a backend.

Vault is a tool for securely accessing secrets. A secret is anything that to which you want to tightly control access, such as API keys, passwords, certificates, and other sensitive information. Vault provides a unified interface to any secret while providing tight access control and recording a detailed audit log.

For more information on Vault, see the Vault quick start guide.

To enable the config server to use a Vault backend, you can run your config server with the vault profile. For example, in your config server’s application.properties, you can add spring.profiles.active=vault.

By default, the config server assumes that your Vault server runs at http://127.0.0.1:8200. It also assumes that the name of backend is secret and the key is application. @@ -366,15 +367,15 @@ secret/myApp secret/application,dev secret/application

Properties written to secret/application are available to all applications using the Config Server. An application with the name, myApp, would have any properties written to secret/myApp and secret/application available to it. -When myApp has the dev profile enabled, properties written to all of the above paths would be available to it, with properties in the first path in the list taking priority over the others.

2.1.5 Sharing Configuration With All Applications

Sharing configuration between all applications varies according to which approach you take, as described in the following topics:

File Based Repositories

With file-based (git, svn, and native) repositories, resources with file names in application* (application.properties, application.yml, application-*.properties, and so on) are shared between all client applications. +When myApp has the dev profile enabled, properties written to all of the above paths would be available to it, with properties in the first path in the list taking priority over the others.

2.1.12 Sharing Configuration With All Applications

Sharing configuration between all applications varies according to which approach you take, as described in the following topics:

File Based Repositories

With file-based (git, svn, and native) repositories, resources with file names in application* (application.properties, application.yml, application-*.properties, and so on) are shared between all client applications. You can use resources with these file names to configure global defaults and have them be overridden by application-specific files as necessary.

The #_property_overrides[property overrides] feature can also be used for setting global defaults, with placeholders applications allowed to override them locally.

[Tip]Tip

With the “native” profile (a local file system backend) , you should use an explicit search location that is not part of the server’s own configuration. Otherwise, the application* resources in the default search locations get removed because they are part of the server.

Vault Server

When using Vault as a backend, you can share configuration with all applications by placing configuration in secret/application. -For example, if you run the following Vault command, all applications using the config server will have the properties foo and baz available to them:

$ vault write secret/application foo=bar baz=bam

2.1.6 JDBC Backend

Spring Cloud Config Server supports JDBC (relational database) as a backend for configuration properties. +For example, if you run the following Vault command, all applications using the config server will have the properties foo and baz available to them:

$ vault write secret/application foo=bar baz=bam

2.1.13 JDBC Backend

Spring Cloud Config Server supports JDBC (relational database) as a backend for configuration properties. You can enable this feature by adding spring-jdbc to the classpath and using the jdbc profile or by adding a bean of type JdbcEnvironmentRepository. If you include the right dependencies on the classpath (see the user guide for more details on that), Spring Boot configures a data source.

The database needs to have a table called PROPERTIES with columns called APPLICATION, PROFILE, and LABEL (with the usual Environment meaning), plus KEY and VALUE for the key and value pairs in Properties style. All fields are of type String in Java, so you can make them VARCHAR of whatever length you need. -Property values behave in the same way as they would if they came from Spring Boot properties files named {application}-{profile}.properties, including all the encryption and decryption, which will be applied as post-processing steps (that is, not in the repository implementation directly).

2.1.7 Composite Environment Repositories

In some scenarios, you may wish to pull configuration data from multiple environment repositories. +Property values behave in the same way as they would if they came from Spring Boot properties files named {application}-{profile}.properties, including all the encryption and decryption, which will be applied as post-processing steps (that is, not in the repository implementation directly).

2.1.14 Composite Environment Repositories

In some scenarios, you may wish to pull configuration data from multiple environment repositories. To do so, you can enable multiple profiles in your config server’s application properties or YAML file. If, for example, you want to pull configuration data from a Git repository as well as an SVN repository, you can set the following properties for your configuration server:

spring:
   profiles:
@@ -394,7 +395,7 @@ The priority order of a repository helps resolve any potential conflicts between
 If you have an environment similar to the one in the preceding example and you request configuration data with the master label but the SVN repository does not contain a branch called master, the entire request fails.

Custom Composite Environment Repositories

In addition to using one of the environment repositories from Spring Cloud, you can also provide your own EnvironmentRepository bean to be included as part of a composite environment. To do so, your bean must implement the EnvironmentRepository interface. If you want to control the priority of your custom EnvironmentRepository within the composite environment, you should also implement the Ordered interface and override the getOrdered method. -If you do not implement the Ordered interface, your EnvironmentRepository is given the lowest priority.

2.1.8 Property Overrides

The Config Server has an “overrides” feature that lets the operator provide configuration properties to all applications. +If you do not implement the Ordered interface, your EnvironmentRepository is given the lowest priority.

2.1.15 Property Overrides

The Config Server has an “overrides” feature that lets the operator provide configuration properties to all applications. The overridden properties cannot be accidentally changed by the application with the normal Spring Boot hooks. To declare overrides, add a map of name-value pairs to spring.cloud.config.server.overrides, as shown in the following example:

spring:
   cloud:
diff --git a/spring-cloud-config.xml b/spring-cloud-config.xml
index 30ef14f3..afabf4e2 100644
--- a/spring-cloud-config.xml
+++ b/spring-cloud-config.xml
@@ -215,8 +215,8 @@ If the YAML files have documents inside them that point to Spring profiles, thos
 If there are profile-specific YAML (or properties) files, these are also applied with higher precedence than the defaults.
 Higher precedence translates to a PropertySource listed earlier in the Environment.
 (These same rules apply in a standalone Spring Boot application.)
-

-Git Backend
+You can set spring.cloud.config.server.accept-empty to false so that Server would return a HTTP 404 status, if the application is not found.By default, this flag is set to true.
+==== Git Backend
 The default implementation of EnvironmentRepository uses a Git backend, which is very convenient for managing upgrades and physical
 environments and for auditing changes.
 To change the location of the repository, you can set the spring.cloud.config.server.git.uri configuration property in the Config Server (for example in application.yml).
@@ -536,7 +536,6 @@ Example:
 The default value for deleteUntrackedBranches property is false.
 
 

-
 

 Version Control Backend Filesystem Use