Managing Service Instances with the cf CLI

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 Services Overview. 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                       broker
p-mysql            100mb, 1gb          A DBaaS                           mysql-broker
p-riakcs           developer           An S3-compatible object store     object-store-broker

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 apps with services that are not available in their Cloud Foundry marketplace. For more information, see the User Provided Service Instances topic.

Note: When multiple brokers provide two or more services with the same name, you must specify the broker by including the -b BROKER flag in the cf create-service command.

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 apps 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      broker                upgrade available
mybucket   p-riakcs      developer   myapp        create succeeded    object-store-broker   no
mydb       p-mysql       100mb                    create succeeded    mysql-broker          yes

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
service broker:         mysql-broker

This service is not currently shared.

Showing status of last operation from service mydb...

status:    create succeeded
message:
started:   2019-02-13T12:02:19Z
updated:   2019-02-13T12:02:19Z

There are no bound apps for this service.

Bind a Service Instance

Depending on the service, you can bind service instances to apps and/or routes.

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

Bind a Service Instance to an App

Depending on the service, binding a service instance to your app may deliver credentials for the service instance to the app. See the Delivering Service Credentials to an App topic for more information. Binding a service instance to an app may also trigger app logs to be streamed to the service instance. For more information, see Streaming App 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 app for changes to be applied to the VCAP_SERVICES environment variable and for the app to recognize these changes.

Binding with App Manifest

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

The following excerpt from an app manifest binds a service instance called test-mysql-01 to the app 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 app manifests, see Deploying with App Manifests.

Bind a Service Instance to a Route

Binding a service instance to a route will cause app 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 App 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 app 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 App

Unbinding a service instance from an app removes the credentials created for your app 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 app for changes to be applied to the VCAP_SERVICES environment variable and for the app 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 App Requests with Route Services.

Note: If your bound service instance is providing security features, like authorization, unbinding the service instance may leave your app 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 app 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 apps, the name of the instance will change in the VCAP_SERVICES environment variable. If your app depends on the instance name for discovering credentials, changing the name could break your app’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

Changing a Service Plan

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

By updating the service plan for an instance, users can change 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 apps 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

Upgrade a Service Instance

Upgrading a Service Instance requires cf CLI v6.46.0+ and CAPI release 1.83.0+

Some service brokers support upgrading service instances to the latest version of a service plan. For example, a broker may want to provide a way for users of the service to upgrade the underlying operating system that their service instances run on.

To upgrade your service instances, do the following:

  1. Confirm that an upgrade is available by running cf services and reviewing the upgrade available column:

    $ cf services
    Getting services in org acceptance / space dev as admin...
    
    name      service   plan     bound apps   last operation     broker         upgrade available
    mydb      p-mysql   small                 create succeeded   mysql-broker   yes
    otherdb   p-mysql   medium                create succeeded   mysql-broker   no
    
  2. Upgrade the service instance using the --upgrade flag:

    $ cf update-service mydb --upgrade
    You are about to update mydb.
    Warning: This operation may be long running and will block further operations on the service until complete.
    Really update service mydb? [yN]: y
    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
Create a pull request or raise an issue on the source for this page in GitHub