Diskimage-Builder Roles

ensure-dib

This role installs diskimage-builder and dependencies.

Currently, only Ubuntu and Debian distributions are supported.

Note

The disk-image-create script will be located in {{ dib_venv_dir }}/bin/disk-image-create.

Role variables

ensure_dib_venv_dir Default: "{{ ansible_user_dir }}/dib": Directory for the virtualenv to install the diskimage-builder.

ensure_dib_version Default: undefined: The version of diskimage-builder to install. The default is to install the lastest version.

Output Variables

ensure_dib_command: This variable points to the disk-image-create command installed in the {{ dib_venv_dir }}.

build-diskimage

Role for building images using diskimage-builder.

Diskimage-builder and diskimage elements can be configured by passing corresponding settings as environment variables to this role, or using the build_diskimage_environment variable.

By default the build-disk-image command does not print its output to stdout, but only to a log file in the configured log directory. To additionally log to stdout, set DIB_QUIET: 0 in build_diskimage_environment.

Example:

roles:
 - name: build-diskimage
   environment:
     ELEMENTS_PATH: /tmp/elements
     DIB_PYPI_MIRROR_URL: https://example.com

Role variables

build_diskimage_command Default: "{{ ensure_dib_command }}": Path to the build-disk-image command. This defaults to {{ ensure_dib_command }}. as being set by the ensure-dib role.

build_diskimage_image_name: Name of the image to build.

build_diskimage_formats Default: ['qcow2'] Type: list: List of image types to generate.

build_diskimage_elements Default: ['ubuntu', 'vm'] Type: list

List of elements that should be used when creating the disk image.

For ease of use with YAML anchors, this may be provided as a list of lists which will be flattened automatically.

build_diskimage_environment Type: dict: Environment variables for the diskimage builder command may be supplied using this variable (or by directly using the Ansible environment argument).

build_diskimage_image_root Default: "{{ ansible_user_dir }}/dib-images": Directory to store the build images.

build_diskimage_logs_dir Default: {{ ansible_user_dir }}/zuul-output/logs: The path where the log output of the diskimage-builder shall be written to

build_diskimage_retry_limit Default: 0: The number of times the build-diskimage command shall be retried until successful.

build_diskimage_retry_delay Default: 120: The number of seconds to wait between retries of the build-diskimage command.

convert-diskimage

This role converts diskimages from one format to other using the qemu-img tool.

Currently, only Ubuntu and Debian distributions are supported.

Role variables

convert_diskimage_source_image: The path to the source image file.

convert_diskimage_target_image: The path of the desired target image file.

convert_diskimage_target_image_formats Type: list: The desired formats of the target image. Supported values are “raw” and “qcow2”.

upload-image-swift

Upload a filesystem image to a swift container

This uploads a filesystem image (for example, one built by diskimage builder) to an OpenStack Object Store (Swift) container. The role returns an artifact to Zuul suitable for use by the zuul-launcher.

Role Variables

upload_image_swift_cloud_config: Complex argument which contains the cloud configuration in os-cloud-config (clouds.yaml) format. It is expected that this argument comes from a Secret.

upload_image_swift_container

This role will create containers which do not already exist.

Note that you will want to set this to a value that uniquely identifies your Zuul installation if using shared object stores that require globally unique container names. For example if using a public cloud whose Swift API is provided by Ceph.

The container should be dedicated to image uploads so that the “delete_after” option may be safely used.

upload_image_swift_delete_after Default: 0: Number of seconds to delete objects after upload. Default is 0 (disabled). This will tell swift to delete the file automatically, but if that fails, the next run of the role will attempt to delete any objects in the bucket older than this time.

upload_image_swift_image_name Default: `{{ build_diskimage_image_name }}`: The Zuul image name for use by zuul-launcher (e.g., debian-bookworm).

upload_image_swift_format: The image format (e.g., qcow2).

upload_image_swift_extension Default: `{{ upload_image_swift_format }}`: The extension to use when uploading (only used in the default values for the following variables.

upload_image_swift_filename Default: `{{ build_diskimage_image_root }}/{{ build_diskimage_image_name }}.{{ upload_image_swift_extension }}`: The path of the local file to upload.

upload_image_swift_name Default: `{{ zuul.build }}-{{ build_diskimage_image_name }}.{{ upload_image_swift_extension }}`: The object name to use when uploading.

upload-image-s3

Upload a filesystem image to an S3 bucket

This uploads a filesystem image (for example, one built by diskimage builder) to an S3 bucket. The role returns an artifact to Zuul suitable for use by the zuul-launcher.

Role Variables

upload_image_s3_endpoint: The endpoint to use when uploading an image to an s3 compatible service. By default this will be automatically constructed by boto but should be set when working with non-AWS hosted s3 service.

upload_image_s3_aws_access_key: AWS access key to use.

upload_image_s3_aws_secret_key: AWS secret key for the AWS access key.

upload_image_s3_bucket

This role will not create buckets which do not already exist.

Note that you will want to set this to a value that uniquely identifies your Zuul installation.

The bucket should be dedicated to image uploads so that the “delete_after” option may be safely used.

upload_image_s3_delete_after Default: 0

Number of seconds to delete objects after upload. Default is 0 (disabled). Each run of the role will attempt to delete any objects in the bucket older than this time.

It is also recommended to use the AWS console to configure automatic expiration of objects in this bucket.

upload_image_s3_image_name Default: `{{ build_diskimage_image_name }}`: The Zuul image name for use by zuul-launcher (e.g., debian-bookworm).

upload_image_s3_format: The image format (e.g., qcow2).

upload_image_s3_extension Default: `{{ upload_image_s3_format }}`: The extension to use when uploading (only used in the default values for the following variables.

upload_image_s3_filename Default: `{{ build_diskimage_image_root }}/{{ build_diskimage_image_name }}.{{ upload_image_s3_extension }}`: The path of the local file to upload.

upload_image_s3_name Default: `{{ zuul.build }}-{{ build_diskimage_image_name }}.{{ upload_image_s3_extension }}`: The object name to use when uploading.