# Basic Configuration

Glance has a number of options that you can use to configure the Glance API server and the various storage backends that Glance can use to store images.

Most configuration is done via configuration files.

When starting up a Glance server, you can specify the configuration file to use (see the documentation on controller Glance servers). If you do not specify a configuration file, Glance will look in the following directories for a configuration file, in order:

- `~/.glance`

- `~/`

- `/etc/glance`

- `/etc`

The Glance API server configuration file should be named `glance-api.conf`. There are many other configuration files also since Glance maintains a configuration file for each of its services. If you installed Glance via your operating system’s package management system, it is likely that you will have sample configuration files installed in `/etc/glance`.

In addition, sample configuration files for each server application with detailed comments are available in the Glance Sample Configuration section.

The PasteDeploy configuration (controlling the deployment of the WSGI application for each component) may be found by default in <component>-paste.ini alongside the main configuration file, <component>.conf. For example, `glance-api-paste.ini` corresponds to `glance-api.conf`. This pathname for the paste config is configurable, as follows:

    [paste_deploy]
    config_file = /path/to/paste/config

## Common Configuration Options in Glance

Glance has a few command-line options that are common to all Glance programs:

`--verbose`

  Optional. Default: `False`

  Can be specified on the command line and in configuration files.

  Turns on the INFO level in logging and prints more verbose command-line interface printouts.

`--debug`

  Optional. Default: `False`

  Can be specified on the command line and in configuration files.

  Turns on the DEBUG level in logging.

`--config-file=PATH`

  Optional. Default: See below for default search order.

  Specified on the command line only.

  Takes a path to a configuration file to use when running the program. If this CLI option is not specified, then we check to see if the first argument is a file. If it is, then we try to use that as the configuration file. If there is no file or there were no arguments, we search for a configuration file in the following order:

  - `~/.glance`

  - `~/`

  - `/etc/glance`

  - `/etc`

  The filename that is searched for depends on the server application name. So, if you are starting up the API server, `glance-api.conf` is searched for.

`--config-dir=DIR`

  Optional. Default: `None`

  Specified on the command line only.

  Takes a path to a configuration directory from which all *.conf fragments are loaded. This provides an alternative to multiple `--config-file` options when it is inconvenient to explicitly enumerate all the configuration files, for example when an unknown number of config fragments are being generated by a deployment framework.

  If `--config-dir` is set, then `--config-file` is ignored.

  An example usage would be:

      $ glance-api --config-dir=/etc/glance/glance-api.d

      $ ls /etc/glance/glance-api.d
        00-core.conf
        01-swift.conf
        02-ssl.conf
        ... etc.

  The numeric prefixes in the example above are only necessary if a specific parse ordering is required (i.e. if an individual config option set in an earlier fragment is overridden in a later fragment).

  Note that `glance-manage` currently loads configuration from three files:

  - `glance-api.conf`

  - `glance-manage.conf`

  By default `glance-manage.conf` only specifies a custom logging file but other configuration options for `glance-manage` should be migrated in there. Warning: Options set in `glance-manage.conf` will override options of the same section and name set in `glance-api.conf`

## Configuring Server Startup Options

Glance is deployed under a WSGI server (for example uWSGI). Binding, worker processes, and socket tuning are configured in the WSGI server, not in `glance-api.conf`. The former standalone/eventlet server options (`bind_host`, `bind_port`, `workers`, `backlog`, `tcp_keepidle`, `client_socket_timeout`, `http_keepalive`, and `max_header_line`) have been removed.

`max_request_id_length=LENGTH`

  Limits the maximum size of the x-openstack-request-id header which is logged. Affects only if context middleware is configured in pipeline.

  Optional. Default: `64`

## Configuring Logging in Glance

There are a number of configuration options in Glance that control how Glance servers log messages.

`--log-config=PATH`

  Optional. Default: `None`

  Specified on the command line only.

  Takes a path to a configuration file to use for configuring logging.

### Logging Options Available Only in Configuration Files

You will want to place the different logging options in the [DEFAULT] section in your application configuration file. As an example, you might do the following for the API server, in a configuration file called `etc/glance-api.conf`:

    [DEFAULT]
    log_file = /var/log/glance/api.log

`log_file`

  The filepath of the file to use for logging messages from Glance’s servers. If missing, 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`

  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`

  The format string for timestamps in the log output.

  Defaults to `%Y-%m-%d %H:%M:%S`. See the logging module documentation for more information on setting this format string.

`log_use_syslog`

  Use syslog logging functionality.

  Defaults to False.

## Configuring Glance Storage Backends

There are a number of configuration options in Glance that control how Glance stores disk images. Enabled backends must be defined in the `[DEFAULT]` section.

`enabled_backends=store1_id:store1_type, store2_id:store2_type[,...]`

  Required.

  A comma-separated list of “store_id:store_type” strings. The store ids can be chosen by the user, whereas valid store types are (`file`, `http`, `rbd`, `swift`, `cinder`, `vmware`, `s3`).

The default backend must then be set in the `[glance_store]` section:

`default_backend = store1_id`

  Required.

  This option must be set to one of the store identifiers used in `enabled_backends`.

Additionally, one section must be created for every key:value pair defined in `enabled_backends`. Each section must be populated with store-specific options. See Configuring multiple Cinder Storage Backend for a full example.

### Configuring the Filesystem Storage Backend

`filesystem_store_datadir=PATH`

  Optional. Default: `/var/lib/glance/images/`

  Can only be specified in configuration files.

  This option is specific to the filesystem storage backend.

  Sets the path where the filesystem storage backend write disk images. Note that the filesystem storage backend will attempt to create this directory if it does not exist. Ensure that the user that `glance-api` runs under has write permissions to this directory.

`filesystem_store_file_perm=PERM_MODE`

  Optional. Default: `0`

  Can only be specified in configuration files.

  This option is specific to the filesystem storage backend.

  The required permission value, in octal representation, for the created image file. You can use this value to specify the user of the consuming service (such as Nova) as the only member of the group that owns the created files. To keep the default value, assign a permission value that is less than or equal to 0. Note that the file owner must maintain read permission; if this value removes that permission an error message will be logged and the BadStoreConfiguration exception will be raised. If the Glance service has insufficient privileges to change file access permissions, a file will still be saved, but a warning message will appear in the Glance log.

`filesystem_store_chunk_size=SIZE_IN_BYTES`

  Optional. Default: `65536`

  Can only be specified in configuration files.

  This option is specific to the filesystem storage backend.

  The chunk size used when reading or writing image files. Raising this value may improve the throughput but it may also slightly increase the memory usage when handling a large number of requests.

### Configuring the Filesystem Storage Backend with multiple stores

`filesystem_store_datadirs=PATH:PRIORITY`

  Optional. Default: `/var/lib/glance/images/:1`

  Example:

      filesystem_store_datadirs = /var/glance/store
      filesystem_store_datadirs = /var/glance/store1:100
      filesystem_store_datadirs = /var/glance/store2:200

  This option can only be specified in configuration file and is specific to the filesystem storage backend only.

  filesystem_store_datadirs option allows administrators to configure multiple store directories to save glance image in filesystem storage backend. Each directory can be coupled with its priority.

  NOTE:

  - This option can be specified multiple times to specify multiple stores.

  - Either filesystem_store_datadir or filesystem_store_datadirs option must be specified in glance-api.conf

  - Store with priority 200 has precedence over store with priority 100.

  - If no priority is specified, default priority ‘0’ is associated with it.

  - If two filesystem stores have same priority store with maximum free space will be chosen to store the image.

  - If same store is specified multiple times then BadStoreConfiguration exception will be raised.

### Configuring the Swift Storage Backend

`swift_store_auth_address=URL`

  Required when using the Swift storage backend.

  Can only be specified in configuration files.

  Deprecated. Use `auth_address` in the Swift back-end configuration file instead.

  This option is specific to the Swift storage backend.

  Sets the authentication URL supplied to Swift when making calls to its storage system. For more information about the Swift authentication system, please see the Swift auth documentation.

  IMPORTANT NOTE: Swift authentication addresses use HTTPS by default. This means that if you are running Swift with authentication over HTTP, you need to set your `swift_store_auth_address` to the full URL, including the `http://`.

`swift_store_user=USER`

  Required when using the Swift storage backend.

  Can only be specified in configuration files.

  Deprecated. Use `user` in the Swift back-end configuration file instead.

  This option is specific to the Swift storage backend.

  Sets the user to authenticate against the `swift_store_auth_address` with.

`swift_store_key=KEY`

  Required when using the Swift storage backend.

  Can only be specified in configuration files.

  Deprecated. Use `key` in the Swift back-end configuration file instead.

  This option is specific to the Swift storage backend.

  Sets the authentication key to authenticate against the `swift_store_auth_address` with for the user `swift_store_user`.

`swift_store_container=CONTAINER`

  Optional. Default: `glance`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Sets the name of the container to use for Glance images in Swift.

`swift_store_create_container_on_put`

  Optional. Default: `False`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  If true, Glance will attempt to create the container `swift_store_container` if it does not exist.

`swift_store_large_object_size=SIZE_IN_MB`

  Optional. Default: `5120`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  What size, in MB, should Glance start chunking image files and do a large object manifest in Swift? By default, this is the maximum object size in Swift, which is 5GB

`swift_store_large_object_chunk_size=SIZE_IN_MB`

  Optional. Default: `200`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  When doing a large object manifest, what size, in MB, should Glance write chunks to Swift? The default is 200MB.

`swift_store_multi_tenant=False`

  Optional. Default: `False`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  If set to True enables multi-tenant storage mode which causes Glance images to be stored in tenant specific Swift accounts. When set to False Glance stores all images in a single Swift account.

`swift_store_multiple_containers_seed`

  Optional. Default: `0`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  When set to 0, a single-tenant store will only use one container to store all images. When set to an integer value between 1 and 32, a single-tenant store will use multiple containers to store images, and this value will determine how many characters from an image UUID are checked when determining what container to place the image in. The maximum number of containers that will be created is approximately equal to 16^N. This setting is used only when swift_store_multi_tenant is disabled.

  Example: if this config option is set to 3 and swift_store_container = ‘glance’, then an image with UUID ‘fdae39a1-bac5-4238-aba4-69bcc726e848’ would be placed in the container ‘glance_fda’. All dashes in the UUID are included when creating the container name but do not count toward the character limit, so in this example with N=10 the container name would be ‘glance_fdae39a1-ba’.

  When choosing the value for swift_store_multiple_containers_seed, deployers should discuss a suitable value with their swift operations team. The authors of this option recommend that large scale deployments use a value of ‘2’, which will create a maximum of ~256 containers. Choosing a higher number than this, even in extremely large scale deployments, may not have any positive impact on performance and could lead to a large number of empty, unused containers. The largest of deployments could notice an increase in performance if swift rate limits are throttling on single container. Note: If dynamic container creation is turned off, any value for this configuration option higher than ‘1’ may be unreasonable as the deployer would have to manually create each container.

`swift_store_admin_tenants`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: Not set.

  A list of swift ACL strings that will be applied as both read and write ACLs to the containers created by Glance in multi-tenant mode. This grants the specified tenants/users read and write access to all newly created image objects. The standard swift ACL string formats are allowed, including:

  <tenant_id>:<username> <tenant_name>:<username> *:<username>

  Multiple ACLs can be combined using a comma separated list, for example: swift_store_admin_tenants = service:glance,*:admin

`swift_store_auth_version`

  Can only be specified in configuration files.

  Deprecated. This option will be removed in a future release.

  This option is specific to the Swift storage backend.

  Optional. Default: `3`

  A string indicating which version of Swift OpenStack authentication to use. See the project python-swiftclient for more details.

`swift_store_service_type`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: `object-store`

  A string giving the service type of the swift service to use.

`swift_store_region`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: Not set.

  A string giving the region of the swift service endpoint to use. This setting is especially useful for disambiguation if multiple swift services might appear in a service catalog during authentication.

`swift_store_endpoint_type`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: `publicURL`

  A string giving the endpoint type of the swift service endpoint to use.

`swift_store_ssl_compression`

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: True.

  If set to False, disables SSL layer compression of https swift requests. Setting to ‘False’ may improve performance for images which are already in a compressed format, e.g. qcow2. If set to True then compression will be enabled (provided it is supported by the swift proxy).

`swift_store_cacert`

  Can only be specified in configuration files.

  Optional. Default: `None`

  A string giving the path to a CA certificate bundle that will allow Glance’s services to perform SSL verification when communicating with Swift.

`swift_store_retry_get_count`

  The number of times a Swift download will be retried before the request fails. Optional. Default: `0`

#### Configuring Multiple Swift Accounts/Stores

In order to not store Swift account credentials in the database, and to have support for multiple accounts (or multiple Swift backing stores), a reference is stored in the database and the corresponding configuration (credentials/ parameters) details are stored in the configuration file. Optional. Default: not enabled.

The location for this file is specified using the `swift_store_config_file` configuration file in the section `[DEFAULT]`. If an incorrect value is specified, Glance API Swift store service will not be configured.

`swift_store_config_file=PATH`

  This option is specific to the Swift storage backend.

`default_swift_reference=DEFAULT_REFERENCE`

  Required when multiple Swift accounts/backing stores are configured.

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  It is the default swift reference that is used to add any new images.

`swift_store_auth_insecure`

  If True, bypass SSL certificate verification for Swift.

  Can only be specified in configuration files.

  This option is specific to the Swift storage backend.

  Optional. Default: `False`

#### Configuring Swift configuration file

If `swift_store_config_file` is set, Glance will use information from the file specified under this parameter.

Note

The `swift_store_config_file` is currently used only for single-tenant Swift store configurations. If you configure a multi-tenant Swift store back end (`swift_store_multi_tenant=True`), ensure that both `swift_store_config_file` and `default_swift_reference` are not set.

The file contains a set of references like:

    [ref1]
    user = project_name1:user_name1
    key = key1
    user_domain_id = default
    project_domain_id = default
    auth_address = http://localhost:5000/v3

    [ref2]
    user = project_name2:user_name2
    key = key2
    user_domain_id = default
    project_domain_id = default
    auth_address = http://localhost:5000/v3

A default reference must be configured. Its parameters will be used when creating new images. For example, to specify `ref2` as the default reference, add the following value to the [glance_store] section of `glance-api.conf` file:

    default_swift_reference = ref2

In the reference, a user can specify the following parameters:

`user`

  A project_name user_name pair in the `project_name:user_name` format to authenticate against the Swift authentication service.

`key`

  An authentication key for a user authenticating against the Swift authentication service.

`auth_address`

  An address where the Swift authentication service is located.

`auth_version`

  A version of the authentication service to use. Valid version is `3`.

  Deprecated. This option will be removed in a future release.

  Optional. Default: `3`

`project_domain_id`

  A domain ID of the project which is the requested project-level authorization scope.

  Optional. Default: `None`

`project_domain_name`

  A domain name of the project which is the requested project-level authorization scope.

  Optional. Default: `None`

`user_domain_id`

  A domain ID of the user which is the requested domain-level authorization scope.

  Optional. Default: `None`

`user_domain_name`

  A domain name of the user which is the requested domain-level authorization scope.

  Optional. Default: `None`

### Configuring the RBD Storage Backend

Note: the RBD storage backend requires the python bindings for librados and librbd. These are in the python-ceph package on Debian-based distributions.

`rbd_store_pool=POOL`

  Optional. Default: `rbd`

  Can only be specified in configuration files.

  This option is specific to the RBD storage backend.

  Sets the RADOS pool in which images are stored.

`rbd_store_chunk_size=CHUNK_SIZE_MB`

  Optional. Default: `8`

  Can only be specified in configuration files.

  This option is specific to the RBD storage backend.

  Images will be chunked into objects of this size (in megabytes). For best performance, this should be a power of two.

`rados_connect_timeout`

  Optional. Default: `0`

  Can only be specified in configuration files.

  This option is specific to the RBD storage backend.

  Prevents glance-api hangups during the connection to RBD. Sets the time to wait (in seconds) for glance-api before closing the connection. Setting `rados_connect_timeout<=0` means no timeout.

`rbd_store_ceph_conf=PATH`

  Optional. Default: `/etc/ceph/ceph.conf`, `~/.ceph/config`, and `./ceph.conf`

  Can only be specified in configuration files.

  This option is specific to the RBD storage backend.

  Sets the Ceph configuration file to use.

`rbd_store_user=NAME`

  Optional. Default: `admin`

  Can only be specified in configuration files.

  This option is specific to the RBD storage backend.

  Sets the RADOS user to authenticate as. This is only needed when RADOS authentication is enabled.

A keyring must be set for this user in the Ceph configuration file, e.g. with a user `glance`:

    [client.glance]
    keyring=/etc/glance/rbd.keyring

To set up a user named `glance` with minimal permissions, using a pool called `images`, first create the pool and then the Ceph auth user:

    ceph osd pool create images
    ceph auth get-or-create client.glance \
      mon 'profile rbd' \
      osd 'profile rbd pool=images' \
      mgr 'profile rbd pool=images'

Then copy the keyring to the Glance API server:

    ceph auth get-or-create client.glance | ssh {your-glance-api-server} \
      sudo tee /etc/ceph/ceph.client.glance.keyring
    ssh {your-glance-api-server} \
      sudo chown glance:glance /etc/ceph/ceph.client.glance.keyring

Note

The `profile rbd` capabilities are preferred over raw capabilities such as `allow rwx` because they include permissions needed for RBD exclusive locks (e.g. blocklisting stale clients). They also stay up to date as Ceph evolves. See the Ceph user management documentation for details.

For the complete set of Ceph authentication setup commands for all OpenStack services (Glance, Cinder, Nova), refer to the Ceph Block Devices and OpenStack documentation.

### Configuring the Cinder Storage Backend

The cinder store gives you the ability to store images in volumes (one volume per image) in the Block Storage (Cinder) service. Glance does not have direct access to whatever backend(s) are configured for Cinder; it simply hands the image data over to the Block Storage service, and Cinder decides where exactly it will be stored.

Glance can influence where the data will be stored by setting the `cinder_volume_type` option when configuring your cinder store. See below for details.

Note: To create a Cinder volume from an image in this store quickly, additional settings are required. Please see the Volume-backed image documentation for more information.

Warning

Because an Image-Volume created in a user account is susceptible to modifications by normal users that can corrupt the image, we recommend that service credentials should always be set in the configuration file so that the Image-Volume will be created in an internal project not directly accessible by non-service users.

To create the Image-Volume in internal project, we need to set the following configuration parameters to the glance service user and the internal service project:

- `cinder_store_user_name`

- `cinder_store_password`

- `cinder_store_project_name`

- `cinder_store_auth_address`

`cinder_catalog_info=<service_type>:<service_name>:<endpoint_type>`

  Optional. Default: `volumev3::publicURL`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Sets the info to match when looking for cinder in the service catalog. Format is : separated values of the form: <service_type>:<service_name>:<endpoint_type>

`cinder_endpoint_template=http://ADDR:PORT/VERSION/%(tenant)s`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Override service catalog lookup with template for cinder endpoint. `%(...)s` parts are replaced by the value in the request context. e.g. http://localhost:8776/v3/%(tenant)s

`os_region_name=REGION_NAME`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Region name of this node.

  Deprecated. Use `cinder_os_region_name` instead.

`cinder_os_region_name=REGION_NAME`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Region name of this node. If specified, it is used to locate cinder from the service catalog.

`cinder_ca_certificates_file=CA_FILE_PATH`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Location of ca certificates file to use for cinder client requests.

`cinder_http_retries=TIMES`

  Optional. Default: `3`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Number of cinderclient retries on failed http calls.

`cinder_state_transition_timeout`

  Optional. Default: `300`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Time period, in seconds, to wait for a cinder volume transition to complete.

`cinder_api_insecure=ON_OFF`

  Optional. Default: `False`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Allow to perform insecure SSL requests to cinder.

`cinder_store_user_name=NAME`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  User name to authenticate against Cinder. If <None>, the user of current context is used.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set. These options are useful to put image volumes into the internal service project in order to hide the volume from users, and to make the image shareable among projects.

`cinder_store_user_domain_name=NAME`

  Optional. Default: `Default`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Domain of the user to authenticate against cinder.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set.

`cinder_store_password=PASSWORD`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Password for the user authenticating against Cinder. If <None>, the current context auth token is used.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set.

`cinder_store_project_name=NAME`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Project name where the image is stored in Cinder. If <None>, the project in current context is used.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set.

`cinder_store_project_domain_name=NAME`

  Optional. Default: `Default`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Domain of the project where the image volume is stored in cinder.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set.

`cinder_store_auth_address=URL`

  Optional. Default: `None`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  The address where the Cinder authentication service is listening. If <None>, the cinder endpoint in the service catalog is used.

  NOTE: This option is applied only if all of `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address` are set.

`rootwrap_config=NAME`

  Optional. Default: `/etc/glance/rootwrap.conf`

  Can only be specified in configuration files.

  This option is specific to the Cinder storage backend.

  Path to the rootwrap configuration file to use for running commands as root.

`lock_path`

  Required. Defaults to environment variable OSLO_LOCK_PATH, though we recommend setting a value in the configuration file.

  This specifies the directory to use for lock files.

  NOTE: This option must be set in the `[oslo_concurrency]` section of the configuration file.

      [oslo_concurrency]
      # ...
      lock_path = /var/lib/glance/tmp

## Configuring multi-attach volume type

When using Cinder as Glance backend, we store the image into an Image-Volume residing in the `service` project owned by the `glance` user (recommended).

When we use the image to create a volume or a server, the Image-Volume gets attached to the Glance host and we copy the image data to the destination whether being the volume or the server.

This workflow can cause problem when we try to create multiple resources using the same image since Cinder volumes, by default, does not provide the ability to attach the same volume multiple times.

This requires a special feature called Volume multi-attach which enables the volume to be attached multiple times to same or different host.

To enable multi-attach functionality for Image-Volumes, we can perform the following steps:

- Create a multiattach volume type and set the `<is> multiattach` property

    $ openstack volume type create glance-multiattach
    $ openstack volume type set --property multiattach="<is> True"  glance-multiattach

Note

Creating a new volume type is an admin-only operation by default.

- (OPTIONAL) Set the `volume_backend_name` property

Once you create the multi-attach volume type for Glance, you should also set the `volume_backend_name` property so that your Image-Volumes don’t end up in random backends based on the scheduling done by Cinder.

Note

This is not needed if you are going to re-use the existing volume types created for Cinder volumes.

Ask your Cinder administrator for the right `volume_backend_name` to set for your multi-attach volume type. Here we are using `LVM_iSCSI` as an example.

    $ openstack volume type set glance-multiattach --property volume_backend_name=LVM_iSCSI

- Finally you need to set the multi-attach volume type as the value of `cinder_volume_type` config option to use it for creating Image-Volumes.

In glance-api.conf:

    [DEFAULT]
    # list of enabled stores identified by their property group name
    enabled_backends = fast:cinder

    # the default store, if not set glance-api service will not start
    [glance_store]
    default_backend = fast

    # conf props for fast store instance
    [fast]
    ...
    cinder_volume_type = glance-multiattach

### Configuring multiple Cinder Storage Backend

From Victoria onwards Glance fully supports configuring multiple cinder stores by taking advantage of cinder `volume-types`. Note that volume-types are defined by a Cinder administrator, and hence setting up multiple cinder stores will require collaboration with the Cinder admin.

From the Glance side, you will add each of the cinder stores you want to define to the `enabled_backends` configuration option in glance configuration file. For each of these stores, you must then set the `cinder_volume_type` configuration option in the store’s specific configuration section of glance-api.conf. What to set it to will depend on the volume-types that are available in Cinder; consult with your Cinder administrator to get a list of appropriate volume-types.

Warning

It is mandatory to set the following configuration parameters for multiple cinder stores to work:

- `cinder_store_user_name`

- `cinder_store_password`

- `cinder_store_project_name`

- `cinder_store_auth_address`

- `cinder_volume_type`

This is because, when initializing the cinder store, we query cinder to validate the volume types set in the glance configuration file using the above credentials. If this is not validated during sevice start, we might fail to create the image later due to invalid volume type being configured.

Below are some multiple cinder store configuration examples.

Example 1: Fresh deployment

For example, if cinder has configured 2 volume types fast and slow then glance configuration should look like;:

    [DEFAULT]
    # list of enabled stores identified by their property group name
    enabled_backends = fast:cinder, slow:cinder

    # the default store, if not set glance-api service will not start
    [glance_store]
    default_backend = fast

    # conf props for fast store instance
    [fast]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-fast
    description = LVM based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

    # conf props for slow store instance
    [slow]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-slow
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

Example 2: Upgrade from single cinder store to multiple cinder stores, if default_volume_type is set in cinder.conf and cinder_volume_type is also set in glance-api.conf then operator needs to create one store in glance where cinder_volume_type is same as the old glance configuration:

    # cinder.conf
    The glance administrator has to find out what the default volume-type is
    in the cinder installation, so they need to discuss with either cinder
    admin or cloud admin to identify default volume-type from cinder and then
    explicitly configure that as the value of ``cinder_volume_type``.

Example config before upgrade:

    # old configuration in glance
    [glance_store]
    stores = cinder, file, http
    default_store = cinder
    cinder_state_transition_timeout = 300
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    cinder_catalog_info = volumev3::publicURL
    cinder_volume_type = glance-old

Example config after upgrade:

    # new configuration in glance
    [DEFAULT]
    enabled_backends = old:cinder, new:cinder

    [glance_store]
    default_backend = new

    [new]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-new
    description = LVM based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

    [old]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-old # as per old cinder.conf
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

Example 3: Upgrade from single cinder store to multiple cinder stores, if default_volume_type is not set in cinder.conf neither cinder_volume_type set in glance-api.conf then administrator needs to create one store in glance to replicate exact old configuration:

    # cinder.conf
    The glance administrator has to find out what the default volume-type is
    in the cinder installation, so they need to discuss with either cinder
    admin or cloud admin to identify default volume-type from cinder and then
    explicitly configure that as the value of ``cinder_volume_type``.

Example config before upgrade:

    # old configuration in glance
    [glance_store]
    stores = cinder, file, http
    default_store = cinder
    cinder_state_transition_timeout = 300
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_catalog_info = volumev3::publicURL

Example config after upgrade:

    # new configuration in glance
    [DEFAULT]
    enabled_backends = old:cinder, new:cinder

    [glance_store]
    default_backend = new

    # cinder store as per old (single store configuration)
    [old]
    rootwrap_config = /etc/glance/rootwrap.conf
    description = LVM based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

    [new]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-new
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

Example 4: Upgrade from single cinder store to multiple cinder stores, if default_volume_type is set in cinder.conf but cinder_volume_type is not set in glance-api.conf then administrator needs to set cinder_volume_type same as the default_backend set in cinder.conf to one of the store:

    # cinder.conf
    The glance administrator has to find out what the default volume-type is
    in the cinder installation, so they need to discuss with either cinder
    admin or cloud admin to identify default volume-type from cinder and then
    explicitly configure that as the value of ``cinder_volume_type``.

Example config before upgrade:

    # old configuration in glance
    [glance_store]
    stores = cinder, file, http
    default_store = cinder
    cinder_state_transition_timeout = 300
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service

Example config after upgrade:

    # new configuration in glance
    [DEFAULT]
    enabled_backends = old:cinder,new:cinder

    [glance_store]
    default_backend = old

    [old]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-old # as per old cinder.conf
    description = LVM based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

    [new]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-new
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

Example 5: Upgrade from single cinder store to multiple cinder stores, if properties like `cinder_store_user_name`, `cinder_store_password`, `cinder_store_project_name` and `cinder_store_auth_address`, are not set in single store:

    # old configuration in glance
    [glance_store]
    stores = cinder, file, http
    default_store = cinder
    cinder_state_transition_timeout = 300
    rootwrap_config = /etc/glance/rootwrap.conf

Example config after upgrade:

    # new configuration in glance
    [DEFAULT]
    enabled_backends = new:cinder

    [glance_store]
    default_backend = new

    [new]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-new
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service
    # etc..

Since the cinder specific properties were not set in single store, the Image-Volumes would exist in user projects which needs to be transferred. After upgrading to multi store, you need to make sure all the Image-Volumes are transferred to the `service` project.

Procedure:

1. Login to the user and project owning the Image-Volume and create a volume transfer request.

    openstack volume transfer request create <Image-Volume-ID>

Note down the `id` and `auth_key` as they will be used when accepting the transfer.

2. List the transfer request to verify the transfer was created successfully.

    openstack volume transfer request list

3. Login to the glance user and service project and accept the transfer.

    openstack volume transfer request accept transferID authKey

4. List the volumes to see if the Image-Volume was transferred successfully.

    openstack volume list --name <Image-Volume-Name>

Once all the Image-Volumes are migrated to the service project, you can list or show the images and it will update the location from old format to the new format.

Warning

It is important to note that when upgrading from single store to multiple stores, the values for cinder store specific configuration parameters should remain the same before and after the upgrade.

Example: Suppose you have the following credentials set in single store configuration:

    [glance_store]
    stores = cinder, file, http
    default_store = cinder
    cinder_state_transition_timeout = 300
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service

Then after the upgrade, the cinder specific paramter values for `cinder_store_auth_address`, `cinder_store_user_name`, `cinder_store_password` and `cinder_store_project_name` should be same:

    [DEFAULT]
    enabled_backends = new:cinder

    [glance_store]
    default_backend = new

    [new]
    rootwrap_config = /etc/glance/rootwrap.conf
    cinder_volume_type = glance-new
    description = NFS based cinder store
    cinder_catalog_info = volumev3::publicURL
    cinder_store_auth_address = http://localhost/identity/v3
    cinder_store_user_name = glance
    cinder_store_password = admin
    cinder_store_project_name = service

While upgrading from single cinder stores to multiple single stores, location URLs for legacy images will be changed from `cinder://volume-id` to `cinder://store-name/volume-id`.

Note: After upgrade from single cinder store to use multiple cinder stores the first `image-list` or first `GET` or `image-show` call for image will take additional time as we will perform the lazy loading operation to update legacy image location url to use new image location urls. Subsequent `GET` or `image-list` or `image-show` calls will perform as they were performing earlier.

### Configuring the VMware Storage Backend

`vmware_server_host=ADDRESS`

  Required when using the VMware storage backend.

  Can only be specified in configuration files.

  Sets the address of the ESX/ESXi or vCenter Server target system. The address can contain an IP (`127.0.0.1`), an IP and port (`127.0.0.1:443`), a DNS name (`www.my-domain.com`) or DNS and port.

  This option is specific to the VMware storage backend.

`vmware_server_username=USERNAME`

  Required when using the VMware storage backend.

  Can only be specified in configuration files.

  Username for authenticating with VMware ESX/ESXi or vCenter Server.

`vmware_server_password=PASSWORD`

  Required when using the VMware storage backend.

  Can only be specified in configuration files.

  Password for authenticating with VMware ESX/ESXi or vCenter Server.

`vmware_datastores`

  Required when using the VMware storage backend.

  This option can only be specified in configuration file and is specific to the VMware storage backend.

  vmware_datastores allows administrators to configure multiple datastores to save glance image in the VMware store backend. The required format for the option is: <datacenter_path>:<datastore_name>:<optional_weight>.

  where datacenter_path is the inventory path to the datacenter where the datastore is located. An optional weight can be given to specify the priority.

  Example:

      vmware_datastores = datacenter1:datastore1
      vmware_datastores = dc_folder/datacenter2:datastore2:100
      vmware_datastores = datacenter1:datastore3:200

  NOTE:

  - This option can be specified multiple times to specify multiple datastores.

  - Either vmware_datastore_name or vmware_datastores option must be specified in glance-api.conf

  - Datastore with weight 200 has precedence over datastore with weight 100.

  - If no weight is specified, default weight ‘0’ is associated with it.

  - If two datastores have same weight, the datastore with maximum free space will be chosen to store the image.

  - If the datacenter path or datastore name contains a colon (:) symbol, it must be escaped with a backslash.

`vmware_api_retry_count=TIMES`

  Optional. Default: `10`

  Can only be specified in configuration files.

  The number of times VMware ESX/VC server API must be retried upon connection related issues.

`vmware_task_poll_interval=SECONDS`

  Optional. Default: `5`

  Can only be specified in configuration files.

  The interval used for polling remote tasks invoked on VMware ESX/VC server.

`vmware_store_image_dir`

  Optional. Default: `/openstack_glance`

  Can only be specified in configuration files.

  The path to access the folder where the images will be stored in the datastore.

`vmware_api_insecure=ON_OFF`

  Optional. Default: `False`

  Can only be specified in configuration files.

  Allow to perform insecure SSL requests to ESX/VC server.

### Configuring the S3 Storage Backend

`s3_store_host`

  Can only be specified in configuration files.

  The host where the S3 server is listening. This option can contain a DNS name (e.g. s3.amazonaws.com, my-object-storage.com) or an IP address (127.0.0.1).

  Example:

      s3_store_host = http://s3-ap-northeast-1.amazonaws.com
      s3_store_host = https://s3-ap-northeast-1.amazonaws.com
      s3_store_host = http://my-object-storage.com
      s3_store_host = https://my-object-storage.com:9000

`s3_store_access_key`

  Can only be specified in configuration files.

  Access Key for authenticating with the Amazon S3 or S3 compatible storage server.

`s3_store_secret_key`

  Can only be specified in configuration files.

  Secret Key for authenticating with the Amazon S3 or S3 compatible storage server.

`s3_store_bucket`

  Can only be specified in configuration files.

  Bucket name where the glance images will be stored in the S3. If `s3_store_create_bucket_on_put` is set to true, it will be created automatically even if the bucket does not exist.

`s3_store_create_bucket_on_put`

  Optional. Default: `False`

  Can only be specified in configuration files.

  Determine whether S3 should create a new bucket. This option takes boolean value to indicate whether or not Glance should create new bucket to S3 if it does not exist.

`s3_store_bucket_url_format`

  Optional. Default: `auto`

  Can only be specified in configuration files.

  This option takes access model that is used to specify the address of an object in an S3 bucket. You can set the value from `auto`, `virtual` or `path`.

  NOTE:

  - In `path`-style, the endpoint for the object looks like `https://s3.amazonaws.com/bucket/example.img`.

  - In `virtual`-style, the endpoint for the object looks like `https://bucket.s3.amazonaws.com/example.img`.

  - If you do not follow the DNS naming convention in the bucket name, you can get objects in the path style, but not in the virtual style.

`s3_store_large_object_size`

  Optional. Default: `100`

  Can only be specified in configuration files.

  What size, in MB, should S3 start chunking image files and do a multipart upload in S3.

`s3_store_large_object_chunk_size`

  Optional. Default: `10`

  Can only be specified in configuration files.

  What multipart upload part size, in MB, should S3 use when uploading parts.

`s3_store_thread_pools`

  Optional. Default: `10`

  Can only be specified in configuration files.

  The number of thread pools to perform a multipart upload in S3.

### Configuring multiple S3 Storage Backend

From Victoria onwards Glance fully supports configuring multiple S3 stores. From the Glance side, you will add each of the S3 stores you want to define to the `enabled_backends` configuration option in glance configuration file. For each of these stores, you must then set the S3-specific configuration options in the store’s specific configuration section of glance-api.conf.

Below is an example of multiple S3 store configuration.

Example 1: Fresh deployment

For example, if you want to configure 2 S3 stores s3-primary and s3-backup then glance configuration should look like:

    [DEFAULT]
    # list of enabled stores identified by their property group name
    enabled_backends = s3-primary:s3, s3-backup:s3

    # the default store, if not set glance-api service will not start
    [glance_store]
    default_backend = s3-primary

    # conf props for s3-primary store instance
    [s3-primary]
    s3_store_host = https://s3-us-east-1.amazonaws.com
    s3_store_access_key = primary-access-key
    s3_store_secret_key = primary-secret-key
    s3_store_bucket = glance-primary-bucket
    s3_store_create_bucket_on_put = True
    s3_store_bucket_url_format = virtual
    # etc..

    # conf props for s3-backup store instance
    [s3-backup]
    s3_store_host = https://s3-us-west-2.amazonaws.com
    s3_store_access_key = backup-access-key
    s3_store_secret_key = backup-secret-key
    s3_store_bucket = glance-backup-bucket
    s3_store_create_bucket_on_put = True
    s3_store_bucket_url_format = virtual
    # etc..

Example 2: Upgrade from single S3 store to multiple S3 stores

When upgrading from a single traditional S3 store to multistore, you need to ensure that the `s3_store_host` value remains the same as it was in the old configuration. This is critical for maintaining compatibility with existing images.

Warning

When upgrading from single S3 store to multiple S3 stores, the `s3_store_host` configuration parameter value must remain the same before and after the upgrade. Changing `s3_store_host` during upgrade will break access to existing images.

However, you can update `s3_store_access_key` and `s3_store_secret_key` at any time, including during the upgrade. Glance will automatically handle credential updates for existing images using lazy updating on each GET API call. This allows for seamless credential rotation without requiring immediate updates to all existing image locations.

Example config before upgrade:

    # old configuration in glance
    [glance_store]
    stores = s3, file, http
    default_store = s3
    s3_store_host = https://s3.amazonaws.com
    s3_store_access_key = old-access-key
    s3_store_secret_key = old-secret-key
    s3_store_bucket = glance-images
    s3_store_create_bucket_on_put = True
    s3_store_bucket_url_format = virtual

Example config after upgrade:

    # new configuration in glance
    [DEFAULT]
    enabled_backends = s3-legacy:s3

    [glance_store]
    default_backend = s3-legacy

    # S3 store matching old (single store) configuration
    # NOTE: s3_store_host MUST remain the same as old configuration
    [s3-legacy]
    s3_store_host = https://s3.amazonaws.com  # Same as before upgrade
    s3_store_access_key = old-access-key  # Can be updated anytime
    s3_store_secret_key = old-secret-key  # Can be updated anytime
    s3_store_bucket = glance-images
    s3_store_create_bucket_on_put = True
    s3_store_bucket_url_format = virtual

Credential Rotation: You can update `s3_store_access_key` and `s3_store_secret_key` in the store configuration at any time, including during or after the upgrade. When an image with old credentials is accessed via a GET API call, Glance will automatically detect the credential mismatch and update the image location URL with the new credentials. This lazy update mechanism ensures that:

- Credential rotation can be performed without downtime

- Existing images continue to work with old credentials until accessed

- Image locations are automatically updated when images are accessed

- No manual intervention is required for credential updates

Note: After upgrade from single S3 store to use multiple S3 stores, the first `GET` or `image-show` call for an image will take additional time as we will perform the lazy loading operation to update legacy image location URL to use new image location URLs with updated credentials if needed. Subsequent `GET` or `image-show` calls will perform as normal.

### Configuring the Storage Endpoint

`swift_store_endpoint=URL`

  Optional. Default: `None`

  Can only be specified in configuration files.

  Overrides the storage URL returned by auth. The URL should include the path up to and excluding the container. The location of an object is obtained by appending the container and object to the configured URL. e.g. `https://www.my-domain.com/v1/path_up_to_container`

## Configuring Glance Image Size Limit

The following configuration option is specified in the `glance-api.conf` configuration file in the section `[DEFAULT]`.

`image_size_cap=SIZE`

  Optional. Default: `1099511627776` (1 TB)

  Maximum image size, in bytes, which can be uploaded through the Glance API server.

  IMPORTANT NOTE: this value should only be increased after careful consideration and must be set to a value under 8 EB (9223372036854775808).

## Configuring Glance User Storage Quota

The following configuration option is specified in the `glance-api.conf` configuration file in the section `[DEFAULT]`.

Note

As of the Xena release, Glance supports per-tenant quotas with more granularity than the global limit provided by this option. You may want to enable per-tenant quotas and leave this unset.

`user_storage_quota`

  Optional. Default: 0 (Unlimited).

  This value specifies the maximum amount of storage that each user can use across all storage systems. Optionally unit can be specified for the value. Values are accepted in B, KB, MB, GB or TB which are for Bytes, KiloBytes, MegaBytes, GigaBytes and TeraBytes respectively. Default unit is Bytes.

  Example values would be,

    user_storage_quota=20GB

## Configuring Glance Per-Tenant Quotas

Glance can utilize per-tenant resource limits set in Keystone to enforce quotas on users. These limits must be registered with defaults in Keystone, with optional per-tenant overrides, prior to enabling them in Glance. To instruct glance to use limits in Keystone, set `[DEFAULT]/use_keystone_limits=True` in `glance-api.conf`.

## Configuring the Image Cache

Glance API servers can be configured to have a local image cache. Caching of image files is transparent and happens using a piece of middleware that can optionally be placed in the server application pipeline.

This pipeline is configured in the PasteDeploy configuration file, <component>-paste.ini. You should not generally have to edit this file directly, as it ships with ready-made pipelines for all common deployment flavors.

### Enabling the Image Cache Middleware

To enable the image cache middleware, the cache middleware must occur in the application pipeline after the appropriate context middleware.

The cache middleware should be in your `glance-api-paste.ini` in a section titled `[filter:cache]`. It should look like this:

    [filter:cache]
    paste.filter_factory = glance.api.middleware.cache:CacheFilter.factory

A ready-made application pipeline including this filter is defined in the `glance-api-paste.ini` file, looking like so:

    [pipeline:glance-api-caching]
    pipeline = versionnegotiation context cache apiv1app

To enable the above application pipeline, in your main `glance-api.conf` configuration file, select the appropriate deployment flavor like so:

    [paste_deploy]
    flavor = caching

### Enabling the Image Cache Management Middleware (DEPRECATED)

There is an optional `cachemanage` middleware that allows you to directly interact with cache images. Use this flavor in place of the `cache` flavor in your API configuration file. There are three types you can chose: `cachemanagement`, `keystone+cachemanagement` and `trusted-auth+cachemanagement`.:

    [paste_deploy]
    flavor = keystone+cachemanagement

The new cache management endpoints were introduced in Images API v. 2.13. If cache middleware is configured the new endpoints will be active and there is no need to use the cachemanagement middleware unless the old glance-cache-manage tooling is desired to be still used.

### Configuration Options Affecting the Image Cache

Note

These configuration options must be set in both the glance-cache and glance-api configuration files.

One main configuration file option affects the image cache.

`image_cache_dir=PATH`

  Required when image cache middleware is enabled.

  Default: `/var/lib/glance/image-cache`

  This is the base directory the image cache can write files to. Make sure the directory is writable by the user running the `glance-api` server

`image_cache_driver=DRIVER`

  Optional. Choice of `sqlite`, `xattr` or `centralized_db`

  Default: `centralized_db`

  The default `centralized_db` cache driver has no special dependencies, other than `worker_self_reference_url` which needs to be configured to store the reference of node in the database. Earlier cache database used to be independent for each glance api service, now with `centralized_db` cache driver it stores information about the cached files at one place which is in a central database. Old records from SQLite database will be migrated to central database on service restart during upgrade process.

  The `sqlite` cache driver has no special dependencies, and uses the built-in `sqlite3` module. It stores information about the cached files in a SQLite database.

  NOTE In Caracal release `sqlite` cache driver has been deprecated and will be removed in `F` development cycle.

  The `xattr` cache driver required the `python-xattr>=0.6.0` library and requires that the filesystem containing `image_cache_dir` have access times tracked for all files (in other words, the noatime option CANNOT be set for that filesystem). In addition, `user_xattr` must be set on the filesystem’s description line in fstab.

`image_cache_sqlite_db=DB_FILE`

  Optional.

  Default: `cache.db`

  When using the `sqlite` cache driver, you can set the name of the database that will be used to store the cached images information. The database is always contained in the `image_cache_dir`.

  NOTE In Caracal release `image_cache_sqlite_db` option has been deprecated and will be removed in `F` development cycle.

`image_cache_max_size=SIZE`

  Optional.

  Default: `10737418240` (10 GB)

  Size, in bytes, that the image cache should be constrained to. Images files are cached automatically in the local image cache, even if the writing of that image file would put the total cache size over this size. The `glance-cache-pruner` executable is what prunes the image cache to be equal to or less than this value. The `glance-cache-pruner` executable is designed to be run via cron on a regular basis. See more about this executable in Controlling the Growth of the Image Cache

## Migrating records from SQLite to Central database

In case of upgrades/updates we need to deal with migrating existing records from SQLite database to central database. This operation will be performed one time during service startup. If SQLite database file, configured using `image_cache_sqlite_db` configuration option (default `cache.db`) is present at service start and `image_cache_driver` is not set to `centralized_db` then we will read records from SQLite database and insert those in newly created `cached_images` table in central database. Once all records are migrated we will clear the SQLite database table and keep the SQLite database file as it is (to be deleted by administrator/operator later if required). Important point here is once deployer chooses to use `centralized_db` and we migrate their records out of SQLite database to central database, then we will not migrate them back if deployer wants to revert back to `sqlite` driver.

## Configuring Notifications

Glance can optionally generate notifications to be logged or sent to a message queue. The configuration options are specified in the `glance-api.conf` configuration file.

`[oslo_messaging_notifications]/driver`

  Optional. Default: `noop`

  Sets the notification driver used by oslo.messaging. Options include `messaging`, `messagingv2`, `log` and `routing`.

  NOTE In M release, the``[DEFAULT]/notification_driver`` option has been deprecated in favor of `[oslo_messaging_notifications]/driver`.

  For more information see Glance notifications and oslo.messaging.

`[DEFAULT]/disabled_notifications`

  Optional. Default: `[]`

  List of disabled notifications. A notification can be given either as a notification type to disable a single event, or as a notification group prefix to disable all events within a group.

  Example: if this config option is set to [“image.create”, “metadef_namespace”], then “image.create” notification will not be sent after image is created and none of the notifications for metadefinition namespaces will be sent.

## Configuring Glance Property Protections

Access to image meta properties may be configured using a Property Protections Configuration file. The location for this file can be specified in the `glance-api.conf` configuration file in the section `[DEFAULT]`. If an incorrect value is specified, glance API service will not start.

`property_protection_file=PATH`

  Optional. Default: not enabled.

  If property_protection_file is set, the file may use either roles or policies to specify property protections.

`property_protection_rule_format=<roles|policies>`

  Optional. Default: `roles`.

## Configuring Glance APIs

The glance-api service implements versions 2 of the OpenStack Images API. Currently there are no options to enable or disable specific API versions.

## Configuring Glance Tasks

Glance Tasks are implemented only for version 2 of the OpenStack Images API.

The config value `task_time_to_live` is used to determine how long a task would be visible to the user after transitioning to either the `success` or the `failure` state.

`task_time_to_live=<Time_in_hours>`

  Optional. Default: `48`

  The config value `task_executor` is used to determine which executor should be used by the Glance service to process the task. Only `taskflow` is supported.

`task_executor=taskflow`

  Optional. Default: `taskflow`

  The `taskflow` engine has its own set of configuration options, under the `taskflow_executor` section, that can be tuned to improve the task execution process. Among the available options, you may find `engine_mode` and `max_workers`. The former allows for selecting an execution model and the available options are `serial` and `parallel`. The `max_workers` option, instead, allows for controlling the number of workers that will be instantiated per executor instance.

  The default value for the `engine_mode` is `parallel`, whereas the default number of `max_workers` is `10`.

## Configuring Glance performance profiling

Glance supports using osprofiler to trace the performance of each key internal handling, including RESTful API calling, DB operation and etc.

`Please be aware that Glance performance profiling is currently a work in progress feature.` Although, some trace points is available, e.g. API execution profiling at wsgi main entry and SQL execution profiling at DB module, the more fine-grained trace point is being worked on.

The config value `enabled` is used to determine whether fully enable profiling feature for glance-api service.

`enabled=<True|False>`

  Optional. Default: `False`

  There is one more configuration option that needs to be defined to enable Glance services profiling. The config value `hmac_keys` is used for encrypting context data for performance profiling.

`hmac_keys=<secret_key_string>`

  Optional. Default: `SECRET_KEY`

  IMPORTANT NOTE: in order to make profiling work as designed operator needs to make those values of HMAC key be consistent for all services in their deployment. Without HMAC key the profiling will not be triggered even profiling feature is enabled.

  The config value `trace_sqlalchemy` is used to determine whether fully enable sqlalchemy engine based SQL execution profiling feature for glance-api service.

`trace_sqlalchemy=<True|False>`

  Optional. Default: `False`

## Configuring Glance public endpoint

This setting allows an operator to configure the endpoint URL that will appear in the Glance “versions” response (that is, the response to `GET /` ). This can be necessary when the Glance API service is run behind a proxy because the default endpoint displayed in the versions response is that of the host actually running the API service. If Glance is being run behind a load balancer, for example, direct access to individual hosts running the Glance API may not be allowed, hence the load balancer URL would be used for this value.

`public_endpoint=<None|URL>`

  Optional. Default: `None`

## Configuring http_keepalive option

`http_keepalive=<True|False>`

  If False, server will return the header “Connection: close”, If True, server will return “Connection: Keep-Alive” in its responses. In order to close the client socket connection explicitly after the response is sent and read successfully by the client, you simply have to set this option to False when you create a wsgi server.

## Configuring the Health Check

This setting allows an operator to configure the endpoint URL that will provide information to load balancer if given API endpoint at the node should be available or not. Glance API server can be configured to expose a health check URL.

To enable the health check middleware, it must occur in the beginning of the application pipeline.

The health check middleware should be placed in your `glance-api-paste.ini` in a section titled `[app:healthcheck]`. It should look like this:

    [app:healthcheck]
    paste.app_factory = oslo_middleware:Healthcheck.app_factory
    backends = disable_by_file
    disable_by_file_path = /etc/glance/healthcheck_disable

A ready-made composite including this application is defined e.g. in the `glance-api-paste.ini` file, looking like so:

    [composite:glance-api]
    paste.composite_factory = glance.api:root_app_factory
    /: apiv2app
    /healthcheck: healthcheck

For more information see oslo.middleware.

## Configuring supported disk formats

Each image in Glance has an associated disk format property. When creating an image the user specifies a disk format. They must select a format from the set that the Glance service supports. This supported set can be seen by querying the `/v2/schemas/images` resource. An operator can add or remove disk formats to the supported set. This is done by setting the `disk_formats` parameter which is found in the `[image_format]` section of `glance-api.conf`.

`disk_formats=<Comma separated list of disk formats>`

  Optional. Default: `ami,ari,aki,vhd,vhdx,vmdk,raw,qcow2,vdi,iso,ploop`

this page last updated: 2026-08-19 03:42:39

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug