Creating an Instance

Page last updated:

You can create a Config Server service instance using either the Cloud Foundry Command Line Interface tool (cf CLI) or the PWS Apps Manager (you cannot configure a service instance using Apps Manager).

Using the cf CLI

Begin by targeting the correct org and space.

$ 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

You can view plan details for the Config Server product using cf marketplace -s.

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

service                       plans          description
p-circuit-breaker-dashboard   standard       Circuit Breaker Dashboard for Spring Cloud Applications
p-config-server               standard       Config Server for Spring Cloud Applications
p-service-registry            standard       Service Registry for Spring Cloud Applications

TIP:  Use 'cf marketplace -s SERVICE' to view descriptions of individual plans of a given service.

$ cf marketplace -s p-config-server
Getting service plan information for service p-config-server as username@example.com...
OK

service plan   description     free or paid
standard       Standard Plan   free

Create the service instance using cf create-service, using the -c flag to provide a JSON object that specifies the 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 create an instance, specifying settings for the configuration sources, that the default configuration source Git repository should be cloned when the Config Server starts up, and that three nodes should be provisioned:

$ cf create-service -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" } } }, "count": 3 }' p-config-server standard config-server
Creating service instance config-server in org myorg / space development as username@example.com...
OK

Create 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 service instance is ready, the cf service command will give a status of create 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-service-broker.cfapps.io/dashboard/p-config-server/e5eb4089-8cb8-4bba-a08b-10ba2c7d18e1

Last Operation
Status: create succeeded
Message: 
Started: 2016-09-09T16:51:15Z
Updated: 2016-09-09T16:53:19Z

Important: The cf service and cf services commands may report a create 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 created and have a create succeeded status.

If the service instance does not appear to be functioning correctly, you can visit its dashboard to double-check that the provided settings are valid and accurate. See the Using the Dashboard 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 create a Config Server service instance that uses SSH to access a configuration source, allowing for host key verification, run:

$ cf create-service p-config-server standard 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 create a Config Server service instance that uses SSH to access a configuration source, without host key verification, run:

$ cf create-service p-config-server standard 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 create a Config Server service instance with a default repository and a repository specific to an application named “cook”, run:

$ cf create-service p-config-server standard 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 create a Config Server service instance with a default repository and a repository specific to applications using the dev profile, run:

$ cf create-service p-config-server standard 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 create a Config Server service instance with a repository URI that enables one repository per application, run:

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

To create a Config Server service instance with a repository URI that enables one repository per profile, run:

$ cf create-service p-config-server standard 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 create a Config Server service instance that uses an HTTP proxy to access configuration sources, run:

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

To create 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, run:

$ cf create-service p-config-server standard 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" } } } }'

Using Apps Manager

Note: If you create a Config Server service instance using Apps Manager, you will need to use the cf CLI to update the service instance and provide settings (including one or more configuration sources) before the instance will be usable. For information on updating a Config Server service instance, see the Updating an Instance topic.

Log into Apps Manager as a Space Developer. In the Marketplace, select Config Server.

Marketplace

Select the desired plan for the new service instance.

Select plan

Provide a name for the service instance (for example, “config-server”). Click the Add button.

Instance name

In the Services section of the space in Apps Manager, click the listing for the new service instance.

Service successfully added

Click the Manage link.

5 manage link

It may take a few minutes to provision the service instance; while it is being provisioned, you will see a “The service instance is initializing” message. When the instance is ready, its dashboard will load automatically.

Dashboard new

The dashboard displays the current settings for the Config Server service instance. Before you can use this service instance, you must update it using the cf CLI to supply it with a configuration source. For information about updating a service instance to configure instance settings, see the Updating an Instance topic.

Was this helpful?
What can we do to improve?
View the source for this page in GitHub