-
Notifications
You must be signed in to change notification settings - Fork 20
/
dev-services.html.md.erb
338 lines (255 loc) · 15.2 KB
/
dev-services.html.md.erb
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
---
breadcrumb: PCF Dev Documentation
title: Using Services in PCF Dev
owner: PCF Dev
---
<strong><%= modified_date %></strong>
This topic describes how to deploy, create, delete, update, and bind Marketplace services in PCF Dev.
PCF Dev provides access to three Marketplace services: Redis, RabbitMQ, and MySQL. You can create instances of these services and bind them to your applications to generate and deliver credentials to the applications.
<p class="note"><strong>Note</strong>: To manage and bind service instances you must be running the PCF Dev .iso or .tgz and you must be logged in to your PCF Dev instance. Complete the steps in the <a href="usage.html">Using PCF Dev</a> topic before following the procedures below.</p>
## <a id='marketplace'></a> List Marketplace Services ##
Run the command `cf marketplace` to display information about the Marketplace services available in PCF Dev. Services that are not started do not appear in Marketplace.
<pre class='terminal'>
$ cf marketplace
Getting services from marketplace in org pcfdev-org / space pcfdev-space as admin...
OK
service plans description
p-mysql 512mb, 1gb MySQL databases on demand
p-rabbitmq standard RabbitMQ is a robust and scalable high-performance multi-protocol messaging broker.
p-redis shared-vm Redis service to provide a key-value store
</pre>
## <a id='marketplace'></a> Deploy Services ##
<p class="note"><strong>Note</strong>: Ad hoc service deployment requires PCF Dev v1.0.0 or later.</p>
Run the command `cf dev deploy-service SERVICE NAME` to deploy a service.
<pre class='terminal'>
$ cf dev deploy-service redis
Deploying redis...
OK
</pre>
PCF Dev supports Marketplace services, giving developers access to Spring Cloud Services, Redis, RabbitMQ, and MySQL.
| flag | description |
|---|---|---|---|
| `scs` | Server-side components for Spring Cloud projects. |
| `redis` | Redis service provides a key-value store. |
| `rabbitmq` | RabbitMQ is a robust and scalable high-performance multi-protocol messaging broker. |
| `mysql` | MySQL databases on demand. |
## <a id='create'></a>Create Service Instances ##
You can create a service instance with the command: `cf create-service SERVICE PLAN SERVICE_INSTANCE`
* `SERVICE` The service you choose.
* `PLAN` Service plans are a way for providers to offer varying levels
of resources or features for the same service.
* `SERVICE_INSTANCE` A 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.
Example:
<pre class="terminal">
$ cf create-service p-mysql 512mb my\_mysql
Creating service my_mysql in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
<p class="note"><strong>Note</strong>: The <a href="http://docs.pivotal.io/pivotalcf/devguide/services/user-provided.html">User Provided Service Instances</a> topic provides a way for developers to bind applications with services that are not available in their Cloud Foundry Marketplace.</p>
### <a id='arbitrary-params-create'></a> Arbitrary Parameters ###
<p class="note"><strong>Note</strong>: Arbitrary parameters require cf CLI v6.12.1 or later.</p>
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 the documentation for the
particular service offering.
Example providing 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 pcfdev-org / space pcfdev-space as admin...
OK
</pre>
Example providing 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 pcfdev-org / space pcfdev-space as admin...
OK
</pre>
### <a id='instance-tags-create'></a> Instance Tags ###
<p class="note"><strong>Note</strong>: Instance tags require cf CLI v6.12.1+</p>
Some services provide a list of tags that Cloud Foundry delivers in the
[VCAP_SERVICES Environment Variable](http://docs.pivotal.io/pivotalcf/devguide/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 can provide their own tags when creating a service instance by including a comma-separated list of tags with the `-t` flag.
Example:
<pre class="terminal">
$ cf create-service my-db-service small-plan my-db -t "prod, workers"
Creating service my-db in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
## <a id='list'></a>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.
Example:
<pre class="terminal">
$ cf services
Getting services in org pcfdev-org / space pcfdev-space as admin...
OK
name service plan bound apps last operation
my_mysql p-mysql 512mb myapp 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.
Example:
<pre class='terminal'>
$ cf service my\_mysql
Service instance: my\_mysql
Service: p-mysql
Plan: 512mb
Description: MySQL databases on demand
Documentation url:
Dashboard: http<span>s</span>://mysql-broker.local.pcfdev.io/manage/instances/478d839c-dcfa-41cc-88ed-12f1b0b12a31
Last Operation
Status: create succeeded
Message:
Started: 2016-04-14T17:47:44Z
Updated:
</pre>
## <a id='rename_service'></a>Rename a Service Instance ##
You can change the name given to a service instance.
When restarting any bound applications, the name of the instance changes in the [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) 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.
Example:
<pre class="terminal">
$ cf rename-service my\_mysql my\_mysql1
Renaming service my\_mysql to my\_mysql1 in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
## <a id='update_service'></a>Update a Service Instance ##
### Upgrade/Downgrade Service Plan
<p class="note"><strong>Note</strong>: Changing a plan requires cf CLI v6.7+ and cf-release v192+</p>
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 support this feature, services must expressly
implement support for it, and not all services do.
Furthermore, 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.
Example:
<pre class="terminal">
$ cf update-service my\_mysql -p 1gb
Updating service instance my\_mysql as admin...
OK
</pre>
### <a id='arbitrary-params-update'></a> Arbitrary Parameters ###
<p class="note"><strong>Note</strong>: Arbitrary parameters require cf CLI v6.12.1+</p>
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 the documentation for the
particular service offering.
Example providing parameters in-line:
<pre class="terminal">
$ cf update-service mydb -c '{"storage_gb":4}'
Updating service instance mydb as admin...
</pre>
Example providing parameters in a file:
<pre class="terminal">
$ cf update-service mydb -c /tmp/config.json
Updating service instance mydb as admin...
</pre>
### <a id='instance-tags-update'></a> Instance Tags ###
<p class="note"><strong>Note</strong>: Instance tags require cf CLI v6.12.1+</p>
Some services provide a list of tags that Cloud Foundry delivers in the
[VCAP_SERVICES Environment Variable](http://docs.pivotal.io/pivotalcf/devguide/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 can provide their own tags when creating a service instance by
including a comma-separated list of tags with the `-t` flag.
Example:
<pre class="terminal">
$ cf update-service my-db -t "staging, web"
Updating service my-db in org org pcfdev-org / space pcfdev-space as admin...
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.
Example:
<pre class="terminal">
$ cf delete-service my_mysql
Really delete the service my\_mysql?> y
Deleting service my\_mysql in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
## <a id='bind'></a>Bind a Service Instance ##
Binding a service instance to your application triggers credentials to be
provisioned for the service instance and delivered to the application runtime
in the [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable.
For details on consuming these credentials with your application, see [Using Bound Service Instances](#use).
Not all services support binding, as some services deliver value to users
directly without integration with an application.
Example:
<pre class="terminal">
$ cf bind-service my-app my\_mysql
Binding service my\_mysql to app my_app in org pcfdev-org / space pcfdev-space as admin...
OK
TIP: Use 'cf restage my\_app' to ensure your env <%# "environment" is preferred %>variable changes take effect
$ cf restage 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="http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a> environment variable and for the application to recognize these changes.</p>
### <a id='arbitrary-params-binding'></a> Arbitrary Parameters ###
<p class="note"><strong>Note</strong>: Arbitrary parameters require cf CLI v6.12.1+</p>
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 the documentation for the
particular service offering.
Example providing parameters in-line:
<pre class="terminal">
$ cf bind-service rails-sample my-db -c '{"role":"read-only"}'
Binding service my-db to app rails-sample in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
Example providing parameters in a file:
<pre class="terminal">
$ cf bind-service rails-sample my-db -c /tmp/config.json
Binding service my-db to app rails-sample in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
### <a id='bind-with-manifest'></a> Binding with Application Manifest ###
As an alternative to binding a service instance 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.
The following excerpt from an application manifest would bind 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/user/test-apps/test-msg-app/manifest.yml
...
Binding service test-mysql-01 to test-msg-app in org pcfdev-org / space pcfdev-space as admin...
OK
</pre>
For more information about application manifests, see [Deploying with Application Manifests](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/manifest.html#services-block).
### <a id='use'></a>Using Bound Service Instance<%# Only capitalize "service instance" when it is part of a title %>s ###
Once you have a service instance created and bound to your application, you need to configure the application to dynamically fetch the credentials for your service instance. The [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable contains credentials and additional metadata for all bound service instances. There are two methods developers can leverage to have their applications consume binding credentials.
* **Parse the JSON yourself:** See the documentation for [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES). Helper libraries are available for some frameworks.
* **Auto-configuration:** Some buildpacks create a service connection for you by creating additional environment variables, updating config files, or passing system parameters to the JVM.
For details on consuming credentials specific to your development framework, refer <%# "see" is preferred. %>to the Service Binding section in the documentation for [your framework's buildpack](http://docs.pivotal.io/pivotalcf/buildpacks/index.html).
## <a id='update-credentials'></a>Update Service Credentials
To update your service credentials, perform the following steps:
1. [Unbind the service instance](#unbind) using the credentials you are updating with the following command:
<pre class='terminal'>
$ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
</pre>
1. [Bind the service instance](#bind) with the following command. This adds your credentials to the [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable.
<pre class='terminal'>
$ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
</pre>
1. Restart or re-push the application bound to the service instance so that the application recognizes your environment variable updates.
## <a id='unbind'></a>Unbind a Service Instance<%# Only capitalize "service instance" when it is part of a title %> ##
Unbinding a service removes the credentials created for your application from the [VCAP_SERVICES](http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) environment variable.
<pre class="terminal">
$ cf unbind-service my-app my\_mysql
Unbinding app my-app from service my\_mysql in org pcfdev-org / space pcfdev-space as admin...
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="http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES">VCAP_SERVICES</a> environment variable and for the application to recognize these changes.</p>