Skip to content

README.md

Latest commit

 

History

History
334 lines (270 loc) · 13 KB

README.md

File metadata and controls

334 lines (270 loc) · 13 KB

Cloud images

This Makefile automates the process of building cloud images for hotstack deployments. The tasks are executed using the make utility.

Images

  • controller: A customized CentOS 9 Stream image with packages needed for the hotstack controller node. Built using diskimage-builder (DIB) with custom elements from the dib/ subdirectory.
  • microshift: A CentOS 9 Stream image with MicroShift packages installed from GitHub releases. Built using diskimage-builder (DIB) with the hotstack-microshift element. The image is intentionally unconfigured and requires cloud-init or manual setup to enable services and configure runtime settings.
  • blank: A minimal blank image used for virtual baremetal node disks with Redfish virtual BMC
  • nat64: A NAT64 appliance image built using ci-framework for IPv6-only environments
  • switch-host (experimental): A CentOS 9 Stream image with libvirt/qemu for running virtual network switches using nested virtualization

Download Pre-built Images

Pre-built images are available from GitHub releases. These are automatically built by CI workflows and can be downloaded instead of building locally.

Controller Image

# Download latest controller image
curl -L -O https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-controller/controller-latest.qcow2

Blank Image

# Download latest blank image
curl -L -O https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-blank/blank-image-latest.qcow2

NAT64 Appliance Image

The NAT64 appliance image is built and released in the openstack-k8s-operators-ci repository:

# Download latest NAT64 appliance image
curl -L -O https://github.com/openstack-k8s-operators/openstack-k8s-operators-ci/releases/download/latest/nat64-appliance-latest.qcow2

For specific versions, see the respective releases pages:

Building Images Locally

The following sections describe how to build images locally using the included Makefiles.

Variables

  • CONTROLLER_IMAGE_NAME: The name of the controller image file to be created (default: controller.qcow2).
  • CONTROLLER_IMAGE_FORMAT: The desired format for the controller image (default: raw). Set to qcow2 to skip conversion and keep the original DIB output format.
  • CONTROLLER_DIB_VENV: Path to the Python virtual environment for diskimage-builder (default: ~/controller-dib-venv).
  • CONTROLLER_DIB_WORKDIR: Working directory for DIB build artifacts and cache (default: .controller-build).
  • BLANK_IMAGE_NAME: The name of the blank image file to be created.
  • BLANK_IMAGE_FORMAT: The format for the blank image (default: raw). Can be set to qcow2 or any format supported by qemu-img.
  • BLANK_IMAGE_SIZE: The size of the blank image file in megabytes.
  • NAT64_IMAGE_NAME: The name of the NAT64 appliance image file.
  • NAT64_IMAGE_FORMAT: The desired format for the NAT64 image (default: raw). Set to qcow2 to keep the original format.
  • NAT64_CIFMW_DIR: Directory where ci-framework will be cloned (default: .ci-framework).
  • NAT64_BASEDIR: Build directory for NAT64 appliance artifacts (default: .nat64-build).
  • SWITCH_HOST_IMAGE_URL: The URL to download the CentOS 9 Stream image for switch host.
  • SWITCH_HOST_IMAGE_NAME: The name of the switch host image file.
  • SWITCH_HOST_IMAGE_FORMAT: The desired format for the switch host image (default: raw). Set to qcow2 to keep the original format.
  • SWITCH_HOST_INSTALL_PACKAGES: A list of packages to install on the switch host image (includes libvirt, qemu-kvm, networking tools).
  • FORCE10_10_IMAGE: Path to Force10 OS10 image file (zip archive like OS10_Virtualization_10.6.0.2.74V.zip). Will be copied to /opt/force10_10/ in the image. (Experimental support only)

Note: Raw format is required for cloud backends using Ceph, as Ceph cannot directly use qcow2 images for VM disks.

Targets

  • all: The default target that depends on controller, blank, and nat64.
  • clean: A target that removes the controller, blank, and NAT64 images, as well as build artifacts.
  • controller: Builds the controller image using diskimage-builder (DIB). Depends on controller_dib_setup, controller_dib_build, and controller_convert.
    • controller_dib_setup: Creates a Python virtual environment and installs diskimage-builder.
    • controller_dib_build: Builds the controller image using DIB with the configuration from dib/controller-image.yaml and the custom hotstack-controller element from dib/elements/.
    • controller_convert: Converts the image to the format specified by CONTROLLER_IMAGE_FORMAT (in-place conversion if raw).
    • controller_clean: Removes the controller image, virtual environment, and build artifacts.
  • microshift: Builds the MicroShift image using diskimage-builder (DIB). Depends on microshift_dib_setup, microshift_dib_build, and microshift_convert.
    • microshift_dib_setup: Creates a Python virtual environment and installs diskimage-builder.
    • microshift_dib_build: Builds the MicroShift image using DIB with the configuration from dib/microshift-image.yaml and the custom hotstack-microshift element from dib/elements/.
    • microshift_convert: Converts the image to the format specified by MICROSHIFT_IMAGE_FORMAT (in-place conversion if raw).
    • microshift_clean: Removes the MicroShift image, virtual environment, and build artifacts.
  • blank: A target that creates a blank image file of the specified size in the format specified by BLANK_IMAGE_FORMAT.
  • blank_clean: A target that removes the blank image file.
  • nat64: A target that depends on nat64_setup, nat64_build, and nat64_convert.
    • nat64_setup: A target that clones ci-framework and sets up the molecule environment with required dependencies.
    • nat64_build: A target that builds the NAT64 appliance image using the build-nat64-appliance-image.yaml playbook and the ci-framework nat64_appliance role.
    • nat64_convert: A target that converts the image to the format specified by NAT64_IMAGE_FORMAT (in-place conversion if raw).
    • nat64_clean: A target that removes the NAT64 image and build artifacts.
  • switch-host (experimental): A standalone target that depends on switch-host_download, switch-host_customize, and switch-host_convert. Not included in all or clean targets.
    • switch-host_download: A target that downloads the base image from the specified URL.
    • switch-host_customize: A target that customizes the downloaded image by installing packages (libvirt, qemu, networking tools), copying helper scripts to /usr/local/bin/, installing the systemd service, and creating necessary directories.
    • switch-host_convert: A target that converts the image to the format specified by SWITCH_HOST_IMAGE_FORMAT (in-place conversion if raw).
    • switch-host_clean: A target that removes the switch-host image file.

MicroShift Image Variables

  • MICROSHIFT_IMAGE_NAME: The name of the MicroShift image file to be created (default: microshift.qcow2).
  • MICROSHIFT_IMAGE_FORMAT: The desired format for the MicroShift image (default: raw). Set to qcow2 to skip conversion and keep the original DIB output format.
  • MICROSHIFT_DIB_VENV: Path to the Python virtual environment for diskimage-builder (default: ~/microshift-dib-venv).
  • MICROSHIFT_DIB_WORKDIR: Working directory for DIB build artifacts and cache (default: .microshift-build).
  • MICROSHIFT_VERSION: MicroShift major.minor version for dependency resolution (default: 4.20). This determines which OpenShift mirror repository to enable and which GitHub release to auto-discover.
  • DIB_MICROSHIFT_RPM_ARCHIVE: Optional. Direct URL to the MicroShift RPM archive (tgz file) from a GitHub release. When not set, the latest release matching MICROSHIFT_VERSION is auto-discovered from the microshift-io/microshift GitHub releases. Example: https://github.com/microshift-io/microshift/releases/download/4.20.0_g153ff0ca9_4.20.0_okd_scos.16/microshift-rpms-x86_64.tgz

Examples

Cleanup

make clean

Building and uploading the controller image to glance

  1. Build the controller image (using diskimage-builder):

    make controller

    This will create a Python virtual environment, install diskimage-builder, build the image using the configuration from dib/controller-image.yaml, and convert it to raw format (default).

  2. Upload the controller image to Glance:

    openstack image create hotstack-controller \
  --disk-format raw \
  --file controller.qcow2

    Note: To build as qcow2 without conversion:

    make controller CONTROLLER_IMAGE_FORMAT=qcow2
openstack image create hotstack-controller \
  --disk-format qcow2 \
  --file controller.qcow2

Building and uploading the MicroShift image to glance

  1. Build the MicroShift image (using diskimage-builder):

    The latest RPM archive for the configured version is auto-discovered from GitHub releases:

    make microshift \
  MICROSHIFT_VERSION=4.20 \
  MICROSHIFT_IMAGE_FORMAT=raw  # Optional, defaults to raw

    To pin a specific release, set DIB_MICROSHIFT_RPM_ARCHIVE explicitly:

    make microshift \
  DIB_MICROSHIFT_RPM_ARCHIVE=https://github.com/microshift-io/microshift/releases/download/4.20.0_g153ff0ca9_4.20.0_okd_scos.16/microshift-rpms-x86_64.tgz \
  MICROSHIFT_VERSION=4.20

    This will create a Python virtual environment, install diskimage-builder, build the image using the configuration from dib/microshift-image.yaml, and convert it to raw format (default).

  2. Upload the MicroShift image to Glance:

    openstack image create hotstack-microshift \
  --disk-format raw \
  --file microshift.qcow2 \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35

  3. See dib/elements/hotstack-microshift/README.rst for detailed runtime configuration instructions, including firewall setup, LVM configuration for TopoLVM, kubeconfig setup, and service enablement.

Building and uploading the blank image to glance

  1. Create the blank image:

    make blank

  2. Upload the blank image to Glance:

    openstack image create sushy-tools-blank-image \
  --disk-format raw \
  --file blank-image.qcow2 \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35 \
  --property os_shutdown_timeout=5

Building and uploading the NAT64 appliance image to glance

  1. Build the NAT64 appliance image:

    make nat64

    This will:

    • Clone the ci-framework repository (if not already present)
    • Setup the molecule environment with required dependencies
    • Run the build-nat64-appliance-image.yaml playbook using the nat64_appliance role
    • Copy the resulting image to nat64-appliance.qcow2

  2. Upload the NAT64 appliance image to Glance:

    openstack image create nat64-appliance \
  --disk-format raw \
  --file nat64-appliance.qcow2 \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35

    Note: The NAT64 image build process requires the ci-framework and its dependencies. The build artifacts are stored in .nat64-build, the ci-framework clone is stored in .ci-framework, and a Python virtual environment is created at ~/test-python. All of these can be cleaned up with make nat64_clean.

Building and uploading the switch-host image to glance

  1. Build the switch-host image:

    make switch-host

    Or with vendor switch images pre-installed:

    make switch-host \
  FORCE10_10_IMAGE=/path/to/OS10_Virtualization_10.6.0.2.74V.zip

    This will:

    • Download CentOS 9 Stream image
    • Install libvirt, qemu-kvm, and networking tools
    • Copy helper scripts to /usr/local/bin/
    • Install systemd service for managing nested switch VMs
    • Create directories for each switch model under /opt/
    • Copy any provided vendor switch images to their respective directories

  2. Upload the switch-host image to Glance:

    openstack image create hotstack-switch-host \
  --disk-format raw \
  --file switch-host.qcow2 \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35

    See switch-host-scripts/README.md for details on switch image requirements and configuration.