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.

Service Data¶

Source Data¶

The Service Types Authority information is maintained in YAML for ease of human interactions and so that comments can be used if needed.

services:
- service_type: identity
  project: keystone
- service_type: compute
  project: nova
- service_type: image
  project: glance
- service_type: load-balancer
  project: octavia
- service_type: object-store
  project: swift
- service_type: clustering
  project: senlin
  aliases:
  - resource-cluster
  - cluster
- service_type: data-processing
  project: sahara
- service_type: baremetal
  project: ironic
  aliases:
  - bare-metal
- service_type: baremetal-introspection
  project: ironic-inspector
  api_reference: https://docs.openstack.org/ironic-inspector/latest/user/http-api.html
- service_type: key-manager
  project: barbican
  api_reference: https://docs.openstack.org/barbican/latest/api/
- service_type: ec2-api
  project: ec2-api
- service_type: resource-optimization
  project: watcher
  aliases:
  - infra-optim
- service_type: message
  project: zaqar
  aliases:
  - messaging
- service_type: application-catalog
  project: murano
- service_type: container-infrastructure-management
  project: magnum
  aliases:
  - container-infrastructure
  - container-infra
- service_type: search
  project: searchlight
- service_type: dns
  project: designate
- service_type: workflow
  project: mistral
  api_reference: https://docs.openstack.org/mistral/latest/api/index.html
  aliases:
  - workflowv2
- service_type: rating
  project: cloudkitty
  api_reference: https://docs.openstack.org/cloudkitty/latest/api-reference/index.html
- service_type: operator-policy
  project: congress
  api_reference: https://docs.openstack.org/congress/latest/user/api.html
  aliases:
  - policy
- service_type: shared-file-system
  project: manila
  aliases:
  - sharev2
  - share
- service_type: data-protection-orchestration
  project: karbor
- service_type: orchestration
  project: heat
- service_type: block-storage
  project: cinder
  aliases:
  - volumev3
  - volumev2
  - volume
  - block-store
- service_type: alarm
  project: aodh
  api_reference: https://docs.openstack.org/developer/aodh/webapi/index.html
  aliases:
  - alarming
- service_type: meter
  project: ceilometer
  api_reference: https://docs.openstack.org/developer/ceilometer/webapi/index.html
  aliases:
  - metering
  - telemetry
- service_type: event
  project: panko
  api_reference: https://docs.openstack.org/developer/panko/webapi/index.html
  aliases:
  - events
- service_type: application-deployment
  project: solum
  api_reference: https://docs.openstack.org/solum/latest/admin/webapi/index.html
  aliases:
  - application_deployment
- service_type: multi-region-network-automation
  project: tricircle
  api_reference: https://docs.openstack.org/tricircle/latest/admin/api_v1.html
  aliases:
  - tricircle
- service_type: database
  project: trove
- service_type: application-container
  project: zun
  aliases:
  - container
- service_type: log-management
  project: venus
- service_type: root-cause-analysis
  project: vitrage
  api_reference: https://docs.openstack.org/vitrage/latest/contributor/vitrage-api.html
  aliases:
  - rca
- service_type: nfv-orchestration
  project: tacker
- service_type: network
  project: neutron
  api_reference_project: neutron-lib
- service_type: backup
  project: freezer-api
- service_type: monitoring-logging
  project: monasca-log-api
  aliases:
  - monitoring-log-api
- service_type: monitoring
  project: monasca-api
- service_type: monitoring-events
  project: monasca-events-api
- service_type: placement
  project: placement
- service_type: instance-ha
  aliases:
  - ha
  project: masakari
- service_type: reservation
  project: blazar
- service_type: function-engine
  project: qinling
- service_type: accelerator
  project: cyborg
- service_type: admin-logic
  project: adjutant
  aliases:
  - registration

It is described by a Service Types Authority Schema.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "https://specs.openstack.org/openstack/service-types-authority/_downloads/schema.json#",
  "type": "object",
  "required": ["services"],
  "additionalProperties": false,
  "properties": {
    "services": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/service"
      }
    }
  },
   "definitions":{
      "service":{
         "properties": {
            "service_type": {
               "type":"string",
               "pattern":"^([a-z][a-z-]*[a-z]+|ec2-api)$",
               "description": "The unique identifier for the service to be used in the service catalog"
            },
            "project": {
               "type":"string",
               "pattern":"^([a-z][a-z-]*[a-z]+|ec2-api)$",
               "description": "The OpenStack project name that contains the definition of the API"
            },
            "api_reference": {
               "type":"string",
               "format": "url",
               "description": "A published API reference document for the API identified by this service type."
            },
            "api_reference_project": {
               "type":"string",
               "description": "Project where API reference is found, if not the same as the main project"
            },
            "description": {
               "type":"string",
               "description": "A short description about the service in question."
            },
            "aliases": {
               "type": "array",
               "items": {
                 "type": "string"
               },
               "description": "An ordered list of historical aliases for this service type."
            },
            "secondary": {
                "type": "boolean",
                "description": "Is this a secondary service for a project?"
            }
         },
         "additionalProperties":false,
         "required":[
            "api_reference",
            "project",
            "service_type"
         ]
      }
   }
}

Publication¶

The information is also transformed into a JSON format and published to https://service-types.openstack.org/service-types.json for ease of machine interactions. The published format is different than the source format.

The published format contains five keys.

version: An ISO Format Date Time string of the build time in UTC.
sha: The git sha from which the file was built.
service_types: A list of all of the official service types.
forward: A mapping of official service type to aliases. Only contains entries for services that have aliaes.
reverse: A mapping of aliases to official service type.
primary_service_by_project: A mapping of project names to the primary service associated with that project. Every project has only one primary service.
all_types_by_service_type: A mapping of service type to a list containing the official service type and all of its aliases. Contains an entry for every service.
service_types_by_project: A mapping of project name to a list of all service types associated with that project.

The published format is described by a Service Types Authority Published Schema.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "https://specs.openstack.org/openstack/service-types-authority/_downloads/schema.json#",
  "type": "object",
  "required": ["services"],
  "additionalProperties": false,
  "properties": {
    "services": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/service"
      }
    }
  },
   "definitions":{
      "service":{
         "properties": {
            "service_type": {
               "type":"string",
               "pattern":"^([a-z][a-z-]*[a-z]+|ec2-api)$",
               "description": "The unique identifier for the service to be used in the service catalog"
            },
            "project": {
               "type":"string",
               "pattern":"^([a-z][a-z-]*[a-z]+|ec2-api)$",
               "description": "The OpenStack project name that contains the definition of the API"
            },
            "api_reference": {
               "type":"string",
               "format": "url",
               "description": "A published API reference document for the API identified by this service type."
            },
            "api_reference_project": {
               "type":"string",
               "description": "Project where API reference is found, if not the same as the main project"
            },
            "description": {
               "type":"string",
               "description": "A short description about the service in question."
            },
            "aliases": {
               "type": "array",
               "items": {
                 "type": "string"
               },
               "description": "An ordered list of historical aliases for this service type."
            },
            "secondary": {
                "type": "boolean",
                "description": "Is this a secondary service for a project?"
            }
         },
         "additionalProperties":false,
         "required":[
            "api_reference",
            "project",
            "service_type"
         ]
      }
   }
}

Service Types Authority

Service Types Authority¶

Attributes¶

service-type (required)¶

project (required)¶

api_reference (required)¶

api_reference_project (optional)¶

description (optional)¶

aliases (optional)¶

secondary (optional)¶

Naming¶

Non Official Types in Service Catalog¶

Service Data¶

Source Data¶

Publication¶

Service Types Authority

Page Contents