Include Metadata Defs Concepts in Dev Docs
The http://docs.openstack.org/developer/glance/ site currently doesn't include the Juno Metadata Definitions concepts. This patch adds an overview of the concepts to this site. This provides a synopis of the concepts in: https://github.com/openstack/glance-specs/blob/master/specs/juno/metadata-schema-catalog.rst DocImpact Closes-Bug: 1367432 Related-Bug: 1367908 Related-Bug: 1363615 Related-Bug: 1366286 Related-Bug: 1363383 Change-Id: Iad4d388cbbf2f63fa243d04d35032de0cb0bc1b4
This commit is contained in:
Travis Tripp
parent
e550cac697
commit
0aab5e2716
@ -17,7 +17,11 @@
|
|||||||
Welcome to Glance's documentation!
|
Welcome to Glance's documentation!
|
||||||
==================================
|
==================================
|
||||||
|
|
||||||
The Glance project provides services for discovering, registering, and
|
The Glance project provides a service where users can upload and discover
|
||||||
|
data assets that are meant to be used with other services. This currently
|
||||||
|
includes images and metadata definitions.
|
||||||
|
|
||||||
|
Glance image services include discovering, registering, and
|
||||||
retrieving virtual machine images. Glance has a RESTful API that allows
|
retrieving virtual machine images. Glance has a RESTful API that allows
|
||||||
querying of VM image metadata as well as retrieval of the actual image.
|
querying of VM image metadata as well as retrieval of the actual image.
|
||||||
|
|
||||||
@ -50,6 +54,7 @@ Concepts
|
|||||||
statuses
|
statuses
|
||||||
formats
|
formats
|
||||||
common-image-properties
|
common-image-properties
|
||||||
|
metadefs-concepts
|
||||||
|
|
||||||
Installing/Configuring Glance
|
Installing/Configuring Glance
|
||||||
=============================
|
=============================
|
||||||
|
|||||||
185
doc/source/metadefs-concepts.rst
Normal file
185
doc/source/metadefs-concepts.rst
Normal file
@ -0,0 +1,185 @@
|
|||||||
|
..
|
||||||
|
Copyright (c) 2014 Hewlett-Packard Development Company, L.P.
|
||||||
|
All Rights Reserved.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Metadata Definition Concepts
|
||||||
|
============================
|
||||||
|
|
||||||
|
The metadata definition service was added to Glance in the Juno release of
|
||||||
|
OpenStack.
|
||||||
|
|
||||||
|
It provides a common API for vendors, admins, services, and users to
|
||||||
|
meaningfully **define** available key / value pair metadata that
|
||||||
|
can be used on different types of resources (images, artifacts, volumes,
|
||||||
|
flavors, aggregates, etc). A definition includes a property's key,
|
||||||
|
its description, its constraints, and the resource types to which it can be
|
||||||
|
associated.
|
||||||
|
|
||||||
|
This catalog does not store the values for specific instance properties.
|
||||||
|
|
||||||
|
For example, a definition of a virtual CPU topology property for the number of
|
||||||
|
cores will include the base key to use (for example, cpu_cores), 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.
|
||||||
|
|
||||||
|
When the user adds the property its key and value will be stored in the
|
||||||
|
service that owns that resource (for example, Nova for flavors and in Glance
|
||||||
|
for images). The catalog also includes any additional prefix required when
|
||||||
|
the property is applied to different types of resources, such as "hw_" for
|
||||||
|
images and "hw:" for flavors. So, on an image, the user would know to set the
|
||||||
|
property as "hw_cpu_cores=1".
|
||||||
|
|
||||||
|
Terminology
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Background
|
||||||
|
~~~~~~~~~~
|
||||||
|
The term *metadata* can become very overloaded and confusing. This
|
||||||
|
catalog is about the additional metadata that is passed as arbitrary
|
||||||
|
key / value pairs or tags across various artifacts and OpenStack services.
|
||||||
|
|
||||||
|
Below are a few examples of the various terms used for metadata across
|
||||||
|
OpenStack services today:
|
||||||
|
|
||||||
|
+-------------------------+---------------------------+----------------------+
|
||||||
|
| Nova | Cinder | Glance |
|
||||||
|
+=========================+===========================+======================+
|
||||||
|
| Flavor | Volume & Snapshot | Image & Snapshot |
|
||||||
|
| + *extra specs* | + *image metadata* | + *properties* |
|
||||||
|
| Host Aggregate | + *metadata* | + *tags* |
|
||||||
|
| + *metadata* | VolumeType | |
|
||||||
|
| Instances | + *extra specs* | |
|
||||||
|
| + *metadata* | + *qos specs* | |
|
||||||
|
| + *tags* | | |
|
||||||
|
+-------------------------+---------------------------+----------------------+
|
||||||
|
|
||||||
|
Catalog Concepts
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The below figure illustrates the concept terminology used in the metadata
|
||||||
|
definitions catalog::
|
||||||
|
|
||||||
|
A namespace is associated with 0 to many resource types, making it visible to
|
||||||
|
the API / UI for applying to that type of resource. RBAC Permissions are
|
||||||
|
managed at a namespace level.
|
||||||
|
|
||||||
|
+----------------------------------------------+
|
||||||
|
| Namespace |
|
||||||
|
| |
|
||||||
|
| +-----------------------------------------+ |
|
||||||
|
| | Object Definition | |
|
||||||
|
| | | | +--------------------+
|
||||||
|
| | +-------------------------------------+ | | +--> | Resource Type: |
|
||||||
|
| | | Property Definition A (key=integer) | | | | | e.g. Nova Flavor |
|
||||||
|
| | +-------------------------------------+ | | | +--------------------+
|
||||||
|
| | | | |
|
||||||
|
| | +-------------------------------------+ | | |
|
||||||
|
| | | Property Definition B (key=string) | | | | +--------------------+
|
||||||
|
| | +-------------------------------------+ | +--+--> | Resource Type: |
|
||||||
|
| | | | | | e.g. Glance Image |
|
||||||
|
| +-----------------------------------------+ | | +--------------------+
|
||||||
|
| | |
|
||||||
|
| +-------------------------------------+ | |
|
||||||
|
| | Property Definition C (key=boolean) | | | +--------------------+
|
||||||
|
| +-------------------------------------+ | +--> | Resource Type: |
|
||||||
|
| | | e.g. Cinder Volume |
|
||||||
|
+----------------------------------------------+ +--------------------+
|
||||||
|
|
||||||
|
Properties may be defined standalone or within the context of an object.
|
||||||
|
|
||||||
|
|
||||||
|
Catalog Terminology
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following terminology is used within the metadata definition catalog.
|
||||||
|
|
||||||
|
**Namespaces**
|
||||||
|
|
||||||
|
Metadata definitions are contained in namespaces.
|
||||||
|
|
||||||
|
- Specify the access controls (CRUD) for everything defined in it. Allows for
|
||||||
|
admin only, different projects, or the entire cloud to define and use the
|
||||||
|
definitions in the namespace
|
||||||
|
- Associates the contained definitions to different types of resources
|
||||||
|
|
||||||
|
**Properties**
|
||||||
|
|
||||||
|
A property describes a single property and its primitive constraints. Each
|
||||||
|
property can ONLY be a primitive type:
|
||||||
|
|
||||||
|
* string, integer, number, boolean, array
|
||||||
|
|
||||||
|
Each primitive type is described using simple JSON schema notation. This
|
||||||
|
means NO nested objects and no definition referencing.
|
||||||
|
|
||||||
|
**Objects**
|
||||||
|
|
||||||
|
An object describes a group of one to many properties and their primitive
|
||||||
|
constraints. Each property in the group can ONLY be a primitive type:
|
||||||
|
|
||||||
|
* string, integer, number, boolean, array
|
||||||
|
|
||||||
|
Each primitive type is described using simple JSON schema notation. This
|
||||||
|
means NO nested objects.
|
||||||
|
|
||||||
|
The object may optionally define required properties under the semantic
|
||||||
|
understanding that a user who uses the object should provide all required
|
||||||
|
properties.
|
||||||
|
|
||||||
|
**Resource Type Association**
|
||||||
|
|
||||||
|
Resource type association specifies the relationship between resource
|
||||||
|
types and the namespaces that are applicable to them. This information can be
|
||||||
|
used to drive UI and CLI views. For example, the same namespace of
|
||||||
|
objects, properties, and tags may be used for images, snapshots, volumes, and
|
||||||
|
flavors. Or a namespace may only apply to images.
|
||||||
|
|
||||||
|
Resource types should be aligned with Heat resource types whenever possible.
|
||||||
|
http://docs.openstack.org/developer/heat/template_guide/openstack.html
|
||||||
|
|
||||||
|
It is important to note that the same base property key can require different
|
||||||
|
prefixes depending on the target resource type. The API provides a way to
|
||||||
|
retrieve the correct property based on the target resource type.
|
||||||
|
|
||||||
|
Below are a few examples:
|
||||||
|
|
||||||
|
The desired virtual CPU topology can be set on both images and flavors
|
||||||
|
via metadata. The keys have different prefixes on images than on flavors.
|
||||||
|
On flavors keys are prefixed with ``hw:``, but on images the keys are prefixed
|
||||||
|
with ``hw_``.
|
||||||
|
|
||||||
|
For more: https://github.com/openstack/nova-specs/blob/master/specs/juno/virt-driver-vcpu-topology.rst
|
||||||
|
|
||||||
|
Another example is the AggregateInstanceExtraSpecsFilter and scoped properties
|
||||||
|
(e.g. properties with something:something=value). For scoped / namespaced
|
||||||
|
properties, the AggregateInstanceExtraSpecsFilter requires a prefix of
|
||||||
|
"aggregate_instance_extra_specs:" to be used on flavors but not on the
|
||||||
|
aggregate itself. Otherwise, the filter will not evaluate the property during
|
||||||
|
scheduling.
|
||||||
|
|
||||||
|
So, on a host aggregate, you may see:
|
||||||
|
|
||||||
|
companyx:fastio=true
|
||||||
|
|
||||||
|
But then when used on the flavor, the AggregateInstanceExtraSpecsFilter needs:
|
||||||
|
|
||||||
|
aggregate_instance_extra_specs:companyx:fastio=true
|
||||||
|
|
||||||
|
In some cases, there may be multiple different filters that may use
|
||||||
|
the same property with different prefixes. In this case, the correct prefix
|
||||||
|
needs to be set based on which filter is enabled.
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user