2
Copyright 2011 OpenStack, LLC
5
Licensed under the Apache License, Version 2.0 (the "License"); you may
6
not use this file except in compliance with the License. You may obtain
7
a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
License for the specific language governing permissions and limitations
17
================================
18
Endpoints and Endpoint Templates
19
================================
27
Simply, endpoints are URLs that point to OpenStack services. When you
28
authenticate to Keystone you get back a token which has a service catalog in
29
it. The service catalog is basically a list of the OpenStack services that
30
you have access to and the URLs you can use to get to them; their endpoints.
32
Here is an example response from Keystone when you authenticate::
37
"id":"ab48a9efdfedb23ty3494",
38
"expires":"2010-11-01T03:32:15-05:00",
49
"name":"compute:admin"
53
"name":"object-store:admin",
64
"publicURL":"https://compute.north.host.com/v1/t1000",
65
"internalURL":"https://compute.north.internal/v1/t1000",
68
"versionInfo":"https://compute.north.host.com/v1/",
69
"versionList":"https://compute.north.host.com/"
73
"publicURL":"https://compute.north.host.com/v1.1/t1000",
74
"internalURL":"https://compute.north.internal/v1.1/t1000",
77
"versionInfo":"https://compute.north.host.com/v1.1/",
78
"versionList":"https://compute.north.host.com/"
85
"type":"object-store",
88
"publicURL":"https://storage.north.host.com/v1/t1000",
89
"internalURL":"https://storage.north.internal/v1/t1000",
92
"versionInfo":"https://storage.north.host.com/v1/",
93
"versionList":"https://storage.north.host.com/"
97
"publicURL":"https://storage.south.host.com/v1/t1000",
98
"internalURL":"https://storage.south.internal/v1/t1000",
101
"versionInfo":"https://storage.south.host.com/v1/",
102
"versionList":"https://storage.south.host.com/"
107
"name":"DNS-as-a-Service",
108
"type":"dnsextension:dns",
111
"publicURL":"https://dns.host.com/v2.0/t1000",
113
"versionInfo":"https://dns.host.com/v2.0/",
114
"versionList":"https://dns.host.com/"
122
Note the following about this response:
124
#. There are two endpoints given to the Nova compute service. The only
125
difference between them is the version (1.0 vs. 1.1). This allows for code
126
written to look for the version 1.0 endpoint to still work even after the 1.1
129
#. There are two endpoints for the Swift object-store service. The difference
130
between them is they are in different regions (North and South).
132
#. Note the DNS service is global; it does not have a Region. Also, since DNS
133
is not a core OpenStack service, the endpoint type is "dnsextension:dns"
134
showing it is coming from an extension to the Keystone service.
136
#. The Region, Tenant, and versionId are listed under the endpoint. You do not
137
(and should not) have to parse those out of the URL. In fact, they may not be
138
embedded in the URL if the service developer so chooses.
141
What do the fields in an Endpoint mean?
142
---------------------------------------
144
The schema definition for an endpoint is in endpoints.xsd under
145
keystone/content/common/xsd in the Keystone code repo. The fields are:
148
A unique ID for the endpoint.
151
The OpenStack-registered type (ex. 'compute', 'object-store', 'image service')
152
This can also be extended using the OpenStack Extension mechanism to support
153
non-core services. Extended services will be in the form ``extension:type``
154
(e.g. ``dnsextension:dns``)
157
This can be anything that the operator of OpenStack chooses. It could be a
158
brand or marketing name (ex. Rackspace Cloud Servers).
161
This is a string that identifies the region where this endpoint exists.
162
Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or
163
'Data Center 1', 'Data Center 2'.
164
The list of regions and what a region means is decided by the operator. The
165
spec treats them as opaque strings.
168
This is the URL to use to access that endpoint over the internet.
171
This is the URL to use to communicate between services. This is genenrally
172
a way to communicate between services over a high bandwidth, low latency,
173
unmetered (free, no bandwidth charges) network. An example would be if you
174
want to access a swift cluster from inside your Nova VMs and want to make
175
sure the communication stays local and does not go over a public network
176
and rack up your bandwidth charges.
179
This is the URL to use to administer the service. In Keystone, this URL
180
is only shown to users with the appropriate rights.
183
If an endpoint is specific to a tenant, the tenantId field identifies the
184
tenant that URL applies to. Some operators include the tenant in the
185
URLs for a service, while others may provide one endpoint and use some
186
other mechanism to identify the tenant. This field is therefore optional.
187
Having this field also means you do not have to parse the URL to identify
188
a tenant if the operator includes it in the URL.
191
This identifies the version of the API contract that endpoint supports.
192
While many APIs include the version in the URL (ex: https://compute.host/v1),
193
this field allows you to identify the version without parsing the URL. It
194
therefore also allows operators and service developers to publish endpoints
195
that do not have versions embedded in the URL.
198
This is the URL to call to get some information on the version. This returns
199
information in this format::
205
"updated": "2011-01-21T11:33:21-06:00",
209
"href": "http://identity.api.openstack.org/v2.0/"
211
"rel": "describedby",
212
"type": "application/pdf",
213
"href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf"
215
"rel": "describedby",
216
"type": "application/vnd.sun.wadl+xml",
217
"href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl"
222
"base": "application/xml",
223
"type": "application/vnd.openstack.identity+xml;version=2.0"
225
"base": "application/json",
226
"type": "application/vnd.openstack.identity+json;version=2.0"
234
This is the URL to call to find out which versions are supported at that
235
endpoint. The response is in this format::
240
"status":"DEPRECATED",
241
"updated":"2009-10-09T11:30:00Z",
244
"href":"http://identity.api.openstack.org/v1.0/"
251
"updated":"2010-12-12T18:30:02.25Z",
254
"href":"http://identity.api.openstack.org/v1.1/"
261
"updated":"2011-05-27T20:22:02.25Z",
264
"href":"http://identity.api.openstack.org/v2.0/"
272
Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0.
273
It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA.
275
What are Endpoint Templates?
276
----------------------------
278
Endpoint Templates are a way for an administrator to manage endpoints en masse.
279
They provide a way to define Endpoints that apply to many or all tenants
280
without having to a create each endpoint on each tenant manually. Without
281
Endpoint Templates, if I wanted to create Endpoints for each tenant in my
282
OpenStack deployment, I'd have to manually create a bunch of endpoints on
283
each tenant (probably when I created the tenant). And then I'd have to go change
284
them all whenever a service changed versions or I added a new service.
286
To provide a simpler mechanism to manage endpoints on tenants, Keystone uses
287
Endpoint Templates. I can, for example, define a template with parametrized URLs
288
and set it's `global` to true and that will show up as an endpoint on all the tenants
289
I have. Here is an example:
291
Define a global Endpoint Template::
293
$ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1
295
The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global'
297
This creates a global endpoint (global means it gets applied to all tenants automatically).
299
Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example
300
authentication request for use against tenant 1::
302
$ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens
312
"internalURL": "https://compute.north.example.local",
313
"publicURL": "https://compute.north.example.com/v1/1/",
322
"expires": "2012-02-05T00:00:00",
323
"id": "887665443383838",
343
Notice the adminURL is not showing (this user is a regular user and does not
344
have rights to see the adminURL) and the tenant ID has been substituted in the
347
"publicURL": "https://compute.north.example.com/v1/1/",
349
This endpoint will show up for all tenants. The OpenStack administrator does
350
not need to create the endpoint manually.
352
.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are).
355
What parameters can I use in a Template URL
356
-------------------------------------------
358
Currently the only parameterization available is %tenant_id% which gets
359
substituted by the Tenant ID.
362
Endpoint Template Types: Global or not
363
--------------------------------------
365
When the global flag is set to true on an Endpoint Template, it means it should
366
be available to all tenants. Whenever someone authenticates to a tenant, they
367
will see the Endpoint generated by that template.
369
When the global flag is not set, the template only shows up when it is added to
370
a tenant manually. To add an endpoint to a tenant manually, you must create
371
the Endpoint and supply the Endpoint Template ID:
373
Create the Endpoint Template::
375
$ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0
377
Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating.
379
Find the Endpoint Template ID::
381
$ ./keystone-manage endpointTemplates list
383
All EndpointTemplates
384
id service type region enabled is_global Public URL Admin URL
385
-------------------------------------------------------------------------------
386
15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp
387
16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp
389
Add the Endpoint to the tenant::
391
$ ./keystone-manage endpoint add customer-x 16
393
Now, when the user authenticates, they get the endpoint::
396
"internalURL": "https://compute.west.example.local",
397
"publicURL": "https://compute.west.example.com/v1/1/",
401
Who can see the AdminURL?
402
-------------------------
404
Users who have the Keystone `Admin` or `Service Admin` roles will see the
405
AdminURL when they authenticate or when they retrieve token information:
407
Using an administrator token to authenticate, GET a client token's endpoints::
409
$ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints
414
"adminURL": "https://compute.west.example.corp",
416
"internalURL": "https://compute.west.example.local",
418
"publicURL": "https://compute.west.example.com/v1/1/",
426
"href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10",
added
removed
doc/source/endpoints.rst
