OpenStack Service Types Authority
Go to file
2024-05-08 19:24:41 +00:00
doc/source Switch to newer openstackdocstheme version 2020-06-10 16:09:27 +02:00
.gitignore Add script to prepare data for publication 2017-07-05 16:09:27 -05:00
.gitreview OpenDev Migration Patch 2019-04-19 19:44:04 +00:00
.zuul.yaml Switch service-types-authority-tox-publish for promote 2020-02-18 22:06:48 +01:00
publish.py Small cleanups 2020-02-18 21:57:35 +01:00
published-schema.json Add three more transformations 2017-08-15 07:38:59 -05:00
README.rst Small cleanups 2020-02-18 21:57:35 +01:00
requirements.txt Switch to newer openstackdocstheme version 2020-06-10 16:09:27 +02:00
schema.json Add flag to indicate a service is a secondary service 2017-08-15 07:38:08 -05:00
service-types.yaml Drop override for venus api-ref 2024-05-08 18:11:47 +00:00
setup.cfg Cleanup py27 support 2020-04-11 16:24:10 +02:00
setup.py Set py_modules to an empty list in setup.py 2022-09-13 13:45:56 +02:00
tox.ini Correct the tox option for skipping sdist generation 2024-05-08 18:13:19 +00:00
transform.py Update api-ref location 2019-07-22 20:56:53 +02:00
validate.py Add three more transformations 2017-08-15 07:38:59 -05:00

Service Types Authority

The following is a central authority for handing out service types to projects for their services.

Each OpenStack service with a REST API must have a well known service type. The well known service type guarantees a documented API is available for that service. Users of this service can trust that it will be the same between different OpenStack environments.

Attributes

The following attributes are required for a service type registration:

service-type (required)

The unique identifier for the service to be used in the service catalog.

project (required)

The name of the OpenStack project that contains the definition of the API claimed by this service type. OpenStack project source code is found in https://opendev.org/openstack/{project}. If the API reference docs are not found in the project repository, the api_reference_project field can be used to indicate the repository in which they are found.

api_reference (required)

A published API reference document for the API identified by this service type. If not specified in the source yaml file, it will be generated as https://docs.openstack.org/api-ref/{service-type}/.

api_reference_project (optional)

An OpenStack git project holding the source code for the project's API reference.

description (optional)

A short description about the service in question. It helps people reading only this document.

aliases (optional)

An ordered list of historical aliases for this service type.

Note

The list of aliases is only for communicating the existing set of other names that services have gone by from the time before this list existed. Changing a service-type is VERY BAD and breaks users. It's important to list them so that everyone can share in the knowledge of what to do with the clouds that are out there, but seriously, putting things here is only for documenting history, not for making new changes.

A service must have one and only one known service type. However, there are older names that have been commonly used for some services. In order for API consumers to be able to count on the Service Types Authority service-type as an inbound interface they expect, aliases provides a ordered list of known fallback names. If an API consumer cannot find a given service-type in the service-catalog, they are directed to try the list of aliases here, in the order they are given, in order to find the requested endpoint.

secondary (optional)

If secondary is set and is true, the project is not the primary service people associate with the project codename. For instance, the nova project has two services, compute and placement. compute is the primary project. placement is secondary.

Naming

Note

Established service types need not be forcefully retrofitted to conform to these guidelines. For this reason you may see entries such as ec2-api (contains a digit) or clustering (an action, not a thing).

New service type names should:

  • Be English words
  • Match the regex ^[a-z][a-z-]*[a-z]$.
  • Be meaningful
  • Not use terms which are incredibly overloaded in OpenStack space (e.g. policy)
  • Be a thing, not an action (e.g. load-balancer, not load-balancing)
  • Be singular instead of plural (e.g. image, not images)
  • Be unversioned (e.g. volume, not volumev2)

Non Official Types in Service Catalog

The OpenStack Service Catalog can be used for listing services outside of the standardized service types. There will be no official registry of these types, so conflicts are possible. As such, the types should include an org prefix '$org:' where $org is something recognizable to a particular organization and not part of the OpenStack ecosystem.