Configuring with Git

Overview

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

General Configuration

Parameters used to configure configuration sources are part of a JSON object called git, as in {"git": { "uri": "http://example.com/config" } }. For more information on the purposes of these fields, see the The Config Server section of the Background Information topic.

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 (e.g., if the spring.cloud.config.label property is not set in a client application)
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)
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 shown in the following JSON:

'{"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 JSON:

'{"git": { "uri": "https://github.com/myorg/config-repo", "label": "v1.1" } }'

Within a client application, 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.

Encryption and Encrypted Values

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 applications. The Config Server has an /encrypt endpoint, which can be used to encrypt property values.

To use these features in a client application, 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 the Managing Custom Buildpacks topic to add this buildpack to Pivotal Cloud Foundry. Be sure that it has the lowest position of all enabled Java buildpacks.

If you wish to use public-key (or asymmetric) encryption, you must 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

When the Config Server has been configured to encrypt values, you can make a POST request to the /encrypt endpoint, including the property value in the request. To do this, you will need the binding credentials of an application that is bound to the service instance.

Note: The following procedure uses the jq command-line JSON processing tool.

Run cf env, giving the name of an application that is bound to the service instance:

$ cf services
Getting services in org myorg / space development as user@example.com...
OK

name             service           plan        bound apps   last operation
config-server    p-config-server   standard    cook         create succeeded

$ cf env cook
Getting env variables for app cook in org myorg / space development as user@example.com...
OK

System-Provided:
{
 "VCAP_SERVICES": {
  "p-config-server": [
   {
    "credentials": {
     "access_token_uri": "https://p-spring-cloud-services.uaa.run.pivotal.io/oauth/token",
     "client_id": "p-config-server-876cd13b-1564-4a9a-9d44-c7c8a6257b73",
     "client_secret": "rU7dMUw6bQjR",
     "uri": "https://config-629f5587-41f5-4257-a521-3582b0d4ca7b.cfapps.io"
    },
[...]

Then run the following Bash script, which fetches a token and uses the token to access an endpoint on a service instance backing application:


TOKEN=$(curl -k ACCESS_TOKEN_URI -u CLIENT_ID:CLIENT_SECRET -d
grant_type=client_credentials | jq -r .access_token); curl -k -H
"Authorization: bearer $TOKEN" -H "Accept: application/json"
URI/encrypt -d 'VALUE'

In this script, replace the following placeholders using values from the cf env command above:

  • ACCESS_TOKEN_URI with the value of credentials.access_token_uri
  • CLIENT_ID with the value of credentials.client_id
  • CLIENT_SECRET with the value of credentials.client_secret
  • URI with the value of credentials.uri
  • VALUE with the 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 the Configuration Properties topic.

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 JSON object:

'{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config.git" }, "encrypt": { "key": "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 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 JSON:

'{"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 JSON:

'{"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

To configure a Config Server service instance that uses SSH to access a configuration source, allowing for host key verification, use the following JSON object:

'{"git": { "uri": "ssh://git@github.com/spring-cloud-services-samples/cook.git", "hostKey": "AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+...", "hostKeyAlgorithm": "ssh-rsa", "privateKey": "-----BEGIN 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 JSON object:

'{"git": { "uri": "ssh://git@github.com/spring-cloud-services-samples/cook.git", "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIJKQIB..."} }'

Host and private keys are masked in the Config Server dashboard.

Multiple Repositories

You can configure a Config Server service instance to use multiple configuration sources, which will be used only for specific applications or for applications 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 JSON, the name is “cookie”:

'{ "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 application 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 JSON, the pattern is co*/dev* (matching any application whose name begins with co and which is using a profile whose name begins with dev), and the default pattern would be cookie:

'{"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 applications 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 (e.g., if the spring.cloud.config.label property is not set in a client application)
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".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 JSON:

'{"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 JSON:

'{"git": { "repos": { "cookie": { "uri": "https://github.com/myorg/config-repo", "label": "v1.1" } } } }'

Within a client application, 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 and a repository specific to an application named “cook”, use the following JSON object:

'{"git": { "uri": "https://github.com/spring-cloud-services-samples/fortune-teller", "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 applications using the dev profile, use the following JSON object:

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

Placeholders in Repository URIs

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 application
  • {profile}: a profile listed in the spring.profiles.active property on an application

You can use these placeholders to (for example) set a single URI which maps one repository each to multiple applications 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 application might be expressed as shown in the following JSON. For an application named “cook”, this would locate the repository named cook-config:

'{"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 JSON. For an application using the dev profile, this would locate a repository named config-dev:

'{"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 application, use the following JSON object:

'{"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 JSON object:

'{"git": { "uri": "https://github.com/spring-cloud-services-samples/config-{profile}"  } }'

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.

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 JSON:

'{"git": { "proxy": { "http": { "host": "proxy.wise.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 JSON:

'{"git": { "proxy": { "https": { "host": "secure.wise.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 JSON object:

'{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config", "proxy": { "http": { "host": "proxy.wise.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 JSON object:

'{"git": {"uri": "https://github.com/spring-cloud-services-samples/cook-config", "proxy": { "https": { "host": "secure.wise.com", "port": "443", "username": "jim", "password": "wright62", "nonProxyHosts": "example.com" } } } }'
Create a pull request or raise an issue on the source for this page in GitHub