You can manage lifecycle operations for service instances using the Cloud Foundry CLI (cf CLI). This includes creating, updating, and deleting service instances. For documentation about other service management operations, see Services Overview. If you are interested in building services for Ops Manager and making them available to end users, see Services.
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, to view the services available to your targeted organization, run the cf CLI 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 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 [email protected]... 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 User Provided Service Instances.
Important 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 [email protected]...
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 [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 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 [email protected]... OK
List service instances
To list the service instances in your targeted space, run:
cf services
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 [email protected]... 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 [email protected]... OK TIP: Use 'cf push' to ensure your env variable changes take effect $ cf restart my-app
Important 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 [email protected] 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 Managing 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 [email protected]... 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 [email protected]...
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 [email protected]... 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 [email protected]... OK
Important 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 Managing App Requests with Route Services.
Important 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 [email protected]... 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 [email protected]... OK
Update a service instance
Changing a service plan
Changing a plan requires cf CLI v6.7+ and cf-release v192+. CLI v7 or v8 is recommended.
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 [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 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 [email protected]... 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:
-
Confirm that an upgrade is available by running
cf servicesand reviewing theupgrade availablecolumn. For example:$ 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
-
Upgrade the service instance using the
--upgradeflag:cf update-service SERVICE-INSTANCE --upgradeFor example:
$ 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 [email protected]... OK
