Managing Service Instances with the CLI
Page last updated: September 8, 2015
This page assumes you are using cf CLI v6.
This topic describes lifecycle operations for service instances, including creating, updating, and deleting. For an overview of services, and documentation on other service management operations, see Using Services. If you are interested in building Services for Cloud Foundry and making them available to end users, see the Custom Services documentation.
List Marketplace Services
After targeting and logging into Cloud Foundry, you can view what services are available to your targeted organization with the command cf marketplace. Available services may differ between organizations and between Cloud Foundry marketplaces.
$ cf marketplace Getting services from marketplace in org my-org / space test as [email protected]... 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 command: cf create-service SERVICE PLAN SERVICE_INSTANCE
SERVICEThe service you choose.PLANService plans are a way for providers to offer varying levels of resources or features for the same service.SERVICE_INSTANCEA name you provide for your service instance. This is an alias for the instance which is meaningful to you. Use any series of alpha-numeric characters, hyphens (-), and underscores (_). You can rename the instance at any time.
$ cf create-service rabbitmq small-plan my_rabbitmq Creating service my_rabbitmq in org console / space development as [email protected]... OK
Note: User Provided Service Instances provide a way for developers to bind applications with services that are not available in their Cloud Foundry marketplace.
Arbitrary Parameters
Arbitrary parameters require cf CLI v6.12.1+
Some services support additional configuration parameters with the provision 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 create-service my-db-service small-plan my-db -c '{"storage_gb":4}'
Creating service my-db in org console / space development as [email protected]...
OK
$ cf create-service my-db-service small-plan my-db -c /tmp/config.json Creating service my-db in org console / space development as [email protected]... 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 a comma-separated list of tags with the -t flag.
$ cf create-service my-db-service small-plan my-db -t "prod, workers" Creating service my-db in org console / space development as [email protected]... OK
List Service Instances
You can list the service instances in your targeted space with the command cf services. The output includes any bound apps, along with the state of the last requested operation for the service instance.
$ cf services Getting services in org my-org / space test as [email protected]... 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/cc4eab9d-aff4-4beb-bc46-123f2a02dcf1 Last Operation Status: create succeeded Message: Started: 2015-05-08T22:59:07Z Updated: 2015-05-18T22:01:26Z
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 applications use of the service instance.
$ cf rename-service mydb mydb1 Renaming service mydb to mydb1 in org my-org / space test as [email protected]... 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 (e.g., 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 [email protected]... 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 [email protected]...
$ cf update-service mydb -c /tmp/config.json Updating service instance mydb as [email protected]...
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 [email protected]... 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 [email protected]... OK