Updating an Instance

Page last updated:

You can update settings on a Config Server service instance using the Cloud Foundry Command Line Interface tool (cf CLI). The cf update-service command can be given a -c flag with a JSON object containing parameters used to configure the service instance.

To update a Config Server service instance’s settings, target the org and space of the service instance:

$ cf target -o myorg -s development

API endpoint:   https://api.run.pivotal.io (API version: 2.61.0)
User:           username@example.com
Org:            myorg
Space:          development

Then run cf update-service SERVICE_NAME -c '{ "PARAMETER": "VALUE" }', where SERVICE_NAME is the name of the service instance, PARAMETER is a supported parameter, and VALUE is the value for the parameter. For information about supported parameters, see the next section.

Configuration Parameters

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

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

Other parameters accepted for the Config Server are listed below.

Parameter Function Example
count The number of nodes to provision: 1 by default, more for running in high-availability mode '{"count": 3}'
upgrade Whether to upgrade the instance '{"upgrade": true}'

To update a service instance, setting the configuration sources and specifying that the default configuration source Git repository should be cloned when the Config Server starts up, run:

$ cf update-service config-server -c '{"git": { "uri": "https://github.com/spring-cloud-samples/config-repo", "cloneOnStart": "true", "repos": { "cook": { "pattern": "cook*", "uri": "https://github.com/spring-cloud-samples/cook-config" } } } }'
Updating service instance config-server as username@example.com...
OK

Update in progress. Use 'cf services' or 'cf service config-server' to check operation status.

To update a service instance and set the count of instances for running in high-availability mode, run:

$ cf update-service config-server -c '{"count": 3}'
Updating service instance config-server as username@example.com...
OK

Update in progress. Use 'cf services' or 'cf service config-server' to check operation status.

As the command output suggests, you can use the cf services or cf service commands to check the status of the service instance. When the update is complete, the cf service command will give a status of update succeeded:

$ cf service config-server

Service instance: config-server
Service: p-config-server
Bound apps:
Tags:
Plan: standard
Description: Config Server for Spring Cloud Applications
Documentation url: http://docs.pivotal.io/spring-cloud-services/
Dashboard: https://spring-cloud-broker.wise.com/dashboard/p-config-server/e2615a44-66f5-4fda-9ddc-079af1db9ae4

Last Operation
Status: update succeeded
Message:
Started: 2016-06-24T21:11:53Z
Updated: 2016-06-24T21:13:59Z

Important: The cf service and cf services commands may report an update succeeded status even if the Config Server cannot initialize using the provided settings. For example, given an invalid URI for a configuration source, the service instance may still be restarted and have an update succeeded status.

If the service instance does not appear to be functioning correctly after an update, you can visit its dashboard to double-check that the provided settings are valid and accurate. See the Using the Dashboard topic.

The service instance is now updated and ready to be used. For information about using an application to access configuration values served by a Config Server service instance, see the Writing Client Applications topic.

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-samples/cook.git"} }'

An equivalent SCP-style URI might be specified as shown in the following JSON:

'{"git": { "uri": "git@github.com:spring-cloud-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 corresponding to privateKey (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, with all newline characters replaced by \n

To update a Config Server service instance to use SSH to access a configuration source, allowing for host key verification, run:

$ cf update-service config-server -c '{"git": { "uri": "ssh://git@github.com/spring-cloud-samples/cook.git", "hostKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC7+mgZfOyxx6MX/yG+d9R2ogcm76...", "hostKeyAlgorithm": "ssh-rsa", "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIJKQIB..."} }'

To update a Config Server service instance to use SSH to access a configuration source, without host key verification, run:

$ cf update-service config-server -c '{"git": { "uri": "ssh://git@github.com/spring-cloud-samples/cook.git", "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIJKQIB..."} }'

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

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

To update a Config Server service instance to have a default repository and a repository specific to an application named “cook”, run:

$ cf update-service config-server -c '{"git": { "uri": "https://github.com/spring-cloud-samples/fortune-teller", "searchPaths": "configuration", "repos": { "cookie": { "pattern": "cook", "uri": "https://github.com/spring-cloud-samples/cook-config" } } } }'

To update a Config Server service instance to have a default repository and a repository specific to applications using the dev profile, run:

$ cf update-service config-server -c '{"git": { "uri": "https://github.com/spring-cloud-samples/fortune-teller", "searchPaths": "configuration", "repos": { "cookie": { "pattern": "*/dev", "uri": "https://github.com/spring-cloud-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-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-samples/config-{profile}"  } }'

For more information about using placeholders, see “Placeholders in Git URI” in the Spring Cloud Config documentation.

To update a Config Server service instance to have a repository URI that enables one repository per application, run:

$ cf update-service config-server -c '{"git": { "uri": "https://github.com/spring-cloud-samples/{application}-config" } }'

To update a Config Server service instance to have a repository URI that enables one repository per profile, run:

$ cf update-service config-server -c '{"git": { "uri": "https://github.com/spring-cloud-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.

Important: Config Server does not support use of a private Git repository accessed via an authenticated proxy server as a configuration source at this time.

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

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 update a Config Server service instance to use an HTTP proxy to access configuration sources, run:

$ cf update-service config-server -c '{"git": {"uri": "https://github.com/spring-cloud-samples/cook-config", "proxy": { "http": { "host": "proxy.wise.com", "port": "80" } } } }'

To update a Config Server service instance to use an authenticated HTTPS proxy to access configuration sources, specifying that example.com should be accessed outside of the proxy, run:

$ cf update-service config-server -c '{"git": {"uri": "https://github.com/spring-cloud-samples/cook-config", "proxy": { "https": { "host": "secure.wise.com", "port": "443", "username": "jim", "password": "wright62", "nonProxyHosts": "example.com" } } } }'
Was this helpful?
What can we do to improve?
View the source for this page in GitHub