A common API hosted by the Glance service for vendors, admins, services, and users to meaningfully define available key / value pair and tag metadata. The intent is to enable better metadata collaboration across artifacts, services, and projects for OpenStack users.
This is about the definition of the available metadata that can be used on different types of resources (images, artifacts, volumes, flavors, aggregates, etc). A definition includes the properties type, its key, it’s description, and it’s constraints. This catalog will not store the values for specific instance properties.
For example, a definition of a virtual CPU topology property for number of cores will include the key to use, a description, and value constraints like requiring it to be an integer. So, a user, potentially through Horizon, would be able to search this catalog to list the available properties they can add to a flavor or image. They will see the virtual CPU topology property in the list and know that it must be an integer. In the Horizon example, when the user adds the property, its key and value will be stored in the service that owns that resource (Nova for flavors and in Glance for images).
Diagram: https://wiki.openstack.org/w/images/b/bb/Glance-Metadata-API.png
Glance Metadata Definitions Catalog implementation started with API version v2.
Glance depends on Keystone and the OpenStack Identity API to handle authentication of clients. You must obtain an authentication token from Keystone send it along with all API requests to Glance through the X-Auth-Token header. Glance will communicate back to Keystone to verify the token validity and obtain your identity credentials.
See Authentication With Keystone for more information on integrating with Keystone.
For the purpose of examples, assume there is a Glance API server running at the URL http://glance.example.com on the default port 80.
We want to see a list of available namespaces that the authenticated user has access to. This includes namespaces owned by the user, namespaces shared with the user and public namespaces.
We issue a GET request to http://glance.example.com/v2/metadefs/namespaces to retrieve this list of available namespaces. The data is returned as a JSON-encoded mapping in the following format:
{
"namespaces": [
{
"namespace": "MyNamespace",
"display_name": "My User Friendly Namespace",
"description": "My description",
"visibility": "public",
"protected": true,
"owner": "The Test Owner",
"self": "/v2/metadefs/namespaces/MyNamespace",
"schema": "/v2/schemas/metadefs/namespace",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z",
"resource_type_associations": [
{
"name": "OS::Nova::Aggregate",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z"
},
{
"name": "OS::Nova::Flavor",
"prefix": "aggregate_instance_extra_specs:",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z"
}
]
}
],
"first": "/v2/metadefs/namespaces?sort_key=created_at&sort_dir=asc",
"schema": "/v2/schemas/metadefs/namespaces"
}
Note
Listing namespaces will only show the summary of each namespace including counts and resource type associations. Detailed response including all its objects definitions, property definitions etc. will only be available on each individual GET namespace request.
GET /v2/metadefs/namespaces requests take query parameters that serve to filter the returned list of namespaces. The following list details these query parameters.
resource_types=RESOURCE_TYPES
Filters namespaces having a resource_types within the list of comma separated RESOURCE_TYPES.
GET resource also accepts additional query parameters:
sort_key=KEY
Results will be ordered by the specified sort attribute KEY. Accepted values include namespace, created_at (default) and updated_at.
sort_dir=DIR
Results will be sorted in the direction DIR. Accepted values are asc for ascending or desc (default) for descending.
marker=NAMESPACE
A namespace identifier marker may be specified. When present only namespaces which occur after the identifier NAMESPACE will be listed, i.e. the namespaces which have a sort_key later than that of the marker NAMESPACE in the sort_dir direction.
limit=LIMIT
When present the maximum number of results returned will not exceed LIMIT.
Note
If the specified LIMIT exceeds the operator defined limit (api_limit_max) then the number of results returned may be less than LIMIT.
visibility=PUBLIC
An admin user may use the visibility parameter to control which results are returned (PRIVATE or PUBLIC).
We want to see a more detailed information about a namespace that the authenticated user has access to. The detail includes the properties, objects, and resource type associations.
We issue a GET request to http://glance.example.com/v2/metadefs/namespaces/{namespace} to retrieve the namespace details. The data is returned as a JSON-encoded mapping in the following format:
{
"namespace": "MyNamespace",
"display_name": "My User Friendly Namespace",
"description": "My description",
"visibility": "public",
"protected": true,
"owner": "The Test Owner",
"schema": "/v2/schemas/metadefs/namespace",
"resource_type_associations": [
{
"name": "OS::Glance::Image",
"prefix": "hw_",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z"
},
{
"name": "OS::Cinder::Volume",
"prefix": "hw_",
"properties_target": "image",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z"
},
{
"name": "OS::Nova::Flavor",
"prefix": "filter1:",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z"
}
],
"properties": {
"nsprop1": {
"title": "My namespace property1",
"description": "More info here",
"type": "boolean",
"default": true
},
"nsprop2": {
"title": "My namespace property2",
"description": "More info here",
"type": "string",
"default": "value1"
}
},
"objects": [
{
"name": "object1",
"description": "my-description",
"self": "/v2/metadefs/namespaces/MyNamespace/objects/object1",
"schema": "/v2/schemas/metadefs/object",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z",
"required": [],
"properties": {
"prop1": {
"title": "My object1 property1",
"description": "More info here",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"name": "object2",
"description": "my-description",
"self": "/v2/metadefs/namespaces/MyNamespace/objects/object2",
"schema": "/v2/schemas/metadefs/object",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z",
"properties": {
"prop1": {
"title": "My object2 property1",
"description": "More info here",
"type": "integer",
"default": 20
}
}
}
]
}
We want to see the list of all resource types that are available in Glance
We issue a GET request to http://glance.example.com/v2/metadefs/resource_types to retrieve all resource types.
The data is returned as a JSON-encoded mapping in the following format:
{
"resource_types": [
{
"created_at": "2014-08-28T17:13:04Z",
"name": "OS::Glance::Image",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"created_at": "2014-08-28T17:13:04Z",
"name": "OS::Cinder::Volume",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"created_at": "2014-08-28T17:13:04Z",
"name": "OS::Nova::Flavor",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"created_at": "2014-08-28T17:13:04Z",
"name": "OS::Nova::Aggregate",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"created_at": "2014-08-28T17:13:04Z",
"name": "OS::Nova::Server",
"updated_at": "2014-08-28T17:13:04Z"
}
]
}
We want to see the list of resource types that are associated for a specific namespace
We issue a GET request to http://glance.example.com/v2/metadefs/namespaces/{namespace}/resource_types to retrieve resource types.
The data is returned as a JSON-encoded mapping in the following format:
{
"resource_type_associations" : [
{
"name" : "OS::Glance::Image",
"prefix" : "hw_",
"created_at": "2014-08-28T17:13:04Z",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"name" :"OS::Cinder::Volume",
"prefix" : "hw_",
"properties_target" : "image",
"created_at": "2014-08-28T17:13:04Z",
"updated_at": "2014-08-28T17:13:04Z"
},
{
"name" : "OS::Nova::Flavor",
"prefix" : "hw:",
"created_at": "2014-08-28T17:13:04Z",
"updated_at": "2014-08-28T17:13:04Z"
}
]
}
We want to create a new namespace that can contain the properties, objects, etc.
We issue a POST request to add an namespace to Glance:
POST http://glance.example.com/v2/metadefs/namespaces/
The input data is an JSON-encoded mapping in the following format:
{
"namespace": "MyNamespace",
"display_name": "My User Friendly Namespace",
"description": "My description",
"visibility": "public",
"protected": true
}
Note
Optionally properties, objects and resource type associations could be added in the same input. See GET Namespace output above(input will be similar).
We want to update an existing namespace
We issue a PUT request to update an namespace to Glance:
PUT http://glance.example.com/v2/metadefs/namespaces/{namespace}
The input data is similar to Add Namespace
We want to delete an existing namespace including all its objects, properties etc.
We issue a DELETE request to delete an namespace to Glance:
DELETE http://glance.example.com/v2/metadefs/namespaces/{namespace}
We want to associate a resource type with an existing namespace
We issue a POST request to associate resource type to Glance:
POST http://glance.example.com/v2/metadefs/namespaces/{namespace}/resource_types
The input data is an JSON-encoded mapping in the following format:
{
"name" :"OS::Cinder::Volume",
"prefix" : "hw_",
"properties_target" : "image",
"created_at": "2014-08-28T17:13:04Z",
"updated_at": "2014-08-28T17:13:04Z"
}
We want to de-associate namespace from a resource type
We issue a DELETE request to de-associate namespace resource type to Glance:
DELETE http://glance.example.com/v2//metadefs/namespaces/{namespace}/resource_types/{resource_type}
We want to see the list of meta definition objects in a specific namespace
We issue a GET request to http://glance.example.com/v2/metadefs/namespaces/{namespace}/objects to retrieve objects.
The data is returned as a JSON-encoded mapping in the following format:
{
"objects": [
{
"name": "object1",
"description": "my-description",
"self": "/v2/metadefs/namespaces/MyNamespace/objects/object1",
"schema": "/v2/schemas/metadefs/object",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z",
"required": [],
"properties": {
"prop1": {
"title": "My object1 property1",
"description": "More info here",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"name": "object2",
"description": "my-description",
"self": "/v2/metadefs/namespaces/MyNamespace/objects/object2",
"schema": "/v2/schemas/metadefs/object",
"created_at": "2014-08-28T17:13:06Z",
"updated_at": "2014-08-28T17:13:06Z",
"properties": {
"prop1": {
"title": "My object2 property1",
"description": "More info here",
"type": "integer",
"default": 20
}
}
}
],
"schema": "/v2/schemas/metadefs/objects"
}
We want to create a new object which can group the properties
We issue a POST request to add object to a namespace in Glance:
POST http://glance.example.com/v2/metadefs/namespaces/{namespace}/objects
The input data is an JSON-encoded mapping in the following format:
{
"name": "StorageQOS",
"description": "Our available storage QOS.",
"required": [
"minIOPS"
],
"properties": {
"minIOPS": {
"type": "integer",
"description": "The minimum IOPs required",
"default": 100,
"minimum": 100,
"maximum": 30000369
},
"burstIOPS": {
"type": "integer",
"description": "The expected burst IOPs",
"default": 1000,
"minimum": 100,
"maximum": 30000377
}
}
}
We want to update an existing object
We issue a PUT request to update an object to Glance:
PUT http://glance.example.com/v2/metadefs/namespaces/{namespace}/objects/{object_name}
The input data is similar to Add Object
We want to delete an existing object.
We issue a DELETE request to delete object in a namespace to Glance:
DELETE http://glance.example.com/v2/metadefs/namespaces/{namespace}/objects/{object_name}
We want to create a new property definition in a namespace
We issue a POST request to add property definition to a namespace in Glance:
POST http://glance.example.com/v2/metadefs/namespaces/{namespace}/properties
The input data is an JSON-encoded mapping in the following format:
{
"name": "hypervisor_type",
"title" : "Hypervisor",
"type": "array",
"description": "The type of hypervisor required",
"items": {
"type": "string",
"enum": [
"hyperv",
"qemu",
"kvm"
]
}
}
We want to update an existing object
We issue a PUT request to update an property definition in a namespace to Glance:
PUT http://glance.example.com/v2/metadefs/namespaces/{namespace}/properties/{property_name}
The input data is similar to Add property definition
We want to delete an existing object.
We issue a DELETE request to delete property definition in a namespace to Glance:
DELETE http://glance.example.com/v2/metadefs/namespaces/{namespace}/properties/{property_name}
Glance supports HTTP message localization. For example, an HTTP client can receive API messages in Chinese even if the locale language of the server is English.
To receive localized API messages, the HTTP client needs to specify the Accept-Language header to indicate the language to use to translate the message. For more info about Accept-Language, please refer http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
A typical curl API request will be like below:
curl -i -X GET -H 'Accept-Language: zh' -H 'Content-Type: application/json'
http://127.0.0.1:9292/v2/metadefs/namespaces/{namespace}
Then the response will be like the following:
HTTP/1.1 404 Not Found
Content-Length: 234
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-54d403a0-064e-4544-8faf-4aeef086f45a
Date: Sat, 22 Feb 2014 06:26:26 GMT
<html>
<head>
<title>404 Not Found</title>
</head>
<body>
<h1>404 Not Found</h1>
找不到任何具有标识 aaa 的映像<br /><br />
</body>
</html>
Note
Be sure there is the language package under /usr/share/locale-langpack/ on the target Glance server.