LATEST VERSION: 1.4 - CHANGELOG
Spring Cloud Services v1.4

Declarative Composite Backends

Page last updated:

Overview

The Spring Cloud Services Config Server provides the ability to serve configuration properties from a composite of multiple backends, such as from multiple GitHub repositories and a HashiCorp Vault server. This feature builds upon the Composite Environment Repositories feature from the Dalston release of the Spring Cloud Config Server by enabling declaration of multiple Git servers together with (optionally) a Vault server to compose a unified configuration source.

Note: The Spring Cloud Services Config Server cannot serve configuration properties from multiple Vault servers. A composite backend can contain only a single Vault server.

Property Source Precedence

When a Config Server is composed with multiple backends, a request from a client application retrieves properties found in any applicable backend within the composite. The composite backends are always searched in the order in which they are configured, and the Config Server assembles configuration properties beginning at the first backend in the composite by order.

For example, given the following configuration:

  • Property dbhost=foo is defined in the first backend
  • Property dbhost=bar is defined in the second backend
  • Property port=4321 is defined in the third backend

The client will resolve property dbhost to foo, from the first backend, as that backend has precedence over the second. Property port will be resolved to 4321, as it is only defined in the third backend.

Fail-Fast Behavior

If the Config Server encounters an error when retrieving properties from any one of the backends, the client application’s request fails. The Config Server’s composite configuration sources will only be available once all backends are available.

Use of Labels

Within the composite, all repositories or servers must contain the same labels—branches or tags in a Git repository, or paths in a Vault server. A label in a Config Server configuration source corresponds to a Spring application profile on a client application. If a client application makes a request for configuration for a given profile and one of the composite’s backends does not have a corresponding branch, tag, or path, the request fails and no configuration is returned.

See below for information about configuring a Config Server service instance to use a composite backend for configuration sources.

General Configuration

Parameters used to configure configuration sources are part of a JSON array called composite. The composite array can contain one or more git JSON objects, each of which contains settings for a Git repository, and a vault object, which contains settings for a Vault server. For information about configuring a Git configuration source, see the Configuring with Git topic. For information about configuring a Vault configuration source, see the Configuring with Vault topic.

Configuration properties from individual backends are given precedence based on the order in which they are provided to the Config Server. A backend specified later in the composite array is searched after backends specified earlier in the array.

To configure a Config Server service instance to use a composite backend comprising two Git repositories and a Vault server, you might use the following JSON object:

'{
    "composite": [
        {
            "git": {
                "uri": "https://github.com/spring-cloud-services-samples/cook-config"
            }
        },
        {
            "git": {
                "uri": "https://github.com/spring-cloud-samples/config-repo"
            }
        },
        {
            "vault": {
                "host": "127.0.0.1",
                "port": 8200,
                "scheme": "https",
                "backend": "secret",
                "defaultKey": "application",
                "profileSeparator": ","
            }
        }
    ]
}'

In this example, configuration properties found in the Vault server are added to the response only if they are not found in either of the Git repositories specified before the Vault server.

To configure a Config Server service instance to use a composite backend comprising a Vault server and a Git repository, use the following JSON object:

'{
    "composite": [
        {
            "vault": {
                "host": "127.0.0.1",
                "port": 8200,
                "scheme": "https",
                "backend": "secret",
                "defaultKey": "application",
                "profileSeparator": ","
            }
        },
        {
            "git": {
                "uri": "https://github.com/spring-cloud-services-samples/cook-config"
            }
        }
    ]
}'

In this example, the response consists of configuration properties found in the Vault server, plus any properties found only in the Git repository.

For information about using an application to access configuration values served by a Config Server service instance, see the Writing Client Applications topic.

Proxy Servers for Composite Backends

Proxy server configuration must be defined for each item in the composite set. For example:

'{
    "composite": [
        {
            "git": {
                "uri": "https://github.com/spring-cloud-services-samples/cook-config",
                "proxy": {
                   "http": {
                       "host": "http://proxy1.com",
                       "port": 3218
                   }
                }
            }
        },
        {
            "git": {
                "uri": "https://github.com/spring-cloud-samples/config-repo",
                "proxy": {
                   "http": {
                       "host": "http://proxy2.com",
                       "port": 3218
                   }
                }
            }
        },
        {
            "vault": {
                "host": "127.0.0.1",
                "proxy": {
                   "http": {
                       "host": "http://proxy1.com",
                       "port": 3218
                   }
                }

            }
        }
    ]
}'

For detailed information about configuring proxy support, see the HTTP(S) Proxy Repository Access section of the Configuring with Git topic and the HTTP(S) Proxy Repository Access section of the Configuring with Vault topic.

Create a pull request or raise an issue on the source for this page in GitHub