openstack
/
service-types-authority
Code Issues Proposed changes
OpenStack Service Types Authority
43 Commits 1 Branch 0 Tags 961 KiB
Python 100%
Go to file
Monty Taylor 55831f8b2f
Add flag to indicate a service is a secondary service 
In cases where one project provices more than one service, answering the
question "what service-type corresponds with this project name?" becomes
hard. In the one existing example, nova with compute and placement, if
someone asks "what is the service-type associated with 'nova'?" - they
mean compute.

Allow for marking a service as secondary so that data consumption
routines can know.

Change-Id: I9434dc22b5f268fa4035b417e4062f58096ebc40
 		2017-08-15 07:38:08 -05:00
doc/source Ensure git rev-parse output works in python3 2017-08-14 18:34:45 -05:00
.gitignore Add script to prepare data for publication 2017-07-05 16:09:27 -05:00
.gitreview Added .gitreview 2016-02-15 18:01:07 +00:00
README.rst Add flag to indicate a service is a secondary service 2017-08-15 07:38:08 -05:00
publish.py Stop publishing yaml file 2017-07-07 13:04:31 -05:00
published-schema.json Fix regexes in published-schema.json 2017-06-27 16:56:03 -05:00
requirements.txt Add script to prepare data for publication 2017-07-05 16:09:27 -05:00
schema.json Add flag to indicate a service is a secondary service 2017-08-15 07:38:08 -05:00
service-types.yaml Use consistent url schemes 2017-08-14 18:35:04 -05:00
setup.cfg Add validation and publication infrastructure 2017-05-04 15:36:50 +00:00
setup.py Add validation and publication infrastructure 2017-05-04 15:36:50 +00:00
tox.ini Ensure git rev-parse output works in python3 2017-08-14 18:34:45 -05:00
transform.py Ensure git rev-parse output works in python3 2017-08-14 18:34:45 -05:00
validate.py Remove validate.py main() 2017-07-06 21:00:01 +00:00

README.rst

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://git.openstack.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. By default this should be http://developer.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

Service types should be:

  • English words
  • Match the regex ^[a-z][a-z-]*[a-z]$. As a special case, ec2-api is also allowed.
  • Meaningful
  • Not use terms which are incredibly overloaded in OpenStack space (e.g. policy)
  • A thing, not an action (e.g. load-balancer, not load-balancing)
  • Singular instead of plural (e.g. image, not images)
  • 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.