Chapter 4. Configuring the Image service image import method

The default settings for the Image service (glance) are determined by the Orchestration service (heat) templates that you use when you install Red Hat OpenStack Platform (RHOSP). The Orchestration service template for the Image service is deployment/glance/glance-api-container-puppet.yaml.

You can customize aspects of the Image service with a custom environment file, which is a special type of template you can use to customize your Orchestration service templates. For more information about Orchestration service templates and environment files, see Understanding heat templates in Installing and managing Red Hat OpenStack Platform with director.

As a cloud administrator, you can configure an image import workflow for cloud users to upload their own images to the Image service by using the web-download or glance-direct import methods. You can monitor uploaded images in a staging area before they go active in a storage back end, and you can configure the import workflow to run a set of plugins to make user images discoverable, for example, the image property injection plugin for metadata or the image conversion plugin for image formats.

The web-download image import method is enabled by default, but cloud administrators can configure the glance-direct method. For further information about the available import methods in Red Hat OpenStack Platform (RHOSP), see Image service image import methods.

4.1. Configuring the glance-direct image import method

When cloud administrators enable the glance-direct image import method, cloud users can upload local images to a shared staging area in the OpenStack Image service (glance), a temporary shared storage location common to all Image service API workers.

Procedure

  1. Log in to the undercloud host as the stack user.
  2. Source the stackrc undercloud credentials file:

    $ source ~/stackrc
  3. Create or open a YAML environment file to configure the import parameters:

    Example

    $ vi /home/stack/templates/<glance-import-settings>.yaml

    • Replace <glance-import-settings> with the name of your file.
  4. Configure the NFS back end that is required for shared staging:

    parameter_defaults:
      GlanceBackend: file
      GlanceNfsEnabled: true
      GlanceNfsShare: 192.168.122.1:/export/glance
  5. Add glance-direct to the GlanceEnabledImportMethods parameter to enable the glance-direct import method:

    parameter_defaults:
      [...]
      GlanceEnabledImportMethods: glance-direct,web-download
  6. Configure the NFS staging area that is required for the glance-direct import method:

    parameter_defaults:
      [...]
      GlanceStagingNfsShare: 192.168.122.1:/export/glance-staging

    The GlanceEnabledImportMethods parameter is necessary if you want to enable methods other than web-download. For more information about the GlanceBackend, GlanceNfsEnabled, and GlanceStagingNfsShare parameters, see Image Storage (glance) Parameters in Overcloud parameters.

  7. Add your <glance-import-settings>.yaml file to the stack with your other environment files and deploy the overcloud:

    (undercloud)$ openstack overcloud deploy --templates \
    -e [your environment files] \
    -e /home/stack/templates/<glance-import-settings>.yaml

4.2. Controlling image web-import sources

You can limit the sources of web-import image downloads by adding URI blocklists and allowlists to the optional glance-image-import.conf file.

You can allow or block image source URIs at three levels:

  • scheme (allowed_schemes, disallowed_schemes)
  • host (allowed_hosts, disallowed_hosts)
  • port (allowed_ports, disallowed_ports)

If you specify both allowlist and blocklist at any level, the allowlist is honored and the blocklist is ignored.

The Image service (glance) applies the following decision logic to validate image source URIs:

  1. The scheme is checked.

    1. Missing scheme: reject
    2. If there is an allowlist, and the scheme is not present in the allowlist: reject. Otherwise, skip C and continue on to 2.
    3. If there is a blocklist, and the scheme is present in the blocklist: reject.
  2. The host name is checked.

    1. Missing host name: reject
    2. If there is an allowlist, and the host name is not present in the allowlist: reject. Otherwise, skip C and continue on to 3.
    3. If there is a blocklist, and the host name is present in the blocklist: reject.
  3. If there is a port in the URI, the port is checked.

    1. If there is a allowlist, and the port is not present in the allowlist: reject. Otherwise, skip B and continue on to 4.
    2. If there is a blocklist, and the port is present in the blocklist: reject.
  4. The URI is accepted as valid.

If you allow a scheme, either by adding it to an allowlist or by not adding it to a blocklist, any URI that uses the default port for that scheme by not including a port in the URI is allowed. If it does include a port in the URI, the URI is validated according to the default decision logic.

4.2.1. Image import allowlist example

In this example, the default port for FTP is 21.

Because ftp is in the list for allowed_schemes, this URL to the image resource is allowed: ftp://example.org/some/resource.

However, because 21 is not in the list for allowed_ports, this URL to the same image resource is rejected: ftp://example.org:21/some/resource.

allowed_schemes = [http,https,ftp]
disallowed_schemes = []
allowed_hosts = []
disallowed_hosts = []
allowed_ports = [80,443]
disallowed_ports = []

4.2.2. Default image import blocklist and allowlist settings

The glance-image-import.conf file is an optional file that contains the following default options:

  • allowed_schemes - [http, https]
  • disallowed_schemes - empty list
  • allowed_hosts - empty list
  • disallowed_hosts - empty list
  • allowed_ports - [80, 443]
  • disallowed_ports - empty list

If you use the defaults, end users can access URIs by using only the http or https scheme. The only ports that users can specify are 80 and 443. Users do not have to specify a port, but if they do, it must be either 80 or 443.

You can find the glance-image-import.conf file in the etc/ subdirectory of the Image service source code tree. Ensure that you are looking in the correct branch for your release of Red Hat OpenStack Platform.

4.3. Injecting metadata on image import to control where instances launch

Cloud users can upload images to the Image service (glance) and use these images to launch instances. Cloud users must launch these images on a specific set of Compute nodes. You can control the assignment of an instance to a Compute node by using image metadata properties.

The image property injection plugin injects metadata properties to images during import. You can specify the properties by editing the [image_import_opts] and [inject_metadata_properties] sections of the glance-image-import.conf file. You can find the glance-image-import.conf file in the etc/ subdirectory of the Image service source code tree. Ensure that you are looking in the correct branch for your release of Red Hat OpenStack Platform (RHOSP).

To enable the image property injection plugin, add the following line to the [image_import_opts] section:

[image_import_opts]
image_import_plugins = [inject_image_metadata]

To limit the metadata injection to images provided by a certain set of users, set the ignore_user_roles parameter. For example, use the following configuration to inject one value for property1 and two values for property2 into images downloaded by any non-admin user.

[DEFAULT]
[image_conversion]
[image_import_opts]
image_import_plugins = [inject_image_metadata]
[import_filtering_opts]
[inject_metadata_properties]
ignore_user_roles = admin
inject = PROPERTY1:value,PROPERTY2:value;another value

The parameter ignore_user_roles is a comma-separated list of the Identity service (keystone) roles that the plugin ignores. This means that if the user that makes the image import call has any of these roles, the plugin does not inject any properties into the image.

The parameter inject is a comma-separated list of properties and values that are injected into the image record for the imported image. Each property and value must be quoted and separated by a colon (‘:’).