Managing service instances

Here you will find information about managing Spring Cloud Services Config Server service instances using the Cloud Foundry Command Line Interface (cf CLI). You can also manage Config Server service instances using VMware Tanzu Application Service for VMs Apps Manager.

Available parameters

General parameters accepted for the Config Server, passed to the cf create-service and cf update-service commands using the -c flag, are listed below. For information about the parameters used to configure a Git backend, see Configuring with Git. For information about the parameters used to configure a HashiCorp Vault backend, see Configuring with Vault.

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 service instance to the latest version. Valid values: `true`, `false`	`'{"upgrade": true}'`

App Security Groups (ASGs)

A Config Server service instance can use one or more App Security Groups (ASGs). You can use this to allow the service instance to connect to external apps or services (for example, an external HashiCorp Vault server). ASGs are applied to the space of the backing app for the service instance. You can configure the list of ASGs for the service instance by passing an application-security-groups parameter, a JSON array of ASG names, to cf create-service or cf update-service.

To create a Config Server service instance that uses an ASG called my-asg, you might run:

$ cf create-service p.config-server standard my-config-server -c '{ "application-security-groups": [ "my-asg" ] }'

Differences between Spring Cloud Services v3.0-v3.1 and earlier Config Server

Spring Cloud Services (SCS) v3.0 and later include a Config Server service offering called p.config-server. In SCS v2.1 and earlier, this service was called p-config-server. These service offerings are distinct and you cannot upgrade a p-config-server service instance to a p.config-server service instance. Instead, you must recreate p-config-server service instances (see Migrating Spring Cloud Services v2.x or 1.5 Service Instances).

Most parameters used to create or update a p-config-server service instance, including parameters used to configure a Git or HashiCorp Vault backend, can also be used to create or update a p.config-server service instance. The following parameters are exceptions which can be used with the p-config-server service (from SCS v2.1 and earlier) but cannot be used with the p.config-server service (from SCS v3.0 and later):

git.repos
composite.git (see Composite Backends for information about how to configure the composite backend in the SCS v3.x Config Server)
composite.vault (see Composite Backends for information about how to configure the composite backend in the SCS v3.x Config Server)

Creating an instance

Begin by targeting the correct org and space.

$ cf target -o myorg -s development

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

$ cf marketplace -s p.config-server
Getting service plan information for service p.config-server as user...
OK

service plan   description       free or paid
standard       A 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. To create an instance, specifying settings for a Git backend and that three nodes should be provisioned:

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

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 my-config-server
Showing info of service my-config-server in org myorg / space dev as user...

name:            my-config-server
service:         p.config-server
tags:
plan:            standard
[...]

Showing status of last operation from service my-config-server...

status:    create succeeded

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 Git backend, the service instance may still be created and have a create succeeded status.

Updating an instance

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

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. To update a service instance, configuring a Git backend, run:

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

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

$ cf update-service my-config-server -c '{"count": 3}'

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 my-config-server
Showing info of service my-config-server in org myorg / space dev as user...

name:            my-config-server
service:         p.config-server
tags:
plan:            standard
[...]

Showing status of last operation from service my-config-server...

status:    update succeeded

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 Git backend, the service instance may still be restarted and have an update succeeded status.

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

Upgrading an instance

You can upgrade a Config Server service instance to the latest version 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

Then run cf update-service SERVICE_NAME -c '{ "upgrade": true }', where SERVICE_NAME is the name of the service instance:

$ cf update-service my-config-server -c '{"upgrade": true}'

Migrating Spring Cloud Services v2.x or v1.5 service instances

The Config Server (p-config-server) service offering of the Spring Cloud Services v2.x or v1.5 tile cannot be upgraded to the Config Server (p.config-server) service offering of the Spring Cloud Services v3.1 tile. After installing Spring Cloud Services v3.1 alongside the older version of Spring Cloud Services, follow the below instructions to migrate an older Config Server service instance (SI).

Rename the existing SI (for example, adding a suffix -old to the original name):
```
$ cf rename-service my-config-server my-config-server-old
```
Create a new Spring Cloud Services v3.1 (p.config-server) SI, using the existing SI's original name and passing the existing SI's configuration using the -c flag:
```
$ cf create-service p.config-server standard my-config-server \
  -c '{"git": { "uri": "..." } }'
```
For each app bound to the existing SI, bind the app to the new SI:
```
$ cf bind-service myapp my-config-server
```
For each app bound to the existing SI, unbind the app from the existing SI:
```
$ cf unbind-service myapp my-config-server-old
```
For each app bound to the existing SI, restage the app:
```
$ cf restage myapp
```
For each app bound to the existing SI, ensure that the app is receiving configuration from the new SI.

Delete the existing SI:

$ cf delete-service my-config-server-old