Managing Service Instances with the cf CLI

Page last updated:

This topic describes lifecycle operations for service instances, including creating, updating, and deleting. For an overview of services, and documentation about other service management operations, see the Using Services topic. If you are interested in building services for Cloud Foundry and making them available to end users, see the Custom Services documentation.

To run the commands in this topic, you must first install the Cloud Foundry Command Line Interface (cf CLI). See the Cloud Foundry Command Line Interface topics for more information.

List Marketplace Services

After targeting and logging into Cloud Foundry, run the cf marketplace cf CLI command to view the services available to your targeted organization. Available services may differ between organizations and between Cloud Foundry marketplaces.

$ cf marketplace
Getting services from marketplace in org my-org / space test as user@example.com...
OK

service               plans                  description
p-mysql               100mb, 1gb             A DBaaS
p-riakcs              developer              An S3-compatible object store

Creating Service Instances

You can create a service instance with the following command: cf create-service SERVICE PLAN SERVICE_INSTANCE

Use the information in the list below to replace SERVICE, PLAN, and SERVICE_INSTANCE with appropriate values. * SERVICE: The name of the service you want to create an instance of. * PLAN: The name of a plan that meets your needs. Service providers use plans to offer varying levels of resources or features for the same service. * SERVICE_INSTANCE: The name you provide for your service instance. You use this name to refer to your service instance with other commands. Service instance names can include alpha-numeric characters, hyphens, and underscores, and you can rename the service instance at any time.

$ cf create-service rabbitmq small-plan my-rabbitmq

Creating service my-rabbitmq in org console / space development as user@example.com...
OK

User Provided Service Instances provide a way for developers to bind applications with services that are not available in their Cloud Foundry marketplace. For more information, see the User Provided Service Instances topic.

Arbitrary Parameters

Arbitrary parameters require cf CLI v6.12.1+

Some services support providing additional configuration parameters with the provision request. Pass these parameters in a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file. For a list of supported configuration parameters, see the documentation for the particular service offering.

Example providing service-specific configuration parameters in-line:

$ cf create-service my-db-service small-plan my-db -c '{"storage_gb":4}'

Creating service my-db in org console / space development as user@example.com...
OK

Example providing service-specific configuration parameters in a file:

$ cf create-service my-db-service small-plan my-db -c /tmp/config.json

Creating service my-db in org console / space development as user@example.com...
OK

Instance Tags

Instance tags require cf CLI v6.12.1+

Some services provide a list of tags that Cloud Foundry delivers in the VCAP_SERVICES Environment Variable. These tags provide developers with a more generic way for applications to parse VCAP_SERVICES for credentials. Developers may provide their own tags when creating a service instance by including the -t flag followed by a comma-separated list of tags.

Example providing a comma-separated list of tags:

$ cf create-service my-db-service small-plan my-db -t "prod, workers"

Creating service my-db in org console / space development as user@example.com...
OK

List Service Instances

Run the cf services command to list the service instances in your targeted space. The output from running this command includes any bound apps and the state of the last requested operation for the service instance.

$ cf services
Getting services in org my-org / space test as user@example.com...
OK

name       service         plan        bound apps              last operation
mybucket   p-riakcs        developer   myapp                   create succeeded
mydb       p-mysql         100mb                               create succeeded

Get Details for a Particular Service Instance

Details include dashboard urls, if applicable, and operation start and last updated timestamps.

$ cf service mydb

Service instance: mydb
Service: p-mysql
Plan: 100mb
Description: MySQL databases on demand
Documentation url:
Dashboard: https://p-mysql.example.com/manage/instances/abcd-ef12-3456

Last Operation
Status: create succeeded
Message:
Started: 2015-05-08T22:59:07Z
Updated: 2015-05-18T22:01:26Z

Bind a Service Instance

Depending on the service, you can bound service instances to applications and/or routes.

Not all services support binding, as some services deliver value to users directly without integration with Cloud Foundry, such as SaaS applications.

Bind a Service Instance to an Application

Depending on the service, binding a service instance to your application may deliver credentials for the service instance to the application. See the Delivering Service Credentials to an Application topic for more information. Binding a service instance to an application may also trigger application logs to be streamed to the service instance. For more information, see Streaming Application Logs to Log Management Services.

$ cf bind-service my-app mydb
Binding service mydb to my-app in org my-org / space test as user@example.com...
OK
TIP: Use 'cf push' to ensure your env variable changes take effect

$ cf restart my-app

Note: You must restart or in some cases re-push your application for changes to be applied to the VCAP_SERVICES environment variable and for the application to recognize these changes.

Binding with Application Manifest

As an alternative to binding a service instance to an application after pushing an application, you can use the application manifest to bind the service instance during push. As of cf CLI v6.12.1, Arbitrary Parameters are not supported in application manifests. Using the manifest to bind service instances to routes is also not supported.

The following excerpt from an application manifest binds a service instance called test-mysql-01 to the application on push.

services:
 - test-mysql-01

The following excerpt from the cf push command and response demonstrates that the cf CLI reads the manifest and binds the service instance to an app called test-msg-app.

$ cf push
Using manifest file /Users/Bob/test-apps/test-msg-app/manifest.yml

...

Binding service test-mysql-01 to test-msg-app in org My-Org / space development as user@example.com
OK

For more information about application manifests, see Deploying with Application Manifests.

Bind a Service Instance to a Route

Binding a service instance to a route will cause application requests and responses to be proxied through the service instance, where it may be used to transform or intermediate requests. For more information, see Manage Application Requests with Route Services.

$ cf bind-route-service shared-domain.example.com --hostname my-app my-service-instance
Binding route my-app.shared-domain.example.com to service instance my-service-instance in org my-org / space test as user@example.com...
OK

Restaging your application is not required.

Arbitrary Parameters

Arbitrary parameters require cf CLI v6.12.1+

Some services support additional configuration parameters with the bind request. These parameters are passed in a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file. For a list of supported configuration parameters, see documentation for the particular service offering.

$ cf bind-service rails-sample my-db -c '{"role":"read-only"}'

Binding service my-db to app rails-sample in org console / space development as user@example.com...
OK
$ cf bind-service rails-sample my-db -c /tmp/config.json

Binding service my-db to app rails-sample in org console / space development as user@example.com... OK

Unbind a Service Instance

Unbind a Service Instance from an Application

Unbinding a service instance from an application removes the credentials created for your application from the VCAP_SERVICES environment variable.

$ cf unbind-service my-app mydb
Unbinding app my-app from service mydb in org my-org / space test as user@example.com...
OK

Note: You must restart or in some cases re-push your application for changes to be applied to the VCAP_SERVICES environment variable and for the application to recognize these changes.

Unbind a Service Instance from a Route

Unbinding a service instance from a route will result in requests and responses no longer being proxied through the service instance. For more information, see Manage Application Requests with Route Services.

Note: If your bound service instance is providing security features, like authorization, unbinding the service instance may leave your application vulnerable.

$ cf unbind-route-service shared-domain.example.com --hostname my-app my-service-instance

Unbinding may leave apps mapped to route my-app.shared-domain.example.com vulnerable; e.g. if service instance my-service-instance provides authentication. Do you want to proceed?> y

Unbinding route my-app.shared-domain.example.com from service instance my-service-instance n org my-org / space test as user@example.com...
OK

Restaging your application is not required.

Rename a Service Instance

You can change the name given to a service instance. Keep in mind that upon restarting any bound applications, the name of the instance will change in the VCAP_SERVICES environment variable. If your application depends on the instance name for discovering credentials, changing the name could break your application’s use of the service instance.

$ cf rename-service mydb mydb1
Renaming service mydb to mydb1 in org my-org / space test as user@example.com...
OK

Update a Service Instance

Upgrade/Downgrade Service Plan

Changing a plan requires cf CLI v6.7+ and cf-release v192+

By updating the service plan for an instance, users can effectively upgrade and downgrade their service instance to other service plans. Though the platform and CLI now support this feature, services must expressly implement support for it so not all services will. Further, a service might support updating between some plans but not others. For instance, a service might support updating a plan where only a logical change is required, but not where data migration is necessary. In either case, users can expect to see a meaningful error when plan update is not supported.

$ cf update-service mydb -p new-plan
Updating service instance mydb as user@example.com...
OK

Arbitrary Parameters

Arbitrary parameters require cf CLI v6.12.1+

Some services support additional configuration parameters with the update request. These parameters are passed in a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file. For a list of supported configuration parameters, see documentation for the particular service offering.

$ cf update-service mydb -c '{"storage_gb":4}'

Updating service instance mydb as me@example.com...
$ cf update-service mydb -c /tmp/config.json

Updating service instance mydb as user@example.com...

Instance Tags

Instance tags require cf CLI v6.12.1+

Some services provide a list of tags that Cloud Foundry delivers in the VCAP_SERVICES Environment Variable. These tags provide developers with a more generic way for applications to parse VCAP_SERVICES for credentials. Developers may provide their own tags when creating a service instance by including a comma-separated list of tags with the -t flag.

$ cf update-service my-db -t "staging, web"

Updating service my-db in org console / space development as user@example.com...
OK

Delete a Service Instance

Deleting a service instance deprovisions the service instance and deletes all data associated with the service instance.

$ cf delete-service mydb

Are you sure you want to delete the service mydb ? y
Deleting service mydb in org my-org / space test as user@example.com...
OK
View the source for this page in GitHub