Configuring Spring Cloud Services with Git

Spring Cloud Services 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 the Spring Cloud Config Git backend, see the documentation.

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.

General configuration

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`	A Git repository URI, in one of the following formats: `http://` `https://` `ssh://` (only supported in Spring Cloud Services v3.1.16 and later) `[email protected]` Required
`label`	The default "label" used if a request is received without a label. Default value: `main`
`searchPaths`	A pattern used to search for configuration-containing subdirectories in the repository
`username`	The username used to access the repository (if protected by HTTP Basic authentication)
`password`	The password used to access the repository (if protected by HTTP Basic authentication)
`refreshRate`	Interval, in seconds, between refreshes of the Config Server's repository clone from Mirror Service when a client requests configuration
`periodic`	Added in Spring Cloud Services v3.1.2. Whether the Config Server should periodically update its mirror of the Git repository with any changes from the external repository. If set to `true`, the Config Server will update the mirror every 5 minutes. Valid values: `true`, `false`. Default: `false`
`timeout`	Added in Spring Cloud Services v3.2.0. Number of seconds that the Config Server will wait to acquire a connection to the mirrored repository. Default: `5`
`skipSslValidation`	For a `https://` URI, whether to skip validation of the SSL certificate on the repository's server. Valid values: `true`, `false`. Default: `false`
`update-git-repos`	Used only with `cf update-service`; causes the mirror service to update a Config Server's Git repository mirrors. Valid values: `true`

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

To refresh a Config Server's Git repository mirrors and retrieve new configuration property values, run the cf update-service command, passing the update-git-repos flag with value true:

cf update-service my-config-server -c '{"update-git-repos": true }'

Encryption and encrypted values

Support for decrypting encrypted configuration was added in Spring Cloud Services v3.1.6. Support for the /encrypt endpoint was added in v3.1.7.

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.

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)" https://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 Encrypted Configuration.

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

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.

SSH repository access

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 a supported 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.

In Spring Cloud Services v3.1.15 and earlier, Config Server does not support ssh:// URIs. Config Server support for ssh:// URIs was added in Spring Cloud Services v3.1.16.

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://[email protected]/spring-cloud-services-samples/cook.git"} }'

An equivalent Secure Copy Protocol (SCP) style URI might be specified as shown in the following command:

cf create-service p.config-server standard config-server -c '{"git": { "uri": "[email protected]: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": "[email protected]/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": "[email protected]/spring-cloud-services-samples/cook.git", "privateKey": "-----BEGIN EXAMPLE RSA PRIVATE KEY-----\nMIIJKQIB..."} }'

HTTP(S) proxy repository access

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.

If you are using a composite backend with multiple Git repositories that are accessed using the same proxy, you must provide the proxy's settings for each git 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" } } } }'

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.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.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" } } } }'