-
Notifications
You must be signed in to change notification settings - Fork 234
Expand file tree
/
Copy pathmanaging-services.html.md.erb
More file actions
395 lines (260 loc) · 16.4 KB
/
Copy pathmanaging-services.html.md.erb
File metadata and controls
395 lines (260 loc) · 16.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
---
title: Managing service instances with the cf CLI
owner: Core Services
---
You can manage life cycle operations for service instances using the Cloud Foundry CLI (cf CLI). This includes creating, updating, and deleting service instances. For information about other service management operations, see [Services overview](./index.html). <%= 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, to view the services available to your targeted organization, run the cf CLI command:
```console
cf marketplace
```
Available services can 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 broker
p-mysql 100mb, 1gb A DBaaS mysql-broker
p-riakcs developer An S3-compatible object store object-store-broker
</pre>
## <a id='create'></a>Creating service instances
You can create a service instance by running:
```console
cf create-service SERVICE PLAN SERVICE-INSTANCE-NAME
```
Where:
* `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-NAME`: 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.
For example:
<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>
Service creation is asynchronous by default. To wait for the operation to complete before the command returns, use the `--wait` flag:
```console
cf create-service SERVICE PLAN SERVICE-INSTANCE-NAME --wait
```
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 <a href="./user-provided.html">User-provided service instances</a>.
When multiple brokers provide two or more services with the same name, you must specify the broker by including the <code>-b BROKER</code> flag in the <code>cf create-service</code> command.
### <a id='arbitrary-params-create'></a> Arbitrary parameters
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
Some services provide a list of tags that Cloud Foundry delivers to the app when the service is bound. These are included in the [VCAP_SERVICES environment variable](../deploy-apps/environment-variable.html#VCAP-SERVICES) or the file system, depending on the chosen [Credential Delivery Method](./application-binding.html#credential-delivery-methods). These tags provide developers with a more generic way for apps to parse the service binding data for credentials. Developers might 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
To list the service instances in your targeted space, run:
```console
cf services
```
The output from running this command includes any bound apps and the state of the last requested operation for the service instance.
To skip retrieving bound app information (which can be slow in large spaces), use the `--no-apps` flag:
```console
cf services --no-apps
```
To wait for any in-progress asynchronous operations to complete before the command returns, use the `--wait` flag:
```console
cf services --wait
```
<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 broker upgrade available
mybucket p-riakcs developer myapp create succeeded object-store-broker no
mydb p-mysql 100mb create succeeded mysql-broker yes
</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
guid: abcd-ef12-3456
type: managed
offering: p-mysql
plan: 100mb
description: mysql databases on demand
documentation url:
dashboard url: https://p-mysql.example.com/manage/instances/abcd-ef12-3456
broker: mysql-broker
tags:
broker tags:
This service is not 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.
</pre>
## <a id='bind'></a>Bind a service instance
Depending on the service, you can bind service instances to apps and routes.
Not all services support binding, as some services deliver value to users directly without integration with Cloud Foundry, such as SaaS apps.
### <a id='app-binding'></a>Bind a service instance to an app
Depending on the service, binding a service instance to your app might deliver credentials for the service instance to the app. See [Delivering service credentials to an app](application-binding.html) for more information.
Binding a service instance to an app can trigger app logs to be streamed to the service instance. See [Streaming app logs to log management services](log-management.html).
You must restart, or in some cases re-push, your app so that new or changed binding data is delivered in the <a href="../deploy-apps/environment-variable.html">VCAP_SERVICES</a> environment variable or the file system, depending on the chosen [Credential Delivery Method](./application-binding.html#credential-delivery-methods).
<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>
To wait for the bind operation to complete before the command returns, use the `--wait` flag:
```console
cf bind-service APP-NAME SERVICE-INSTANCE-NAME --wait
```
#### <a id='bind-with-manifest'></a> 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. [Arbitrary parameters](#arbitrary-params-binding) are not supported in app manifests. Using the manifest to bind service instances to routes is also not supported.
This excerpt from an app manifest binds a service instance called `test-mysql-01` to the app on push.
```yaml
services:
- test-mysql-01
```
This 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 app manifests, see [Deploying with app 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 causes app requests and responses to be proxied through the service instance, where it can be used to transform or intermediate requests. For more information, see [Managing app 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 app is not required.
### <a id='arbitrary-params-binding'></a> Arbitrary parameters
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 app
Unbinding a service instance from an app removes the credentials from the <a href="../deploy-apps/environment-variable.html">VCAP_SERVICES</a> environment variable or the file system, depending on the chosen [Credential Delivery Method](./application-binding.html#credential-delivery-methods).
You must restart, or in some cases re-push, your app for changes to be applied.
<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>
To wait for the unbind operation to complete before the command returns, use the `--wait` flag:
```console
cf unbind-service APP-NAME SERVICE-INSTANCE-NAME --wait
```
### <a id='route-unbinding'></a>Unbind a service instance from a route
Unbinding a service instance from a route causes requests and responses to no longer be proxied through the service instance. For more information, see [Managing app requests with route services](./route-binding.html).
It's important to note that if your bound service instance is providing security features, like authorization, unbinding the service instance might leave your app vulnerable.
You do not have to restage your app.
<pre class="terminal">
$ cf unbind-route-service <%=vars.app_domain%> --hostname my-app my-service-instance
Unbinding leaves 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>
## <a id='rename_service'></a>Rename a service instance
You can change the name given to a service instance. Upon restarting any bound apps, the name of the instance changes in the [VCAP_SERVICES](../deploy-apps/environment-variable.html) environment variable or the file system depending on the chosen [Credential Delivery Method](./application-binding.html#credential-delivery-methods). If your app depends on the instance name for discovering credentials, changing the name might break your app'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
### Changing a service plan
By updating the service plan for an instance, you can change the service instance to other service plans. Though the platform and CLI now support this feature, services must implement support for it. Further, a service might support updating between some plans but not others. For example, 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
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
<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='upgrade'></a> Upgrade a service instance
Some service brokers support upgrading service instances to the latest version of a service plan. For example, a broker might 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:
1. Confirm that an upgrade is available by running `cf services` and reviewing the `upgrade available` column. For example:
<pre class="terminal">
$ 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
</pre>
2. Upgrade the service instance by running:
```console
cf upgrade-service SERVICE-INSTANCE-NAME
```
For example:
<pre class="terminal">
$ cf upgrade-service mydb
You are about to upgrade mydb.
Warning: This operation might run long and block further operations on the service until complete.
Really upgrade service mydb? [yN]: y
OK
</pre>
To skip the confirmation prompt, use the `--force` flag:
```console
cf upgrade-service SERVICE-INSTANCE-NAME --force
```
## <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>
To wait for the delete operation to complete before the command returns, use the `--wait` flag:
```console
cf delete-service SERVICE-INSTANCE-NAME --wait
```
## <a id='cleanup-bindings'></a>Clean up outdated service bindings
If service instances are deleted outside of Cloud Foundry (for example, directly through a broker or infrastructure), their associated service bindings can become orphaned. To remove these stale bindings, run:
```console
cf cleanup-outdated-service-bindings
```
This command identifies and removes service bindings that no longer have a corresponding service instance. It is a safe operation and will not affect active bindings.