You can use OpenStack Image Service for discovering, registering, and retrieving virtual machine images. The service includes a RESTful API that allows users to query VM image metadata and retrieve the actual image with HTTP requests, or you can use a client class in your Python code to accomplish the same tasks. VM images made available through OpenStack Image Service can be stored in a variety of locations from simple file systems to object-storage systems like the OpenStack Object Storage project, or even use S3 storage either on its own or through an OpenStack Object Storage S3 interface.

There are two main parts to the Image Service’s architecture: API server Registry server(s) OpenStack Image Service is designed to be as adaptable as possible for various back-end storage and registry database solutions. There is a main API server (the ``glance-api`` program) that serves as the communications hub between various client programs, the registry of image metadata, and the storage systems that actually contain the virtual machine image data.

The API server is the main interface for OpenStack Image Service. It routes requests from clients to registries of image metadata and to its backend stores, which are the mechanisms by which OpenStack Image Service actually saves incoming virtual machine images. The backend stores that OpenStack Image Service can work with are as follows: OpenStack Object Storage - OpenStack Object Storage is the highly-available object storage project in OpenStack. Filesystem - The default backend that OpenStack Image Service uses to store virtual machine images is the filesystem backend. This simple backend writes image files to the local filesystem. S3 - This backend allows OpenStack Image Service to store virtual machine images in Amazon’s S3 service. HTTP - OpenStack Image Service can read virtual machine images that are available via HTTP somewhere on the Internet. This store is read-only.

OpenStack Image Service registry servers are servers that conform to the OpenStack Image Service Registry API. OpenStack Image Service ships with a reference implementation of a registry server that complies with this API (bin/OpenStack Image Service-registry).

The OpenStack system has several key projects that are separate installations but can work together depending on your cloud needs: OpenStack Compute, OpenStack Object Storage, and an OpenStack Image Service with a project name of Glance. You can install any of these projects separately and then configure them either as standalone or connected entities.

Hardware: OpenStack components are intended to run on standard hardware. Operating System: The OpenStack Image Service itself currently runs on Ubuntu but the images it stores may contain different operating systems. Networking: 1000 Mbps are suggested. Database: Any SQLAlchemy-compatible database, such as MySQL, Oracle, PostgreSQL, or SQLite. The reference registry server implementation that ships with OpenStack Image Service uses a SQL database to store information about an image, and publishes this information via an HTTP/REST-like interface. Permissions: You can install OpenStack imaging service either as root or as a user with sudo permissions if you configure the sudoers file to enable all the permissions.

The installation of the Image Services themselves are separate from the storage of the virtual images to be retrieved.

These installation instructions have you set up the services on a single node, so the API server and registry services are on the same server. The images themselves can be stored either in OpenStack Object Storage, Amazon's S3 infrastructure, in a filesystem, or if you want read-only access, on a web server to be served via HTTP.

First, add the Glance PPA to your sources.lst. sudo add-apt-repository ppa:glance-core/trunk Run update. sudo apt-get update Now, install the Glance server. sudo apt-get install glance All dependencies should be automatically installed. Refer to the Glance developer documentation site to install from a Bazaar branch.

You start Glance either by calling the server program, glance-api, or using the server daemon wrapper program named glance-control. Glance ships with an etc/ directory that contains sample paste.deploy configuration files that you can copy to a standard configuration directory and adapt for your own uses. If you do not specify a configuration file on the command line when starting the glance-api server, Glance attempts to locate a glance.conf configuration file in one of the following directories, and uses the first config file it finds in this order: . ~/.glance ~/ /etc/glance/ /etc If Glance doesn't find a configuration file in one of these locations, you see an error: ERROR: Unable to locate any configuration file. Cannot load application glance-api. To manually start the glance-api server, use a command like the following: sudo glance-api etc/glance.conf.sample --debug Supply the configuration file as the first argument (etc/glance.conf.sample in the above example) and then any common options you want to use. In the above example, the --debug option shows some of the debugging output that the server shows when starting up. Call the server program with --help to see all available options you can specify on the command line. Note that the server does not daemonize itself when run manually from the terminal. You can force the server to daemonize using the standard shell backgrounding indicator, However, for most use cases, we recommend using the glance-control server daemon wrapper for daemonizing. See below for more details on daemonization with glance-control. The second way to start up a Glance server is to use the glance-control program. glance-control is a wrapper script that allows the user to start, stop, restart, and reload the other Glance server programs in a fashion that is more conducive to automation and scripting. Servers started via the glance-control program are always daemonized, meaning that the server program process runs in the background. To start a Glance server with glance-control, simply call glance-control with a server and the word “start”, followed by any command-line options you wish to provide. Start the server with glance-control in the following way: sudo glance-control {SERVER} start [CONFPATH] Here is an example that shows how to start the glance-registry server with the glance-control wrapper script. sudo glance-control registry start etc/glance.conf.sample Starting glance-registry with /home/jpipes/repos/glance/trunk/etc/glance.conf.sample To start all the Glance servers (currently the glance-api and glance-registry programs) at once, you can specify “all” for the {SERVER}. You can use Ctrl-C to stop a Glance server if it was started manually. If you started the Glance server using the glance-control program, you can use the glance-control program to stop it. Simply do the following: sudo glance-control {SERVER} stop as this example shows: sudo glance-control registry stop Stopping glance-registry pid: 17602 signal: 15 You can restart a server with the glance-control program, as demonstrated here: sudo glance-control registry restart etc/glance.conf.sample Stopping glance-registry pid: 17611 signal: 15 Starting glance-registry with /home/jpipes/repos/glance/trunk/etc/glance.conf.sample

Once Glance is installed and the server is running, you should edit your nova.conf file to add or edit the following flags: --glance_api_servers=GLANCE_SERVER_IP --image_service=nova.image.glance.GlanceImageService Where the GLANCE_SERVER_IP is the IP address of the server running the glance-api service.

There are a number of configuration options in Glance that control how Glance servers log messages. The configuration options are specified in the glance.conf configuration file.

Description of glance.conf flags for Glance logging

Flag	Default	Description
--log-config=PATH	default: none	Path name to a configuration file to use for configuring logging: Specified on the command line only.
--log-format	default: %(asctime)s %(levelname)8s [%(name)s] %(message)s	Format of log records: Because of a bug in the PasteDeploy package, this option is only available on the command line. See the Python logging module documentation for more information about the options in the format string.
--log_file	default: none	Path name: The filepath of the file to use for logging messages from Glance’s servers. Without this setting, the default is to output messages to stdout, so if you are running Glance servers in a daemon mode (using glance-control) you should make sure that the log_file option is set appropriately.
--log_dir	default: none	Path name: The filepath of the directory to use for log files. If not specified (the default) the log_file is used as an absolute filepath.
--log_date_format	default: %Y-%m-%d %H:%M:%S	Python logging module formats: The format string for timestamps in the log output. See the Python logging module documentation for more information on setting this format string.

Glance has a RESTful API that exposes both metadata about registered virtual machine images and the image data itself. A host that runs the bin/glance-api service is said to be a Glance API Server. Assume there is a Glance API server running at the URL http://glance.example.com. Let's walk through how a user might request information from this server.

We want to see a list of available virtual machine images that the Glance server knows about. We issue a GET request to http://glance.example.com/images/ to retrieve this list of available public images. The data is returned as a JSON-encoded mapping in the following format: {'images': [ {'uri': 'http://glance.example.com/images/1', 'name': 'Ubuntu 10.04 Plain', 'disk_format': 'vhd', 'container_format': 'ovf', 'size': '5368709120'} ...]} All images returned from the above `GET` request are *public* images

We want to see more detailed information on available virtual machine images that the Glance server knows about. We issue a GET request to http://glance.example.com/images/detail to retrieve this list of available public images. The data is returned as a JSON-encoded mapping in the following format: {'images': [ {'uri': 'http://glance.example.com/images/1', 'name': 'Ubuntu 10.04 Plain 5GB', 'disk_format': 'vhd', 'container_format': 'ovf', 'size': '5368709120', 'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3', 'location': 'swift://account:key/container/image.tar.gz.0', 'created_at': '2010-02-03 09:34:01', 'updated_at': '2010-02-03 09:34:01', 'deleted_at': '', 'status': 'active', 'is_public': True, 'properties': {'distro': 'Ubuntu 10.04 LTS'}}, ...]} All images returned from the above `GET` request are *public* images. 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/value pairs that have been saved with the image metadata. The `checksum` field is an MD5 checksum of the image file data.

Both the GET /images and GET /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 About Disk and Container Formats. disk_format=FORMAT Filters images having a disk_format attribute matching FORMAT For more information, see About Disk and Container Formats. status=STATUS Filters images having a status attribute matching STATUS For more information, see :doc:`About Image Statuses <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 sort 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.

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 public 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 public 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.example.com/images/1 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.example.com/images/1 x-image-meta-name Ubuntu 10.04 Plain 5GB 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-location swift://account:key/container/image.tar.gz.0 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-property-distro Ubuntu 10.04 LTS 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/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.

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 public 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 public 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.example.com/images/1 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.example.com/images/1 x-image-meta-name Ubuntu 10.04 Plain 5GB 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-location swift://account:key/container/image.tar.gz.0 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-property-distro Ubuntu 10.04 LTS 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/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 image data itself will be the body of the HTTP response returned from the request, which will have content-type of `application/octet-stream`.

We have created a new virtual machine image in some way (created a "golden image" or snapshotted/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 glance.example.com, we issue a POST request to add an image to Glance: POST http://glance.example.com/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.

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. Its value should be the name of the image. Note that 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. 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, s3, or swift 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 default. See the configuration option default_store for more information. x-image-meta-disk-format This header is optional. Valid values are one of aki, ari, ami, raw, iso, vhd, vdi, qcow2, or vmdk. For more information, see :doc:`About Disk and Container Formats <formats>` x-image-meta-container-format This header is optional. Valid values are one of aki, ari, ami, bare, or ovf. For more information, see :doc:`About Disk and Container Formats <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 shall be the expected MD5 checksum of the image file data. When present, Glance will verify the checksum generated from the backend store when 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 image, 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 specific to a user. 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 the lower-cased string following the prefix x-image-meta-property- with dashes and punctuation replaced with underscores. For example, if the following HTTP header were sent: x-image-meta-property-distro Ubuntu 10.10 Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the image in Glance. There is no limit on the number of free-form key/value attributes that can be attached to the image. However, keep in mind that the 8K limit on the size of all HTTP headers sent in a request will effectively limit the number of image properties.

Glance will view as image metadata any HTTP header that it receives in a ``PUT`` request where the header key is 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 as data associated with it (e.g. 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: :doc:`Image Statuses <statuses>`