Permalink
Fetching contributors…
Cannot retrieve contributors at this time
290 lines (190 sloc) 13.9 KB
---
title: Managing Service Instances with the cf CLI
owner: Core Services
---
<strong><%= modified_date %></strong>
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](index.html) topic. <%= vars.custom_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](../../cf-cli/index.html) topics for more information.
## <a id='marketplace'></a> 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.
<pre class="terminal">
$ 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
</pre>
## <a id='create'></a>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.
<pre class="terminal">
$ cf create-service rabbitmq small-plan my-rabbitmq
Creating service my-rabbitmq in org console / space development as user@example.com...
OK
</pre>
<strong>User Provided Service Instances</strong> provide a way for developers to bind applications with services that are not available in their Cloud Foundry marketplace. For more information, see the <a href="./user-provided.html">User Provided Service Instances</a> topic.
### <a id='arbitrary-params-create'></a> 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:
<pre class="terminal">
$ 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
</pre>
Example providing service-specific configuration parameters in a file:
<pre class="terminal">
$ 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
</pre>
### <a id='instance-tags-create'></a> 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](../deploy-apps/environment-variable.html#VCAP-SERVICES). 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:
<pre class="terminal">
$ 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
</pre>
## <a id='list'></a>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.
<pre class="terminal">
$ 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
</pre>
### <a id='get-details'></a>Get Details for a Particular Service Instance ###
Details include dashboard urls, if applicable, and operation start and last updated timestamps.
<pre class='terminal'>
$ 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
</pre>
## <a id='bind'></a>Bind a Service Instance ##
Depending on the service, you can bind 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.
### <a id='app-binding'></a>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](application-binding.html) 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](log-management.html).
<pre class="terminal">
$ 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
</pre>
<p class='note'><strong>Note</strong>: You must restart or in some cases re-push your application for changes to be applied to the <a href="../deploy-apps/environment-variable.html">VCAP_SERVICES</a> environment variable and for the application to recognize these changes.</p>
#### <a id='bind-with-manifest'></a> 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](#arbitrary-params-binding) 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`.
<pre class="terminal">
$ 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
</pre>
For more information about application manifests, see [Deploying with Application Manifests](../deploy-apps/manifest.html#services-block).
### <a id='route-binding'></a>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](./route-binding.html).
<pre class="terminal">
$ cf bind-route-service <%=vars.app_domain%> --hostname my-app my-service-instance
Binding route my-app.<%=vars.app_domain%> to service instance my-service-instance in org my-org / space test as user@example.com...
OK
</pre>
Restaging your application is not required.
### <a id='arbitrary-params-binding'></a> 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.
<pre class="terminal">
$ 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
</pre>
<pre class="terminal">
$ 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
</pre>
## <a id='unbind'></a>Unbind a Service Instance ##
### <a id='app-unbinding'></a>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](../deploy-apps/environment-variable.html) environment variable.
<pre class="terminal">
$ cf unbind-service my-app mydb
Unbinding app my-app from service mydb in org my-org / space test as user@example.com...
OK
</pre>
<p class='note'><strong>Note</strong>: You must restart or in some cases re-push your application for changes to be applied to the <a href="../deploy-apps/environment-variable.html">VCAP_SERVICES</a> environment variable and for the application to recognize these changes.</p>
### <a id='route-unbinding'></a>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](./route-binding.html).
<p class='note'><strong>Note</strong>: If your bound service instance is providing security features, like authorization, unbinding the service instance may leave your application vulnerable.</p>
<pre class="terminal">
$ cf unbind-route-service <%=vars.app_domain%> --hostname my-app my-service-instance
Unbinding may leave apps mapped to route my-app.<%=vars.app_domain%> vulnerable; e.g. if service instance my-service-instance provides authentication. Do you want to proceed?> y
Unbinding route my-app.<%=vars.app_domain%> from service instance my-service-instance n org my-org / space test as user@example.com...
OK
</pre>
Restaging your application is not required.
## <a id='rename_service'></a>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](../deploy-apps/environment-variable.html) 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.
<pre class="terminal">
$ cf rename-service mydb mydb1
Renaming service mydb to mydb1 in org my-org / space test as user@example.com...
OK
</pre>
## <a id='update_service'></a>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.
<pre class="terminal">
$ cf update-service mydb -p new-plan
Updating service instance mydb as user@example.com...
OK
</pre>
### <a id='arbitrary-params-update'></a> 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.
<pre class="terminal">
$ cf update-service mydb -c '{"storage_gb":4}'
Updating service instance mydb as me@example.com...
</pre>
<pre class="terminal">
$ cf update-service mydb -c /tmp/config.json
Updating service instance mydb as user@example.com...
</pre>
### <a id='instance-tags-update'></a> 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](../deploy-apps/environment-variable.html#VCAP-SERVICES). 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.
<pre class="terminal">
$ cf update-service my-db -t "staging, web"
Updating service my-db in org console / space development as user@example.com...
OK
</pre>
## <a id='delete'></a>Delete a Service Instance ##
Deleting a service instance deprovisions the service instance and deletes all data associated with the service instance.
<pre class="terminal">
$ 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
</pre>