forked from cloudfoundry/docs-services
-
Notifications
You must be signed in to change notification settings - Fork 0
/
api-v2.9.html.md.erb
1407 lines (1202 loc) · 54.6 KB
/
api-v2.9.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
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
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Service Broker API v2.9
owner: Services API
---
<strong><%= modified_date %></strong>
## <a id='changelog'></a>Document Changelog ##
[v2 API Change Log](v2-api-changelog.html)
<%= partial "version_table.html" %>
## <a id='changes'></a>Changes ##
### <a id='change-policy'></a>Change Policy ###
* Existing endpoints and fields will not be removed or renamed.
* New optional endpoints, or new HTTP methods for existing endpoints, may be
added to enable support for new features.
* New fields may be added to existing request/response messages.
These fields must be optional and should be ignored by clients and servers
that do not understand them.
### <a id='api-changes-since-v2-8'></a>Changes Since v2.8 ###
1. Querying `last_operation` now supports `service_id` and `plan_id` query parameters.
1. Provision, Update, Deprovision responses now accepts an optional `operation` json param for async responses. This is used to by service brokers to return an state related to the operation. Provided back to the service broker via the `last_operation` call.
1. Querying `last_operation` now supports `operation` param back to the service broker.
## <a id='dependencies'></a>Dependencies ##
v2.9 of the services API has been supported since:
* [Final build 238](https://github.com/cloudfoundry/cf-release/tree/v238) of [cf-release](https://github.com/cloudfoundry/cf-release/)
* v2.57.0 of the Cloud Controller API
* CLI [v6.14.0](https://github.com/cloudfoundry/cli/releases/tag/v6.14.0)
## <a id='api-overview'></a>API Overview ##
The Cloud Foundry services API defines the contract between the Cloud
Controller and the service broker.
The broker is expected to implement several HTTP (or HTTPS) endpoints
underneath a URI prefix.
One or more services can be provided by a single broker, and load balancing
enables horizontal scalability of redundant brokers.
Multiple Cloud Foundry instances can be supported by a single broker using
different URL prefixes and credentials.
<%= image_tag("../images/v2services-new.png", :width =>"960", :height =>"720", :style => 'background-color:#fff') %>
## <a id='api-version-header'></a>API Version Header ##
Requests from the Cloud Controller to the broker contain a header that defines
the version number of the Broker API that Cloud Controller will use.
This header will be useful in future minor revisions of the API to allow
brokers to reject requests from Cloud Controllers that they do not understand.
While minor API revisions will always be additive, it is possible that brokers
will come to depend on a feature that was added after 2.0, so they may use this
header to reject the request.
Error messages from the broker in this situation should inform the operator of
what the required and actual version numbers are so that an operator can go
upgrade Cloud Controller and resolve the issue.
A broker should respond with a `412 Precondition Failed` message when rejecting
a request.
The version numbers are in the format `MAJOR.MINOR`, using semantic versioning
such that 2.9 comes before 2.10.
An example of this header as of publication time is:
`X-Broker-Api-Version: 2.9`
## <a id='authentication'></a>Authentication ##
Cloud Controller (final release v145+) authenticates with the Broker using HTTP
basic authentication (the `Authorization:` header) on every request and will
reject any broker registrations that do not contain a username and password.
The broker is responsible for checking the username and password and returning
a `401 Unauthorized` message if credentials are invalid.
Cloud Controller supports connecting to a broker using SSL if additional
security is desired.
## <a id='catalog-mgmt'></a>Catalog Management ##
The first endpoint that a broker must implement is the service catalog.
Cloud Controller will initially fetch this endpoint from all brokers and make
adjustments to the user-facing service catalog stored in the Cloud Controller
database.
If the catalog fails to initially load or validate, Cloud Controller will not
allow the operator to add the new broker and will give a meaningful error
message.
Cloud Controller will also update the catalog whenever a broker is updated, so
you can use `update-service-broker` with no changes to force a catalog refresh.
When Cloud Controller fetches a catalog from a broker, it will compare the
broker's id for services and plans with the `unique_id` values for services and
plans in the Cloud Controller database.
If a service or plan in the broker catalog has an id that is not present
amongst the `unique_id` values in the database, a new record will be added to
the database.
If services or plans in the database are found with `unique_id`s that match the
broker catalog's id, Cloud Controller will update the records to match
the broker’s catalog.
If the database has plans which are not found in the broker catalog, and there
are no associated service instances, Cloud Controller will remove these plans
from the database. Cloud Controller will then delete services that do not have associated plans
from the database.
If the database has plans which are not found in the broker catalog, and there
**are** provisioned instances, the plan will be marked “inactive” and will
no longer be visible in the marketplace catalog or be provisionable.
### Request ###
#### Route ####
`GET /v2/catalog`
#### cURL ####
<pre class="terminal">
$ curl -H "X-Broker-API-Version: 2.9" http://username:password@broker-url/v2/catalog
</pre>
### Response ###
<table border="1" class="nice">
<thead>
<tr>
<th>Status Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>200 OK</td>
<td>The expected response body is below.</td>
</tr>
</tbody>
</table>
#### Body - Schema of Service Objects ####
CLI and web clients have different needs with regard to service and plan names.
A CLI-friendly string is all lowercase, with no spaces.
Keep it short -- imagine a user having to type it as an argument for a longer
command.
A web-friendly display name is camel-cased with spaces and punctuation supported.
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>services*</td>
<td>array-of-service-objects</td>
<td>Schema of service objects defined below.</td>
</tr>
</tbody>
</table>
<h5> Service Objects </h5>
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> name*</td>
<td>string</td>
<td>The CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.</td>
</tr>
<tr>
<td> id*</td>
<td>string</td>
<td>An identifier used to correlate this service in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended. </td>
</tr>
<tr>
<td> description*</td>
<td>string</td>
<td>A short description of the service that will appear in the catalog.</td>
</tr>
<tr>
<td> tags</td>
<td>array-of-strings</td>
<td>Tags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp.</td>
</tr>
<tr>
<td> requires</td>
<td>array-of-strings</td>
<td>A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are <tt>syslog_drain</tt>, <tt>route_forwarding</tt> and <tt>volume_mount</tt>; for more info see <a href="app-log-streaming.html">Application Log Streaming</a>, <a href="route-services.html">Route Services</a> and <a href="volume-services.html">Volume Services</a>.</td>
<tr>
<td> max_db_per_node:</td>
<td>strings</td>
<td></td>
<tr>
<td> bindable*</td>
<td>boolean</td>
<td>Whether the service can be bound to applications.</td>
</tr>
<tr>
<td> metadata</td>
<td>object</td>
<td>A list of metadata for a service offering. For more information, see <a href="catalog-metadata.html">Service Metadata</a>.</td>
</tr>
<tr>
<td><a href="#DObject"> dashboard_client</a></td>
<td>object</td>
<td>Contains the data necessary to activate the <a href="dashboard-sso.html">Dashboard SSO feature</a> for this service</td>
</tr>
<tr>
<td> plan_updateable</td>
<td>boolean</td>
<td>
Whether the service supports upgrade/downgrade for some plans.
<br/>
Please note that the misspelling of the attribute <i>plan_updatable</i> to <i>plan_updateable</i> was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility.
</td>
</tr>
<tr>
<td><a href="#PObject"> plans*</a></td>
<td>array-of-objects</td>
<td>A list of plans for this service, schema is defined below.</td>
</tr>
</tbody>
</table>
<h5> Dashboard Client Object <a name="DObject"></a> </h5>
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> id</td>
<td>string</td>
<td>The id of the Oauth2 client that the service intends to use. The name may be taken, in which case the updat will return an error to the operator</td>
</tr>
<tr>
<td> secret</td>
<td>string</td>
<td>A secret for the dashboard client</td>
</tr>
<tr>
<td> redirect_uri</td>
<td>string</td>
<td>A domain for the service dashboard that will be whitelisted by the UAA to enable SSO</td>
</tr>
</tbody>
</table>
<h5> Plan Object <a name="PObject"></a> </h5>
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> id*</td>
<td>string</td>
<td>An identifier used to correlate this plan in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended.</td>
</tr>
<tr>
<td> name*</td>
<td>string</td>
<td>The CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.</td>
</tr>
<tr>
<td> description*</td>
<td>string</td>
<td>A short description of the service that will appear in the catalog.</td>
</tr>
<tr>
<td> metadata</td>
<td>object</td>
<td>A list of metadata for a service plan. For more information, see <a href="catalog-metadata.html">Service Metadata</a>.</td>
</tr>
<tr>
<td> free</td>
<td>boolean</td>
<td>This field allows the plan to be limited by the non_basic_services_allowed field in a Cloud Foundry Quota, see <a href="http://docs.cloudfoundry.org/running/managing-cf/quota-plans.html">Quota Plans</a>. Default: true</td>
</tr>
</tbody>
</table>
\* Fields with an asterisk are required.
<pre>
{
"services": [{
"name": "fake-service",
"id": "acb56d7c-XXXX-XXXX-XXXX-feb140a59a66",
"description": "fake service",
"tags": ["no-sql", "relational"],
"requires": ["route_forwarding"],
"max_db_per_node": 5,
"bindable": true,
"metadata": {
"provider": {
"name": "The name"
},
"listing": {
"imageUrl": "http://example.com/cat.gif",
"blurb": "Add a blurb here",
"longDescription": "A long time ago, in a galaxy far far away..."
},
"displayName": "The Fake Broker"
},
"dashboard_client": {
"id": "398e2f8e-XXXX-XXXX-XXXX-19a71ecbcf64",
"secret": "277cabb0-XXXX-XXXX-XXXX-7822c0a90e5d",
"redirect_uri": "http://localhost:1234"
},
"plan_updateable": true,
"plans": [{
"name": "fake-plan",
"id": "d3031751-XXXX-XXXX-XXXX-a42377d3320e",
"description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections",
"max_storage_tb": 5,
"metadata": {
"cost": 0,
"bullets": [{
"content": "Shared fake server"
}, {
"content": "5 TB storage"
}, {
"content": "40 concurrent connections"
}]
}
}, {
"name": "fake-async-plan",
"id": "0f4008b5-XXXX-XXXX-XXXX-dace631cd648",
"description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
"max_storage_tb": 5,
"metadata": {
"cost": 0,
"bullets": [{
"content": "40 concurrent connections"
}]
}
}, {
"name": "fake-async-only-plan",
"id": "8d415f6a-XXXX-XXXX-XXXX-e61f3baa1c77",
"description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
"max_storage_tb": 5,
"metadata": {
"cost": 0,
"bullets": [{
"content": "40 concurrent connections"
}]
}
}]
}]
}
</pre>
### <a id='create-broker'></a>Adding a Broker to Cloud Foundry ###
Once you've implemented the first endpoint `GET /v2/catalog` above, you'll want
to [register the broker with CF](managing-service-brokers.html#register-broker)
to make your services and plans available to end users.
## <a id='asynchronous-operations'></a>Asynchronous Operations ##
Previously, Cloud Foundry only supported synchronous integration with service brokers. Brokers must return a valid response within 60 seconds and if the response is `201 CREATED`, users expect a service instance to be usable. This limits the services brokers can offer to those that can be provisioned in 60 seconds; brokers could return a success prematurely, but this leaves users wondering why their service instance is not usable and when it will be.
With support for Asynchronous Operations, brokers still must respond within 60 seconds but may now return a `202 ACCEPTED`, indicating that the requested operation has been accepted but is not complete. This triggers Cloud Foundry to poll a new endpoint `/v2/service_instances/:guid/last_operation` until the broker indicates that the requested operation has succeeded or failed. During the intervening time, end users are able to discover the state of the requested operation using Cloud Foundry API clients such as the CLI.
For an operation to be executed asynchronously, all three components (CF API client, CF, and broker) must support the feature. The parameter `accepts_incomplete=true` must be passed in a request by the CF API client, triggering CF to include the same parameter in a request to the broker. The broker can then choose to execute the request synchronously or asynchronously.
If the broker executes the request asynchronously, the response must use the status code `202 ACCEPTED`; the response body should be the same as if the broker were serving the request synchronously.
<p class='note'><strong>Note:</strong> Asynchronous Operations are currently supported only for provision, update, and deprovision. Bind and unbind will be added once the feature is considered stable.</p>
If the `accepts_incomplete=true` parameter is not included, and the broker cannot fulfill the request synchronously (guaranteeing that the operation is complete on response), then the broker should reject the request with the status code `422 UNPROCESSABLE ENTITY` and the following body:
<pre class="terminal">
{
"error": "AsyncRequired",
"description": "This service plan requires client support for asynchronous service operations."
}
</pre>
To execute a request synchronously, the broker need only return the usual status codes; `201 CREATED` for create, and `200 OK` for update and delete.
### <a id='sequence-diagram'></a>Sequence Diagram ###
<a href='images/async-service-broker-flow.png' target='_blank'>
<%= image_tag("images/async-service-broker-flow.png", :width =>"1250", :height =>"823", :style => 'background-color:#fff') %>
</a>
### <a id='blocking'></a>Blocking Operations ###
The Cloud Controller ensures that service brokers do not receive requests for an instance while an asynchronous operation is in progress. For example, if a broker is in the process of provisioning an instance asynchronously, the Cloud Controller will not allow any update, bind, unbind, or deprovision requests to be made through the platform. A user who attempts to perform one of these actions while an operation is already in progress will get an HTTP 400 with error message "Another operation for this service instance is in progress."
### <a id='when-to-use-async'></a>When to use Asynchronous Service Operations ###
Service brokers should respond to all Cloud Controller requests within 60 seconds. Brokers that can guarantee completion of the requested operation with the response may return the synchronous response (e.g. `201 CREATED` for a provision request). Brokers that cannot guarantee completion of the operation with the response should implement support for asynchronous provisioning. Support for synchronous or asynchronous responses may vary by service offering, even by service plan.
## <a id='polling'></a>Polling Last Operation (async only) ##
When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance), or [deprovision](#deprovisioning), Cloud Foundry will begin to poll the `/v2/service_instances/:guid/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`.
Valid values for `state` are `in progress`, `succeeded`, and `failed`. Cloud Foundry will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause Cloud Foundry to cease polling. The value provided for `description` will be passed through to the CF API client and can be used to provide additional detail for users about the state of the operation.
### Request ###
##### Route #####
`GET /v2/service_instances/:instance_id/last_operation`
##### Parameters #####
The request provides these query string parameters as useful hints for brokers.
<table border="1" class="nice">
<thead>
<tr>
<th>Query-String Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>service_id</td>
<td>string</td>
<td>ID of the service from the catalog.</td>
</tr>
<tr>
<td>plan_id</td>
<td>string</td>
<td>ID of the plan from the catalog.</td>
</tr>
<tr>
<td>operation</td>
<td>string</td>
<td>The field optionally returned by the service broker on Provision, Update, Deprovision async responses. Represents any state the service broker responsed with as a URL encoded string.</a>.</td>
</tr>
</tbody>
</table>
<p class="note"><strong>Note:</strong> Although the request query parameters <code>service_id</code> and <code>plan_id</code> are not required, Cloud Controller includes them on all <code>last_operation</code> requests it makes to service brokers.</p>
##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
</pre>
### Response ###
<table border="1" class="nice">
<thead>
<tr>
<th>Status Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>200 OK</td>
<td>The expected response body is below.</td>
</tr>
<tr>
<td>410 GONE</td>
<td>Appropriate only for asynchronous delete requests. Cloud Foundry will consider this response a success and remove the resource from its database. The expected response body is <code>{}</code>. Returning this while Cloud Foundry is polling for create or update operations will be interpreted as an invalid response and Cloud Foundry will continue polling.</td>
</tr>
</tbody>
</table>
Responses with any other status code will be interpreted as an error or invalid response; Cloud Foundry will continue polling until the broker returns a valid response or the [maximum polling duration](#max-polling-duration) is reached. Brokers may use the `description` field to expose user-facing error messages about the operation state; for more info see [Broker Errors](api.html#broker-errors).
##### Body #####
All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
For success responses, the following fields are valid.
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>state*</td>
<td>string</td>
<td>Valid values are <code>in progress</code>, <code>succeeded</code>, and <code>failed</code>. While <code>"state": "in progress"</code>, Cloud Foundry will continue polling. A response with <code>"state": "succeeded"</code> or <code>"state": "failed"</code> will cause Cloud Foundry to cease polling.</td>
</tr>
<tr>
<td>description</td>
<td>string</td>
<td>Optional field. A user-facing message displayed to the Cloud Foundry API client. Can be used to tell the user details about the status of the operation.</td>
</tr>
</tboby>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"state": "in progress",
"description": "Creating service (10% complete)."
}
</pre>
### <a id='polling-interval'></a> Polling Interval ###
When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state at a configured interval. The Cloud Foundry operator can configure this interval in the BOSH deployment manifest using the property `properties.cc.broker_client_default_async_poll_interval_seconds` (defaults to 60 seconds). The maximum supported polling interval is 86400 seconds (24 hours).
### <a id='max-polling-duration'></a>Maximum Polling Duration ###
When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state until the broker response includes `"state":"succeeded"` or `"state":"failed"`, or until a maximum polling duration is reached. If the max polling duration is reached, Cloud Foundry will cease polling and the operation state will be considered `failed`. The Cloud Foundry operator can configure this max polling duration in the BOSH deployment manifest using the property `properties.cc.broker_client_max_async_poll_duration_minutes` (defaults to 10080 minutes or 1 week).
### <a id='additional-resources'></a>Additional Resources ###
* An example broker that implements this feature can be found at [Example Service Brokers](examples.html).
* A demo video of the CLI user experience using the above broker can be found [here](https://youtu.be/Ij5KSKrAq9Q).
## <a id='provisioning'></a>Provisioning ##
When the broker receives a provision request from Cloud Controller, it should
synchronously take whatever action is necessary to create a new service
resource for the developer.
The result of provisioning varies by service type, although there are a few
common actions that work for many services.
For a MySQL service, provisioning could result in:
* An empty dedicated `mysqld` process running on its own VM.
* An empty dedicated `mysqld` process running in a lightweight container on a
shared VM.
* An empty dedicated `mysqld` process running on a shared VM.
* An empty dedicated database, on an existing shared running `mysqld`.
* A database with business schema already there.
* A copy of a full database, for example a QA database that is a copy of the
production database.
For non-data services, provisioning could just mean getting an account on an
existing system.
### Request ###
##### Route #####
`PUT /v2/service_instances/:instance_id`
<p class="note"><strong>Note</strong>: The <code>:instance_id</code> of a service instance is provided by the Cloud Controller. This ID will be used for future requests (bind and deprovision), so the broker must use it to correlate the resource it creates.</p>
##### Body #####
<table border="1" class="nice">
<thead>
<tr>
<th>Request field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>organization_guid*</td>
<td>string</td>
<td>The Cloud Controller GUID of the organization under which the service is to be provisioned. Although most brokers will not use this field, it could be helpful in determining data placement or applying custom business rules.</td>
</tr>
<tr>
<td>plan_id*</td>
<td>string</td>
<td>The ID of the plan within the above service (from the catalog endpoint) that the user would like provisioned. Because plans have identifiers unique to a broker, this is enough information to determine what to provision.</td>
</tr>
<tr>
<td>service_id*</td>
<td>string</td>
<td>The ID of the service within the catalog above.</td>
</tr>
<tr>
<td>space_guid*</td>
<td>string</td>
<td>Similar to organization_guid, but for the space.</td>
</tr>
<tr>
<td>parameters</td>
<td>JSON object</td>
<td>Cloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.</td>
</tr>
<tr>
<td>accepts_incomplete</td>
<td>boolean</td>
<td>A value of true indicates that both the Cloud Controller and the requesting client support asynchronous provisioning. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.</td>
</tr>
</tbody>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"organization_guid": "org-guid-here",
"plan_id": "plan-guid-here",
"service_id": "service-guid-here",
"space_guid": "space-guid-here",
"parameters": {
"parameter1": 1,
"parameter2": "value"
}
}
</pre>
##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
"organization_guid": "org-guid-here",
"plan_id": "plan-guid-here",
"service_id": "service-guid-here",
"space_guid": "space-guid-here",
"parameters": {
"parameter1": 1,
"parameter2": "value"
}
}' -X PUT -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
</pre>
In this case, `instance_id` refers to the service instance id generated by Cloud
Controller
### Response ###
<table border="1" class="nice">
<thead>
<tr>
<th>Status Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>201 Created</td>
<td>Service instance has been created. The expected response body is below.</td>
</tr>
<tr>
<td>200 OK</td>
<td>
May be returned if the service instance already exists and the requested parameters are identical to the existing service instance.
The expected response body is below.
</td>
</tr>
<tr>
<td>202 Accepted</td>
<td>Service instance creation is in progress. This triggers Cloud Controller to poll the <a href="#polling">Service Instance Last Operation Endpoint</a> for operation status.</td>
</tr>
<tr>
<td>409 Conflict</td>
<td>Should be returned if the requested service instance already exists. The expected response body is <code>{}</code>.</td>
</tr>
<tr>
<td>422 Unprocessable Entity</td>
<td>Should be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include <code>?accepts_incomplete=true</code>. The expected response body is: <code>{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }</code>, as described below.</td>
</tr>
</tbody>
</table>
Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
##### Body #####
All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>dashboard_url</td>
<td>string</td>
<td>The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed ("9189kdfsk0vfnku" in the example below). For information on how users can authenticate with service dashboards via SSO, see <a href="dashboard-sso.html">Dashboard Single Sign-On</a>.</td>
</tr>
<tr>
<td>operation</td>
<td>string</td>
<td>For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on <code>last_operation</code> requests as a URL encoded query param.</a>.</td>
</tr>
</tboby>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku",
"operation": "task_10"
}
</pre>
## <a id='updating_service_instance'></a>Updating a Service Instance ##
Brokers that implement this endpoint can enable users to modify attributes of an existing service instance. The first attribute Cloud Foundry supports users modifying is the service plan. This effectively enables users to upgrade or downgrade their service instance to other plans. To see how users make these requests, see [Managing Services](../devguide/services/managing-services.html#update_service).
To enable this functionality, a broker declares support for each service by including `plan_updateable: true` in its [catalog endpoint](#catalog-mgmt). If this optional field is not included, Cloud Foundry will return a meaningful error to users for any plan change request, and will not make an API call to the broker. If this field is included and configured as true, Cloud Foundry will make API calls to the broker for all plan change requests, and it is up to the broker to validate whether a particular permutation of plan change is supported. Not all permutations of plan changes are expected to be supported. For example, a service may support upgrading from plan "shared small" to "shared large" but not to plan "dedicated". If a particular plan change is not supported, the broker should return a meaningful error message in response.
### Request ###
##### Route #####
`PATCH /v2/service_instances/:instance_id`
<p class="note"><strong>Note</strong>: <code>:instance_id</code> is the global unique ID of a previously-provisioned service instance.</p>
##### Body #####
<table border="1" class="nice">
<thead>
<tr>
<th>Request Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>service_id*</td>
<td>string</td>
<td>The ID of the service within the catalog above.</td>
</tr>
<tr>
<td>plan_id</td>
<td>string</td>
<td>ID of the new plan from the catalog.</td>
</tr>
<tr>
<td>parameters</td>
<td>JSON object</td>
<td>Cloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.</td>
</tr>
<tr>
<td>previous_values</td>
<td>object</td>
<td>Information about the instance prior to the update.</td>
</tr>
<tr>
<td>previous_values.plan_id</td>
<td>string</td>
<td>ID of the plan prior to the update.</td>
</tr>
<tr>
<td>previous_values.service_id</td>
<td>string</td>
<td>ID of the service for the instance.</td>
</tr>
<tr>
<td>previous_values.organization_id</td>
<td>string</td>
<td>ID of the organization containing the instance.</td>
</tr>
<tr>
<td>previous_values.space_id</td>
<td>string</td>
<td>ID of the space containing the instance..</td>
</tr>
<tr>
<td>accepts_incomplete</td>
<td>boolean</td>
<td>A value of true indicates that both the Cloud Controller and the requesting client support asynchronous update. If this parameter is not included in the request, and the broker can only update an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.</td>
</tr>
</tbody>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"service_id": "service-guid-here",
"plan_id": "plan-guid-here",
"parameters": {
"parameter1": 1,
"parameter2": "value"
},
"previous_values": {
"plan_id": "old-plan-guid-here",
"service_id": "service-guid-here",
"organization_id": "org-guid-here",
"space_id": "space-guid-here"
}
}
</pre>
##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
"service_id": "service-guid-here",
"plan_id": "plan-guid-here",
"parameters": {
"parameter1": 1,
"parameter2": "value"
},
"previous_values": {
"plan_id": "old-plan-guid-here",
"service_id": "service-guid-here",
"organization_id": "org-guid-here",
"space_id": "space-guid-here"
}
}' -X PATCH -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
</pre>
### Response ###
<table border="1" class="nice">
<thead>
<tr>
<th>Status Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>200 OK</td>
<td>New plan is effective. The expected response body is <code>{}</code>.</td>
</tr>
<tr>
<td>202 Accepted</td>
<td>Service instance update is in progress. This triggers Cloud Controller to poll the <a href="#polling">Service Instance Last Operation Endpoint</a> for operation status.</td>
</tr>
<tr>
<td>422 Unprocessable entity</td>
<td>
May be returned if the particular plan change requested is not supported or if the request cannot currently be fulfilled due to the state of the instance (eg. instance utilization is over the quota of the requested plan). Broker should include a user-facing message in the body; for details see <a href="#broker-errors">Broker Errors</a>. Additionally, a <code>422</code> can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include <code>?accepts_incomplete=true</code>. The expected response body is: <code>{ "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }</code></a>.
</td>
</tr>
</tbody>
</table>
Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
##### Body #####
All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
<table border="1" class="nice">
<thead>
<tr>
<th>Response field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>operation</td>
<td>string</td>
<td>For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param.</a>.</td>
</tr>
</tboby>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"operation": "task_10"
}
</pre>
## <a id='binding'></a>Binding ##
<p class="note"><strong>Note</strong>: Not all services must be bindable --- some deliver value just from being provisioned. Brokers that offer services that are bindable should declare them as such using <code>bindable: true</code> in the <a href="#catalog-mgmt">Catalog</a>. Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.</p>
### <a id='binding-types'></a>Types of Binding ###
#### <a id='binding-credentials'></a>Credentials ####
Credentials are a set of information used by an application or a user to utilize the service instance. If `bindable:true` is declared for a service in the catalog endpoint, users may request generation of credentials either by binding the service instance to an application or by creating a service key. When a service instance is bound to an app, Cloud Foundry will send the app id with the request. When a service key is created, the app id is not included. If the broker supports generation of credentials it should return `credentials` in the response. Credentials should be unique whenever possible, so access can be revoked for one application or user without affecting another. For more information on credentials, see [Binding Credentials](binding-credentials.html).
#### <a id='binding-syslog-drain'></a>Application Log Streaming ####
In response to a bind request for an application (`app_id` included), a broker may also enable streaming of application logs from Cloud Foundry to a consuming service instance by returning `syslog_drain_url`. For details, see [Application Log Streaming](app-log-streaming.html).
#### <a id='binding-route-services'></a>Route Services ####
If a broker has declared `"requires":["route_forwarding"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind a service to a route. When bound to a route, the route itself will be sent with the bind request. A route is an address used by clients to reach apps mapped to the route. In response a broker may return a `route_service_url` which Cloud Foundry will use to proxy any request for the route to the service instance at URL specified by `route_service_url`. A broker may declare `"requires":["route_forwarding"]` but not return `route_service_url`; this enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router. For more information, see [Route Services](route-services.html).
#### <a id='binding-volume-services'></a>Volume Services (Experimental)####
If a broker has declared `"requires":["volume_mount"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind one or more volumes to an application. In response to a bind request a volume service broker should return a set of `volume_mount` instructions that Cloud Foundry will ensure are mounted into the application's containers. For more information, see [Volume Services](volume-services.html)
### Request ###
##### Route #####
`PUT /v2/service_instances/:instance_id/service_bindings/:binding_id`
<p class="note"><strong>Note</strong>: The <code>:binding_id</code> of a service binding is provided by the Cloud Controller.
<code>:instance_id</code> is the ID of a previously-provisioned service instance; <code>:binding_id</code>
will be used for future unbind requests, so the broker must use it to correlate
the resource it creates.</p>
##### Body #####
<table border="1" class="nice">
<thead>
<tr>
<th>Request Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>service_id*</td>
<td>string</td>
<td>ID of the service from the catalog.</td>
</tr>
<tr>
<td>plan_id*</td>
<td>string</td>
<td>ID of the plan from the catalog.</td>
</tr>
<tr>
<td>app_guid</td>
<td>string</td>
<td>GUID of the application that you want to bind your service to. Will be included when users bind applications to service instances.</td>
</tr>
<tr>
<td>bind_resource</td>
<td>JSON object</td>
<td>A JSON object that contains the required fields of the resource being bound. Currently only <code>app_guid</code> for application bindings and <code>route</code> for route bindings are supported.</td>
</tr>
<tr>
<td>parameters</td>
<td>JSON object</td>
<td>Cloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.</td>
</tr>
</tbody>
</table>
\* Fields with an asterisk are required.
<pre class="terminal">
{
"plan_id": "plan-guid-here",
"service_id": "service-guid-here",
"app_guid": "app-guid-here",
"bind_resource": {
"app_guid": "app-guid-here"
},
"parameters": {
"parameter1-name-here": 1,
"parameter2-name-here": "parameter2-value-here"
}
}
</pre>
<pre class="terminal">
{
"plan_id": "plan-guid-here",
"service_id": "service-guid-here",
"bind_resource": {
"route": "route-url-here"
},
"parameters": {
"parameter1-name-here": 1,
"parameter2-name-here": "parameter2-value-here"
}
}
</pre>
##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
"plan_id": "plan-guid-here",
"service_id": "service-guid-here",
"app_guid": "app-guid-here",
"bind_resource": {
"app_guid": "app-guid-here"
},
"parameters": {
"parameter1-name-here": 1,