Image API configuration

Image API configuration

The Image service has two APIs: the user-facing API, and the registry API, which is for internal requests that require access to the database.

Both of the APIs currently have two major versions: v1 (SUPPORTED) and v2 (CURRENT). You can run either or both versions by setting appropriate values of enable_v1_api, enable_v2_api, enable_v1_registry, and enable_v2_registry. If the v2 API is used, running glance-registry is optional, as v2 of glance-api can connect directly to the database.

To assist you in formulating your deployment strategy for the Image APIs, the Glance team has published a statement concerning the status and development plans of the APIs: Using public Image API.

Configuration options

Tables of all the options used to configure the APIs, including enabling SSL and modifying WSGI settings are found below.

Description of API configuration options
Configuration option = Default value Description
[DEFAULT]  
admin_role = admin

(String) Role used to identify an authenticated user as administrator.

Provide a string value representing a Keystone role to identify an administrative user. Users with this role will be granted administrative privileges. The default value for this option is ‘admin’.

Possible values:

  • A string value which is a valid Keystone role

Related options:

  • None
allow_anonymous_access = False

(Boolean) Allow limited access to unauthenticated users.

Assign a boolean to determine API access for unathenticated users. When set to False, the API cannot be accessed by unauthenticated users. When set to True, unauthenticated users can access the API with read-only privileges. This however only applies when using ContextMiddleware.

Possible values:

  • True
  • False

Related options:

  • None
available_plugins = (List) A list of artifacts that are allowed in the format name or name-version. Empty list means that any artifact can be loaded.
client_socket_timeout = 900

(Integer) Timeout for client connections’ socket operations.

Provide a valid integer value representing time in seconds to set the period of wait before an incoming connection can be closed. The default value is 900 seconds.

The value zero implies wait forever.

Possible values:

  • Zero
  • Positive integer

Related options:

  • None
enable_v1_api = True

(Boolean) Deploy the v1 OpenStack Images API.

When this option is set to True, Glance service will respond to requests on registered endpoints conforming to the v1 OpenStack Images API.

NOTES:

  • If this option is enabled, then enable_v1_registry must also be set to True to enable mandatory usage of Registry service with v1 API.
  • If this option is disabled, then the enable_v1_registry option, which is enabled by default, is also recommended to be disabled.
  • This option is separate from enable_v2_api, both v1 and v2 OpenStack Images API can be deployed independent of each other.
  • If deploying only the v2 Images API, this option, which is enabled by default, should be disabled.

Possible values:

  • True
  • False

Related options:

  • enable_v1_registry
  • enable_v2_api
enable_v1_registry = True

(Boolean) Deploy the v1 API Registry service.

When this option is set to True, the Registry service will be enabled in Glance for v1 API requests.

NOTES:

  • Use of Registry is mandatory in v1 API, so this option must be set to True if the enable_v1_api option is enabled.
  • If deploying only the v2 OpenStack Images API, this option, which is enabled by default, should be disabled.

Possible values:

  • True
  • False

Related options:

  • enable_v1_api
enable_v2_api = True

(Boolean) Deploy the v2 OpenStack Images API.

When this option is set to True, Glance service will respond to requests on registered endpoints conforming to the v2 OpenStack Images API.

NOTES:

  • If this option is disabled, then the enable_v2_registry option, which is enabled by default, is also recommended to be disabled.
  • This option is separate from enable_v1_api, both v1 and v2 OpenStack Images API can be deployed independent of each other.
  • If deploying only the v1 Images API, this option, which is enabled by default, should be disabled.

Possible values:

  • True
  • False

Related options:

  • enable_v2_registry
  • enable_v1_api
enable_v2_registry = True

(Boolean) Deploy the v2 API Registry service.

When this option is set to True, the Registry service will be enabled in Glance for v2 API requests.

NOTES:

  • Use of Registry is optional in v2 API, so this option must only be enabled if both enable_v2_api is set to True and the data_api option is set to glance.db.registry.api.
  • If deploying only the v1 OpenStack Images API, this option, which is enabled by default, should be disabled.

Possible values:

  • True
  • False

Related options:

  • enable_v2_api
  • data_api
http_keepalive = True

(Boolean) Set keep alive option for HTTP over TCP.

Provide a boolean value to determine sending of keep alive packets. If set to False, the server returns the header “Connection: close”. If set to True, the server returns a “Connection: Keep-Alive” in its responses. This enables retention of the same TCP connection for HTTP conversations instead of opening a new one with each new request.

This option must be set to False if the client socket connection needs to be closed explicitly after the response is received and read successfully by the client.

Possible values:

  • True
  • False

Related options:

  • None
image_size_cap = 1099511627776

(Integer) Maximum size of image a user can upload in bytes.

An image upload greater than the size mentioned here would result in an image creation failure. This configuration option defaults to 1099511627776 bytes (1 TiB).

NOTES:

  • This value should only be increased after careful consideration and must be set less than or equal to 8 EiB (9223372036854775808).
  • This value must be set with careful consideration of the backend storage capacity. Setting this to a very low value may result in a large number of image failures. And, setting this to a very large value may result in faster consumption of storage. Hence, this must be set according to the nature of images created and storage capacity available.

Possible values:

  • Any positive number less than or equal to 9223372036854775808
load_enabled = True (Boolean) When false, no artifacts can be loaded regardless of available_plugins. When true, artifacts can be loaded.
location_strategy = location_order

(String) Strategy to determine the preference order of image locations.

This configuration option indicates the strategy to determine the order in which an image’s locations must be accessed to serve the image’s data. Glance then retrieves the image data from the first responsive active location it finds in this list.

This option takes one of two possible values location_order and store_type. The default value is location_order, which suggests that image data be served by using locations in the order they are stored in Glance. The store_type value sets the image location preference based on the order in which the storage backends are listed as a comma separated list for the configuration option store_type_preference.

Possible values:

  • location_order
  • store_type

Related options:

  • store_type_preference
max_header_line = 16384

(Integer) Maximum line size of message headers.

Provide an integer value representing a length to limit the size of message headers. The default value is 16384.

NOTE: max_header_line may need to be increased when using large tokens (typically those generated by the Keystone v3 API with big service catalogs). However, it is to be kept in mind that larger values for max_header_line would flood the logs.

Setting max_header_line to 0 sets no limit for the line size of message headers.

Possible values:

  • 0
  • Positive integer

Related options:

  • None
max_request_id_length = 64

(Integer) Limit the request ID length.

Provide an integer value to limit the length of the request ID to the specified length. The default value is 64. Users can change this to any ineteger value between 0 and 16384 however keeping in mind that a larger value may flood the logs.

Possible values:

  • Integer value between 0 and 16384

Related options:

  • None
owner_is_tenant = True

(Boolean) Set the image owner to tenant or the authenticated user.

Assign a boolean value to determine the owner of an image. When set to True, the owner of the image is the tenant. When set to False, the owner of the image will be the authenticated user issuing the request. Setting it to False makes the image private to the associated user and sharing with other users within the same tenant (or “project”) requires explicit image sharing via image membership.

Possible values:

  • True
  • False

Related options:

  • None
public_endpoint = None

(String) Public url endpoint to use for Glance/Glare versions response.

This is the public url endpoint that will appear in the Glance/Glare “versions” response. If no value is specified, the endpoint that is displayed in the version’s response is that of the host running the API service. Change the endpoint to represent the proxy URL if the API service is running behind a proxy. If the service is running behind a load balancer, add the load balancer’s URL for this value.

Possible values:

  • None
  • Proxy URL
  • Load balancer URL

Related options:

  • None
secure_proxy_ssl_header = None (String) DEPRECATED: The HTTP header used to determine the scheme for the original request, even if it was removed by an SSL terminating proxy. Typical value is “HTTP_X_FORWARDED_PROTO”. Use the http_proxy_to_wsgi middleware instead.
send_identity_headers = False

(Boolean) Send headers received from identity when making requests to registry.

Typically, Glance registry can be deployed in multiple flavors, which may or may not include authentication. For example, trusted-auth is a flavor that does not require the registry service to authenticate the requests it receives. However, the registry service may still need a user context to be populated to serve the requests. This can be achieved by the caller (the Glance API usually) passing through the headers it received from authenticating with identity for the same request. The typical headers sent are X-User-Id, X-Tenant-Id, X-Roles, X-Identity-Status and X-Service-Catalog.

Provide a boolean value to determine whether to send the identity headers to provide tenant and user information along with the requests to registry service. By default, this option is set to False, which means that user and tenant information is not available readily. It must be obtained by authenticating. Hence, if this is set to False, flavor must be set to value that either includes authentication or authenticated user context.

Possible values:

  • True
  • False

Related options:

  • flavor
show_multiple_locations = False

(Boolean) DEPRECATED: Show all image locations when returning an image.

This configuration option indicates whether to show all the image locations when returning image details to the user. When multiple image locations exist for an image, the locations are ordered based on the location strategy indicated by the configuration opt location_strategy. The image locations are shown under the image property locations.

NOTES:

  • Revealing image locations can present a GRAVE SECURITY RISK as image locations can sometimes include credentials. Hence, this is set to False by default. Set this to True with EXTREME CAUTION and ONLY IF you know what you are doing!
  • If an operator wishes to avoid showing any image location(s) to the user, then both this option and show_image_direct_url MUST be set to False.

Possible values:

  • True
  • False

Related options:

  • show_image_direct_url
  • location_strategy This option will be removed in the Ocata release because the same functionality can be achieved with greater granularity by using policies. Please see the Newton release notes for more information.
tcp_keepidle = 600

(Integer) Set the wait time before a connection recheck.

Provide a positive integer value representing time in seconds which is set as the idle wait time before a TCP keep alive packet can be sent to the host. The default value is 600 seconds.

Setting tcp_keepidle helps verify at regular intervals that a connection is intact and prevents frequent TCP connection reestablishment.

Possible values:

  • Positive integer value representing time in seconds

Related options:

  • None
use_user_token = True (Boolean) DEPRECATED: Whether to pass through the user token when making requests to the registry. To prevent failures with token expiration during big files upload, it is recommended to set this parameter to False.If “use_user_token” is not in effect, then admin credentials can be specified. This option was considered harmful and has been deprecated in M release. It will be removed in O release. For more information read OSSN-0060. Related functionality with uploading big images has been implemented with Keystone trusts support.
[glance_store]  
default_store = file

(String) The default scheme to use for storing images.

Provide a string value representing the default scheme to use for storing images. If not set, Glance uses file as the default scheme to store images with the file store.

NOTE: The value given for this configuration option must be a valid scheme for a store registered with the stores configuration option.

Possible values:

  • file
  • filesystem
  • http
  • https
  • swift
  • swift+http
  • swift+https
  • swift+config
  • rbd
  • sheepdog
  • cinder
  • vsphere

Related Options:

  • stores
store_capabilities_update_min_interval = 0

(Integer) Minimum interval in seconds to execute updating dynamic storage capabilities based on current backend status.

Provide an integer value representing time in seconds to set the minimum interval before an update of dynamic storage capabilities for a storage backend can be attempted. Setting store_capabilities_update_min_interval does not mean updates occur periodically based on the set interval. Rather, the update is performed at the elapse of this interval set, if an operation of the store is triggered.

By default, this option is set to zero and is disabled. Provide an integer value greater than zero to enable this option.

NOTE: For more information on store capabilities and their updates, please visit: https://specs.openstack.org/openstack/glance-specs/specs/kilo/store-capabilities.html

For more information on setting up a particular store in your deplyment and help with the usage of this feature, please contact the storage driver maintainers listed here: http://docs.openstack.org/developer/glance_store/drivers/index.html

Possible values:

  • Zero
  • Positive integer

Related Options:

  • None
stores = file, http

(List) List of enabled Glance stores.

Register the storage backends to use for storing disk images as a comma separated list. The default stores enabled for storing disk images with Glance are file and http.

Possible values:

  • A comma separated list that could include:
  • file
  • http
  • swift
  • rbd
  • sheepdog
  • cinder
  • vmware

Related Options:

  • default_store
[oslo_middleware]  
enable_proxy_headers_parsing = False (Boolean) Whether the application is behind a proxy or not. This determines if the middleware should parse the headers or not.
max_request_body_size = 114688 (Integer) The maximum body size for each request, in bytes.
secure_proxy_ssl_header = X-Forwarded-Proto (String) DEPRECATED: The HTTP Header that will be used to determine what the original request protocol scheme was, even if it was hidden by a SSL termination proxy.
[paste_deploy]  
config_file = glance-api-paste.ini

(String) Name of the paste configuration file.

Provide a string value representing the name of the paste configuration file to use for configuring piplelines for server application deployments.

NOTES:

  • Provide the name or the path relative to the glance directory for the paste configuration file and not the absolute path.
  • The sample paste configuration file shipped with Glance need not be edited in most cases as it comes with ready-made pipelines for all common deployment flavors.

If no value is specified for this option, the paste.ini file with the prefix of the corresponding Glance service’s configuration file name will be searched for in the known configuration directories. (For example, if this option is missing from or has no value set in glance-api.conf, the service will look for a file named glance-api-paste.ini.) If the paste configuration file is not found, the service will not start.

Possible values:

  • A string value representing the name of the paste configuration file.

Related Options:

  • flavor
flavor = keystone

(String) Deployment flavor to use in the server application pipeline.

Provide a string value representing the appropriate deployment flavor used in the server application pipleline. This is typically the partial name of a pipeline in the paste configuration file with the service name removed.

For example, if your paste section name in the paste configuration file is [pipeline:glance-api-keystone], set flavor to keystone.

Possible values:

  • String value representing a partial pipeline name.

Related Options:

  • config_file
[store_type_location_strategy]  
store_type_preference =

(List) Preference order of storage backends.

Provide a comma separated list of store names in the order in which images should be retrieved from storage backends. These store names must be registered with the stores configuration option.

NOTE: The store_type_preference configuration option is applied only if store_type is chosen as a value for the location_strategy configuration option. An empty list will not change the location order.

Possible values:

  • Empty list
  • Comma separated list of registered store names. Legal values are:
  • file
  • http
  • rbd
  • swift
  • sheepdog
  • cinder
  • vmware

Related options:

  • location_strategy
  • stores
Description of CA and SSL configuration options
Configuration option = Default value Description
[DEFAULT]  
ca_file = /etc/ssl/cafile

(String) Absolute path to the CA file.

Provide a string value representing a valid absolute path to the Certificate Authority file to use for client authentication.

A CA file typically contains necessary trusted certificates to use for the client authentication. This is essential to ensure that a secure connection is established to the server via the internet.

Possible values:

  • Valid absolute path to the CA file

Related options:

  • None
cert_file = /etc/ssl/certs

(String) Absolute path to the certificate file.

Provide a string value representing a valid absolute path to the certificate file which is required to start the API service securely.

A certificate file typically is a public key container and includes the server’s public key, server name, server information and the signature which was a result of the verification process using the CA certificate. This is required for a secure connection establishment.

Possible values:

  • Valid absolute path to the certificate file

Related options:

  • None
key_file = /etc/ssl/key/key-file.pem

(String) Absolute path to a private key file.

Provide a string value representing a valid absolute path to a private key file which is required to establish the client-server connection.

Possible values:

  • Absolute path to the private key file

Related options:

  • None
Creative Commons Attribution 3.0 License

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