-
Notifications
You must be signed in to change notification settings - Fork 61
/
managing-service-brokers.html.md.erb
246 lines (187 loc) · 11.7 KB
/
managing-service-brokers.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
---
title: Managing Service Brokers
owner: Core Services
---
This page assumes you are using cf CLI v6.16 or later.
In order to run many of the commands, you must be authenticated with <%= vars.app_runtime_full %> as an admin user or
as a space developer.
## <a id='quick-start'></a>Quick start
Given a service broker that has implemented the [Service Broker API](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md), two steps are required to
make its services available to end users in all orgs or a limited number of orgs by service plan.
1. [Registering a broker](#register-broker)
1. [Making plans public](#make-plans-public)
## <a id='register-broker'></a>Registering a broker
Registering a broker causes Cloud Controller to fetch and validate the catalog
from your broker, and save the catalog to the Cloud Controller database.
The basic auth username and password which are provided when adding a broker are
encrypted in Cloud Controller database, and used by the Cloud Controller to
authenticate with the broker when making all API calls.
Your service broker can validate the username and password sent in every
request; otherwise, anyone could curl your broker to delete service instances. When the broker is registered with an URL having the scheme `https`, Cloud Controller makes all calls to the broker over HTTPS.
As of cf-release 229, CC API 2.47.0, <%= vars.platform_name %> supports two types of brokers: _standard brokers_ and _space-scoped brokers_. A list of their differences follows:
**Standard Brokers**
* Publish service plans to specific orgs or all orgs in the deployment. Can also keep plans unavailable, or _private_.
* Created by admins, with the command `cf create-service-broker`
<pre class="terminal">
$ cf create-service-broker mybrokername someuser somethingsecure <span>https</span>://mybroker.example.com
</pre>
* Managed by admins
* Service plans are created private. Before anyone can use them, an admin must explicitly [make them available](#make-plans-public) within an org or across all orgs.
**Space-scoped brokers**
* Publish service plans only to users within the space they are created. Plans are unavailable outside of this space.
* Created by space developers using the command `cf create-service-broker` with the `--space-scoped` flag
<pre class="terminal">
$ cf create-service-broker mybrokername someuser somethingsecure <span>https</span>://mybroker.example.com --space-scoped
</pre>
If a space developer runs <code>cf create-service-broker</code> without the <code>--space-scoped</code> flag, they receive an error.
* Managed by space developers
* Newly created plans are published to all users in their space.
### <a id='make-plans-public'></a>Making plans public
After an admin creates a new service plan from a standard broker, no one can use it until the admin explicitly makes it available to users within a specific org or all orgs in the deployment.
See the [Access Control](./access-control.html#enable-access) topic for how to make standard broker service plans available to users.
### <a id='multiple-brokers'></a>Multiple brokers, services and plans
Many service brokers can be added to a <%= vars.platform_name %> instance, each offering
many services and plans.
Keep the following constraints in mind:
- It is not possible to have multiple brokers with the same name.
- Prior to Cloud Foundry API (CAPI) v1.71, the service ID and plan IDs of each service advertised by the broker must be unique across <%= vars.platform_name %>.
- With CAPI v1.71 or later, the service ID and plan IDs of each service advertised by the broker must be unique only within the broker and can overlap ids defined in other brokers.
- GUIDs are recommended for the service ID and plan IDs of each service.
<p class="note important">
<span class="note__title"><strong>Important</strong></span>
If your deployment uses CAPI v1.71 or later, you can add multiple brokers with the same URL. In this case, the brokers must have different names. CAPI v1.70 and
earlier do not support this feature.</p>
See [Possible errors](#possible-errors) for error messages and what do to
when you see them.
## <a id='list-brokers'></a> Listing service brokers
<pre class="terminal">
$ cf service-brokers
Getting service brokers as admin...
OK
Name URL
my-service-broker https://mybroker.example.com
</pre>
## <a id='update-broker'></a>Updating a broker
Updating a broker is how to ingest changes a broker author has made into Cloud
Foundry.
Similar to adding a broker, update causes Cloud Controller to fetch the catalog
from a broker, validate it, and update the Cloud Controller database with any
changes found in the catalog.
Update also provides a means to change the basic auth credentials cloud
controller uses to authenticate with a broker, as well as the base URL of the
broker's API endpoints.
<pre class="terminal">
$ cf update-service-broker mybrokername someuser somethingsecure <span>https</span>://mybroker.example.com
</pre>
## <a id='rename-broker'></a>Renaming a broker
A service broker can be renamed with the `rename-service-broker`
command.
This name is used only by the <%= vars.platform_name %> operator to identify brokers, and
has no relation to configuration of the broker itself.
<pre class="terminal">
$ cf rename-service-broker mybrokername mynewbrokername
</pre>
## <a id='remove-broker'></a>Removing a broker
When you remove a service broker, all services and plans in the broker's catalog are removed from the <%= vars.platform_name %> Marketplace.
<pre class="terminal">
$ cf delete-service-broker mybrokername
</pre>
When you attempt to remove a service broker it can fail if there are service instances for any service plan in its catalog. When you are planning to shut down or
delete a broker, make sure to remove all service instances first. Failure to do so
leaves <a href="https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#orphans">orphaned service instances</a> in the <%= vars.platform_name %> database. If a
service broker has been shut down without first deleting service instances, you can remove the instances with the CLI, see <a href="#purge-service">Purge a Service</a>.
### <a id='purge-service'></a>Purging a service
If a service broker has been shut down or removed without first deleting service instances from <%= vars.platform_name %>, you can be unable to remove the service broker or its services and plans from the Marketplace. In development environments, broker authors often destroy their broker deployments and need a way to clean up the Cloud Controller database.
The following command deletes a service offering, all of its plans, and all associated service instances and bindings from the Cloud Controller database, without making any API calls to a service broker. Once all services for a broker have been purged, the broker can be removed normally.
<pre class="terminal">
$ cf purge-service-offering service-test
Warning: This operation assumes that the service broker responsible for this
service offering is no longer available, and all service instances have been
deleted, leaving orphan records in <%= vars.platform_name %>'s database. All knowledge of
the service can be removed from <%= vars.platform_name %>, including service instances and
service bindings. No attempt is made to contact the service broker; running
this command without destroying the service broker causes orphan service
instances. After running this command you might want to run either
delete-service-auth-token or delete-service-broker to complete the cleanup.
Really purge service offering service-test from <%= vars.platform_name %>? y
OK
</pre>
### <a id='purge-service-instance'></a>Purging a service instance
The following command deletes a single service instance, its service bindings and its service keys from the Cloud Controller database, without making any API calls to a service broker.
This helps in instances when a Service Broker is not conforming to the Service Broker API and not returning a 200 or 410 to requests to delete the service instance.
<pre class="terminal">
$ cf purge-service-instance mysql-dev
WARNING: This operation assumes that the service broker responsible for this
service instance is no longer available or is not responding with a 200 or 410,
and the service instance has been deleted, leaving orphan records in Cloud
Foundry's database. All knowledge of the service instance is removed from
<%= vars.platform_name %>, including service bindings and service keys.
Really purge service instance mysql-dev from <%= vars.platform_name %>?> y
Purging service mysql-dev...
OK
</pre>
`purge-service-instance` requires cf-release v218 and cf CLI 6.14.0.
When multiple brokers provide two or more service instances with the same name, you must specify the broker by including
the <code>-b BROKER</code> flag in the <code>cf purge-service-instance</code> command.
## <a id='catalog-validation'></a> Catalog validation behaviors
When <%= vars.platform_name %> fetches a catalog from a broker, and compares the
broker's id for services and plans with the `unique_id` values for services and
plans in the Cloud Controller database.
<table class=“table”>
<thead>
<tr>
<th>Event</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td>The catalog fails to load or validate.</td>
<td><%= vars.platform_name %> returns a meaningful error that the broker could not be reached or the catalog was not valid.</td>
</tr>
<tr>
<td>A service or plan in the broker catalog has an ID that is not present among the <code>unique_id</code> values in the marketplace database.</td>
<td>A new record must be added to the marketplace database.</td>
</tr>
<tr>
<td>A service or plan in the marketplace database are found with a <code>unique_id</code> that matches the broker catalog's ID.</td>
<td>The marketplace must update the records to match the broker's catalog.</td>
</tr>
<tr>
<td>The database has plans that are not found in the broker catalog, and there are no associated service instances.</td>
<td>The marketplace must remove these plans from the database, and then delete services that do not have associated plans from the database.
</tr>
<tr>
<td>The database has plans that are not found in the broker catalog, but there are provisioned instances.</td>
<td>The marketplace must mark the plan inactive and no longer allow it to be provisioned.</td>
</table>
## <a id='possible-errors'></a>Possible errors
If incorrect basic auth credentials are provided:
<pre class="terminal">
Server error, status code: 500, error code: 10001, message: Authentication
failed for the service broker API.
Verify that the username and password are correct:
https://github-broker.a1-app.example.com/v2/catalog
</pre>
If you receive the following errors, check your broker logs.
You might have an internal error.
<pre class="terminal">
Server error, status code: 500, error code: 10001, message:
The service broker response was not understood
Server error, status code: 500, error code: 10001, message:
The service broker API returned an error from
https://github-broker.a1-app.example.com/v2/catalog: 404 Not Found
Server error, status code: 500, error code: 10001, message:
The service broker API returned an error from
https://github-broker.primo.example.com/v2/catalog: 500 Internal Server Error
</pre>
If your broker's catalog of services and plans violates validation of presence,
uniqueness, and type, you can receive meaningful errors.
<pre class="terminal">
Server error, status code: 502, error code: 270012, message: Service broker catalog is invalid:
Service service-name-1
service id must be unique
service description is required
service "bindable" field must be a boolean, but has value "true"
Plan plan-name-1
plan metadata must be a hash, but has value [{"bullets"=>["bullet1", "bullet2"]}]
</pre>