Configuring with Git

Page last updated:

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

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 The URI (http://, https://, or ssh://) of a Git repository. Required
label The default “label” used if a request is received without a label. Default value: master
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 when a client requests configuration
skipSslValidation For a https:// URI, whether to skip validation of the SSL certificate on the repository’s server. Valid values: true, false
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: true, 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 }'

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

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

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

Storing Configuration Properties

When using a Git configuration source, you can store properties in YAML or Java .properties files. Configuration properties can be applicable to all apps that use the Config Server, specific to an app, or specific to a Spring application profile.

Global Configuration

You can store configuration properties so that they are served to all apps which use the Config Server. In the configuration repository, a file named application.yml or application.properties contains configuration which will be served to all apps that access the Config Server.

Using YAML

An example of a global application.yml file:

message: Hi there!

Using a Properties File

An example of a global application.properties file:

message=Hi there!

Application-Specific Configuration

You can store configuration properties so that they are served only to a specific app. In the configuration repository, a file named [APP-NAME].yml or [APP-NAME].properties, where [APP-NAME] is the name of an app, contains configuration which will be served only to the APP-NAME app.

Using YAML

An example of an app-specific cook.yml file:

server:
  port: 80

cook:
  special: Fried Salamander

Using a Properties File

An example of an app-specific cook.properties file:

server.port=80

cook.special=Fried Salamander

Profile-Specific Configuration

You can store configuration properties so that they are served only to apps which have activated a specific Spring application profile. In the configuration repository, a file named [APP-NAME]-[PROFILE-NAME].yml or [APP-NAME]-[PROFILE-NAME].properties, where [APP-NAME] is the name of an app and [PROFILE-NAME] is the name of an application profile, contains configuration which will be served only to the APP-NAME app running with the [PROFILE-NAME] profile activated. Within a YAML file named [APP-NAME].yml, a document that begins by setting the spring.profiles property contains configuration which will be served only to the APP-NAME app running with the profile specified by the spring.profiles property.

Using YAML

An example of a profile-specific cook-dev.yml file:

server:
  port: 8080

cook:
  special: Birdfeather Tea

An example of a profile-specific YAML document within a cook.yml file:

---
spring:
  profiles: dev

server:
  port: 8080

cook:
  special: Birdfeather Tea

Using a Properties File

An example of a profile-specific cook-dev.properties file:

server.port=8080

cook.special=Birdfeather Tea

Plain Text Configuration

You can store configuration in files of other file types. The Spring Cloud Services Config Client library includes a PlainTextConfigClient that can be used to retrieve the contents of a plain text file as a Spring Resource.

For more information about using the Config Server to serve plain text files to a client app, see the Use Plain Text Configuration Files section of Writing Client Applications.