.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ======================== Service Catalog Overview ======================== The OpenStack keystone service catalog allows API clients to dynamically discover and navigate to cloud services. The service catalog may differ from deployment-to-deployment, user-to-user, and project-to-project. The service catalog is the first hurdle that API consumers will need to understand after successfully authenticating with Keystone, making it a critical focal point for the overall user experience of OpenStack. *If you're integrating your OpenStack service with Keystone*, then please follow the guidelines provided below. *If you're writing an OpenStack client*, hopefully this helps you navigate the service catalog that you're being presented so that you can quickly move on to the business of consuming cloud services. An example service catalog ========================== The following is an example service catalog. It actually excludes several common attributes such as ``id``, which are of no concern to end users, ``region_id``, which are a bit out of scope for this topic, and ``enabled``, which is always ``true`` for end users. This service catalog contains just one service, "Keystone", which is accessible via a single endpoint URL: .. code-block:: json { "catalog": [ { "name": "Keystone", "type": "identity", "endpoints": [ { "interface": "public", "url": "https://identity.example.com:5000/" } ] } ] } The service catalog itself may appear in a token creation response (``POST /v3/auth/tokens``), a token validation response (``GET /v3/auth/tokens``), or as a standalone resource (``GET /v3/auth/catalog``). Services ======== The service catalog itself is composed of a list of services. Service entities represent web services in the OpenStack deployment. A service may have zero or more endpoints associated with it, although a service with zero endpoints is essentially useless in an OpenStack configuration. In addition to the related endpoints, there are two attributes of services that important to end users: * ``name`` (string): user-facing name of the service This attribute is not intended to be machine-parseable or otherwise meaningful beyond branding or name-recognition for end users. Logical values might include "Keystone" or maybe "Brand X Public Cloud Identity Service". Deployers should be free to rename, and therefore rebrand, a service at will. * ``type`` (string): describes the API implemented by the service. To support future projects, the value should not be validated against a list. An OpenStack-wide effort to standardize service types has been done outside of Keystone and is known as the `service-types authority`_. This should not convey the version of the API implemented by the service (as in Cinder's ``volumev2`` service type) because both the ``volume`` service and ``volumev2`` service provide "block storage as a service" which is what the service type is meant to convey. The underlying implementation is completely irrelevant here. In the general case, there should only be one service in a deployment per service type, although Keystone does not enforce this today. .. _service-types authority: https://service-types.openstack.org/ Endpoints ========= Each service should have one or more related endpoints. An endpoint is essentially a base URL for an API, along with some metadata about the endpoint itself and represents a set of URL endpoints for OpenStack web services. * ``interface`` (string): describes the visibility of the endpoint according to one of three values (``public``, ``internal``, and ``admin``) ``public`` endpoints are intended for consumption by end users or other service users, generally on a publicly available network interface. ``internal`` endpoints are intended for consumption by end users, generally on an unmetered internal network interface. ``admin`` endpoints are intended only for consumption by those needing administrative access to the service, generally on a secure network interface. You might also think of each interface value as the result of a matrix of use cases: * **Public API** on a **public network**: use a ``public`` interface. * **Public API** on an **internal network**: use an ``internal`` interface. * **Privileged API** on a **public network**: unsupported! Use access controls on your ``public`` endpoint instead. * **Privileged API** on an **internal network**: ``admin`` interface, but use access controls on your ``public`` endpoint instead. The notion of a "privileged API" endpoint makes security-conscious developers instantly lazy (security becomes someone else's problem), and is an obvious attack vector if someone were to infiltrate your internal network. It also adds more complexity to your API architecture which makes documentation, testing, and API evolution that much more difficult. * ``url`` (string): fully qualified URL of the service endpoint This should be unversioned base URL for an API. Good examples include ``https://identity.example.com:5000/`` and ``https://keystone.example.com/``. Conversely, ``https://identity.example.com:5000/v3/`` is an unfortunate example because it directs all clients to connect to a versioned endpoint, regardless of which API versions they understand. This makes it hard for services to do any sort of API versioning, and for clients to dynamically discover additional available versions. For a period of time, keystone was stuck in a position where it implements a ``/v3/`` API, but for backwards compatibility with existing v2 clients, was forced to continue advertising the ``/v2.0/`` endpoint in the service catalog until it was reasonable to assume that all clients in the ecosystem are capable of handling an unversioned URL. As a side effect, this has had a tremendous impact on the awareness of, and thus adoption of, Keystone's Identity API v3 (which has been enabled by default — and stable — since the 2013.1 Grizzly release). Don't put your project in that position! Similarly, ``https://object-store.example.com/v1/KEY_\$(project_id)s`` (which would ultimately be rendered to clients as a project-specific URL, such as ``https://object-store.example.com/v1/KEY_d12af07f4e2c4390a21acc31517ebec9``) is an unfortunate example because not only does it hardcode an API version as in the above example, but it also exposes the client's project ID directly to the client. Instead, the operational scope or a request can be determined by inspecting the user's token or consuming values populated by ``keystonemiddleware.auth_token``. It's also far less cacheable than a URL that is neither project nor user specific, which is important given that every client needs access to consume the service catalog prior to nearly every API request.