Git is a distributed version control system (DVCS). It encourages parallel development through simplified branching and merging, optimizes performance by conducting many operations on the local copy of the repository, and uses SHA-1 hashes for checksums to assure integrity and guard against corruption of repository data. For more information about Git, see the documentation.
Spring Cloud Config provides a Git backend so that the Spring Cloud Config Server can serve configuration stored in Git. The Spring Cloud Services Config Server supports this backend and can serve configuration stored in Git to client apps when given the URL to a Git repository (for example, the URL of a repository hosted on GitHub or Bitbucket). For more information about Spring Cloud Config's Git backend, see the documentation.
See below for information about configuring a Config Server service instance to use Git for configuration sources.
Parameters used to configure configuration sources are part of a JSON object called git, as in {"git": { "uri": "https://example.com/config" } }. General parameters used to configure the Config Server's default configuration source are listed below.
| Parameter | Function |
|---|---|
uri |
The URI (http://, https://, or ssh://) of a repository that can be used as the default configuration source |
label |
The default "label" that can be used with the default repository if a request is received without a label (for example if the spring.cloud.config.label property is not set in a client app) |
searchPaths |
A pattern used to search for configuration-containing subdirectories in the default repository |
cloneOnStart |
Whether the Config Server should clone the default repository when it starts up (by default, the Config Server will only clone the repository when configuration is first requested from the repository). Valid values are true and false |
username |
The username used to access the default repository (if protected by HTTP Basic authentication) |
password |
The password used to access the default repository (if protected by HTTP Basic authentication) |
refreshRate |
Interval, in seconds, to wait between refreshes of the Config Server's repository clone when a client requests configuration |
skipSslValidation |
For a https:// URI, whether to skip validation of the SSL certificate on the default repository's server. Valid values are true and false |
Important: If you set cloneOnStart to true for a service instance that uses a repository which is secured with HTTP Basic authentication, you must set the username and password at the same time as you set cloneOnStart. Otherwise, the Config Server will be unable to access the repository and the service instance may fail to initialize.
The uri setting is required; you cannot define a Config Server configuration source without including a uri.
The default value of the label setting is master. You can set label to a branch name, a tag name, or a specific Git commit hash.
To set label to point to the develop branch of a repository, you might configure settings as in the following:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/myorg/config-repo", "label": "develop" } }'
To set label to point to the v1.1 tag in a repository, you might configure settings as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/myorg/config-repo", "label": "v1.1" } }'
Within a client app, you can override the Config Server's label setting by setting the spring.cloud.config.label property (for example, in bootstrap.yml).
spring:
cloud:
config:
label: v1.2
Passwords are masked in the Config Server dashboard.
The Config Server can serve encrypted property values from a configuration file. If the Config Server is configured with a symmetric or asymmetric encryption key and the encrypted values are prefixed with the string {cipher}, the Config Server will decrypt the values before serving them to client apps. The Config Server has an /encrypt endpoint, which can be used to encrypt property values.
To use these features in a client app, you must use a Java buildpack which contains the Java Cryptography Extension (JCE) Unlimited Strength policy files. These files are contained in the Cloud Foundry Java buildpack from version 3.7.1.
If you cannot use version 3.7.1 or later, you can add the JCE Unlimited Strength policy files to an earlier version of the Cloud Foundry Java buildpack. Fork the buildpack on GitHub, then download the policy files from Oracle and place them in the buildpack's resources/open_jdk_jre/lib/security directory. Follow the instructions in Managing Custom Buildpacks to add this buildpack to VMware Tanzu Application Service for VMs. Be sure that it has the lowest position of all enabled Java buildpacks.
When the Config Server has been configured to encrypt values, you can make a POST request to the /encrypt endpoint. Include the property value in the request. A request to encrypt a value might look something like the following (using cURL), where the cf oauth-token command is used to provide an OAuth 2.0 token and SERVER is the URL of the Config Server:
curl -H 'Authorization: $(cf oauth-token)' http://SERVER/encrypt -d 'Value to be encrypted'
The Config Server returns the encrypted value. You can use the encrypted value in a configuration file as described in the Encrypted Configuration section of Configuration Properties.
The parameters used to configure server-side encryption for a Config Server are listed below.
| Parameter | Function |
|---|---|
encrypt.key |
The key to use for encryption. |
To configure a Config Server service instance that can encrypt property values, use the following command:
cf create-service p-config-server standard config-server -c '{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config.git" }, "encrypt": { "key": "KEY" }}'
If you wish to use public-key (or asymmetric) encryption, you may configure the Config Server to use a PEM-encoded keypair. You might generate such a keypair using, for example, OpenSSL on the command line:
$ openssl genpkey -algorithm RSA -outform PEM -pkeyopt rsa_keygen_bits:2048 > server.key
# Translate PEM encoded private key to a RSA private key and escape newlines
$ openssl rsa -in server.key | awk '{printf "%s\n", $0}' > server_rsa.key
Important: The key must be correctly formatted in order to be usable by the Config Server. Either use the above commands or ensure that you otherwise create a similar PEM-encoded keypair. The beginning of the key should include BEGIN RSA PRIVATE KEY.
To configure a Config Server service instance that can encrypt property values with an assymetric keypair, use the following JSON object, where the value of key is the content of the server_rsa.key file:
'{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config.git" }, "encrypt": { "key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE......\n-----END RSA PRIVATE KEY-----" }}'
The encryption key is masked in the Config Server dashboard.
You can configure a Config Server configuration source so that the Config Server accesses it using the Secure Shell (SSH) protocol. To do so, you must specify a URI using the ssh:// URI scheme or the Secure Copy Protocol (SCP) style URI format, and you must supply a private key. You may also supply a host key with which the server will be identified. If you do not provide a host key, the Config Server will not verify the host key of the configuration source's server.
A SSH URI must include a username, host, and repository path. This might be specified as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "ssh://git@github.com/spring-cloud-services-samples/cook.git"} }'
An equivalent SCP-style URI might be specified as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "git@github.com:spring-cloud-services-samples/cook-config.git"} }'
The parameters used to configure SSH for a Config Server configuration source's URI are listed below.
| Parameter | Function |
|---|---|
hostKey |
The host key of the Git server. If you have connected to the server via git on the command line, this is in your .ssh/known_hosts. Do not include the algorithm prefix; this is specified in hostKeyAlgorithm. (Optional.) |
hostKeyAlgorithm |
The algorithm of hostKey: one of "ssh-dss", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", and "ecdsa-sha2-nistp521". (Required if supplying hostKey.) |
privateKey |
The private key that identifies the Git user, with all newline characters replaced by \n. Passphrase-encrypted private keys are not supported. |
strictHostKeyChecking |
Whether the Config Server should fail to start if it encounters an error when using the provided hostKey. (Optional.) Valid values are true and false. Default is true. |
To configure a Config Server service instance that uses SSH to access a configuration source, allowing for host key verification, use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "ssh://git@github.com/spring-cloud-services-samples/cook.git", "hostKey": "EXAMPLEcccc1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+...", "hostKeyAlgorithm": "ssh-rsa", "privateKey": "-----BEGIN EXAMPLE RSA PRIVATE KEY-----\nMIIJKQIB..."} }'
To configure a Config Server service instance that uses SSH to access a configuration source, without host key verification, use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "ssh://git@github.com/spring-cloud-services-samples/cook.git", "privateKey": "-----BEGIN EXAMPLE RSA PRIVATE KEY-----\nMIIJKQIB..."} }'
Host and private keys are masked in the Config Server dashboard.
You can configure a Config Server service instance to use multiple configuration sources, which will be used only for specific apps or for apps which are using specific profiles. To do so, you must provide parameters in repository objects within the git.repos JSON object. Most parameters set in the git object for the default configuration source are also available for specific configuration sources and can be set in repository objects within the git.repos object.
Each repository object in the git.repos object has a name. In the repository specified in the following command, the name is "cookie":
cf create-service p-config-server standard config-server -c '{ "git": { "repos": { "cookie": { "uri": "https://github.com/spring-cloud-services-samples/cook-config" } } } }'
Each repository object also has a pattern, which is a comma-separated list of app and profile names separated with forward slashes (/, as in app/profile) and potentially including wildcards (*, as in app*/profile*). If you do not supply a pattern, the repository object's name will be used as the pattern. In the repository specified in the following command, the pattern is co*/dev* (matching any app whose name begins with co and which is using a profile whose name begins with dev), and the default pattern would be cookie:
cf create-service p-config-server standard config-server -c '{"git": { "repos": { "cookie": { "pattern": "co*/dev*", "uri": "https://github.com/spring-cloud-services-samples/cook-config" } } } }'
For more information about the pattern format, see "Pattern Matching and Multiple Repositories" in the Spring Cloud Config documentation.
The parameters used to configure specific configuration sources for the Config Server are listed below.
| Parameter | Function |
|---|---|
repos."name" |
A repository object, containing repository fields |
repos."name".pattern |
A pattern for the names of apps that store configuration from this repository (if not supplied, will be "name") |
repos."name".uri |
The URI (http://, https://, or ssh://) of this repository |
repos."name".label |
The default "label" to use with this repository if a request is received without a label (for example if the spring.cloud.config.label property is not set in a client app) |
repos."name".searchPaths |
A pattern used to search for configuration-containing subdirectories in this repository |
repos."name".cloneOnStart |
Whether the Config Server should clone this repository when it starts up (by default, the Config Server will only clone the repository when configuration is first requested from the repository). Valid values are true and false |
repos."name".username |
The username used to access this repository (if protected by HTTP Basic authentication) |
repos."name".password |
The password used to access this repository (if protected by HTTP Basic authentication) |
repos."name".refreshRate |
Interval, in seconds, to wait between refreshes of the Config Server's clone of this repository when a client requests configuration |
repos."name".skipSslValidation |
For a https:// URI, whether to skip validation of the SSL certificate on the default repository's server. Valid values are true and false |
repos."name".hostKey |
The host key used by the Config Server to access this repository (if accessing via SSH). See the SSH Repository Access section for more information |
repos."name".hostKeyAlgorithm |
The algorithm of hostKey: one of "ssh-dss", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", and "ecdsa-sha2-nistp521" |
repos."name".privateKey |
The private key corresponding to hostKey, with all newline characters replaced by \n |
Important: If you set cloneOnStart to true for a repository which is secured with HTTP Basic authentication, you must set the username and password at the same time as you set cloneOnStart. Otherwise, the Config Server will be unable to access the repository and the service instance may fail to initialize.
The uri setting is required; you cannot define a Config Server configuration source without including a uri.
The default value of the label setting is master. You can set label to a branch name, a tag name, or a specific Git commit hash.
To set label to point to the develop branch of a repository, you might configure the setting as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "repos": { "cookie": { "uri": "https://github.com/myorg/config-repo", "label": "develop" } } } }'
To set label to point to the v1.1 tag in a repository, you might configure the setting as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "repos": { "cookie": { "uri": "https://github.com/myorg/config-repo", "label": "v1.1" } } } }'
Within a client app, you can override this label setting's value by setting the spring.cloud.config.label property (for example, in bootstrap.yml).
spring:
cloud:
config:
label: v1.2
Passwords are masked in the Config Server dashboard.
To configure a Config Server service instance with a default repository that uses a refreshRate of 30 seconds and a repository specific to an app named "cook", use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/fortune-teller", "refreshRate": 30, "searchPaths": "configuration", "repos": { "cookie": { "pattern": "cook", "uri": "https://github.com/spring-cloud-services-samples/cook-config" } } } }'
To configure a Config Server service instance with a default repository and a repository specific to apps using the dev profile, use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/fortune-teller", "searchPaths": "configuration", "repos": { "cookie": { "pattern": "*/dev", "uri": "https://github.com/spring-cloud-services-samples/cook-config" } } } }'
The URIs for configuration source Git repositories can include a couple of special strings as placeholders:
{application}: the name set in the spring.application.name property on an app{profile}: a profile listed in the spring.profiles.active property on an appYou can use these placeholders to (for example) set a single URI which maps one repository each to multiple apps that use the same Config Server, or to set a single URI which maps one repository each to multiple profiles.
Note: URI placeholders cannot be used with a repository that has the cloneOnStart setting set to true. See the listing for cloneOnStart in the table of general configuration parameters.
A repository URI that enables use of one repository per app might be expressed as shown in the following command. For an app named "cook", this would locate the repository named cook-config:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/{application}-config" } }'
A repository URI that enables use of one repository per profile might be expressed as shown in the following command. For an app using the dev profile, this would locate a repository named config-dev:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/config-{profile}" } }'
For more information about using placeholders, see "Placeholders in Git URI" in the Spring Cloud Config documentation.
To configure a Config Server service instance with a repository URI that enables one repository per app, use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/{application}-config" } }'
To configure a Config Server service instance with a repository URI that enables one repository per profile, use the following command:
cf create-service p-config-server standard config-server -c '{"git": { "uri": "https://github.com/spring-cloud-services-samples/config-{profile}" } }'
You can configure a Config Server service instance to access configuration sources using an HTTP or HTTPS proxy. To do so, you must provide proxy settings in either of the git.proxy.http or git.proxy.https JSON objects. You can set the proxy host and port, the proxy username and password (if applicable), and a list of hosts which the Config Server should access outside of the proxy.
Note: Proxy settings must be set once in each git object, where applicable. If you are using a composite backend with multiple configuration sources that use the same proxy, you must provide that proxy's settings for each configuration source object.
Settings for an HTTP proxy are set in the git.proxy.http object. These might be set as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "proxy": { "http": { "host": "proxy.example.com", "port": "80" } } } }'
Settings for an HTTPS proxy are set in the git.proxy.https object. These might be set as shown in the following command:
cf create-service p-config-server standard config-server -c '{"git": { "proxy": { "https": { "host": "secure.example.com", "port": "443" } } } }'
Note: Some networks require that separate proxy servers are used for HTTP and HTTPS URLs. In such a case, you can set both the proxy.http and proxy.https objects.
The parameters used to configure HTTP or HTTPS proxy settings for the Config Server are listed below.
| Parameter | Function |
|---|---|
proxy.http |
A proxy object, containing HTTP proxy fields |
proxy.http.host |
The HTTP proxy host |
proxy.http.port |
The HTTP proxy port |
proxy.http.nonProxyHosts |
The hosts to access outside the HTTP proxy |
proxy.http.username |
The username to use with an authenticated HTTP proxy |
proxy.http.password |
The password to use with an authenticated HTTP proxy |
proxy.https |
A proxy object, containing HTTPS proxy fields |
proxy.https.host |
The HTTPS proxy host |
proxy.https.port |
The HTTPS proxy port |
proxy.https.nonProxyHosts |
The hosts to access outside the HTTPS proxy (if proxy.http.nonProxyHosts is also provided, http.nonProxyHosts will be used instead of https.nonProxyHosts) |
proxy.https.username |
The username to use with an authenticated HTTPS proxy (if proxy.http.username is also provided, http.username will be used instead of https.username) |
proxy.https.password |
The password to use with an authenticated HTTPS proxy (if proxy.http.password is also provided, http.password will be used instead of https.password) |
To configure a Config Server service instance that uses an HTTP proxy to access configuration sources, use the following command:
cf create-service p-config-server standard config-server -c '{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config", "proxy": { "http": { "host": "proxy.example.com", "port": "80" } } } }'
To configure a Config Server service instance that uses an authenticated HTTPS proxy to access configuration sources, specifying that example.com should be accessed outside of the proxy, use the following command:
cf create-service p-config-server standard config-server -c '{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config", "proxy": { "https": { "host": "secure.example.com", "port": "443", "username": "jim", "password": "wright62", "nonProxyHosts": "example.com" } } } }'
