Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE OpenStack Cloud Crowbar

1 Glance User Guide

1.1 Image Identifiers

Images are uniquely identified by way of a URI that matches the following signature:

<Glance Server Location>/v1/images/<ID>

where <Glance Server Location> is the resource location of the Glance service that knows about an image, and <ID> is the image’s identifier. Image identifiers in Glance are uuids, making them globally unique.

1.2 Image Statuses

Images in Glance can be in one the following statuses:

  • queued

    The image identifier has been reserved for an image in the Glance registry. No image data has been uploaded to Glance and the image size was not explicitly set to zero on creation.

  • saving

    Denotes that an image’s raw data is currently being uploaded to Glance. When an image is registered with a call to POST /images and there is an x-image-meta-location header present, that image will never be in the saving status (as the image data is already available in some other location).

  • active

    Denotes an image that is fully available in Glance. This occurs when the image data is uploaded, or the image size is explicitly set to zero on creation.

  • deactivated

    Denotes that access to image data is not allowed to any non-admin user. Prohibiting downloads of an image also prohibits operations like image export and image cloning that may require image data.

  • killed

    Denotes that an error occurred during the uploading of an image’s data, and that the image is not readable.

  • deleted

    Glance has retained the information about the image, but it is no longer available to use. An image in this state will be removed automatically at a later date.

  • pending_delete

    This is similar to deleted, however, Glance has not yet removed the image data. An image in this state is not recoverable.

This is a representation of how the image move from one status to the next.
Figure 1.1: This is a representation of how the image move from one status to the next.

1.3 Task Statuses

Tasks in Glance can be in one the following statuses:

  • pending

    The task identifier has been reserved for a task in the Glance. No processing has begun on it yet.

  • processing

    The task has been picked up by the underlying executor and is being run using the backend Glance execution logic for that task type.

  • success

    Denotes that the task has had a successful run within Glance. The result field of the task shows more details about the outcome.

  • failure

    Denotes that an error occurred during the execution of the task and it cannot continue processing. The message field of the task shows what the error was.

1.4 Image Statuses

Images in Glance can be in one the following statuses:

  • queued

    The image identifier has been reserved for an image in the Glance registry. No image data has been uploaded to Glance and the image size was not explicitly set to zero on creation.

  • saving

    Denotes that an image’s raw data is currently being uploaded to Glance. When an image is registered with a call to POST /images and there is an x-image-meta-location header present, that image will never be in the saving status (as the image data is already available in some other location).

  • active

    Denotes an image that is fully available in Glance. This occurs when the image data is uploaded, or the image size is explicitly set to zero on creation.

  • deactivated

    Denotes that access to image data is not allowed to any non-admin user. Prohibiting downloads of an image also prohibits operations like image export and image cloning that may require image data.

  • killed

    Denotes that an error occurred during the uploading of an image’s data, and that the image is not readable.

  • deleted

    Glance has retained the information about the image, but it is no longer available to use. An image in this state will be removed automatically at a later date.

  • pending_delete

    This is similar to deleted, however, Glance has not yet removed the image data. An image in this state is not recoverable.

This is a representation of how the image move from one status to the next.
Figure 1.2: This is a representation of how the image move from one status to the next.

1.5 Task Statuses

Tasks in Glance can be in one the following statuses:

  • pending

    The task identifier has been reserved for a task in the Glance. No processing has begun on it yet.

  • processing

    The task has been picked up by the underlying executor and is being run using the backend Glance execution logic for that task type.

  • success

    Denotes that the task has had a successful run within Glance. The result field of the task shows more details about the outcome.

  • failure

    Denotes that an error occurred during the execution of the task and it cannot continue processing. The message field of the task shows what the error was.

1.6 Disk and Container Formats

When adding an image to Glance, you must specify what the virtual machine image’s disk format and container format are. Disk and container formats are configurable on a per-deployment basis. This document intends to establish a global convention for what specific values of disk_format and container_format mean.

1.6.1 Disk Format

The disk format of a virtual machine image is the format of the underlying disk image. Virtual appliance vendors have different formats for laying out the information contained in a virtual machine disk image.

You can set your image’s disk format to one of the following:

  • raw

    This is an unstructured disk image format

  • vhd

    This is the VHD disk format, a common disk format used by virtual machine monitors from VMware, Xen, Microsoft, VirtualBox, and others.

  • vhdx

    This is the VHDX disk format, an enhanced version of the VHD format which supports larger disk sizes among other features.

  • vmdk

    Another common disk format supported by many common virtual machine monitors.

  • vdi

    A disk format supported by VirtualBox virtual machine monitor and the QEMU emulator.

  • iso

    An archive format for the data contents of an optical disc (For example, CDROM).

  • ploop

    A disk format supported and used by Virtuozzo to run OS Containers.

  • qcow2

    A disk format supported by the QEMU emulator that can expand dynamically and supports Copy on Write.

  • aki

    This indicates what is stored in Glance is an Amazon kernel image.

  • ari

    This indicates what is stored in Glance is an Amazon ramdisk image.

  • ami

    This indicates what is stored in Glance is an Amazon machine image.

1.6.2 Container Format

The container format refers to whether the virtual machine image is in a file format that also contains metadata about the actual virtual machine.

Note
Note

The container format string is not currently used by Glance or other OpenStack components, so it is safe to simply specify bare as the container format if you are unsure.

You can set your image’s container format to one of the following:

  • bare

    This indicates there is no container or metadata envelope for the image.

  • ovf

    This is the OVF container format.

  • aki

    This indicates what is stored in Glance is an Amazon kernel image.

  • ari

    This indicates what is stored in Glance is an Amazon ramdisk image.

  • ami

    This indicates what is stored in Glance is an Amazon machine image

  • ova

    This indicates what is stored in Glance is an OVA tar archive file.

  • docker

    This indicates what is stored in Glance is a Docker tar archive of the container filesystem.

1.7 Common Image Properties

When adding an image to Glance, you may specify some common image properties that may prove useful to consumers of your image.

This document explains the names of these properties and the expected values.

The common image properties are also described in a JSON schema, found in /etc/glance/schema-image.json in the Glance source code.

1.7.1 architecture

Operating system architecture as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html.

1.7.2 instance_uuid

Metadata which can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)

1.7.3 kernel_id

The ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.

1.7.4 ramdisk_id

The ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.

1.7.5 os_distro

The common name of the operating system distribution as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html.

1.7.6 os_version

The operating system version as specified by the distributor.

1.8 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 and value pair metadata that can be used on different types of resources (images, artifacts, volumes, flavors, aggregates, and other resources). 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.

1.8.1 Terminology

1.8.1.1 Background

The term metadata can become very overloaded and confusing. This catalog is about the additional metadata that is passed as arbitrary key and 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
  • extra specs

Host Aggregate
  • metadata

Servers
  • metadata

  • scheduler_hints

  • tags

Volume & Snapshot
  • image metadata

  • metadata

VolumeType
  • extra specs

  • qos specs

Image & Snapshot
  • properties

  • tags

1.8.1.2 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 and 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.

1.8.1.3 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/implemented/virt-driver-vcpu-topology.rst.

Another example is the AggregateInstanceExtraSpecsFilter and scoped properties (For example, properties with something:something=value). For scoped or 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.

1.9 Using Glance’s Image Public APIs

Glance is the reference implementation of the OpenStack Images API. As such, Glance fully implements versions 1 and 2 of the Images API.

Note
Note

The Images API v1 has been DEPRECATED in the Newton release. The migration path is to use the Images API v2 instead of version 1 of the API. The Images API v1 will ultimately be removed, following the OpenStack standard deprecation policy.

There used to be a sentence here saying, “The Images API specification is developed alongside Glance, but is not considered part of the Glance project.” That’s only partially true (or completely false, depending upon how strict you are about these things). Conceptually, the OpenStack Images API is an independent definition of a REST API. In practice, however, the only way to participate in the evolution of the Images API is to work with the Glance community to define the new functionality and provide its reference implementation. Further, Glance falls under the designated sections provision of the OpenStack DefCore Guidelines, which basically means that in order to qualify as OpenStack, a cloud exposing an OpenStack Images API must include the Glance Images API implementation code. Thus, although conceptually independent, the OpenStack Images APIs are intimately associated with Glance.

References

1.9.1 Glance and the Images APIs: Past, Present, and Future

Here’s a quick summary of the Images APIs that have been implemented by Glance. If you’re interested in more details, you can consult the Release Notes for all the OpenStack releases (beginning with “Bexar”) to follow the evolution of features in Glance and the Images APIs.

1.9.1.1 Images v1 API

The v1 API was originally designed as a service API for use by Nova and other OpenStack services. In the Kilo release, the v1.1 API was downgraded from CURRENT to SUPPORTED. In the Newton release, the version 1 API is officially declared DEPRECATED.

During the deprecation period, the Images v1 API is closed to further development. The Glance code implementing the v1 API accepts only serious bug fixes.

Since Folsom, it has been possible to deploy OpenStack without exposing the Images v1 API to end users. The Compute v2 API contains image-related API calls allowing users to list images, list images details, show image details for a specific image, delete images, and manipulate image metadata. Nova acts as a proxy to Glance for these image-related calls. It’s important to note that the image-related calls in the Compute v2 API are a proper subset of the calls available in the Images APIs.

In the Newton release, Nova (and other OpenStack services that consume images) have been modified to use the Images v2 API by default.

Reference

1.9.1.2 Images v2 API

The v2 API is the CURRENT OpenStack Images API. It provides a more friendly interface to consumers than did the v1 API, as it was specifically designed to expose images-related functionality as a public-facing endpoint. It’s the version that’s currently open to development.

A common strategy is to deploy multiple Glance nodes: internal-facing nodes providing the Images APIs for internal consumers like Nova, and external-facing nodes providing the Images v2 API for public use.

1.9.1.3 The Future

During the long and tumultuous design phase of what has since become an independent service named “Glare” (the Glance Artifacts Repository), the Glance community loosely spoke about the Artifacts API being “Glance v3”. This, however, was only a shorthand way of speaking of the Artifacts effort. The Artifacts API can’t be the Images v3 API since Artifacts are not the same as Images. Conceptually, a virtual machine image could be an Artifact, and the Glare code has been designed to be compatible with the Images v2 API. But at this time, there are no plans to implement an Images v3 API.

During the Newton development cycle, Glare became an independent OpenStack project. While it’s evident that there’s a need for an Artifact Repository in OpenStack, whether it will be as ubiquitous as the need for an Images Repository isn’t clear. On the other hand, industry trends could go in the opposite direction where everyone needs Artifacts and deployers view images as simply another type of digital artifact.

1.9.2 Authentication

Glance depends on Keystone and the OpenStack Identity API to handle authentication of clients. You must obtain an authentication token from Keystone using and 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.

1.9.3 Using v1.X

Note
Note

The Images API v1 has been DEPRECATED in the Newton release. The migration path is to use the Images API v2 instead of version 1 of the API. The Images API v1 will ultimately be removed, following the OpenStack standard deprecation policy.

For the purpose of examples, assume there is a Glance API server running at the URL http://glance.openstack.example.org on the default port 80.

1.9.3.1 List Available Images

We want to see a list of available images that the authenticated user has access to. This includes images owned by the user, images shared with the user and public images.

We issue a GET request to http://glance.openstack.example.org/v1/images to retrieve this list of available images. The data is returned as a JSON-encoded mapping in the following format:

{'images': [
  {'uri': 'http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
   'name': 'SLES 15',
   'disk_format': 'vhd',
   'container_format': 'ovf',
   'size': '5368709120'}
  ...]}

1.9.3.2 List Available Images in More Detail

We want to see a more detailed list of available images that the authenticated user has access to. This includes images owned by the user, images shared with the user and public images.

We issue a GET request to http://glance.openstack.example.org/v1/images/detail to retrieve this list of available images. The data is returned as a JSON-encoded mapping in the following format:

{'images': [
  {'uri': 'http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
   'name': 'SLES 15',
   'disk_format': 'vhd',
   'container_format': 'ovf',
   'size': '5368709120',
   'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3',
   'created_at': '2010-02-03 09:34:01',
   'updated_at': '2010-02-03 09:34:01',
   'deleted_at': '',
   'status': 'active',
   'is_public': true,
   'min_ram': 256,
   'min_disk': 5,
   'owner': null,
   'properties': {'distro': 'SLES 15'}},
  ...]}
Note
Note

All timestamps returned are in UTC.

The updated_at timestamp is the timestamp when an image’s metadata was last updated, not its image data, as all image data is immutable once stored in Glance.

The properties field is a mapping of free-form key and value pairs that have been saved with the image metadata.

The checksum field is an MD5 checksum of the image file data.

The is_public field is a boolean indicating whether the image is publicly available.

The min_ram field is an integer specifying the minimum amount of RAM needed to run this image on an instance in megabytes.

The min_disk field is an integer specifying the minimum amount of disk space needed to run this image on an instance in gigabytes.

The owner field is a string which may either be null or which will indicate the owner of the image.

1.9.3.3 Filtering Images Lists

Both the GET /v1/images and GET /v1/images/detail requests take query parameters that serve to filter the returned list of images. The following list details these query parameters.

  • name=NAME

    Filters images having a name attribute matching NAME.

  • container_format=FORMAT

    Filters images having a container_format attribute matching FORMAT.

    For more information, see Section 1.6, “Disk and Container Formats”.

  • disk_format=FORMAT

    Filters images having a disk_format attribute matching FORMAT.

    For more information, see Section 1.6, “Disk and Container Formats”.

  • status=STATUS

    Filters images having a status attribute matching STATUS.

    For more information, see Section 1.2, “Image Statuses”.

  • size_min=BYTES

    Filters images having a size attribute greater than or equal to BYTES.

  • size_max=BYTES

    Filters images having a size attribute less than or equal to BYTES.

These two resources also accept additional query parameters:

  • sort_key=KEY

    Results will be ordered by the specified image attribute KEY. Accepted values include id, name, status, disk_format, container_format, size, 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=ID

    An image identifier marker may be specified. When present, only images which occur after the identifier ID will be listed. (These are the images that have a sort_key later than that of the marker ID in the sort_dir direction.)

  • limit=LIMIT

    When present, the maximum number of results returned will not exceed LIMIT.

Note
Note

If the specified LIMIT exceeds the operator defined limit (api_limit_max) then the number of results returned may be less than LIMIT.

  • is_public=PUBLIC

    An admin user may use the is_public parameter to control which results are returned.

    When the is_public parameter is absent or set to True the following images will be listed: Images whose is_public field is True, owned images and shared images.

    When the is_public parameter is set to False the following images will be listed: Images (owned, shared, or non-owned) whose is_public field is False.

    When the is_public parameter is set to None all images will be listed irrespective of owner, shared status or the is_public field.

Note
Note

Use of the is_public parameter is restricted to admin users. For all other users it will be ignored.

1.9.3.4 Retrieve Image Metadata

We want to see detailed information for a specific virtual machine image that the Glance server knows about.

We have queried the Glance server for a list of images and the data returned includes the uri field for each available image. This uri field value contains the exact location needed to get the metadata for a specific image.

Continuing the example from above, in order to get metadata about the first image returned, we can issue a HEAD request to the Glance server for the image’s URI.

We issue a HEAD request to http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9 to retrieve complete metadata for that image. The metadata is returned as a set of HTTP headers that begin with the prefix x-image-meta-. The following shows an example of the HTTP headers returned from the above HEAD request:

x-image-meta-uri              http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name             SLES 15
x-image-meta-disk_format      vhd
x-image-meta-container_format ovf
x-image-meta-size             5368709120
x-image-meta-checksum         c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at       2010-02-03 09:34:01
x-image-meta-updated_at       2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status           available
x-image-meta-is_public        true
x-image-meta-min_ram          256
x-image-meta-min_disk         0
x-image-meta-owner            null
x-image-meta-property-distro  SLES 15
Note
Note

All timestamps returned are in UTC.

The x-image-meta-updated_at timestamp is the timestamp when an image’s metadata was last updated, not its image data, as all image data is immutable once stored in Glance.

There may be multiple headers that begin with the prefix x-image-meta-property-. These headers are free-form key and value pairs that have been saved with the image metadata. The key is the string after x-image-meta-property- and the value is the value of the header.

The response’s ETag header will always be equal to the x-image-meta-checksum value.

The response’s x-image-meta-is_public value is a boolean indicating whether the image is publicly available.

The response’s x-image-meta-owner value is a string which may either be null or which will indicate the owner of the image.

1.9.3.5 Retrieve Raw Image Data

We want to retrieve that actual raw data for a specific virtual machine image that the Glance server knows about.

We have queried the Glance server for a list of images and the data returned includes the uri field for each available image. This uri field value contains the exact location needed to get the metadata for a specific image.

Continuing the example from above, in order to get metadata about the first image returned, we can issue a HEAD request to the Glance server for the image’s URI.

We issue a GET request to http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9 to retrieve metadata for that image as well as the image itself encoded into the response body.

The metadata is returned as a set of HTTP headers that begin with the prefix x-image-meta-. The following shows an example of the HTTP headers returned from the above GET request:

x-image-meta-uri              http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name             SLES 15
x-image-meta-disk_format      vhd
x-image-meta-container_format ovf
x-image-meta-size             5368709120
x-image-meta-checksum         c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at       2010-02-03 09:34:01
x-image-meta-updated_at       2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status           available
x-image-meta-is_public        true
x-image-meta-min_ram          256
x-image-meta-min_disk         5
x-image-meta-owner            null
x-image-meta-property-distro  SLES 15
Note
Note

All timestamps returned are in UTC.

The x-image-meta-updated_at timestamp is the timestamp when an image’s metadata was last updated, not its image data, as all image data is immutable once stored in Glance.

There may be multiple headers that begin with the prefix x-image-meta-property-. These headers are free-form key and value pairs that have been saved with the image metadata. The key is the string after x-image-meta-property- and the value is the value of the header.

The response’s Content-Length header shall be equal to the value of the x-image-meta-size header.

The response’s ETag header will always be equal to the x-image-meta-checksum value.

The response’s x-image-meta-is_public value is a boolean indicating whether the image is publicly available.

The response’s x-image-meta-owner value is a string which may either be null or which will indicate the owner of the image.

The image data itself will be the body of the HTTP response returned from the request, which will have content-type of application/octet-stream.

1.9.3.6 Add a New Image

We have created a new virtual machine image in some way (created a snapshot or backed up an existing image) and we wish to do two things:

  • Store the disk image data in Glance.

  • Store metadata about this image in Glance.

We can do the above two activities in a single call to the Glance API. Assuming, like in the examples above, that a Glance API server is running at http://glance.openstack.example.org, we issue a POST request to add an image to Glance:

POST http://glance.openstack.example.org/v1/images

The metadata about the image is sent to Glance in HTTP headers. The body of the HTTP request to the Glance API will be the MIME-encoded disk image data.

1.9.3.7 Reserve a New Image

We can also perform the activities described in Section 1.9.3.6, “Add a New Image” using two separate calls to the Image API; the first to register the image metadata, and the second to add the image disk data. This is known as reserving an image.

The first call should be a POST to http://glance.openstack.example.org/v1/images, which will result in a new image id being registered with a status of queued:

{'image':
 {'status': 'queued',
  'id': '71c675ab-d94f-49cd-a114-e12490b328d9',
  ...}
 ...}

The image data can then be added using a PUT to http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9. The image status will then be set to active by Glance.

Image Metadata in HTTP Headers

Glance will view as image metadata any HTTP header that it receives in a POST request where the header key is prefixed with the strings x-image-meta- and x-image-meta-property-.

The list of metadata headers that Glance accepts are listed below.

  • x-image-meta-name

    This header is required, unless reserving an image. Its value should be the name of the image.

    Note
    Note

    The name of an image is not unique to a Glance node. It would be an unrealistic expectation of users to know all the unique names of all other user’s images.

  • x-image-meta-id

    This header is optional.

    When present, Glance will use the supplied identifier for the image. If the identifier already exists in that Glance node, then a 409 Conflict will be returned by Glance. The value of the header must be a uuid in hexadecimal string notation (that is 71c675ab-d94f-49cd-a114-e12490b328d9).

    When this header is not present, Glance will generate an identifier for the image and return this identifier in the response (see below).

  • x-image-meta-store

    This header is optional. Valid values are one of file, rbd, swift, cinder, sheepdog or vsphere.

    When present, Glance will attempt to store the disk image data in the backing store indicated by the value of the header. If the Glance node does not support the backing store, Glance will return a 400 Bad Request.

    When not present, Glance will store the disk image data in the backing store that is marked as default. See the configuration option default_store for more information.

  • x-image-meta-disk_format

    This header is required, unless reserving an image. Valid values are one of aki, ari, ami, raw, iso, vhd, vhdx, vdi, qcow2, vmdk or ploop.

    For more information, see Section 1.6, “Disk and Container Formats”.

  • x-image-meta-container_format

    This header is required, unless reserving an image. Valid values are one of aki, ari, ami, bare, ova, ovf, or docker.

    For more information, see Section 1.6, “Disk and Container Formats”.

  • x-image-meta-size

    This header is optional.

    When present, Glance assumes that the expected size of the request body will be the value of this header. If the length in bytes of the request body does not match the value of this header, Glance will return a 400 Bad Request.

    When not present, Glance will calculate the image’s size based on the size of the request body.

  • x-image-meta-checksum

    This header is optional. When present, it specifies the MD5 checksum of the image file data.

    When present, Glance will verify the checksum generated from the back-end store while storing your image against this value and return a 400 Bad Request if the values do not match.

  • x-image-meta-is_public

    This header is optional.

    When Glance finds the string true (case-insensitive), the image is marked as a public one, meaning that any user may view its metadata and may read the disk image from Glance.

    When not present, the image is assumed to be not public and owned by a user.

  • x-image-meta-min_ram

    This header is optional. When present, it specifies the minimum amount of RAM in megabytes required to run this image on a server.

    When not present, the image is assumed to have a minimum RAM requirement of 0.

  • x-image-meta-min_disk

    This header is optional. When present, it specifies the expected minimum disk space in gigabytes required to run this image on a server.

    When not present, the image is assumed to have a minimum disk space requirement of 0.

  • x-image-meta-owner

    This header is optional and only meaningful for admins.

    Glance normally sets the owner of an image to be the tenant or user (depending on the owner_is_tenant configuration option) of the authenticated user issuing the request. However, if the authenticated user has the Admin role, this default may be overridden by setting this header to null or to a string identifying the owner of the image.

  • x-image-meta-property-*

    When Glance receives any HTTP header whose key begins with the string prefix x-image-meta-property-, Glance adds the key and value to a set of custom, free-form image properties stored with the image. The key is a lower-cased string following the prefix x-image-meta-property- with dashes and punctuation replaced with underscores.

    There is no limit on the number of free-form key and value attributes that can be attached to the image. However, keep in mind that the 8K limit on the size of all the HTTP headers sent in a request will effectively limit the number of image properties.

1.9.3.8 Update an Image

Glance will consider any HTTP header that it receives in a PUT request as an instance of image metadata. In this case, the header key should be prefixed with the strings x-image-meta- and x-image-meta-property-.

If an image was previously reserved, and thus is in the queued state, then image data can be added by including it as the request body. If the image already has data associated with it (for example, it is not in the queued state), then including a request body will result in a 409 Conflict exception.

On success, the PUT request will return the image metadata encoded as HTTP headers.

See more about image statuses here Section 1.2, “Image Statuses”.

1.9.3.9 List Image Memberships

We want to see a list of the other system tenants (or users, if owner_is_tenant is False) that may access a given virtual machine image that the Glance server knows about. We take the uri field of the image data, append /members to it, and issue a GET request on the resulting URL.

Continuing from the example above, in order to get the memberships for the first image returned, we can issue a GET request to the Glance server for http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members. And we will get back JSON data such as the following:

{'members': [
 {'member_id': 'tenant1',
  'can_share': false}
 ...]}

The member_id field identifies a tenant with which the image is shared. If that tenant is authorized to further share the image, the can_share field is true.

1.9.3.10 List Shared Images

We want to see a list of images which are shared with a given tenant. We issue a GET request to http://glance.openstack.example.org/v1/shared-images/tenant1. We will get back JSON data such as the following:

{'shared_images': [
 {'image_id': '71c675ab-d94f-49cd-a114-e12490b328d9',
  'can_share': false}
 ...]}

The image_id field identifies an image shared with the tenant named by member_id. If the tenant is authorized to further share the image, the can_share field is true.

1.9.3.11 Add a Member to an Image

We want to authorize a tenant to access a private image. We issue a PUT request to http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1. With no body, this will add the membership to the image, leaving existing memberships unmodified and defaulting new memberships to have can_share set to false. We may also optionally attach a body of the following form:

{'member':
 {'can_share': true}
}

If such a body is provided, both existing and new memberships will have can_share set to the provided value (either true or false). This query will return a 204 (No Content) status code.

1.9.3.12 Remove a Member from an Image

We want to revoke a tenant’s right to access a private image. We issue a DELETE request to http://glance.openstack.example.org/v1/images/1/members/tenant1. This query will return a 204 (No Content) status code.

1.9.3.13 Replace a Membership List for an Image

The full membership list for a given image may be replaced. We issue a PUT request to http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members with a body of the following form:

{'memberships': [
 {'member_id': 'tenant1',
  'can_share': false}
 ...]}

All existing memberships which are not named in the replacement body are removed, and those which are named have their can_share settings changed as specified. (The can_share setting may be omitted, which will cause that setting to remain unchanged in the existing memberships.) All new memberships will be created, with can_share defaulting to false unless it is specified otherwise.

1.9.4 Image Membership Changes in Version 2.0

Version 2.0 of the Images API eliminates the can_share attribute of image membership. In the version 2.0 model, image sharing is not transitive.

In version 2.0, image members have a status attribute that reflects how the image should be treated with respect to that image member’s image-list.

  • The status attribute may have one of three values: pending, accepted, or rejected.

  • By default, only those shared images with status accepted are included in an image member’s image-list.

  • Only an image member may change their membership status.

  • Only an image owner may create members on an image. The status of a newly created image member is pending. The image owner cannot change the status of a member.

1.9.4.1 Distinctions from Version 1.x API Calls

  • The response to a request to list the members of an image has changed.

    call: GET on /v2/images/{imageId}/members

    response: see the JSON schema at /v2/schemas/members

  • The request body in the call to create an image member has changed.

    call: POST to /v2/images/{imageId}/members

    request body:

    { "member": "<MEMBER_ID>" }

    Where the {memberId} is the tenant ID of the image member.

    The member status of a newly created image member is pending.

1.9.4.2 New API Calls

  • Change the status of an image member

    call: PUT on /v2/images/{imageId}/members/{memberId}.

    Request body:

    { "status": "<STATUS_VALUE>" }

    Where <STATUS_VALUE> is pending, accepted, or rejected. The {memberId} is the tenant ID of the image member.

1.9.5 Images v2 Tasks API

Version 2 of the OpenStack Images API introduces a Task resource that is used to create and monitor long-running asynchronous image-related processes. See the Tasks section of the Glance documentation for more information.

The following Task calls are available:

1.9.5.1 Create a Task

A user wants to initiate a Task. The user issues a POST request to /v2/tasks. The request body is of Content-type application/json and must contain the following fields:

  • type: A string specified by the enumeration defined in the Task schema.

  • input: A JSON object. The content is defined by the cloud provider who has exposed the endpoint being contacted.

The response is a Task entity as defined by the Task schema. It includes an id field that can be used in a subsequent call to poll the Task for status changes.

A Task is created in pending status.

1.9.5.2 Show a Task

A user wants to see detailed information about a Task the user owns. The user issues a GET request to /v2/tasks/{taskId}.

The response is in application/json format. The exact structure is given by the Task schema located at /v2/schemas/task.

1.9.5.3 List Tasks

A user wants to see what Tasks have been created in their project. The user issues a GET request to /v2/tasks.

The response is in application/json format. The exact structure is given by the task schema located at /v2/schemas/tasks.

Note
Note

As indicated by the schema, the list of Tasks is provided in a sparse format. To see more information about a particular Task in the list, the user would use the show Task call described above.

1.9.5.4 Filtering and Sorting the Tasks List

The GET /v2/tasks request takes query parameters that server to filter the returned list of Tasks. The following list details these query parameters.

  • status={status}

    Filters the list to display only those tasks in the specified status. See the Task schema or the Section 1.3, “Task Statuses” section of this documentation for the legal values to use for {status}.

    For example, a request to GET /v2/tasks?status=pending would return only those Tasks whose current status is pending.

  • type={type}

    Filters the list to display only those Tasks of the specified type. See the enumeration defined in the Task schema for the legal values to use for {type}.

    For example, a request to GET /v2/tasks?type=import would return only import Tasks.

  • sort_dir={direction}

    Sorts the list of tasks according to updated_at datetime. Legal values are asc (ascending) and desc (descending). By default, the Task list is sorted by created_at time in descending chronological order.

1.9.6 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.

1.9.6.1 How to use it

To receive localized API messages, the HTTP client needs to specify the Accept-Language header to indicate the language that will translate the message. For more information about Accept-Language, refer to 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://glance.openstack.example.org/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>
&#25214;&#19981;&#21040;&#20219;&#20309;&#20855;&#26377;&#26631;&#35782; aaa &#30340;&#26144;&#20687;<br /><br />
</body>
</html>
Note
Note

Make sure to have a language package under /usr/share/locale-langpack/ on the target Glance server.

1.10 Using Glance’s Client Tools

The command-line tool and python library for Glance are both installed through the python-glanceclient project. Explore the following resources for more information:

1.11 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 and 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, its description, and its 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.

1.11.1 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 Authentication With Keystone for more information on integrating with Keystone.

1.11.2 Using v2.X

For the purpose of examples, assume there is a Glance API server running at the URL http://glance.openstack.example.org on the default port 80.

1.11.2.1 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.openstack.example.org/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
Note

Listing namespaces will only show the summary of each namespace including counts and resource type associations. Detailed responses including all its objects definitions, property definitions will only be available on each individual GET namespace request.

1.11.2.2 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 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, for example 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
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).

1.11.2.3 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.openstack.example.org/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
              }
          }
      }
  ]
}

1.11.2.4 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.openstack.example.org/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"
      }
  ]
}

1.11.2.5 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.openstack.example.org/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"
      }
  ]
}

1.11.2.6 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.openstack.example.org/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
Note

Optionally properties, objects and resource type associations could be added in the same input. See GET Namespace output above (input will be similar).

1.11.2.7 Update Namespace

We want to update an existing namespace.

We issue a PUT request to update an namespace to Glance:

PUT http://glance.openstack.example.org/v2/metadefs/namespaces/{namespace}

The input data is similar to Add Namespace.

1.11.2.8 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.openstack.example.org/v2/metadefs/namespaces/{namespace}

1.11.2.9 Associate Resource Type with 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.openstack.example.org/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"
}

1.11.2.10 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.openstack.example.org/v2//metadefs/namespaces/{namespace}/resource_types/{resource_type}

1.11.2.11 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.openstack.example.org/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"
}

1.11.2.12 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.openstack.example.org/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
      }
  }
}

1.11.2.13 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.openstack.example.org/v2/metadefs/namespaces/{namespace}/objects/{object_name}

The input data is similar to Add Object.

1.11.2.14 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.openstack.example.org/v2/metadefs/namespaces/{namespace}/objects/{object_name}

1.11.2.15 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.openstack.example.org/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"
      ]
  }
}

1.11.2.16 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.openstack.example.org/v2/metadefs/namespaces/{namespace}/properties/{property_name}

The input data is similar to Add property definition.

1.11.2.17 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.openstack.example.org/v2/metadefs/namespaces/{namespace}/properties/{property_name}

1.11.3 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.

1.11.3.1 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, 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://glance.openstack.example.org/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>
&#25214;&#19981;&#21040;&#20219;&#20309;&#20855;&#26377;&#26631;&#35782; aaa &#30340;&#26144;&#20687;<br /><br />
</body>
</html>
Note
Note

Ensure there is the language package under /usr/share/locale-langpack/ on the target Glance server.

1.12 Image Signature Verification

Glance has the ability to perform image validation using a digital signature and asymmetric cryptography. To trigger this, you must define specific image properties (described below), and have stored a certificate signed with your private key in a local Barbican installation.

When the image properties exist on an image, Glance will validate the uploaded image data against these properties before storing it. If validation is unsuccessful, the upload will fail and the image will be deleted.

Additionally, the image properties may be used by other services (for example, Nova) to perform data verification when the image is downloaded from Glance.

1.12.1 Requirements

Barbican key manager - See http://docs.openstack.org/developer/barbican/setup/devstack.html.

1.12.2 Configuration

The etc/glance-api.conf can be modified to change keystone endpoint of barbican. By default barbican will try to connect to keystone at http://localhost:5000/v3 but if keystone is on another host then this should be changed.

In glance-api.conf find the following lines:

[barbican]
auth_endpoint = http://localhost:5000/v3

Then replace http://localhost:5000/v3 with the URL of keystone, also adding /v3 to the end of it. For example, ‘https://192.168.245.9:5000/v3’.

Another option in etc/glance-api.conf which can be configured is which key manager to use. By default Glance will use the default key manager defined by the Castellan key manager interface, which is currently the Barbican key manager.

In glance-api.conf find the following lines:

[key_manager]
api_class = castellan.key_manager.barbican_key_manager.BarbicanKeyManager

Then replace the value with the desired key manager class.

Note
Note

If those lines do not exist then simply add them to the end of the file.

1.12.3 Using the Signature Verification

An image will need a few properties for signature verification to be enabled, these are:

img_signature
img_signature_hash_method
img_signature_key_type
img_signature_certificate_uuid

1.12.3.1 Property img_signature

This is the signature of your image.

Note
Note

The max character limit is 255.

1.12.3.2 Property img_signature_hash_method

Hash methods is the method you hash with.

Current ones you can use are:

  • SHA-224

  • SHA-256

  • SHA-384

  • SHA-512

1.12.3.3 Property img_signature_key_type

This is the key_types you can use for your image.

Current ones you can use are:

  • RSA-PSS

  • DSA

  • ECC-CURVES

  • SECT571K1

  • SECT409K1

  • SECT571R1

  • SECT409R1

  • SECP521R1

  • SECP384R1

Note
Note

ECC curves - Only keysizes above 384 are included. Not all ECC curves may be supported by the back end.

1.12.3.4 Property img_signature_certificate_uuid

This is the UUID of the certificate that you upload to Barbican.

Therefore the type passed to glance is:

  • UUID

Note
Note

The supported certificate types are:

  • X_509

1.12.4 Example Usage

Follow these instructions to create your keys:

$ openssl genrsa -out private_key.pem 1024
Generating RSA private key, 1024 bit long modulus
...............................................++++++
..++++++
e is 65537 (0x10001)

$ openssl rsa -pubout -in private_key.pem -out public_key.pem
writing RSA key

$ openssl req -new -key private_key.pem -out cert_request.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.

$ openssl x509 -req -days 14 -in cert_request.csr -signkey private_key.pem -out new_cert.crt
Signature ok
subject=/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd
Getting Private key

Upload your certificate. This only has to be done once as you can use the same Secret href for many images until it expires:

$ openstack secret store --name test --algorithm RSA --expiration 2016-06-29 --secret-type certificate --payload-content-type "application/octet-stream" --payload-content-encoding base64 --payload "$(base64 new_cert.crt)"
+---------------+-----------------------------------------------------------------------+
| Field         | Value                                                                 |
+---------------+-----------------------------------------------------------------------+
| Secret href   | http://127.0.0.1:9311/v1/secrets/cd7cc675-e573-419c-8fff-33a72734a243 |

$ cert_uuid=cd7cc675-e573-419c-8fff-33a72734a243

Get an image and create the signature:

$ echo This is a dodgy image > myimage

$ openssl dgst -sha256 -sign private_key.pem -sigopt rsa_padding_mode:pss -out myimage.signature myimage

$ base64 -w 0 myimage.signature > myimage.signature.b64

$ image_signature=$(cat myimage.signature.b64)
Note
Note

Using Glance v1 requires -w 0 due to not supporting multiline image properties. Glance v2 does support multiline image properties and does not require -w 0 but may still be used.

Create the image:

$ glance image-create --name mySignedImage --container-format bare --disk-format qcow2 --property img_signature="$image_signature" --property img_signature_certificate_uuid="$cert_uuid" --property img_signature_hash_method='SHA-256' --property img_signature_key_type='RSA-PSS' < myimage
Note
Note

Creating the image can fail if validation does not succeed. This will cause the image to be deleted.

Print this page