Instances and Images Guide

Red Hat OpenStack Platform 16.1

Managing Instances and Images

OpenStack Documentation Team

Abstract

This guide provides procedures for creating and managing images and instances, and procedures for configuring the Compute service for instance creation.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your input on our documentation. Tell us how we can make it better.

Using the Direct Documentation Feedback (DDF) function

Use the Add Feedback DDF function for direct comments on specific sentences, paragraphs, or code blocks.

  1. View the documentation in the Multi-page HTML format.
  2. Ensure that you see the Feedback button in the upper right corner of the document.
  3. Highlight the part of text that you want to comment on.
  4. Click Add Feedback.
  5. Complete the Add Feedback field with your comments.
  6. Optional: Add your email address so that the documentation team can contact you for clarification on your issue.
  7. Click Submit.

Chapter 1. Image service

Manage images and storage in Red Hat OpenStack Platform (RHOSP).

A virtual machine image is a file that contains a virtual disk with a bootable operating system installed. Virtual machine images are supported in different formats. The following formats are available in RHOSP:

  • RAW - Unstructured disk image format.
  • QCOW2 - Disk format supported by QEMU emulator. This format includes QCOW2v3 (sometimes referred to as QCOW3), which requires QEMU 1.1 or higher.
  • ISO - Sector-by-sector copy of the data on a disk, stored in a binary file.
  • AKI - Indicates an Amazon Kernel Image.
  • AMI - Indicates an Amazon Machine Image.
  • ARI - Indicates an Amazon RAMDisk Image.
  • VDI - Disk format supported by VirtualBox virtual machine monitor and the QEMU emulator.
  • VHD - Common disk format used by virtual machine monitors from VMware, VirtualBox, and others.
  • VMDK - Disk format supported by many common virtual machine monitors.
  • PLOOP - A disk format supported and used by Virtuozzo to run OS containers.
  • OVA - Indicates that what is stored in the Image service (glance) is an OVA tar archive file.
  • DOCKER - Indicates that what is stored in the Image service (glance) is a Docker tar archive of the container file system.

Although ISO is not normally considered a virtual machine image format, because ISOs contain bootable filesystems with an installed operating system, you use them in the same way as other virtual machine image files.

To download the official Red Hat Enterprise Linux cloud images, your account must have a valid Red Hat Enterprise Linux subscription:

If you are not logged in to the Customer Portal, a prompt opens where you must enter your Red Hat account credentials.

1.1. Understanding the Image service

Red Hat OpenStack Platform (RHOSP) Image service (glance) features.

1.1.1. Supported Image service (glance) back ends

The following Image service (glance) back end scenarios are supported:

  • RBD is the default back end when you use Ceph. For more information, see Configuring Ceph Storage in the Advanced Overcloud Customization guide.
  • RBD multi-store. For more information, see Deploying the central site in the Distributed compute node and storage deployment guide.
  • Object Storage (swift). For more information, see Using an External Object Storage Cluster in the Advanced Overcloud Customization guide.
  • Block Storage (cinder). For more information, see Configuring cinder back end for the Image service in the Advanced Overcloud Customization guide.

    The Image service uses the Block Storage type and back end as the default.

  • NFS. For more information, see Configuring NFS Storage in the Advanced Overcloud Customization guide.

    Important

    Although NFS is a supported Image service deployment option, more robust options are available.

    NFS is not native to the Image service. When you mount an NFS share on the Image service, the Image service does not manage the operation. The Image service writes data to the file system but is unaware that the back end is an NFS share.

    In this type of deployment, the Image service cannot retry a request if the share fails. This means that when a failure occurs on the back end, the store might enter read-only mode, or it might continue to write data to the local file system, in which case you risk data loss. To recover from this situation, you must ensure that the share is mounted and in sync, and then restart the Image service. For these reasons, Red Hat does not recommend NFS as an Image service back end.

    However, if you do choose to use NFS as an Image service back end, some of the following best practices can help to mitigate risks:

    • Use a reliable production-grade NFS back end.
    • Ensure that you have a strong and reliable connection between Controller nodes and the NFS back end, L2 is recommended.
    • Include monitoring and alerts for the mounted share.
    • Set underlying FS permissions.

      • Ensure that the user and the group that the glance-api process runs on do not have write permissions on the mount point at the local file system. This means that the process can detect possible mount failure and put the store into read-only mode during a write attempt.
      • The write permissions must be present in the shared file system that you use as a store.

1.1.2. Image signing and verification

Image signing and verification protects image integrity and authenticity by enabling deployers to sign images and save the signatures and public key certificates as image properties.

By taking advantage of this feature, you can:

  • Sign an image using your private key and upload the image, the signature, and a reference to your public key certificate (the verification metadata). The Image service then verifies that the signature is valid.
  • Create an image in the Compute service, have the Compute service sign the image, and upload the image and its verification metadata. The Image service again verifies that the signature is valid.
  • Request a signed image in the Compute service. The Image service provides the image and its verification metadata, allowing the Compute service to validate the image before booting it.

For information on image signing and verification, refer to the Validate Glance Images chapter of the Manage Secrets with OpenStack Key Manager Guide.

1.1.3. Image conversion

Image conversion converts images by calling the task API while importing an image.

As part of the import workflow, a plugin provides the image conversion. This plugin can be activated or deactivated based on the deployer configuration. Therefore, the deployer needs to specify the preferred format of images for the deployment.

Internally, the Image service receives the bits of the image in a particular format. These bits are stored in a temporary location. The plugin is then triggered to convert the image to the target format and moved to a final destination. When the task is finished, the temporary location is deleted. As a result, the format uploaded initially is not retained by the Image service.

For more information about image conversion, see Enabling image conversion.

Note

The conversion can be triggered only when importing an image. It does not run when uploading an image. For example:

$ glance image-create-via-import \
    --disk-format qcow2 \
    --container-format bare \
    --name NAME \
    --visibility public \
    --import-method web-download \
    --uri http://server/image.qcow2

1.1.4. Image introspection

Every image format comes with a set of metadata embedded inside the image itself. For example, a stream optimized vmdk would contain the following parameters:

$ head -20 so-disk.vmdk

# Disk DescriptorFile
version=1
CID=d5a0bce5
parentCID=ffffffff
createType="streamOptimized"

# Extent description
RDONLY 209714 SPARSE "generated-stream.vmdk"

# The Disk Data Base
#DDB

ddb.adapterType = "buslogic"
ddb.geometry.cylinders = "102"
ddb.geometry.heads = "64"
ddb.geometry.sectors = "32"
ddb.virtualHWVersion = "4"

By introspecting this vmdk, you can easily know that the disk_type is streamOptimized, and the adapter_type is buslogic. These metadata parameters are useful for the consumer of the image. In Compute, the workflow to instantiate a streamOptimized disk is different from the one to instantiate a flat disk. This new feature allows metadata extraction. You can achieve image introspection by calling the task API while importing the image. An administrator can override metadata settings.

1.1.5. Interoperable image import

The interoperable image import workflow enables you to import images in two ways:

  • Use the web-download (default) method to import images from a URI.
  • Use the glance-direct method to import images from a local file system.

1.1.6. Improving scalability with Image service caching

Use the glance-api caching mechanism to store copies of images on Image service (glance) API servers and retrieve them automatically to improve scalability. With Image service caching, glance-api can run on multiple hosts. This means that it does not need to retrieve the same image from back end storage multiple times. Image service caching does not affect any Image service operations.

Configure Image service caching with the Red Hat OpenStack Platform director (tripleo) heat templates:

Procedure

  1. In an environment file, set the value of the GlanceCacheEnabled parameter to true, which automatically sets the flavor value to keystone+cachemanagement in the glance-api.conf heat template:

    parameter_defaults:
        GlanceCacheEnabled: true
  2. Include the environment file in the openstack overcloud deploy command when you redeploy the overcloud.
  3. Optional: Tune the glance_cache_pruner to an alternative frequency when you redeploy the overcloud. The following example shows a frequency of 5 minutes:

    parameter_defaults:
      ControllerExtraConfig:
        glance::cache::pruner::minute: '*/5'

    Adjust the frequency according to your needs to avoid file system full scenarios. Include the following elements when you choose an alternative frequency:

    • The size of the files that you want to cache in your environment.
    • The amount of available file system space.
    • The frequency at which the environment caches images.

1.1.7. Image pre-caching

This feature is available in this release as a Technology Preview, and therefore is not fully supported by Red Hat. It should only be used for testing, and should not be deployed in a production environment. For more information about Technology Preview features, see Scope of Coverage Details.

1.1.7.1. Configuring the default interval for periodic image pre-caching

Red Hat OpenStack Platform (RHOSP) director can pre-cache images as part of the glance-api service. The default periodic interval is 300 seconds. You can increase or decrease the default interval based on your requirements.

Procedure

  1. Add a new interval with the ExtraConfig parameter in an environment file on the undercloud according to your requirements:

    parameter_defaults:
      ControllerExtraConfig:
        glance::config::glance_api_config:
          DEFAULT/cache_prefetcher_interval:
            value: '<300>'

    Replace <300> with the number of seconds that you want as an interval to pre-cache images.

  2. After you adjust the interval in the environment file in /home/stack/templates/, log in as the stack user and deploy the configuration:

    $ openstack overcloud deploy --templates \
    -e /home/stack/templates/<ENV_FILE>.yaml

    Replace <ENV_FILE> with the name of the environment file that contains the ExtraConfig settings that you added.

Important

If you passed any extra environment files when you created the overcloud, pass them again here by using the -e option to avoid making undesired changes to the overcloud.

For more information about the openstack overcloud deploy command, see Deployment command in the Director Installation and Usage guide.

1.1.7.2. Using a periodic job to pre-cache an image

Prerequisites

To use a periodic job to pre-cache an image, you must use the glance-cache-manage command connected directly to the node where the glance_api service is running. Do not use a proxy, which hides the node that answers a service request. Because the undercloud might not have access to the network where the glance_api service is running, run commands on the first overcloud node, which is called controller-0 by default.

Complete the following prerequisite procedure to ensure that you run commands from the correct host, have the necessary credentials, and are also running the glance-cache-manage commands from inside the glance-api container.

Procedure

  1. Log in to the undercloud as the stack user and identify the provisioning IP address of controller-0:

    (undercloud) [stack@site-undercloud-0 ~]$ openstack server list -f value -c Name -c Networks | grep controller
    overcloud-controller-1 ctlplane=192.168.24.40
    overcloud-controller-2 ctlplane=192.168.24.13
    overcloud-controller-0 ctlplane=192.168.24.71
    (undercloud) [stack@site-undercloud-0 ~]$
  2. To authenticate to the overcloud, copy the credentials that are stored in /home/stack/overcloudrc, by default, to controller-0:

    $ scp ~/overcloudrc heat-admin@192.168.24.71:/home/heat-admin/
  3. Connect to controller-0:

    $ ssh heat-admin@192.168.24.71
  4. On controller-0 as the heat-admin user, identify the IP address of the glance_api service. In the following example, the IP address is 172.25.1.105:

    (overcloud) [root@controller-0 ~]# grep -A 10 '^listen glance_api' /var/lib/config-data/puppet-generated/haproxy/etc/haproxy/haproxy.cfg
    listen glance_api
     server central-controller0-0.internalapi.redhat.local 172.25.1.105:9292 check fall 5 inter 2000 rise 2
  5. Because the glance-cache-manage command is only available in the glance_api container, create a script to exec into that container where the environment variables to authenticate to the overcloud are already set. Create a script called glance_pod.sh in /home/heat-admin on controller-0 with the following contents:

    sudo podman exec -ti \
     -e NOVA_VERSION=$NOVA_VERSION \
     -e COMPUTE_API_VERSION=$COMPUTE_API_VERSION \
     -e OS_USERNAME=$OS_USERNAME \
     -e OS_PROJECT_NAME=$OS_PROJECT_NAME \
     -e OS_USER_DOMAIN_NAME=$OS_USER_DOMAIN_NAME \
     -e OS_PROJECT_DOMAIN_NAME=$OS_PROJECT_DOMAIN_NAME \
     -e OS_NO_CACHE=$OS_NO_CACHE \
     -e OS_CLOUDNAME=$OS_CLOUDNAME \
     -e no_proxy=$no_proxy \
     -e OS_AUTH_TYPE=$OS_AUTH_TYPE \
     -e OS_PASSWORD=$OS_PASSWORD \
     -e OS_AUTH_URL=$OS_AUTH_URL \
     -e OS_IDENTITY_API_VERSION=$OS_IDENTITY_API_VERSION \
     -e OS_COMPUTE_API_VERSION=$OS_COMPUTE_API_VERSION \
     -e OS_IMAGE_API_VERSION=$OS_IMAGE_API_VERSION \
     -e OS_VOLUME_API_VERSION=$OS_VOLUME_API_VERSION \
     -e OS_REGION_NAME=$OS_REGION_NAME \
    glance_api /bin/bash
  6. Source the overcloudrc file and run the glance_pod.sh script to exec into the glance_api container with the necessary environment variables to authenticate to the overcloud Controller node.

    [heat-admin@controller-0 ~]$ source overcloudrc
    (overcloudrc) [heat-admin@central-controller-0 ~]$ bash glance_pod.sh
    ()[glance@controller-0 /]$
  7. Use a command such as glance image-list to verify that the container can run authenticated commands against the overcloud.

    ()[glance@controller-0 /]$ glance image-list
    +--------------------------------------+----------------------------------+
    | ID                                   | Name                             |
    +--------------------------------------+----------------------------------+
    | ad2f8daf-56f3-4e10-b5dc-d28d3a81f659 | cirros-0.4.0-x86_64-disk.img       |
    +--------------------------------------+----------------------------------+
    ()[glance@controller-0 /]$

Procedure

  1. As the admin user, queue an image to cache:

    $ glance-cache-manage --host=<host_ip> queue-image <image_id>
    • Replace <host_ip> with the IP address of the Controller node where the glance-api container is running.
    • Replace <image_id> with the ID of the image that you want to queue.

      When you have queued the images that you want to pre-cache, the cache_images periodic job prefetches all queued images concurrently.

      Note

      Because the image cache is local to each node, if your Red Hat OpenStack Platform is deployed with HA (with 3, 5, or 7 Controllers) then you must specify the host address with the --host option when you run the glance-cache-manage command.

  2. Run the following command to view the images in the image cache:

    $ glance-cache-manage --host=<host_ip> list-cached

    Replace <host_ip> with the IP address of the host in your environment.

Related information

You can use additional glance-cache-manage commands for the following purposes:

  • list-cached to list all images that are currently cached.
  • list-queued to list all images that are currently queued for caching.
  • queue-image to queue an image for caching.
  • delete-cached-image to purge an image from the cache.
  • delete-all-cached-images to remove all images from the cache.
  • delete-queued-image to delete an image from the cache queue.
  • delete-all-queued-images to delete all images from the cache queue.

1.1.8. Secure metadef APIs

In Red Hat OpenStack Platform (RHOSP), users can define key value pairs and tag metadata with metadata definition (metadef) APIs. Currently, there is no limit on the number of metadef namespaces, objects, properties, resources, or tags that users can create.

Metadef APIs can leak information to unauthorized users. A malicious user can exploit the lack of restrictions and fill the Image service (glance) database with unlimited resources, which can create a Denial of Service (DoS) style attack.

Image service policies control metadef APIs. However, the default policy setting for metadef APIs allows all users to create or read the metadef information. Because metadef resources are not isolated to the owner, metadef resources with potentially sensitive names, such as internal infrastructure details or customer names, can expose that information to malicious users.

1.1.8.1. Configuring a policy to restrict metadef APIs

To make the Image service (glance) more secure, restrict metadef modification APIs to admin-only access by default in your Red Hat OpenStack Platform (RHOSP) deployments.

Procedure

  1. As a cloud administrator, create a separate heat template environment file, such as lock-down-glance-metadef-api.yaml, to contain policy overrides for the Image service metadef API:

    ...
    parameter_defaults:
      GlanceApiPolicies: {
    	glance-metadef_default: { key: 'metadef_default', value: '' },
    	glance-metadef_admin: { key: 'metadef_admin', value: 'role:admin' },
    	glance-get_metadef_namespace: { key: 'get_metadef_namespace', value: 'rule:metadef_default' },
    	glance-get_metadef_namespaces: { key: 'get_metadef_namespaces', value: 'rule:metadef_default' },
    	glance-modify_metadef_namespace: { key: 'modify_metadef_namespace', value: 'rule:metadef_admin' },
    	glance-add_metadef_namespace: { key: 'add_metadef_namespace', value: 'rule:metadef_admin' },
    	glance-delete_metadef_namespace: { key: 'delete_metadef_namespace', value: 'rule:metadef_admin' },
    	glance-get_metadef_object: { key: 'get_metadef_object', value: 'rule:metadef_default' },
    	glance-get_metadef_objects: { key: 'get_metadef_objects', value: 'rule:metadef_default' },
    	glance-modify_metadef_object: { key: 'modify_metadef_object', value: 'rule:metadef_admin' },
    	glance-add_metadef_object: { key: 'add_metadef_object', value: 'rule:metadef_admin' },
    	glance-delete_metadef_object: { key: 'delete_metadef_object', value: 'rule:metadef_admin' },
    	glance-list_metadef_resource_types: { key: 'list_metadef_resource_types', value: 'rule:metadef_default' },
    	glance-get_metadef_resource_type: { key: 'get_metadef_resource_type', value: 'rule:metadef_default' },
    	glance-add_metadef_resource_type_association: { key: 'add_metadef_resource_type_association', value: 'rule:metadef_admin' },
    	glance-remove_metadef_resource_type_association: { key: 'remove_metadef_resource_type_association', value: 'rule:metadef_admin' },
    	glance-get_metadef_property: { key: 'get_metadef_property', value: 'rule:metadef_default' },
    	glance-get_metadef_properties: { key: 'get_metadef_properties', value: 'rule:metadef_default' },
    	glance-modify_metadef_property: { key: 'modify_metadef_property', value: 'rule:metadef_admin' },
    	glance-add_metadef_property: { key: 'add_metadef_property', value: 'rule:metadef_admin' },
    	glance-remove_metadef_property: { key: 'remove_metadef_property', value: 'rule:metadef_admin' },
    	glance-get_metadef_tag: { key: 'get_metadef_tag', value: 'rule:metadef_default' },
    	glance-get_metadef_tags: { key: 'get_metadef_tags', value: 'rule:metadef_default' },
    	glance-modify_metadef_tag: { key: 'modify_metadef_tag', value: 'rule:metadef_admin' },
    	glance-add_metadef_tag: { key: 'add_metadef_tag', value: 'rule:metadef_admin' },
    	glance-add_metadef_tags: { key: 'add_metadef_tags', value: 'rule:metadef_admin' },
    	glance-delete_metadef_tag: { key: 'delete_metadef_tag', value: 'rule:metadef_admin' },
    	glance-delete_metadef_tags: { key: 'delete_metadef_tags', value: 'rule:metadef_admin' }
      }
    
    …
  2. Include the environment file that contains the policy overrides in the deployment command with the -e option when you deploy the overcloud:

    $ openstack overcloud deploy -e lock-down-glance-metadef-api.yaml

1.1.8.2. Enabling metadef APIs

If you previously restricted metadata definition (metadef) APIs or want to relax the new defaults, you can override metadef modification policies to allow users to update their respective resources.

Important

Cloud administrators with users who depend on write access to the metadef APIs can make those APIs accessible to all users. In this type of configuration, however, there is the potential to unintentionally leak sensitive resource names, such as customer names and internal projects. Administrators must audit their systems to identify previously created resources that might be vulnerable even if only read access is enabled for all users.

Procedure

  1. As a cloud administrator, log in to the undercloud and create a file for policy overrides. For example:

    $ cat open-up-glance-api-metadef.yaml
  2. Configure the policy override file to allow metadef API read-write access to all users:

    GlanceApiPolicies: {
        glance-metadef_default: { key: 'metadef_default', value: '' },
        glance-get_metadef_namespace: { key: 'get_metadef_namespace', value: 'rule:metadef_default' },
        glance-get_metadef_namespaces: { key: 'get_metadef_namespaces', value: 'rule:metadef_default' },
        glance-modify_metadef_namespace: { key: 'modify_metadef_namespace', value: 'rule:metadef_default' },
        glance-add_metadef_namespace: { key: 'add_metadef_namespace', value: 'rule:metadef_default' },
        glance-delete_metadef_namespace: { key: 'delete_metadef_namespace', value: 'rule:metadef_default' },
        glance-get_metadef_object: { key: 'get_metadef_object', value: 'rule:metadef_default' },
        glance-get_metadef_objects: { key: 'get_metadef_objects', value: 'rule:metadef_default' },
        glance-modify_metadef_object: { key: 'modify_metadef_object', value: 'rule:metadef_default' },
        glance-add_metadef_object: { key: 'add_metadef_object', value: 'rule:metadef_default' },
        glance-delete_metadef_object: { key: 'delete_metadef_object', value: 'rule:metadef_default' },
        glance-list_metadef_resource_types: { key: 'list_metadef_resource_types', value: 'rule:metadef_default' },
        glance-get_metadef_resource_type: { key: 'get_metadef_resource_type', value: 'rule:metadef_default' },
        glance-add_metadef_resource_type_association: { key: 'add_metadef_resource_type_association', value: 'rule:metadef_default' },
        glance-remove_metadef_resource_type_association: { key: 'remove_metadef_resource_type_association', value: 'rule:metadef_default' },
        glance-get_metadef_property: { key: 'get_metadef_property', value: 'rule:metadef_default' },
        glance-get_metadef_properties: { key: 'get_metadef_properties', value: 'rule:metadef_default' },
        glance-modify_metadef_property: { key: 'modify_metadef_property', value: 'rule:metadef_default' },
        glance-add_metadef_property: { key: 'add_metadef_property', value: 'rule:metadef_default' },
        glance-remove_metadef_property: { key: 'remove_metadef_property', value: 'rule:metadef_default' },
        glance-get_metadef_tag: { key: 'get_metadef_tag', value: 'rule:metadef_default' },
        glance-get_metadef_tags: { key: 'get_metadef_tags', value: 'rule:metadef_default' },
        glance-modify_metadef_tag: { key: 'modify_metadef_tag', value: 'rule:metadef_default' },
        glance-add_metadef_tag: { key: 'add_metadef_tag', value: 'rule:metadef_default' },
        glance-add_metadef_tags: { key: 'add_metadef_tags', value: 'rule:metadef_default' },
        glance-delete_metadef_tag: { key: 'delete_metadef_tag', value: 'rule:metadef_default' },
        glance-delete_metadef_tags: { key: 'delete_metadef_tags', value: 'rule:metadef_default' }
      }
    Note

    You must configure all metadef policies to use rule:metadeta_default.

  3. Include the new policy file in the deployment command with the -e option when you deploy the overcloud:

    $ openstack overcloud deploy -e open-up-glance-api-metadef.yaml

1.2. Manage images

The Image service (glance) provides discovery, registration, and delivery services for disk and server images. It provides the ability to copy or snapshot a server image, and immediately store it. You can use stored images as a template to commission new servers quickly and more consistently than installing a server operating system and individually configuring services.

1.2.1. Creating an image

Manually create Red Hat OpenStack Platform (RHOSP) compatible images in the QCOW2 format by using Red Hat Enterprise Linux 7 ISO files, Red Hat Enterprise Linux 6 ISO files, or Windows ISO files.

1.2.1.1. Use a KVM guest image with Red Hat OpenStack Platform

You can use a ready RHEL KVM guest QCOW2 image:

These images are configured with cloud-init and must take advantage of ec2-compatible metadata services for provisioning SSH keys to function correctly.

Ready Windows KVM guest QCOW2 images are not available.

Note

For the KVM guest images:

  • The root account in the image is disabled, but sudo access is granted to a special user named cloud-user.
  • There is no root password set for this image.

The root password is locked in /etc/shadow by placing !! in the second field.

For a RHOSP instance, generate an ssh keypair from the RHOSP dashboard or command line and use that key combination to perform an SSH public authentication to the instance as root.

When the instance is launched, this public key is injected to it. You can then authenticate by using the private key that you download when you create the keypair.

If you do not want to use keypairs, you can use the admin password that has been set using the Inject an admin Password Into an Instance procedure.

If you want to create custom Red Hat Enterprise Linux or Windows images, see Create a Red Hat Enterprise Linux 7 Image, Create a Red Hat Enterprise Linux 6 Image, or Create a Windows Image.

1.2.1.2. Create custom Red Hat Enterprise Linux or Windows images

Prerequisites

  • Linux host machine to create an image. This can be any machine on which you can install and run the Linux packages.
  • libvirt, virt-manager to install all packages necessary to create a guest operating system:

    $ sudo dnf groupinstall -y @virtualization
  • Libguestfs tools to install a set of tools to access and modify virtual machine images:

    $ sudo dnf install -y libguestfs-tools-c
  • A Red Hat Enterprise Linux 7 or 6 ISO file. For more information, see RHEL 7.2 Binary DVD or RHEL 6.8 Binary DVD or a Windows ISO file. If you do not have a Windows ISO file, see Microsoft TechNet Evaluation Center to download an evaluation image.
  • Text editor, if you want to change the kickstart files (RHEL only).
Important

If you install the libguestfs-tools package on the undercloud, disable iscsid.socket to avoid port conflicts with the tripleo_iscsid service on the undercloud:

$ sudo systemctl disable --now iscsid.socket
1.2.1.2.1. Create a Red Hat Enterprise Linux 7 Image

Manually create a Red Hat OpenStack Platform (RHOSP) compatible image in the QCOW2 format by using a Red Hat Enterprise Linux 7 ISO file.

Note

You must run all commands with the [root@host]# on your host machine.

  1. Start the installation by using virt-install:

    [root@host]# qemu-img create -f qcow2 rhel7.qcow2 8G
    [root@host]# virt-install --virt-type kvm --name rhel7 --ram 2048 \
    --cdrom /tmp/rhel-server-7.2-x86_64-dvd.iso \
    --disk rhel7.qcow2,format=qcow2 \
    --network=bridge:virbr0 --graphics vnc,listen=0.0.0.0 \
    --noautoconsole --os-type=linux --os-variant=rhel7

    This launches an instance and starts the installation process.

    Note

    If the instance does not launch automatically, run the virt-viewer command to view the console:

    [root@host]# virt-viewer rhel7
  2. Configure the instance:

    1. At the initial Installer boot menu, select Install Red Hat Enterprise Linux 7.
    2. Choose the appropriate Language and Keyboard options.
    3. When prompted about which type of devices your installation uses, select Auto-detected installation media.
    4. When prompted about which type of installation destination, select Local Standard Disks. For other storage options, select Automatically configure partitioning.
    5. For software selection, select Minimal Install.
    6. For network and host name, select eth0 for network and choose a host name for your device. The default host name is localhost.localdomain.
    7. Enter a password in the Root Password field and enter the same password again in the Confirm field.

      Result
      The installation process completes and the Complete! screen is displayed.
  3. After the installation is complete, reboot the instance and log in as the root user.
  4. Update the /etc/sysconfig/network-scripts/ifcfg-eth0 file so that it contains only the following values:

    TYPE=Ethernet
    DEVICE=eth0
    ONBOOT=yes
    BOOTPROTO=dhcp
    NM_CONTROLLED=no
  5. Reboot the machine.
  6. Register the machine with the Content Delivery Network.

    # sudo subscription-manager register
    # sudo subscription-manager attach --pool=Valid-Pool-Number-123456
    # sudo subscription-manager repos --enable=rhel-7-server-rpms
  7. Update the system:

    # dnf -y update
  8. Install the cloud-init packages:

    # dnf install -y cloud-utils-growpart cloud-init
  9. Edit the /etc/cloud/cloud.cfg configuration file and under cloud_init_modules add:

    - resolv-conf

    The resolv-conf option automatically configures the resolv.conf when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain and other options.

  10. Add the following line to /etc/sysconfig/network to avoid problems accessing the EC2 metadata service:

    NOZEROCONF=yes
  11. To ensure that the console messages appear in the Log tab on the dashboard and the nova console-log output, add the following boot option to the /etc/default/grub file:

    GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8"
  12. Run the grub2-mkconfig command:

    # grub2-mkconfig -o /boot/grub2/grub.cfg

    The output is as follows:

    Generating grub configuration file ...
    Found linux image: /boot/vmlinuz-3.10.0-229.7.2.el7.x86_64
    Found initrd image: /boot/initramfs-3.10.0-229.7.2.el7.x86_64.img
    Found linux image: /boot/vmlinuz-3.10.0-121.el7.x86_64
    Found initrd image: /boot/initramfs-3.10.0-121.el7.x86_64.img
    Found linux image: /boot/vmlinuz-0-rescue-b82a3044fb384a3f9aeacf883474428b
    Found initrd image: /boot/initramfs-0-rescue-b82a3044fb384a3f9aeacf883474428b.img
    done
  13. Deregister the instance so that the resulting image does not contain the subscription details for this instance:

    # subscription-manager repos --disable=*
    # subscription-manager unregister
    # dnf clean all
  14. Power off the instance:

    # poweroff
  15. Reset and clean the image by using the virt-sysprep command so that it can be used to create instances without issues:

    [root@host]# virt-sysprep -d rhel7
  16. Reduce the image size by converting any free space within the disk image back to free space within the host:

    [root@host]# virt-sparsify --compress /tmp/rhel7.qcow2 rhel7-cloud.qcow2

    This creates a new rhel7-cloud.qcow2 file in the location from where the command is run.

The rhel7-cloud.qcow2 image file is ready to be uploaded to the Image service. For more information about uploading this image to your RHOSP deployment by using the dashboard, see Upload an Image.

1.2.1.2.2. Create a Red Hat Enterprise Linux 6 Image

Manually create a Red Hat OpenStack Platform (RHOSP) compatible image in the QCOW2 format by using a Red Hat Enterprise Linux 6 ISO file.

Note

You must run all commands with the [root@host]# on your host machine.

  1. Start the installation by using virt-install:

    [root@host]# qemu-img create -f qcow2 rhel6.qcow2 4G
    [root@host]# virt-install --connect=qemu:///system --network=bridge:virbr0 \
    --name=rhel6 --os-type linux --os-variant rhel6 \
    --disk path=rhel6.qcow2,format=qcow2,size=10,cache=none \
    --ram 4096 --vcpus=2 --check-cpu --accelerate \
    --hvm --cdrom=rhel-server-6.8-x86_64-dvd.iso

    This launches an instance and starts the installation process.

    Note

    If the instance does not launch automatically, run the virt-viewer command to view the console:

    [root@host]# virt-viewer rhel6
  2. Configure the instances:

    1. At the initial Installer boot menu, select Install or upgrade an existing system and follow the installation prompts. Accept the defaults.

      The disk installer provides an option to test your installation media before installation. Select OK to run the test or Skip to proceed without testing.

    2. Choose the appropriate Language and Keyboard options.
    3. When prompted about which type of devices your installation uses, select Basic Storage Devices.
    4. Choose a host name for your device. The default host name is localhost.localdomain.
    5. Set the timezone and root password.
    6. Based on the space on the disk, choose the type of installation you want from the options in the Which type of installation would you like? window.
    7. Choose the Basic Server install, which installs an SSH server.
    8. The installation process completes and the Congratulations, your Red Hat Enterprise Linux installation is complete screen is displayed.
  3. Reboot the instance and log in as the root user.
  4. Update the /etc/sysconfig/network-scripts/ifcfg-eth0 file so that it contains only the following values:

    TYPE=Ethernet
    DEVICE=eth0
    ONBOOT=yes
    BOOTPROTO=dhcp
    NM_CONTROLLED=no
  5. Reboot the machine.
  6. Register the machine with the Content Delivery Network:

    # sudo subscription-manager register
    # sudo subscription-manager attach --pool=Valid-Pool-Number-123456
    # sudo subscription-manager repos --enable=rhel-6-server-rpms
  7. Update the system:

    # dnf -y update
  8. Install the cloud-init packages:

    # dnf install -y cloud-utils-growpart cloud-init
  9. Edit the /etc/cloud/cloud.cfg configuration file and add the following content under cloud_init_modules.

    - resolv-conf

    The resolv-conf option automatically configures the resolv.conf configuration file when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain, and other options.

  10. To prevent network issues, create /etc/udev/rules.d/75-persistent-net-generator.rules:

    # echo "#" > /etc/udev/rules.d/75-persistent-net-generator.rules

    This prevents /etc/udev/rules.d/70-persistent-net.rules file from being created. If /etc/udev/rules.d/70-persistent-net.rules is created, networking might not function correctly when you boot from snapshots, the network interface is created as eth1 rather than eth0 and the IP address is not assigned.

  11. Add the following line to /etc/sysconfig/network to avoid problems accessing the EC2 metadata service:

    NOZEROCONF=yes
  12. To ensure that the console messages appear in the Log tab on the dashboard and the nova console-log output, add the following boot option to the /etc/grub.conf file:

    console=tty0 console=ttyS0,115200n8
  13. Deregister the virtual machine so that the resulting image does not contain the same subscription details for this instance:

    # subscription-manager repos --disable=*
    # subscription-manager unregister
    # dnf clean all
  14. Power off the instance:

    # poweroff
  15. Reset and clean the image by using the virt-sysprep command so that it can be used to create instances without issues:

    [root@host]# virt-sysprep -d rhel6
  16. Reduce image size by using the virt-sparsify command. This command converts any free space within the disk image back to free space within the host:

    [root@host]# virt-sparsify --compress rhel6.qcow2 rhel6-cloud.qcow2

    This creates a new rhel6-cloud.qcow2 file in the location from where the command is run.

    Note

    You must manually resize the partitions of instances based on the image in accordance with the disk space in the flavor that is applied to the instance.

The rhel6-cloud.qcow2 image file is ready to be uploaded to the Image service. For more information about uploading this image to your RHOSP deployment by using the dashboard, see Upload an Image

1.2.1.2.3. Create a Windows image

Manually create a Red Hat OpenStack Platform (RHOSP) compatible image in the QCOW2 format by using a Windows ISO file.

Note

You must run all commands with the [root@host]# on your host machine.

  1. Start the installation by using virt-install:

    [root@host]# virt-install --name=<name> \
    --disk size=<size> \
    --cdrom=<path> \
    --os-type=windows \
    --network=bridge:virbr0 \
    --graphics spice \
    --ram=<ram>

    Replace the following values of the virt-install parameters:

    • <name> — the name that the Windows instance has.
    • <size> — disk size in GB.
    • <path> — the path to the Windows installation ISO file.
    • <RAM> — the requested amount of RAM in MB.

      Note

      The --os-type=windows parameter ensures that the clock is configured correctly for the Windows guest, and enables its Hyper-V enlightenment features.

  2. virt-install saves the guest image as /var/lib/libvirt/images/<name>.qcow2 by default. If you want to keep the guest image elsewhere, change the parameter of the --disk option:

    --disk path=<filename>,size=<size>

    Replace <filename> with the name of the file that stores the instance image, and optionally its path. For example, path=win8.qcow2,size=8 creates an 8 GB file named win8.qcow2 in the current working directory.

    Tip

    If the guest does not launch automatically, run the virt-viewer command to view the console:

    [root@host]# virt-viewer <name>

    For more information about how to install Windows, see the relevant Microsoft documentation.

  3. To allow the newly installed Windows system to use the virtualized hardware, you might need to install virtio drivers. To so do, first install the image, which you must attach as a CD-ROM drive to the Windows instance. To install the virtio-win package you must add the virtio ISO image to the instance, and install the virtio drivers. For more information, see Installing KVM paravirtualized drivers for Windows virtual machines in the Configuring and managing virtualization guide.
  4. To complete the configuration, download and execute Cloudbase-Init on the Windows system. At the end of the installation of Cloudbase-Init, select the Run Sysprep and Shutdown checkboxes. The Sysprep tool makes the guest unique by generating an OS ID, which is used by certain Microsoft services.

    Important

    Red Hat does not provide technical support for Cloudbase-Init. If you encounter an issue, see contact Cloudbase Solutions.

When the Windows system shuts down, the <name>.qcow2 image file is ready to be uploaded to the Image service. For more information about uploading this image to your RHOSP deployment by using the dashboard or the command line, see Upload an Image.

Note

libosinfo data

The Compute Service has deprecated support for using libosinfo data to set default device models. Instead, use the following image metadata properties to configure the optimal virtual hardware for an instance:

  • os_distro
  • os_version
  • hw_cdrom_bus
  • hw_disk_bus
  • hw_scsi_model
  • hw_vif_model
  • hw_video_model
  • hypervisor_type

For more information about these metadata properties, see Appendix A, Image Configuration Parameters.

1.2.2. Upload an image

  1. In the dashboard, select Project > Compute > Images.
  2. Click Create Image.
  3. Fill out the values, and click Create Image.

Table 1.1. Image options

FieldNotes

Name

Name for the image. The name must be unique within the project.

Description

Brief description to identify the image.

Image Source

Image source: Image Location or Image File. Based on your selection, the next field is displayed.

Image Location or Image File

  • Select Image Location option to specify the image location URL.
  • Select Image File option to upload an image from the local disk.

Format

Image format (for example, qcow2).

Architecture

Image architecture. For example, use i686 for a 32-bit architecture or x86_64 for a 64-bit architecture.

Minimum Disk (GB)

Minimum disk size required to boot the image. If this field is not specified, the default value is 0 (no minimum).

Minimum RAM (MB)

Minimum memory size required to boot the image. If this field is not specified, the default value is 0 (no minimum).

Public

If selected, makes the image public to all users with access to the project.

Protected

If selected, ensures only users with specific permissions can delete this image.

When the image has been successfully uploaded, its status is active, which indicates that the image is available for use. Note that the Image service can handle even large images that take a long time to upload — longer than the lifetime of the Identity service token which was used when the upload was initiated. This is due to the fact that the Image service first creates a trust with the Identity service so that a new token can be obtained and used when the upload is complete and the status of the image is to be updated.

Note

You can also use the glance image-create command with the property option to upload an image. More values are available on the command line. For a complete listing, see Image Configuration Parameters.

1.2.3. Update an image

  1. In the dashboard, select Project > Compute > Images.
  2. Click Edit Image from the list.

    Note

    The Edit Image option is available only when you log in as an admin user. When you log in as a demo user, you have the option to Launch an instance or Create Volume.

  3. Update the fields and click Update Image . You can update the following values - name, description, kernel ID, ramdisk ID, architecture, format, minimum disk, minimum RAM, public, protected.
  4. Click the drop-down menu and select Update Metadata option.
  5. Specify metadata by adding items from the left column to the right one. In the left column, there are metadata definitions from the Image Service Metadata Catalog. Select Other to add metadata with the key of your choice and click Save when finished.
Note

You can also use the glance image-update command with the property option to update an image. More values are available on the command line; for a complete listing, see Image Configuration Parameters.

1.2.4. Import an image

You can import images into the Image service (glance) using web-download to import an image from a URI and glance-direct to import an image from a local file system. The web-download method is enabled by default.

Import methods are configured by the cloud administrator. Run the glance import-info command to list available import options.

1.2.4.1. Import from a remote URI

You can use the web-download method to copy an image from a remote URI.

  1. Create an image and specify the URI of the image to import.

    glance image-create --uri <URI>
  2. You can monitor the image availability by using the glance image-show <image_id> command. Replace <image_id> with the ID you provided during image creation.

The Image service web download method uses a two-stage process to perform the import. First, it creates an image record. Second, it retrieves the image the specified URI. This method provides a more secure way to import images than the deprecated copy-from method used in Image API v1.

The URI is subject to optional denylist and allowlist filtering as described in the Advanced Overcloud Customization guide.

The Image Property Injection plugin may inject metadata properties to the image as described in the Advanced Overcloud Customization guide. These injected properties determine which compute nodes the image instances are launched on.

1.2.4.2. Import from a local volume

The glance-direct method creates an image record, which generates an image ID. After the image is uploaded to the service from a local volume, it is stored in a staging area and is made active after it passes any configured checks. The glance-direct method requires a shared staging area when used in a highly available (HA) configuration.

Note

Image uploads that use the glance-direct method fail in an HA environment if a common staging area is not present. In an HA active-active environment, API calls are distributed to the Image service controllers. The download API call can be sent to a different controller than the API call to upload the image. For more information about configuring the staging area, see Storage Configuration section in the Advanced Overcloud Customization Guide.

The glance-direct method uses three different calls to import an image:

  • glance image-create
  • glance image-stage
  • glance image-import

You can use the glance image-create-via-import command to perform all three of these calls in one command. In the example below, replace uppercase words with the appropriate options.

glance image-create-via-import --container-format FORMAT --disk-format DISKFORMAT --name NAME --file /PATH/TO/IMAGE

After the image moves from the staging area to the back end location, the image is listed. However, it might take some time for the image to become active.

You can monitor the image availability by using the glance image-show <image_id> command. Replace <image_id with the ID you provided during image creation.

1.2.5. Delete an image

  1. In the dashboard, select Project > Compute > Images.
  2. Select the image you want to delete and click Delete Images.

1.2.6. Hide or unhide an image

You can hide public images from normal listings presented to users. For instance, you can hide obsolete CentOS 7 images and show only the latest version to simplify the user experience. Users can discover and use hidden images.

To hide an image:

glance image-update <image_id> --hidden 'true'

To create a hidden image, add the --hidden argument to the glance image-create command.

To unhide an image:

glance image-update <image_id> --hidden 'false'

1.2.7. Show hidden images

To list hidden images:

glance image-list --hidden 'true'

1.2.8. Enabling image conversion

With the GlanceImageImportPlugins parameter enabled, you can upload a QCOW2 image, and the Image service will convert it to RAW.

Note

Image conversion is automatically enabled when you use Red Hat Ceph Storage RBD to store images and boot Nova instances.

To enable image conversion, create an environment file that contains the following parameter value and include the new environment file with the -e option in the openstack overcloud deploy command:

parameter_defaults:
  GlanceImageImportPlugins:'image_conversion'

1.2.9. Converting an image to RAW format

Red Hat Ceph Storage can store, but does not support using, QCOW2 images to host virtual machine (VM) disks.

When you upload a QCOW2 image and create a VM from it, the compute node downloads the image, converts the image to RAW, and uploads it back into Ceph, which can then use it. This process affects the time it takes to create VMs, especially during parallel VM creation.

For example, when you create multiple VMs simultaneously, uploading the converted image to the Ceph cluster might impact already running workloads. The upload process can starve those workloads of IOPS and impede storage responsiveness.

To boot VMs in Ceph more efficiently (ephemeral back end or boot from volume), the glance image format must be RAW.

Procedure

  1. Converting an image to RAW might yield an image that is larger in size than the original QCOW2 image file. Run the following command before the conversion to determine the final RAW image size:

    qemu-img info <image>.qcow2
  2. Convert an image from QCOW2 to RAW format:

    qemu-img convert -p -f qcow2 -O raw <original qcow2 image>.qcow2 <new raw image>.raw

1.2.9.1. Configuring disk formats in the Image service (glance)

You can the configure the Image service (glance) to enable or reject disk formats by using the GlanceDiskFormats parameter.

Procedure

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

    $ source ~/stackrc
  3. Include the GlanceDiskFormats parameter in an environment file, for example, glance_disk_formats.yaml:

    parameter_defaults:
      GlanceDiskFormats:
        - <disk_format>
    • For example, use the following configuration to enable only RAW and ISO disk formats:

      parameter_defaults:
        GlanceDiskFormats:
        - raw
        - iso
    • Use the following example configuration to reject QCOW2 disk images:

      parameter_defaults:
        GlanceDiskFormats:
        - raw
        - iso
        - aki
        - ari
        - ami
  4. Include the environment file that contains your new configuration in the openstack overcloud deploy command with any other environment files that are relevant to your environment:

    $ openstack overcloud deploy --templates \
      -e <overcloud_environment_files> \
      -e <new_environment_file> \
      …
    • Replace <overcloud_environment_files> with the list of environment files that are part of your deployment.
    • Replace <new_environment_file> with the environment file that contains your new configuration.

For more information about the disk formats available in RHOSP, see Image service.

1.2.10. Storing an image in RAW format

With the GlanceImageImportPlugins parameter enabled, run the following command to store a previously created image in RAW format:

$ glance image-create-via-import \
    --disk-format qcow2 \
    --container-format bare \
    --name NAME \
    --visibility public \
    --import-method web-download \
    --uri http://server/image.qcow2
  • For --name, replace NAME with the name of the image; this is the name that will appear in glance image-list.
  • For --uri, replace http://server/image.qcow2 with the location and file name of the QCOW2 image.
Note

This command example creates the image record and imports it by using the web-download method. The glance-api downloads the image from the --uri location during the import process. If web-download is not available, glanceclient cannot automatically download the image data. Run the glance import-info command to list the available image import methods.

Chapter 2. Image service with multiple stores

The Red Hat OpenStack Platform Image service (glance) supports using multiple stores with distributed edge architecture so that you can have an image pool at every edge site. You can copy images between the central site, which is also known as the hub site, and the edge sites.

The image metadata contains the location of each copy. For example, an image present on two edge sites is exposed as a single UUID with three locations: the central site plus the two edge sites. This means you can have copies of image data that share a single UUID on many stores. For more information about locations, see Understanding the location of images.

With an RBD image pool at every edge site, you can boot VMs quickly by using Ceph RBD copy-on-write (COW) and snapshot layering technology. This means that you can boot VMs from volumes and have live migration. For more information about layering with Ceph RBD, see Ceph block device layering in the Block Device Guide.

2.1. Requirements of storage edge architecture

  • A copy of each image must exist in the Image service at the central location.
  • Prior to creating an instance at an edge site, you must have a local copy of the image at that edge site.
  • Source the centralrc authentication file to schedule workloads at edge sites as well as at the central location. Authentication files that are automatically generated for edge sites are not needed.
  • Images uploaded to an edge site must be copied to the central location before they can be copied to other edge sites.
  • Use the Image service RBD driver for all edge sites. Mixed architecture is not supported.
  • Multistack must be used with a single stack at each site.
  • RBD must be the storage driver for the Image, Compute and Block Storage services.
  • For each site, you must assign the same value to the NovaComputeAvailabilityZone and CinderStorageAvailabilityZone parameters.
  • Red Hat recommends leaving the <role>HostnameFormat parameter as the default value: %stackname%-<role>-%index%. If you do not include the %stackname% prefix, your overcloud will use the same hostnames for distributed compute nodes in different stacks. Ensure your distributed compute nodes use the %stackname% prefix to distinguish nodes from different edge sites. For example, if you deploy two edge sites named dcn0 and dcn1`, the stack name prefix helps you distinguish between dcn0-distributedcompute-0 and dcn1-distributedcompute-0 when you run openstack server list on the undercloud.

2.2. Import an image to multiple stores

Use the interoperable image import workflow to import image data into multiple Ceph Storage clusters. You can import images into the Image service that are available on the local file system or through a web server.

If you import an image from a web server, the image can be imported into multiple stores at once. If the image is not available on a web server, you can import the image from a local file system into the central store and then copy it to additional stores. For more information, see Copy an existing image to multiple stores.

Important

Always store an image copy on the central site, even if there are no instances using the image at the central location. For more information about importing images into the Image service, see the Distributed compute node and storage deployment guide.

2.2.1. Manage image import failures

You can manage failures of the image import operation by using the --allow-failure parameter:

  • If the value of the --allow-failure parameter to true, the image status becomes active after the first store successfully imports the data. This is the default setting. You can view a list of stores that failed to import the image data by using the os_glance_failed_import image property.
  • If you set the value of the --allow-failure parameter to false, the image status only becomes active after all specified stores successfully import the data. Failure of any store to import the image data results in an image status of failed. The image is not imported into any of the specified stores.

2.2.2. Importing image data to multiple stores

Because the default setting of the --allow-failure parameter is true, you do not need to include the parameter in the command if it is acceptable for some stores to fail to import the image data.

Note

This procedure does not require all stores to successfully import the image data.

Procedure

  1. Import image data to multiple, specified stores:

    $ glance image-create-via-import \
    --container-format bare \
    --name IMAGE-NAME \
    --import-method web-download \
    --uri URI \
    --stores STORE1,STORE2,STORE3
    • Replace IMAGE-NAME with the name of the image you want to import.
    • Replace URI with the URI of the image.
    • Replace STORE1, STORE2, and STORE3 with the names of the stores to which you want to import the image data.
    • Alternatively, replace --stores with --all-stores true to upload the image to all the stores.
Note

The glance image-create-via-import command, which automatically converts the QCOW2 image to RAW format, works only with the web-download method. The glance-direct method is available, but it works only in deployments with a configured shared file system. For more information, see Storing an image in RAW format.

2.2.3. Importing image data to multiple stores without failure

This procedure requires all stores to successfully import the image data.

Procedure

  1. Import image data to multiple, specified stores:

    $ glance image-create-via-import \
    --container-format bare \
    --name IMAGE-NAME \
    --import-method web-download \
    --uri URI \
    --stores STORE1,STORE2
    • Replace IMAGE-NAME with the name of the image you want to import.
    • Replace URI with the URI of the image.
    • Replace STORE1, STORE2, and STORE3 with the names of stores to which you want to copy the image data.
    • Alternatively, replace --stores with --all-stores true to upload the image to all the stores.

      Note

      With the --allow-failure parameter set to false, the Image service does not ignore stores that fail to import the image data. You can view the list of failed stores with the image property os_glance_failed_import. For more information see Checking the progress of image import operation.

  2. Verify that the image data was added to specific stores:

    $ glance image-show IMAGE-ID | grep stores

    Replace IMAGE-ID with the ID of the original existing image.

    The output displays a comma-delimited list of stores.

2.2.4. Importing image data to a single store

You can import image data to a single store.

Procedure

  1. Import image data to a single store:

    $ glance image-create-via-import \
    --container-format bare \
    --name IMAGE-NAME \
    --import-method web-download \
    --uri URI \
    --store STORE
    • Replace IMAGE-NAME with the name of the image you want to import.
    • Replace URI with the URI of the image.
    • Replace STORE with the name of the store to which you want to copy the image data.

      Note

      If you do not include the options of --stores, --all-stores, or --store in the command, the Image service creates the image in the central store.

  2. Verify that the image data was added to specific store:

    $ glance image-show IMAGE-ID | grep stores

    Replace IMAGE-ID with the ID of the original existing image.

    The output displays a comma-delimited list of stores.

2.2.5. Checking the progress of the image import operation

The interoperable image import workflow sequentially imports image data into stores. The size of the image, the number of stores, and the network speed between the central site and the edge sites impact how long it takes for the image import operation to complete.

You can follow the progress of the image import by looking at two image properties, which appear in notifications sent during the image import operation:

  • The os_glance_importing_to_stores property lists the stores that have not imported the image data. At the beginning of the import, all requested stores show up in the list. Each time a store successfully imports the image data, the Image service removes the store from the list.
  • The os_glance_failed_import property lists the stores that fail to import the image data. This list is empty at the beginning of the image import operation.
Note

In the following procedure, the environment has three Ceph Storage clusters: the central store and two stores at the edge, dcn0 and dcn1.

Procedure

  1. Verify that the image data was added to specific stores:

    $ glance image-show IMAGE-ID

    Replace IMAGE-ID with the ID of the original existing image.

    The output displays a comma-delimited list of stores similar to the following example snippet:

    | os_glance_failed_import       |
    | os_glance_importing_to_stores | central,dcn0,dcn1
    | status                        | importing
  2. Monitor the status of the image import operation. When you precede a command with watch, the command output refreshes every two seconds.

    $ watch glance image-show IMAGE-ID

    Replace IMAGE-ID with the ID of the original existing image.

    The status of the operation changes as the image import operation progresses:

    | os_glance_failed_import       |
    | os_glance_importing_to_stores | dcn0,dcn1
    | status                        | importing

    Output that shows that an image failed to import resembles the following example:

    | os_glance_failed_import       | dcn0
    | os_glance_importing_to_stores | dcn1
    | status                        | importing

    After the operation completes, the status changes to active:

    | os_glance_failed_import       | dcn0
    | os_glance_importing_to_stores |
    | status                        | active

2.3. Copy an existing image to multiple stores

This feature enables you to copy existing images using Red Hat OpenStack Image service (glance) image data into multiple Ceph Storage stores at the edge by using the interoperable image import workflow.

Note

The image must be present at the central site before you copy it to any edge sites. Only the image owner or administrator can copy existing images to newly added stores.

You can copy existing image data either by setting --all-stores to true or by specifying specific stores to receive the image data.

  • The default setting for the --all-stores option is false. If --all-stores is false, you must specify which stores receive the image data by using --stores STORE1,STORE2. If the image data is already present in any of the specified stores, the request fails.
  • If you set all-stores to true, and the image data already exists in some of the stores, then those stores are excluded from the list.

After you specify which stores receive the image data, the Image service copies data from the central site to a staging area. Then the Image service imports the image data by using the interoperable image import workflow. For more information, see Importing an image to multiple stores.

Important

Red Hat recommends that administrators carefully avoid closely timed image copy requests. Two closely timed copy-image operations for the same image causes race conditions and unexpected results. Existing image data remains as it is, but copying data to new stores fails.

2.3.1. Copying an image to all stores

Use the following procedure to copy image data to all available stores.

Procedure

  1. Copy image data to all available stores:

    $ glance image-import IMAGE-ID \
    --all-stores true \
    --import-method copy-image

    Replace IMAGE-ID with the name of the image you want to copy.

  2. Confirm that the image data successfully replicated to all available stores:

    $ glance image-list --include-stores

    For information about how to check the status of the image import operation, see Checking the progress of the image import operation.

2.3.2. Copying an image to specific stores

Use the following procedure to copy image data to specific stores.

Procedure

  1. Copy image data to specific stores:

    $ glance image-import IMAGE-ID \
    --stores STORE1,STORE2 \
    --import-method copy-image
    • Replace IMAGE-ID with the name of the image you want to copy.
    • Replace STORE1 and STORE2 with the names of the stores to which you want to copy the image data.
  2. Confirm that the image data successfully replicated to the specified stores:

    $ glance image-list --include-stores

    For information about how to check the status of the image import operation, see Checking the progress of the image import operation.

2.4. Deleting an image from a specific store

With this feature you can use the OpenStack Image service (glance) to delete an existing image copy on a specific store.

Procedure

Delete an image from a specific store:

$ glance stores-delete --store _STORE_ID_ _IMAGE_ID_
  • Replace _STORE_ID with the name of the store on which the image copy should be deleted.
  • Replace IMAGE_ID with the ID of the image you want to delete.
Warning

Using glance image-delete will permanently delete the image across all the sites. All image copies will be deleted, as well as the image instance and metadata.

2.5. Understanding the locations of images

Although an image can be present on multiple sites, there is only a single UUID for a given image. The image metadata contains the locations of each copy. For example, an image present on two edge sites is exposed as a single UUID with three locations: the central site plus the two edge sites.

Procedure

  1. Show the sites on which a copy of the image exists:

    $ glance image-show ID | grep "stores"
    
    | stores |  default_backend,dcn1,dcn2

    In the example, the image is present on the central site, the default_backend, and on the two edge sites dcn1 and dcn2.

  2. Alternatively, you can run the glance image-list command with the --include-stores option to see the sites where the images exist:

    $ glance image-list --include-stores
    
    | ID                                   | Name    | Stores
    
    | 2bd882e7-1da0-4078-97fe-f1bb81f61b00 | cirros | default_backend,dcn1,dcn2
  3. List the image locations properties to show the details of each location:

    $ openstack image show ID -c properties
    
    | properties |
    
    (--- cut ---)
    locations='[{'url': 'rbd://79b70c32-df46-4741-93c0-8118ae2ae284/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'default_backend'}}, {'url': 'rbd://63df2767-8ddb-4e06-8186-8c155334f487/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'dcn1'}}, {'url': 'rbd://1b324138-2ef9-4ef9-bd9e-aa7e6d6ead78/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'dcn2'}}]',
    (--- cut --)

    The image properties show the different Ceph RBD URIs for the location of each image.

    In the example, the central image location URI is:

    rbd://79b70c32-df46-4741-93c0-8118ae2ae284/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'default_backend'}}

    The URI is composed of the following data:

    • 79b70c32-df46-4741-93c0-8118ae2ae284 corresponds to the central Ceph FSID. Each Ceph cluster has a unique FSID.
    • The default value for all sites is images, which corresponds to the Ceph pool on which the images are stored.
    • 2bd882e7-1da0-4078-97fe-f1bb81f61b00 corresponds to the image UUID. The UUID is the same for a given image regardless of its location.
    • The metadata shows the glance store to which this location maps. In this example, it maps to the default_backend, which is the central hub site.

Chapter 3. Configure OpenStack Compute Storage

This chapter describes the architecture for the back-end storage of images in OpenStack Compute (nova), and provides basic configuration options.

3.1. Architecture Overview

In Red Hat OpenStack Platform, the OpenStack Compute service uses the KVM hypervisor to execute compute workloads. The libvirt driver handles all interactions with KVM, and enables the creation of virtual machines.

Two types of libvirt storage must be considered for Compute:

  • Base image, which is a cached and formatted copy of the Image service image.
  • Instance disk, which is created using the libvirt base and is the back end for the virtual machine instance. Instance disk data can be stored either in Compute’s ephemeral storage (using the libvirt base) or in persistent storage (for example, using Block Storage).

Creation of Virtual Machines

The steps that Compute takes to create a virtual machine instance are:

  1. Cache the Image service’s backing image as the libvirt base.
  2. Convert the base image to the raw format (if configured).
  3. Resize the base image to match the VM’s flavor specifications.
  4. Use the base image to create the libvirt instance disk.

In the diagram above, the #1 instance disk uses ephemeral storage; the #2 disk uses a block-storage volume.

Ephemeral storage is an empty, unformatted, additional disk available to an instance. This storage value is defined by the instance flavor. The value provided by the user must be less than or equal to the ephemeral value defined for the flavor. The default value is 0, meaning no ephemeral storage is created.

The ephemeral disk appears in the same way as a plugged-in hard drive or thumb drive. It is available as a block device which you can check using the lsblk command. You can format it, mount it, and use it however you normally would a block device. There is no way to preserve or reference that disk beyond the instance it is attached to.

Block storage volume is persistant storage available to an instance regardless of the state of the running instance.

3.2. Configuration

You can configure performance tuning and security for your virtual disks by customizing the Compute (nova) configuration files. Compute is configured in custom environment files and heat templates using the parameters detailed in the Compute (nova) Parameters section in the Overcloud Parameters guide. This configuration is generated and stored in the /var/lib/config-data/puppet-generated/<nova_container>/etc/nova/nova.conf file, as detailed in the following table.

Table 3.1. Compute Image Parameters

SectionParameterDescriptionDefault

[DEFAULT]

force_raw_images

Whether to convert a non-raw cached base image to be raw (boolean). If a non-raw image is converted to raw, Compute:

  • Disallows backing files (which might be a security issue).
  • Removes existing compression (to avoid CPU bottlenecks).

Converting the base to raw uses more space for any image that could have been used directly by the hypervisor (for example, a qcow2 image). If you have a system with slower I/O or less available space, you might want to specify false, trading the higher CPU requirements of compression for that of minimized input bandwidth.

Raw base images are always used with libvirt_images_type=lvm.

true

[DEFAULT]

use_cow_images

Whether to use CoW (Copy on Write) images for libvirt instance disks (boolean):

  • false - The raw format is used. Without CoW, more space is used for common parts of the disk image
  • true - The cqow2 format is used. With CoW, depending on the backing store and host caching, there may be better concurrency achieved by having each VM operate on its own copy.

true

[DEFAULT]

preallocate_images

Preallocation mode for libvirt instance disks. Value can be:

  • none - No storage is provisioned at instance start.
  • space - Storage is fully allocated at instance start (using fallocate), which can help with both space guarantees and I/O performance.

Even when not using CoW instance disks, the copy each VM gets is sparse and so the VM may fail unexpectedly at run time with ENOSPC. By running fallocate(1) on the instance disk images, Compute immediately and efficiently allocates the space for them in the file system (if supported). Run time performance should also be improved because the file system does not have to dynamically allocate blocks at run time (reducing CPU overhead and more importantly file fragmentation).

none

[DEFAULT]

resize_fs_using_block_device

Whether to enable direct resizing of the base image by accessing the image over a block device (boolean). This is only necessary for images with older versions of cloud-init (that cannot resize themselves).

Because this parameter enables the direct mounting of images which might otherwise be disabled for security reasons, it is not enabled by default.

false

[DEFAULT]

default_ephemeral_format

The default format that is used for a new ephemeral volume. Value can be: ext2, ext3, or ext4. The ext4 format provides much faster initialization times than ext3 for new, large disks. You can also override per instance using the guest_format configuration option.

ext4

[DEFAULT]

image_cache_manager_interval

Number of seconds to wait between runs of the image cache manager, which impacts base caching on libvirt compute nodes. This period is used in the auto removal of unused cached images (see remove_unused_base_images and remove_unused_original_minimum_age_seconds).

2400

[DEFAULT]

remove_unused_base_images

Whether to enable the automatic removal of unused base images (checked every image_cache_manager_interval seconds). Images are defined as unused if they have not been accessed in remove_unused_original_minimum_age_seconds seconds.

true

[DEFAULT]

remove_unused_original_minimum_age_seconds

How old an unused base image must be before being removed from the libvirt cache (see remove_unused_base_images).

86400

[libvirt]

images_type

Image type to use for libvirt instance disks (deprecates use_cow_images). Value can be: raw, qcow2, lvm, rbd, or default. If default is specified, the value used for the use_cow_images parameter is used.

default

Chapter 4. Virtual machine instances

OpenStack Compute is the central component that provides virtual machines on demand. Compute interacts with the Identity service for authentication, Image service for images (used to launch instances), and the dashboard service for the user and administrative interface.

Red Hat OpenStack Platform allows you to easily manage virtual machine instances in the cloud. The Compute service creates, schedules, and manages instances, and exposes this functionality to other OpenStack components. This chapter discusses these procedures along with procedures to add components like key pairs, security groups, host aggregates and flavors. The term instance is used by OpenStack to mean a virtual machine instance.

4.1. Manage instances

Before you can create an instance, you need to ensure certain other OpenStack components (for example, a network, key pair and an image or a volume as the boot source) are available for the instance.

This section discusses the procedures to add these components, create and manage an instance. Managing an instance refers to updating, and logging in to an instance, viewing how the instances are being used, resizing or deleting them.

4.1.1. Add Components

Use the following sections to create a network, key pair and upload an image or volume source. These components are used in the creation of an instance and are not available by default. You will also need to create a new security group to allow SSH access to the user.

  1. In the dashboard, select Project.
  2. Select Network > Networks, and ensure there is a private network to which you can attach the new instance (to create a network, see Create a Network section in the Networking Guide).
  3. Select Compute > Access & Security > Key Pairs, and ensure there is a key pair (to create a key pair, see Section 4.2.1.1, “Create a Key Pair”).
  4. Ensure that you have either an image or a volume that can be used as a boot source:

  5. Select Compute > Access & Security > Security Groups, and ensure you have created a security group rule (to create a security group, see Project Security Management in the Users and Identity Management Guide).

4.1.2. Launch an Instance

Launch one or more instances from the dashboard.

Note

By default, the Launch Instance form is used to launch instances. However, you can also enable a Launch Instance wizard that simplifies the steps required. For more information, see Appendix B, Enabling the Launch Instance Wizard.

  1. In the dashboard, select Project > Compute > Instances.
  2. Click Launch Instance.
  3. Fill out the fields (those marked with '* ' are required), and click Launch.

One or more instances are created, and launched based on the options provided.

4.1.2.1. Launch Instance Options

The following table outlines the options available when launching a new instance using the Launch Instance form. The same options are also available in the Launch instance wizard.

Table 4.1. Launch Instance Form Options

TabFieldNotes

Project and User

Project

Select the project from the dropdown list.

 

User

Select the user from the dropdown list.

Details

Availability Zone

Zones are logical groupings of cloud resources in which your instance can be placed. If you are unsure, use the default zone.

 

Instance Name

A name to identify your instance.

 

Flavor

The flavor determines what resources the instance receives, for example, memory. For default flavor allocations and information about creating new flavors, see Creating flavors for launching instances.

 

Instance Count

The number of instances to create with these parameters. 1 is preselected.

 

Instance Boot Source

Select the boot source. Image sources must be compatible with OpenStack, for more information, see Section 1.2, “Manage images”. If a volume or volume source is selected, the source must be formatted using an image. For more information, see Basic Volume Usage and Configuration in the Storage Guide.

Access and Security

Key Pair

The specified key pair is injected into the instance and is used to remotely access the instance using SSH (if neither a direct login information or a static key pair is provided). Usually one key pair per project is created.

 

Security Groups

Security groups contain firewall rules which filter the type and direction of the instance’s network traffic (for more information on configuring groups, see Project Security Management in the Users and Identity Management Guide).

Networking

Selected Networks

You must select at least one network. Instances are typically assigned to a private network, and then later given a floating IP address to enable external access.

Post-Creation

Customization Script Source

You can provide either a set of commands or a script file, which will run after the instance is booted (for example, to set the instance host name or a user password). If Direct Input is selected, write your commands in the Script Data field; otherwise, specify your script file.

Note

Any script that starts with #cloud-config is interpreted as using the cloud-config syntax (for information on the syntax, see http://cloudinit.readthedocs.org/en/latest/topics/examples.html).

Advanced Options

Disk Partition

By default, the instance is built as a single partition and dynamically resized as needed. However, you can choose to manually configure the partitions yourself.

 

Configuration Drive

If selected, OpenStack writes metadata to a read-only configuration drive that is attached to the instance when it boots (instead of to Compute’s metadata service). After the instance has booted, you can mount this drive to view its contents (enables you to provide files to the instance).

4.1.3. Update an Instance (Actions menu)

You can update an instance by selecting Project > Compute > Instances, and selecting an action for that instance in the Actions column. Actions allow you to manipulate the instance in a number of ways:

Table 4.2. Update Instance Options

ActionDescription

Create Snapshot

Snapshots preserve the disk state of a running instance. You can create a snapshot to migrate the instance, as well as to preserve backup copies.

Associate/Disassociate Floating IP

You must associate an instance with a floating IP (external) address before it can communicate with external networks, or be reached by external users. Because there are a limited number of external addresses in your external subnets, it is recommended that you disassociate any unused addresses.

Edit Instance

Update the instance’s name and associated security groups.

Edit Security Groups

Add and remove security groups to or from this instance using the list of available security groups (for more information on configuring groups, see Project Security Management in the Users and Identity Management Guide).

Console

View the instance’s console in the browser (allows easy access to the instance).

View Log

View the most recent section of the instance’s console log. Once opened, you can view the full log by clicking View Full Log.

Pause/Resume Instance

Immediately pause the instance (you are not asked for confirmation); the state of the instance is stored in memory (RAM).

Suspend/Resume Instance

Immediately suspend the instance (you are not asked for confirmation); like hibernation, the state of the instance is kept on disk.

Resize Instance

Bring up the Resize Instance window (see Section 4.1.4, “Resize an Instance”).

Soft Reboot

Gracefully stop and restart the instance. A soft reboot attempts to gracefully shut down all processes before restarting the instance.

Hard Reboot

Stop and restart the instance. A hard reboot effectively just shuts down the instance’s power and then turns it back on.

Shut Off Instance

Gracefully stop the instance.

Rebuild Instance

Use new image and disk-partition options to rebuild the image (shut down, re-image, and re-boot the instance). If encountering operating system issues, this option is easier to try than terminating the instance and starting over.

Terminate Instance

Permanently destroy the instance (you are asked for confirmation).

You can create and allocate an external IP address, see Section 4.2.3, “Create, Assign, and Release Floating IP Addresses”

4.1.4. Resize an Instance

To resize an instance (memory or CPU count), you must select a new flavor for the instance that has the right capacity. If you are increasing the size, remember to first ensure that the host has enough space.

  1. Ensure communication between hosts by setting up each host with SSH key authentication so that Compute can use SSH to move disks to other hosts (for example, compute nodes can share the same SSH key).
  2. Enable resizing on the original host by setting the allow_resize_to_same_host parameter to "True" in your Compute environment file.

    Note

    The allow_resize_to_same_host parameter does not resize the instance on the same host. Even if the parameter equals "True" on all Compute nodes, the scheduler does not force the instance to resize on the same host. This is the expected behavior.

  3. In the dashboard, select Project > Compute > Instances.
  4. Click the instance’s Actions arrow, and select Resize Instance.
  5. Select a new flavor in the New Flavor field.
  6. If you want to manually partition the instance when it launches (results in a faster build time):

    1. Select Advanced Options.
    2. In the Disk Partition field, select Manual.
  7. Click Resize.

4.1.5. Connecting to an instance

You can access an instance console by using the dashboard or the command-line interface. You can also directly connect to the serial port of an instance, which allows you to debug even if the network connection fails.

4.1.5.1. Accessing an instance console by using the dashboard

You can connect to the instance console from the dashboard.

Procedure

  1. In the dashboard, select Compute > Instances.
  2. Click the instance’s More button and select Console. console access
  3. Log in using the image’s user name and password (for example, a CirrOS image uses cirros/cubswin:)).

4.1.5.2. Accessing an instance console by using the CLI

You can connect directly to the VNC console for an instance by entering the VNC console URL in a browser.

Procedure

  1. To display the VNC console URL for an instance, enter the following command:

    $ openstack console url show <vm_name>
    +-------+------------------------------------------------------+
    | Field | Value					     	       |
    +-------+------------------------------------------------------+
    | type  | novnc					               |
    | url	| http://172.25.250.50:6080/vnc_auto.html?token=       |
    |	| 962dfd71-f047-43d3-89a5-13cb88261eb9         	       |
    +-------+-------------------------------------------------------+
  2. To connect directly to the VNC console, enter the displayed URL in a browser.

4.1.6. View Instance Usage

The following usage statistics are available:

  • Per Project

    To view instance usage per project, select Project > Compute > Overview. A usage summary is immediately displayed for all project instances.

    You can also view statistics for a specific period of time by specifying the date range and clicking Submit.

  • Per Hypervisor

    If logged in as an administrator, you can also view information for all projects. Click Admin > System and select one of the tabs. For example, the Resource Usage tab offers a way to view reports for a distinct time period. You might also click Hypervisors to view your current vCPU, memory, or disk statistics.

    Note

    The vCPU Usage value (x of y) reflects the number of total vCPUs of all virtual machines (x) and the total number of hypervisor cores (y).

4.1.7. Delete an Instance

  1. In the dashboard, select Project > Compute > Instances, and select your instance.
  2. Click Terminate Instance.
Note

Deleting an instance does not delete its attached volumes; you must do this separately (see Delete a Volume in the Storage Guide).

4.1.8. Manage Multiple Instances at Once

If you need to start multiple instances at the same time (for example, those that were down for compute or controller maintenance) you can do so easily at Project > Compute > Instances:

  1. Click the check boxes in the first column for the instances that you want to start. If you want to select all of the instances, click the check box in the first row in the table.
  2. Click More Actions above the table and select Start Instances.

Similarly, you can shut off or soft reboot multiple instances by selecting the respective actions.

4.1.9. Creating an instance with a guaranteed minimum bandwidth QoS

You can create instances that request a guaranteed minimum bandwidth by using a Quality of Service (QoS) policy.

QoS policies with a guaranteed minimum bandwidth rule are assigned to ports on a specific physical network. When you create an instance that uses the configured port, the Compute scheduling service selects a host for the instance that satisfies this request. The Compute scheduling service checks the Placement service for the amount of bandwidth reserved by other instances on each physical interface, before selecting a host to deploy an instance on.

Limitations/Restrictions

  • You can only assign a guaranteed minimum bandwidth QoS policy when creating a new instance. You cannot assign a guaranteed minimum bandwidth QoS policy to instances that are already running, as the Compute service only updates resource usage for an instance in placement during creation or move operations, which means the minimum bandwidth available to the instance cannot be guaranteed.
  • You cannot live migrate an instance that uses a port that has resource requests, such as a guaranteed minimum bandwidth QoS policy. Run the following command to check if a port has resource requests:

    $ openstack port show <port_name/port_id>

Prerequisites

Procedure

  1. List the available QoS policies:

    (overcloud)$ openstack network qos policy list
    ----------------------------------------------------------------+
    | ID                                   | Name    | Shared | Default | Project                          |
    ----------------------------------------------------------------+
    | 6d771447-3cf4-4ef1-b613-945e990fa59f | policy2 | True   | False   | ba4de51bf7694228a350dd22b7a3dc24 |
    | 78a24462-e3c1-4e66-a042-71131a7daed5 | policy1 | True   | False   | ba4de51bf7694228a350dd22b7a3dc24 |
    | b80acc64-4fc2-41f2-a346-520d7cfe0e2b | policy0 | True   | False   | ba4de51bf7694228a350dd22b7a3dc24 |
    ----------------------------------------------------------------+
  2. Check the rules of each of the available policies to determine which has the required minimum bandwidth:

    (overcloud)$ openstack network qos policy show policy0
    ----------------------------------------------------------------------------------------------------+
    | Field       | Value                                                                                 |
    ----------------------------------------------------------------------------------------------------+
    | description |                                                                                                                                                                                                                                                                                                                                                                     |
    | id          | b80acc64-4fc2-41f2-a346-520d7cfe0e2b                                                                                                                                                                                                                                                                                                                                |
    | is_default  | False                                                                                                                                                                                                                                                                                                                                                               |
    | location    | cloud=', project.domain_id=, project.domain_name='Default, project.id=ba4de51bf7694228a350dd22b7a3dc24, project.name=admin, region_name=regionOne, zone=                                                                                                                                                                                                    |
    | name        | policy0                                                                                                                                                                                                                                                                                                                                                             |
    | project_id  | ba4de51bf7694228a350dd22b7a3dc24                                                                                                                                                                                                                                                                                                                                    |
    | rules       | [{min_kbps: 100000, direction: egress, id: d46218fe-9218-4e96-952b-9f45a5cb3b3c, qos_policy_id: b80acc64-4fc2-41f2-a346-520d7cfe0e2b, type: minimum_bandwidth}, {min_kbps: 100000, direction: ingress, id: 1202c4e3-a03a-464c-80d5-0bf90bb74c9d, qos_policy_id: b80acc64-4fc2-41f2-a346-520d7cfe0e2b, type: minimum_bandwidth}] |
    | shared      | True                                                                                                                                                                                                                                                                                                                                                                |
    | tags        | []                                                                                                                                                                                                                                                                                                                                                                  |
    ----------------------------------------------------------------------------------------------------+
  3. Create a port from the appropriate policy:

    (overcloud)$ openstack port create port-normal-qos --network net0 --qos-policy policy0
  4. Create an instance, specifying the NIC port to use:

    $ openstack server create --flavor cirros256 --image cirros-0.3.5-x86_64-disk --nic port-id=port-normal-qos --wait qos_instance

    An "ACTIVE" status in the output indicates that you have successfully created the instance on a host that can provide the requested guaranteed minimum bandwidth.

4.1.9.1. Removing a guaranteed minimum bandwidth QoS from an instance

If you want to lift the guaranteed minimum bandwidth QoS policy restriction from an instance, you can detach the interface.

Procedure

  • To detach the interface, enter the following command:

    $ openstack server remove port <vm_name|vm_id> <port_name|port_id>

4.2. Manage instance security

You can manage access to an instance by assigning it the correct security group (set of firewall rules) and key pair (enables SSH user access). Further, you can assign a floating IP address to an instance to enable external network access. The sections below outline how to create and manage key pairs, security groups, floating IP addresses and logging in to an instance using SSH. There is also a procedure for injecting an admin password in to an instance.

For information on managing security groups, see Project Security Management in the Users and Identity Management Guide.

4.2.1. Manage Key Pairs

Key pairs provide SSH access to the instances. Each time a key pair is generated, its certificate is downloaded to the local machine and can be distributed to users. Typically, one key pair is created for each project (and used for multiple instances).

You can also import an existing key pair into OpenStack.

4.2.1.1. Create a Key Pair

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Key Pairs tab, click Create Key Pair.
  3. Specify a name in the Key Pair Name field, and click Create Key Pair.

When the key pair is created, a key pair file is automatically downloaded through the browser. Save this file for later connections from external machines. For command-line SSH connections, you can load this file into SSH by executing:

# ssh-add ~/.ssh/os-key.pem

4.2.1.2. Import a Key Pair

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Key Pairs tab, click Import Key Pair.
  3. Specify a name in the Key Pair Name field, and copy and paste the contents of your public key into the Public Key field.
  4. Click Import Key Pair.

4.2.1.3. Delete a Key Pair

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Key Pairs tab, click the key’s Delete Key Pair button.

4.2.2. Create a Security Group

Security groups are sets of IP filter rules that can be assigned to project instances, and which define networking access to the instance. Security group are project specific; project members can edit the default rules for their security group and add new rule sets.

  1. In the dashboard, select the Project tab, and click Compute > Access & Security.
  2. On the Security Groups tab, click + Create Security Group.
  3. Provide a name and description for the group, and click Create Security Group.

For more information on managing project security, see Project Security Management in the Users and Identity Management Guide.

4.2.3. Create, Assign, and Release Floating IP Addresses

By default, an instance is given an internal IP address when it is first created. However, you can enable access through the public network by creating and assigning a floating IP address (external address). You can change an instance’s associated IP address regardless of the instance’s state.

Projects have a limited range of floating IP address that can be used (by default, the limit is 50), so you should release these addresses for reuse when they are no longer needed. Floating IP addresses can only be allocated from an existing floating IP pool, see Create Floating IP Pools in the Networking Guide.

4.2.3.1. Allocate a Floating IP to the Project

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Floating IPs tab, click Allocate IP to Project.
  3. Select a network from which to allocate the IP address in the Pool field.
  4. Click Allocate IP.

4.2.3.2. Assign a Floating IP

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Floating IPs tab, click the address' Associate button.
  3. Select the address to be assigned in the IP address field.

    Note

    If no addresses are available, you can click the + button to create a new address.

  4. Select the instance to be associated in the Port to be Associated field. An instance can only be associated with one floating IP address.
  5. Click Associate.

4.2.3.3. Release a Floating IP

  1. In the dashboard, select Project > Compute > Access & Security.
  2. On the Floating IPs tab, click the address' menu arrow (next to the Associate/Disassociate button).
  3. Select Release Floating IP.

4.2.4. Log in to an Instance

Prerequisites:

To first load the key pair file into SSH, and then use ssh without naming it:

  1. Change the permissions of the generated key-pair certificate.

    $ chmod 600 os-key.pem
  2. Check whether ssh-agent is already running:

    # ps -ef | grep ssh-agent
  3. If not already running, start it up with:

    # eval `ssh-agent`
  4. On your local machine, load the key-pair certificate into SSH. For example:

    $ ssh-add ~/.ssh/os-key.pem
  5. You can now SSH into the file with the user supplied by the image.

The following example command shows how to SSH into the Red Hat Enterprise Linux guest image with the user cloud-user:

$ ssh cloud-user@192.0.2.24
Note

You can also use the certificate directly. For example:

$ ssh -i /myDir/os-key.pem cloud-user@192.0.2.24

4.2.5. Inject an admin Password Into an Instance

You can inject an admin (root) password into an instance using the following procedure.

  1. In the /etc/openstack-dashboard/local_settings file, set the change_set_password parameter value to True.

    can_set_password: True
  2. Set the inject_password parameter to "True" in your Compute environment file.

    inject_password=true
  3. Restart the Compute service.

    # service nova-compute restart

When you use the nova boot command to launch a new instance, the output of the command displays an adminPass parameter. You can use this password to log into the instance as the root user.

The Compute service overwrites the password value in the /etc/shadow file for the root user. This procedure can also be used to activate the root account for the KVM guest images. For more information on how to use KVM guest images, see Section 1.2.1.1, “Use a KVM guest image with Red Hat OpenStack Platform”

You can also set a custom password from the dashboard. To enable this, run the following command after you have set can_set_password parameter to true.

# systemctl restart httpd.service

The newly added admin password fields are as follows:

dashboard

These fields can be used when you launch or rebuild an instance.

4.3. Manage instance snapshots

An instance snapshot allows you to create a new image from an instance. This is very convenient for upgrading base images or for taking a published image and customizing it for local use.

The difference between an image that you upload directly to the Image Service and an image that you create by snapshot is that an image created by snapshot has additional properties in the Image Service database. These properties are found in the image_properties table and include the following parameters:

Table 4.3. Snapshot Options

NameValue

image_type

snapshot

instance_uuid

<uuid of instance that was snapshotted>

base_image_ref

<uuid of original image of instance that was snapshotted>

image_location

snapshot

Snapshots allow you to create new instances based on that snapshot, and potentially restore an instance to that state. Moreover, this can be performed while the instance is running.

By default, a snapshot is accessible to the users and projects that were selected while launching an instance that the snapshot is based on.

4.3.1. Create an Instance Snapshot

Note

If you intend to use an instance snapshot as a template to create new instances, you must ensure that the disk state is consistent. Before you create a snapshot, set the snapshot image metadata property os_require_quiesce=yes. For example,

$ glance image-update IMAGE_ID --property os_require_quiesce=yes

For this to work, the guest should have the qemu-guest-agent package installed, and the image should be created with the metadata property parameter hw_qemu_guest_agent=yes set. For example,

$ glance image-create --name NAME \
--disk-format raw \
--container-format bare \
--file FILE_NAME \
--is-public True \
--property hw_qemu_guest_agent=yes \
--progress

If you unconditionally enable the hw_qemu_guest_agent=yes parameter, then you are adding another device to the guest. This consumes a PCI slot, and will limit the number of other devices you can allocate to the guest. It also causes Windows guests to display a warning message about an unknown hardware device.

For these reasons, setting the hw_qemu_guest_agent=yes parameter is optional, and the parameter should be used for only those images that require the QEMU guest agent.

  1. In the dashboard, select Project > Compute > Instances.
  2. Select the instance from which you want to create a snapshot.
  3. In the Actions column, click Create Snapshot.
  4. In the Create Snapshot dialog, enter a name for the snapshot and click Create Snapshot.

    The Images category now shows the instance snapshot.

To launch an instance from a snapshot, select the snapshot and click Launch.

4.3.2. Manage a Snapshot

  1. In the dashboard, select Project > Images.
  2. All snapshots you created, appear under the Project option.
  3. For every snapshot you create, you can perform the following functions, using the dropdown list:

    1. Use the Create Volume option to create a volume and entering the values for volume name, description, image source, volume type, size and availability zone. For more information, see Create a Volume in the Storage Guide.
    2. Use the Edit Image option to update the snapshot image by updating the values for name, description, Kernel ID, Ramdisk ID, Architecture, Format, Minimum Disk (GB), Minimum RAM (MB), public or private. For more information, see Section 1.2.3, “Update an image”.
    3. Use the Delete Image option to delete the snapshot.

4.3.3. Rebuild an Instance to a State in a Snapshot

In an event that you delete an instance on which a snapshot is based, the snapshot still stores the instance ID. You can check this information using the nova image-list command and use the snapshot to restore the instance.

  1. In the dashboard, select Project > Compute > Images.
  2. Select the snapshot from which you want to restore the instance.
  3. In the Actions column, click Launch Instance.
  4. In the Launch Instance dialog, enter a name and the other details for the instance and click Launch.

For more information on launching an instance, see Section 4.1.2, “Launch an Instance”.

4.3.4. Consistent Snapshots

Previously, file systems had to be quiesced manually (fsfreeze) before taking a snapshot of active instances for consistent backups.

Compute’s libvirt driver automatically requests the QEMU Guest Agent to freeze the file systems (and applications if fsfreeze-hook is installed) during an image snapshot. Support for quiescing file systems enables scheduled, automatic snapshots at the block device level.

This feature is only valid if the QEMU Guest Agent is installed (qemu-ga) and the image metadata enables the agent (hw_qemu_guest_agent=yes)

Note

Snapshots should not be considered a substitute for an actual system backup.

4.4. Use rescue mode for instances

Compute has a method to reboot a virtual machine in rescue mode. Rescue mode provides a mechanism for access when the virtual machine image renders the instance inaccessible. A rescue virtual machine allows a user to fix their virtual machine by accessing the instance with a new root password. This feature is useful if an instance’s filesystem is corrupted. By default, rescue mode starts an instance from the initial image attaching the current boot disk as a secondary one.

4.4.1. Preparing an Image for a Rescue Mode Instance

Due to the fact that both the boot disk and the disk for rescue mode have same UUID, sometimes the virtual machine can be booted from the boot disk instead of the disk for rescue mode.

To avoid this issue, you should create a new image as rescue image based on the procedure in Section 1.2.1, “Creating an image”:

Note

The rescue image is stored in glance and configured in the nova.conf as a default, or you can select when you do the rescue.

4.4.1.1. Rescue Image if Using ext4 Filesystem

When the base image uses ext4 filesystem, you can create a rescue image from it using the following procedure:

  1. Change the UUID to a random value using the tune2fs command:

    # tune2fs -U random /dev/DEVICE_NODE

    Here DEVICE_NODE is the root device node (for example, sda, vda, and so on).

  2. Verify the details of the filesystem, including the new UUID:

    # tune2fs -l
  3. Update the /etc/fstab to use the new UUID. You may need to repeat this for any additional partitions you have, that are mounted in the fstab by UUID.
  4. Update the /boot/grub2/grub.conf file and update the UUID parameter with the new UUID of the root disk.
  5. Shut down and use this image as your rescue image. This will cause the rescue image to have a new random UUID that will not conflict with the instance that you are rescuing.
Note

The XFS filesystem cannot change the UUID of the root device on the running virtual machine. Reboot the virtual machine until the virtual machine is launched from the disk for rescue mode.

4.4.2. Adding the Rescue Image to the OpenStack Image Service

When you have completed modifying the UUID of your image, use the following commands to add the generated rescue image to the OpenStack Image service:

  1. Add the rescue image to the Image service:

    # glance image-create --name IMAGE_NAME --disk-format qcow2 \
      --container-format bare --is-public True --file IMAGE_PATH

    Here IMAGE_NAME is the name of the image, IMAGE_PATH is the location of the image.

  2. Use the image-list command to obtain the IMAGE_ID required for launching an instace in the rescue mode.

    # glance image-list

You can also upload an image using the OpenStack Dashboard, see Section 1.2.2, “Upload an image”.

4.4.3. Launching an Instance in Rescue Mode

  1. Since you need to rescue an instance with a specific image, rather than the default one, use the --image parameter:

    # nova rescue --image IMAGE_ID VIRTUAL_MACHINE_ID

    Here IMAGE_ID is the ID of the image you want to use and VIRTUAL_MACHINE_ID is ID of a virtual machine that you want to rescue.

    Note

    The nova rescue command allows an instance to perform a soft shut down. This allows the guest operating system to perform a controlled shutdown before the instance is powered off. The shut down behavior is configured using shutdown_timeout in your Compute configuration file. The value stands for the overall period (in seconds) a guest operation system is allowed to complete the shutdown. The default timeout is 60 seconds.

    The timeout value can be overridden on a per image basis by means of os_shutdown_timeout that is an image metadata setting allowing different types of operating systems to specify how much time they need to shut down cleanly.

  2. Reboot the virtual machine.
  3. Confirm the status of the virtual machine is RESCUE on the controller node by using nova list command or by using dashboard.
  4. Log in to the new virtual machine dashboard by using the password for rescue mode.

You can now make the necessary changes to your instance to fix any issues.

4.4.4. Unrescuing an Instance

You can unrescue the fixed instance to restart it from the boot disk.

  1. Execute the following commands on the controller node.

    # nova unrescue VIRTUAL_MACHINE_ID

    Here VIRTUAL_MACHINE_ID is ID of a virtual machine that you want to unrescue.

The status of your instance returns to ACTIVE once the unrescue operation has completed successfully. :leveloffset: +4

4.5. Creating a customized instance

Cloud users can specify additional data to use when they launch an instance, such as a shell script that the instance runs on boot. The cloud user can use the following methods to pass data to instances:

User data
Use to include instructions in the instance launch command for cloud-init to execute.
Instance metadata
A list of key-value pairs that you can specify when you create or update an instance.

You can access the additional data passed to the instance by using a config drive or the metadata service.

Config drive
You can attach a config drive to an instance when it boots. The config drive is presented to the instance as a read-only drive. The instance can mount this drive and read files from it. You can use the config drive as a source for cloud-init information. Config drives are useful when combined with cloud-init for server bootstrapping, and when you want to pass large files to your instances. For example, you can configure cloud-init to automatically mount the config drive and run the setup scripts during the initial instance boot. Config drives are created with the volume label of config-2, and attached to the instance when it boots. The contents of any additional files passed to the config drive are added to the user_data file in the openstack/{version}/ directory of the config drive. cloud-init retrieves the user data from this file.
Metadata service
Provides a REST API to retrieve data specific to an instance. Instances access this service at 169.254.169.254 or at fe80::a9fe:a9fe.

cloud-init can use both a config drive and the metadata service to consume the additional data for customizing an instance. The cloud-init package supports several data input formats. Shell scripts and the cloud-config format are the most common input formats:

  • Shell scripts: The data declaration begins with #! or Content-Type: text/x-shellscript. Shell scripts are invoked last in the boot process.
  • cloud-config format: The data declaration begins with #cloud-config or Content-Type: text/cloud-config. cloud-config files must be valid YAML to be parsed and executed by cloud-init.
Note

cloud-init has a maximum user data size of 16384 bytes for data passed to an instance. You cannot change the size limit, therefore use gzip compression when you need to exceed the size limit.

Vendor-specific data

The RHOSP administrator can also pass data to instances when they are being created. This data may not be visible to you as the cloud user, for example, a cryptographic token that registers the instance with Active Directory.

The RHOSP administrator uses the vendordata feature to pass data to instances. Vendordata configuration is read only, and is located in one of the following files:

  • /openstack/{version}/vendor_data.json
  • /openstack/{version}/vendor_data2.json

You can view these files using the metadata service or from the config drive on your instance. To access the files by using the metadata service, make a GET request to either http://169.254.169.254/openstack/{version}/vendor_data.json or http://169.254.169.254/openstack/{version}/vendor_data2.json.

4.5.1. Customizing an instance by using user data

You can use user data to include instructions in the instance launch command. cloud-init executes these commands to customize the instance as the last step in the boot process.

Procedure

  1. Create a file with instructions for cloud-init. For example, create a bash script that installs and enables a web server on the instance:

    $ vim /home/scripts/install_httpd
    #!/bin/bash
    
    yum -y install httpd python-psycopg2
    systemctl enable httpd --now
  2. Launch an instance with the --user-data option to pass the bash script:

    $ openstack server create \
    --image rhel8 \
    --flavor default \
    --nic net-id=web-server-network \
    --security-group default \
    --key-name web-server-keypair \
    --user-data /home/scripts/install_httpd \
    --wait web-server-instance
  3. When the instance state is active, attach a floating IP address:

    $ openstack floating ip create web-server-network
    $ openstack server add floating ip web-server-instance 172.25.250.123
  4. Log in to the instance with SSH:

    $ ssh -i ~/.ssh/web-server-keypair cloud-user@172.25.250.123
  5. Check that the customization was successfully performed. For example, to check that the web server has been installed and enabled, enter the following command:

    $ curl http://localhost | grep Test
    <title>Test Page for the Apache HTTP Server on Red Hat Enterprise Linux</title>
    <h1>Red Hat Enterprise Linux <strong>Test Page</strong></h1>
  6. Review the /var/log/cloud-init.log file for relevant messages, such as whether or not the cloud-init executed:

    $ sudo less /var/log/cloud-init.log
    ...output omitted...
    ...util.py[DEBUG]: Cloud-init v. 0.7.9 finished at Sat, 23 Jun 2018 02:26:02 +0000. Datasource DataSourceOpenStack [net,ver=2].  Up 21.25 seconds

4.5.2. Customizing an instance by using metadata

You can use instance metadata to specify the properties of an instance in the instance launch command.

Procedure

  1. Launch an instance with the --property <key=value> option. For example, to mark the instance as a webserver, set the following property:

    $ openstack server create \
    --image rhel8 \
    --flavor default \
    --property role=webservers \
    --wait web-server-instance
  2. Optional: Add an additional property to the instance after it is created, for example:

    $ openstack server set \
    --property region=emea \
    --wait web-server-instance

4.5.3. Customizing an instance by using a config drive

You can create a config drive for an instance that is attached during the instance boot process. You can pass content to the config drive that the config drive makes available to the instance.

Procedure

  1. Enable the config drive, and specify a file that contains content that you want to make available in the config drive. For example, the following command creates a new instance named config-drive-instance and attaches a config drive that contains the contents of the file my-user-data.txt:

    (overcloud)$ openstack server create --flavor m1.tiny \
      --config-drive true \
      --user-data ./my-user-data.txt \
      --image cirros config-drive-instance

    This command creates the config drive with the volume label of config-2, which is attached to the instance when it boots, and adds the contents of my-user-data.txt to the user_data file in the openstack/{version}/ directory of the config drive.

  2. Log in to the instance.
  3. Mount the config drive:

    • If the instance OS uses udev:

      # mkdir -p /mnt/config
      # mount /dev/disk/by-label/config-2 /mnt/config
    • If the instance OS does not use udev, you need to first identify the block device that corresponds to the config drive:

      # blkid -t LABEL="config-2" -odevice
      /dev/vdb
      # mkdir -p /mnt/config
      # mount /dev/vdb /mnt/config

Appendix A. Image Configuration Parameters

The following keys can be used with the property option for both the glance image-update and glance image-create commands.

$ glance image-update IMG-UUID --property architecture=x86_64

Table A.1. Property keys

Specific toKeyDescriptionSupported values

All

architecture

The CPU architecture that must be supported by the hypervisor. For example, x86_64, arm, or ppc64. Run uname -m to get the architecture of a machine.

  • alpha - DEC 64-bit RISC
  • armv7l - ARM Cortex-A7 MPCore
  • cris- Ethernet, Token Ring, AXis-Code Reduced Instruction Set
  • i686 - Intel sixth-generation x86 (P6 micro architecture)
  • ia64 - Itanium
  • lm32 - Lattice Micro32
  • m68k - Motorola 68000
  • microblaze - Xilinx 32-bit FPGA (Big Endian)
  • microblazeel - Xilinx 32-bit FPGA (Little Endian)
  • mips - MIPS 32-bit RISC (Big Endian)
  • mipsel - MIPS 32-bit RISC (Little Endian)
  • mips64 - MIPS 64-bit RISC (Big Endian)
  • mips64el - MIPS 64-bit RISC (Little Endian)
  • openrisc - OpenCores RISC
  • parisc - HP Precision Architecture RISC
  • parisc64 - HP Precision Architecture 64-bit RISC
  • ppc - PowerPC 32-bit
  • ppc64 - PowerPC 64-bit
  • ppcemb - PowerPC (Embedded 32-bit)
  • s390 - IBM Enterprise Systems Architecture/390
  • s390x - S/390 64-bit
  • sh4 - SuperH SH-4 (Little Endian)
  • sh4eb - SuperH SH-4 (Big Endian)
  • sparc - Scalable Processor Architecture, 32-bit
  • sparc64 - Scalable Processor Architecture, 64-bit
  • unicore32 - Microprocessor Research and Development Center RISC Unicore32
  • x86_64 - 64-bit extension of IA-32
  • xtensa - Tensilica Xtensa configurable microprocessor core
  • xtensaeb - Tensilica Xtensa configurable microprocessor core (Big Endian)

All

hypervisor_type

The hypervisor type.

kvm, vmware

All

instance_uuid

For snapshot images, this is the UUID of the server used to create this image.

Valid server UUID

All

kernel_id

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

Valid image ID

All

os_distro

The common name of the operating system distribution in lowercase.

  • arch - Arch Linux. Do not use archlinux or org.archlinux.
  • centos - Community Enterprise Operating System. Do not use org.centos or CentOS.
  • debian - Debian. Do not use Debian or org.debian.
  • fedora - Fedora. Do not use Fedora, org.fedora, or org.fedoraproject.
  • freebsd - FreeBSD. Do not use org.freebsd, freeBSD, or FreeBSD.
  • gentoo - Gentoo Linux. Do not use Gentoo or org.gentoo.
  • mandrake - Mandrakelinux (MandrakeSoft) distribution. Do not use mandrakelinux or MandrakeLinux.
  • mandriva - Mandriva Linux. Do not use mandrivalinux.
  • mes - Mandriva Enterprise Server. Do not use mandrivaent or mandrivaES.
  • msdos - Microsoft Disc Operating System. Do not use ms-dos.
  • netbsd - NetBSD. Do not use NetBSD or org.netbsd.
  • netware - Novell NetWare. Do not use novell or NetWare.
  • openbsd - OpenBSD. Do not use OpenBSD or org.openbsd.
  • opensolaris - OpenSolaris. Do not use OpenSolaris or org.opensolaris.
  • opensuse - openSUSE. Do not use suse, SuSE, or org.opensuse.
  • rhel - Red Hat Enterprise Linux. Do not use redhat, RedHat, or com.redhat.
  • sled - SUSE Linux Enterprise Desktop. Do not use com.suse.
  • ubuntu - Ubuntu. Do not use Ubuntu, com.ubuntu, org.ubuntu, or canonical.
  • windows - Microsoft Windows. Do not use com.microsoft.server.

All

os_version

The operating system version as specified by the distributor.

Version number (for example, "11.10")

All

ramdisk_id

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

Valid image ID

All

vm_mode

The virtual machine mode. This represents the host/guest ABI (application binary interface) used for the virtual machine.

hvm-Fully virtualized. This is the mode used by QEMU and KVM.

libvirt API driver

hw_disk_bus

Specifies the type of disk controller to attach disk devices to.

scsi, virtio, ide, or usb. Note that if using iscsi, the hw_scsi_model needs to be set to virtio-scsi.

libvirt API driver

hw_cdrom_bus

Specifies the type of disk controller to attach CD-ROM devices to.

scsi, virtio, ide, or usb. If you specify iscsi, you must set the hw_scsi_model parameter to virtio-scsi.

libvirt API driver

hw_numa_nodes

Number of NUMA nodes to expose to the instance (does not override flavor definition).

Integer.

libvirt API driver

hw_numa_cpus.0

Mapping of vCPUs N-M to NUMA node 0 (does not override flavor definition).

Comma-separated list of integers.

libvirt API driver

hw_numa_cpus.1

Mapping of vCPUs N-M to NUMA node 1 (does not override flavor definition).

Comma-separated list of integers.

libvirt API driver

hw_numa_mem.0

Mapping N MB of RAM to NUMA node 0 (does not override flavor definition).

Integer

libvirt API driver

hw_numa_mem.1

Mapping N MB of RAM to NUMA node 1 (does not override flavor definition).

Integer

libvirt API driver

hw_qemu_guest_agent

Guest agent support. If set to yes, and if qemu-ga is also installed, file systems can be quiesced (frozen) and snapshots created automatically.

yes / no

libvirt API driver

hw_rng_model

Adds a random-number generator device to the image’s instances. The cloud administrator can enable and control device behavior by configuring the instance’s flavor. By default:

  • The generator device is disabled.
  • /dev/random is used as the default entropy source. To specify a physical HW RNG device, set rng_dev_path to "/dev/hwrng" in your Compute environment file.

virtio, or other supported device.

libvirt API driver

hw_scsi_model

Enables the use of VirtIO SCSI (virtio-scsi) to provide block device access for compute instances; by default, instances use VirtIO Block (virtio-blk). VirtIO SCSI is a para-virtualized SCSI controller device that provides improved scalability and performance, and supports advanced SCSI hardware.

virtio-scsi

libvirt API driver

hw_video_model

The video device driver to use in virtual machine instances.

List of supported drivers, in order of precedence:

  • virtio. (Recommended) Virtual GPU with the Gallium GPU specification that uses the VIRGL renderer to render OpenGL. This GPU model is supported in all architectures, and can leverage hardware acceleration if the host has a dedicated GPU. For more information, see https://virgil3d.github.io/.
  • qxl. High-performance driver for Spice or noVNC environments.
  • cirrus. Legacy driver, use if the QXL driver is not available.
  • vga. Use this driver for IBM Power environments.
  • gop. Not supported for QEMU/KVM environments.
  • xen. Not supported for KVM environments.
  • vmvga. Legacy driver, do not use.
  • none. Use this value to disable emulated graphics or video in virtual GPU (vGPU) instances where the driver is configured separately.

libvirt API driver

hw_video_ram

Maximum RAM for the video image. Used only if a hw_video:ram_max_mb value has been set in the flavor’s extra_specs and that value is higher than the value set in hw_video_ram.

Integer in MB (for example, 64)

libvirt API driver

hw_watchdog_action

Enables a virtual hardware watchdog device that carries out the specified action if the server hangs. The watchdog uses the i6300esb device (emulating a PCI Intel 6300ESB). If hw_watchdog_action is not specified, the watchdog is disabled.

  • disabled-The device is not attached. Allows the user to disable the watchdog for the image, even if it has been enabled using the image’s flavor. The default value for this parameter is disabled.
  • reset-Forcefully reset the guest.
  • poweroff-Forcefully power off the guest.
  • pause-Pause the guest.
  • none-Only enable the watchdog; do nothing if the server hangs.

libvirt API driver

os_command_line

The kernel command line to be used by the libvirt driver, instead of the default. For Linux Containers (LXC), the value is used as arguments for initialization. This key is valid only for Amazon kernel, ramdisk, or machine images (aki, ari, or ami).

 

libvirt API driver and VMware API driver

hw_vif_model

Specifies the model of virtual network interface device to use.

The valid options depend on the configured hypervisor.

  • KVM and QEMU: e1000, ne2k_pci, pcnet, rtl8139, and virtio.
  • VMware: e1000, e1000e, VirtualE1000, VirtualE1000e, VirtualPCNet32, VirtualSriovEthernetCard, and VirtualVmxnet.
  • Xen: e1000, netfront, ne2k_pci, pcnet, and rtl8139.

VMware API driver

vmware_adaptertype

The virtual SCSI or IDE controller used by the hypervisor.

lsiLogic, busLogic, or ide

VMware API driver

vmware_ostype

A VMware GuestID which describes the operating system installed in the image. This value is passed to the hypervisor when creating a virtual machine. If not specified, the key defaults to otherGuest.

For more information, see Images with VMware vSphere.

VMware API driver

vmware_image_version

Currently unused.

1

XenAPI driver

auto_disk_config

If true, the root partition on the disk is automatically resized before the instance boots. This value is only taken into account by the Compute service when using a Xen-based hypervisor with the XenAPI driver. The Compute service will only attempt to resize if there is a single partition on the image, and only if the partition is in ext3 or ext4 format.

true / false

libvirt API driver and XenAPI driver

os_type

The operating system installed on the image. The XenAPI driver contains logic that takes different actions depending on the value of the os_type parameter of the image. For example, for os_type=windows images, it creates a FAT32-based swap partition instead of a Linux swap partition, and it limits the injected host name to less than 16 characters.

linux or windows

Appendix B. Enabling the Launch Instance Wizard

There are two methods that you can use to launch instances from the dashboard:

  • The Launch Instance form
  • The Launch Instance wizard

The Launch Instance form is enabled by default, but you can enable the Launch Instance wizard at any time. You can also enable both the Launch Instance form and the Launch Instance wizard at the same time. The Launch Instance wizard simplifies the steps required to create instances.

  1. Edit /etc/openstack-dashboard/local_settings file, and add the following values:

    LAUNCH_INSTANCE_LEGACY_ENABLED = False
    LAUNCH_INSTANCE_NG_ENABLED = True
  2. Restart the httpd service:

    # systemctl restart httpd

The preferences for the Launch Instance form and Launch Instance wizard are updated.

If you enabled only one of these options, the Launch Instance button in the dashboard opens that option by default. If you enabled both options, two Launch Instance buttons are displayed in the dashboard, with the button on the left opening the Launch Instance wizard and the button on the right opening the Launch Instance form.

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.