511 lines
15 KiB
ReStructuredText
511 lines
15 KiB
ReStructuredText
..
|
|
Copyright (c) 2014 Hewlett-Packard Development Company, L.P.
|
|
|
|
|
|
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.
|
|
|
|
Using Glance's Metadata Definitions Catalog Public APIs
|
|
=======================================================
|
|
|
|
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.
|
|
|
|
Glance Metadata Definitions Catalog implementation started with API version v2.
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
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 :doc:`authentication` for more information on integrating with Keystone.
|
|
|
|
Using v2.X
|
|
----------
|
|
|
|
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.
|
|
|
|
List Available Namespaces
|
|
*************************
|
|
|
|
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 images.
|
|
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",
|
|
"property_count": 0,
|
|
"object_count": 2,
|
|
"resource_types": [
|
|
{
|
|
"name": "OS::Nova::Aggregate"
|
|
},
|
|
{
|
|
"name": "OS::Nova::Flavor",
|
|
"prefix": "aggregate_instance_extra_specs:"
|
|
}
|
|
],
|
|
"visibility": "public",
|
|
"protected": true,
|
|
"owner": "The Test Owner"
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
.. 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.
|
|
|
|
Filtering Namespaces Lists
|
|
**************************
|
|
|
|
``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 image 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).
|
|
|
|
|
|
Retrieve Namespace
|
|
******************
|
|
|
|
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",
|
|
"property_count": 2,
|
|
"object_count": 2,
|
|
"resource_types": [
|
|
{
|
|
"name": "OS::Glance::Image",
|
|
"prefix": "hw_"
|
|
},
|
|
{
|
|
"name": "OS::Cinder::Volume",
|
|
"prefix": "hw_",
|
|
"properties_target": "image"
|
|
},
|
|
{
|
|
"name": "OS::Nova::Flavor",
|
|
"prefix": "filter1:"
|
|
}
|
|
],
|
|
"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",
|
|
"properties": {
|
|
"prop1": {
|
|
"title": "My object1 property1",
|
|
"description": "More info here",
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"readonly": false
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "object2",
|
|
"description": "my-description",
|
|
"properties": {
|
|
"prop1": {
|
|
"title": "My object2 property1",
|
|
"description": "More info here",
|
|
"type": "integer",
|
|
"default": 20
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"visibility": "public",
|
|
"protected": true,
|
|
"owner": "The Test Owner"
|
|
}
|
|
|
|
Retrieve available Resource Types
|
|
*********************************
|
|
|
|
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::
|
|
|
|
[
|
|
"OS::Cinder::Volume",
|
|
"OS::Glance::Image",
|
|
"OS::Nova::Flavor",
|
|
"OS::Neutron::Subnet"
|
|
]
|
|
|
|
|
|
Retrieve Resource Types associated with a Namespace
|
|
***************************************************
|
|
|
|
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_types" : [
|
|
{
|
|
"name" : "OS::Glance::Image",
|
|
"prefix" : "hw_"
|
|
},
|
|
{
|
|
"name" :"OS::Cinder::Volume",
|
|
"prefix" : "hw_",
|
|
"properties_target" : "image"
|
|
},
|
|
{
|
|
"name" : "OS::Nova::Flavor",
|
|
"prefix" : "hw:"
|
|
}
|
|
]
|
|
}
|
|
|
|
Add Namespace
|
|
*************
|
|
|
|
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 types could be added in the
|
|
same input. See GET Namespace output above.
|
|
|
|
Update Namespace
|
|
****************
|
|
|
|
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
|
|
|
|
|
|
Delete 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}
|
|
|
|
|
|
Remove Resource Type associated with a Namespace
|
|
************************************************
|
|
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}
|
|
|
|
List Objects in Namespace
|
|
*************************
|
|
|
|
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": "object1-description",
|
|
"properties": {
|
|
"prop1": {
|
|
"title": "My Property",
|
|
"description": "More info here",
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"name": "object2",
|
|
"description": "object2-description",
|
|
"properties": {
|
|
"prop1": {
|
|
"title": "My Property",
|
|
"description": "More info here",
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"schema": "/schema/metadefs/objects"
|
|
}
|
|
|
|
Add object in a specific namespace
|
|
**********************************
|
|
|
|
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
|
|
}
|
|
}
|
|
}
|
|
|
|
Update Object in a specific namespace
|
|
*************************************
|
|
|
|
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
|
|
|
|
|
|
Delete Object in a specific namespace
|
|
*************************************
|
|
|
|
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}
|
|
|
|
|
|
Add property definition in a specific namespace
|
|
***********************************************
|
|
|
|
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"
|
|
]
|
|
}
|
|
}
|
|
|
|
|
|
Update property definition in a specific namespace
|
|
**************************************************
|
|
|
|
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
|
|
|
|
|
|
Delete property definition in a specific namespace
|
|
**************************************************
|
|
|
|
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}
|
|
|
|
|
|
API Message Localization
|
|
------------------------
|
|
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.
|
|
|
|
How to use it
|
|
*************
|
|
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/images/aaa
|
|
|
|
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.
|