Background Information

The Config Server

The Config Server serves configurations stored as either Java Properties files or YAML files. It reads files from a Git repository (a configuration source). Given the URI of a configuration source, the server will clone the repository and make its configurations available to client applications in JSON as a series of propertySources.

Configuration Sources

A configuration source contains one or more configuration files used by one or more applications. Each file applies to an application and can optionally apply to a specific profile and / or label.

The following is the structure of a Git repository which could be used as a configuration source.

master
------
https://github.com/myorg/configurations
|- myapp.yml
|- myapp-development.yml
|- myapp-production.yml

tag v1.0.0
----------
https://github.com/myorg/configurations
|- myapp.yml
|- myapp-development.yml
|- myapp-production.yml

In this example, the configuration source defines configurations for the myapp application. The Server will serve different properties for myapp depending on the values of {profile} and {label} in the request path. If the {profile} is neither development nor production, the server will return the properties in myapp.yml, or if the {profile} is production, the server will return the properties in both myapp-production.yml and myapp.yml.

{label} can be a Git commit hash as well as a tag or branch name. If the request contains a {label} of (e.g.) v1.0.0, the Server will serve properties from the v1.0.0 tag. If the request does not contain a {label}, the Server will serve properties from the default label. For Git repositories, the default label is master. You can reconfigure the default label (see the Configuring with Git topic).

Request Paths

Configuration requests use one of the following path formats:

/{application}/{profile}[/{label}]
/{application}-{profile}.yml
/{label}/{application}-{profile}.yml
/{application}-{profile}.properties
/{label}/{application}-{profile}.properties

A path includes an application, a profile, and optionally a label.

  • Application: The name of the application. In a Spring application, this will be derived from spring.application.name or spring.cloud.config.name.

  • Profile: The name of a profile, or a comma-separated list of profile names. The Config Server’s concept of a “profile” corresponds directly to that of the Spring Profile.

  • Label: The name of a version marker in the configuration source (the repository). This might be a branch name, a tag name, or a Git commit hash. The value given to the Config Server as a default label (the setting of git.label; see the table of the Config Server’s general configuration parameters) can be overridden in a client application by setting the spring.cloud.config.label property.

For information about using a Cloud Foundry application as a Config Server client, see the Configuration Clients section.

Configuration Clients

Config Server client applications can be written in any language. The interface for retrieving configuration is HTTP, and the endpoints are protected by OAuth 2.0.

To be given a base URI and client credentials for accessing a Config Server instance, a Cloud Foundry application needs to bind to the instance.

Bind an Application to a Service Instance

Click the service instance’s listing in Apps Manager. Under App Bindings, click Bind Apps.

Bind apps pws

Select an application and click Save.

Save binding pws

Alternatively, you can use the Cloud Foundry Command Line Interface tool (cf CLI). Run the command cf bind-service, specifying the application name and service instance name.

$ cf bind-service cook config-server
Binding service config-server to app cook in org myorg / space development as admin...
OK
TIP: Use 'cf restage cook' to ensure your env variable changes take effect

Then, as the command output suggests, run the command cf restage to restage the application before proceeding. (See the next section for information about the environment variable to which the command output refers.)

$ cf restage cook
Restaging app cook in org myorg / space development as admin...
...

Configuration Requests and Responses

After an application is bound to the service instance, the application’s VCAP_SERVICES environment variable will contain an entry under the key p-config-server. You can view the application’s environment variables using the cf CLI:

$ cf env cook
Getting env variables for app cook in org myorg / space development as admin...
OK

System-Provided:
{
 "VCAP_SERVICES": {
  "p-config-server": [
   {
    "credentials": {
     "access_token_uri": "https://p-spring-cloud-services.uaa.cf.wise.com/oauth/token",
     "client_id": "p-config-server-c4a56a3d-9507-4c2f-9cd1-f858dbf9e11c",
     "client_secret": "9aGx9K5Vx0cM",
     "uri": "https://config-51711835-4626-4823-b5a1-e5d91012f3f2.apps.wise.com"
    },
    "label": "p-config-server",
    "name": "config-server",
    "plan": "standard",
    "tags": [
     "configuration",
     "spring-cloud"
    ]
   }
  ]
 }
}

The following is an example of a response from the Config Server to a request using the path /cook/production (where the application is cook and the profile is production).


{
  "name":"cook",
  "profiles":[
    "production"
  ],
  "label":null,
  "version":"7b5da0d68d9237f2852f7ac6c5e7474fd433c3f3",
  "propertySources":[
    {
      "name":"https://github.com/spring-cloud-services-samples/cook-config/cook-production.properties",
      "source":
        {
          "cook.special":"Cake a la mode"
        }
    },
    {
      "name":"https://github.com/spring-cloud-services-samples/cook-config/cook.properties",
      "source":
        {
          "cook.special":"Pickled Cactus"
        }
    }
  ]
}

As shown in the above example, the Config Server may include multiple values for the same property in its response. In that case, the client application must decide how to interpret the response; the intent is that the first value in the list should take precedence over the others. Spring applications will do this for you automatically.

Spring Client Applications

A Spring application can use a Config Server as a property source. Properties from a Config Server will override those defined locally (e.g. via an application.yml in the classpath).

The application requests properties from the Config Server using a path such as /{application}/{profile}/[{label}] (see the Request Paths section). It will derive values for these three parameters from the following properties:

  • {application}: spring.cloud.config.name or spring.application.name.
  • {profile}: spring.cloud.config.env or spring.profiles.active.
  • {label}: spring.cloud.config.label if it is defined; otherwise, the Config Server’s default label.

These values can be specified in an application.yml or application.properties file on the classpath, via a system property (as in -Dspring.profiles.active=production), or (more commonly in Cloud Foundry) via an environment variable:

$ cf set-env cook SPRING_PROFILES_ACTIVE production

Given the above example response for the request path /cook/production, a Spring application would give the two Config Server property sources precedence over other property sources. This means that properties from https://github.com/myorg/configurations/cook-production.yml would have precedence over properties from https://github.com/myorg/configurations/cook.yml, which would have precedence over properties from the application’s other property sources (such as classpath:application.yml).

For a specific example of using a Spring application as a Config Server client, see the Writing Client Applications topic.

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