WIP - Add MicroShift support

Introduces disk image building elements, Ansible roles, Heat
templates, and bootstrap/setup playbooks for deploying MicroShift
as an alternative to OCP.

Assisted-By: Claude (claude-4.5-sonnet)
Signed-off-by: Harald Jensås <hjensas@redhat.com>

Author: hjensas

.gitignore

@@ -6,3 +6,6 @@ cloud-secret.*.yaml.bak
 dataplane_ssh_keys_vars.yaml
 *-outputs.yaml
 hotstack_overrides.yaml
+images/*.qcow2
+images/.*-build/
+images/*.d/

03-install_ocp.yml

@@ -36,6 +36,7 @@
     - role: ocp_agent_installer
       delegate_to: controller-0
       vars:
+        ocp_installer_type: "{{ stack_outputs.ocp_installer_type | default('agent') }}"
         install_config: "{{ stack_outputs.ocp_install_config }}"
         agent_config: "{{  stack_outputs.ocp_agent_config }}"
         pull_secret: "{{ slurp_pull_secret.content }}"

03-setup_microshift.yml

@@ -0,0 +1,43 @@
+---
+# Copyright Red Hat, Inc.
+# All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+- name: Setup MicroShift
+  hosts: localhost
+  gather_facts: true
+  strategy: linear
+  pre_tasks:
+    - name: Load stack output vars from file
+      ansible.builtin.include_vars:
+        file: "{{ hotstack_work_dir | default(playbook_dir) }}/{{ stack_name }}-outputs.yaml"
+        name: stack_outputs
+
+    - name: Add controller-0 to the Ansible inventory
+      ansible.builtin.add_host: "{{ stack_outputs.controller_ansible_host }}"
+
+    - name: Add microshift-0 to the Ansible inventory
+      when: stack_outputs.microshift_ansible_host is defined
+      ansible.builtin.add_host: "{{ stack_outputs.microshift_ansible_host }}"
+
+    - name: Slurp the pull-secret file
+      register: slurp_pull_secret
+      ansible.builtin.slurp:
+        src: "{{ pull_secret_file }}"
+
+  roles:
+    - role: microshift_setup
+      delegate_to: controller-0
+      vars:
+        pull_secret: "{{ slurp_pull_secret.content }}"

bootstrap.yml

@@ -23,6 +23,9 @@
 - name: Install Openshift Container Platform
   ansible.builtin.import_playbook: 03-install_ocp.yml
 
+- name: Setup MicroShift
+  ansible.builtin.import_playbook: 03-setup_microshift.yml
+
 - name: Deploy RedFish Virtual BMC
   ansible.builtin.import_playbook: 04-redfish_virtual_bmc.yml
 

images/.gitignore

@@ -2,6 +2,12 @@ CONTROLLER_IMAGE_NAME        ?= controller.qcow2
 CONTROLLER_IMAGE_FORMAT      ?= raw
 CONTROLLER_DIB_VENV          ?= $(HOME)/controller-dib-venv
 CONTROLLER_DIB_WORKDIR       ?= $(CURDIR)/.controller-build
+MICROSHIFT_IMAGE_NAME        ?= microshift.qcow2
+MICROSHIFT_IMAGE_FORMAT      ?= raw
+MICROSHIFT_DIB_VENV          ?= $(HOME)/microshift-dib-venv
+MICROSHIFT_DIB_WORKDIR       ?= $(CURDIR)/.microshift-build
+MICROSHIFT_VERSION           ?= 4.20
+MICROSHIFT_RPM_ARCHIVE       ?=
 BLANK_IMAGE_NAME             ?= blank-image.qcow2
 BLANK_IMAGE_FORMAT           ?= raw
 BLANK_IMAGE_SIZE             ?= 1M
@@ -22,9 +28,9 @@ FORCE10_9_IMAGE             ?=
 NXOS_IMAGE                  ?=
 SONIC_IMAGE                 ?=
 
-all: controller blank nat64
+all: controller microshift blank nat64
 
-clean: controller_clean blank_clean nat64_clean
+clean: controller_clean microshift_clean blank_clean nat64_clean
 
 controller: controller_dib_setup controller_dib_build controller_convert
 
@@ -70,6 +76,52 @@ controller_clean:
 		sudo rm -rf $(CONTROLLER_DIB_WORKDIR); \
 	fi
 
+microshift: microshift_dib_setup microshift_dib_build microshift_convert
+
+microshift_dib_setup:
+	@if [ ! -d "$(MICROSHIFT_DIB_VENV)" ]; then \
+		echo "Creating Python virtual environment at $(MICROSHIFT_DIB_VENV)..."; \
+		python3 -m venv $(MICROSHIFT_DIB_VENV); \
+		. $(MICROSHIFT_DIB_VENV)/bin/activate && \
+		pip install --upgrade pip setuptools wheel && \
+		pip install diskimage-builder; \
+	else \
+		echo "Virtual environment already exists at $(MICROSHIFT_DIB_VENV)"; \
+	fi
+
+microshift_dib_build: microshift_dib_setup
+	@echo "Building MicroShift image using diskimage-builder..."
+	@mkdir -p $(MICROSHIFT_DIB_WORKDIR)/cache
+	@. $(MICROSHIFT_DIB_VENV)/bin/activate && \
+		cd $(CURDIR) && \
+		ELEMENTS_PATH=$(CURDIR)/dib/elements \
+		DIB_IMAGE_CACHE=$(MICROSHIFT_DIB_WORKDIR)/cache \
+		DIB_DEBUG_TRACE=1 \
+		DIB_MICROSHIFT_VERSION=$(MICROSHIFT_VERSION) \
+		DIB_MICROSHIFT_RPM_ARCHIVE=$(MICROSHIFT_RPM_ARCHIVE) \
+		diskimage-builder dib/microshift-image.yaml
+	@echo "MicroShift image built successfully: $(MICROSHIFT_IMAGE_NAME)"
+
+microshift_convert:
+ifeq ($(MICROSHIFT_IMAGE_FORMAT),raw)
+	@echo "Converting MicroShift image to raw format (in-place)..."
+	qemu-img convert -p -f qcow2 -O raw $(MICROSHIFT_IMAGE_NAME) $(MICROSHIFT_IMAGE_NAME).tmp
+	mv $(MICROSHIFT_IMAGE_NAME).tmp $(MICROSHIFT_IMAGE_NAME)
+	@echo "MicroShift image converted to raw format: $(MICROSHIFT_IMAGE_NAME)"
+endif
+
+microshift_clean:
+	rm -f $(MICROSHIFT_IMAGE_NAME)
+	rm -f $(MICROSHIFT_IMAGE_NAME).tmp
+	rm -rf $(MICROSHIFT_DIB_VENV)
+	@if [ -z "$(MICROSHIFT_DIB_WORKDIR)" ] || [ "$(MICROSHIFT_DIB_WORKDIR)" = "/" ]; then \
+		echo "ERROR: MICROSHIFT_DIB_WORKDIR is not set or is dangerous: $(MICROSHIFT_DIB_WORKDIR)"; \
+		exit 1; \
+	fi
+	@if [ -d "$(MICROSHIFT_DIB_WORKDIR)" ]; then \
+		sudo rm -rf $(MICROSHIFT_DIB_WORKDIR); \
+	fi
+
 blank:
 	qemu-img create -f $(BLANK_IMAGE_FORMAT) $(BLANK_IMAGE_NAME) $(BLANK_IMAGE_SIZE)
 

images/Makefile

@@ -13,6 +13,11 @@ deployments. The tasks are executed using the `make` utility.
 - **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
@@ -108,6 +113,18 @@ directly use qcow2 images for VM disks.
     `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.
@@ -134,6 +151,26 @@ directly use qcow2 images for VM disks.
     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
@@ -171,6 +208,45 @@ make clean
      --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:
+
+   ```shell
+   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:
+
+   ```shell
+   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:
+
+   ```shell
+   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:

images/README.md

@@ -0,0 +1,86 @@
+===================
+hotstack-microshift
+===================
+
+DIB element for building CentOS 9 Stream images with MicroShift packages.
+
+This element installs MicroShift and supporting packages. Runtime configuration
+(firewall, MicroShift service, kubeconfig, LVM) is deferred to cloud-init or
+manual setup.
+
+**Packages installed (via install.d):**
+
+- microshift - Core MicroShift service
+- microshift-networking - OVN-Kubernetes networking
+- microshift-topolvm - TopoLVM storage provisioner
+- microshift-olm - Operator Lifecycle Manager
+- greenboot (pinned to 0.15.*) - Health check framework
+
+**Packages installed (via package-installs.yaml):**
+
+- iscsi-initiator-utils - iSCSI initiator for Cinder iSCSI backend
+- device-mapper-multipath - Multipath I/O for Cinder iSCSI backend
+- lvm2 - LVM tools for TopoLVM volume management
+- jq - JSON parsing for GitHub API
+- bash-completion - Shell completion for kubectl
+- createrepo_c - Local RPM repository creation (pre-install.d phase)
+
+**Pre-configured Services (via post-install.d):**
+
+- iscsid.service - iSCSI initiator daemon (enabled)
+- multipathd.service - Multipath daemon (enabled)
+
+**Static Configuration Files (via install-static):**
+
+- ``/etc/iscsi/iscsid.conf`` - iSCSI initiator configuration
+- ``/etc/multipath.conf`` - Multipath I/O configuration
+- ``/etc/sysctl.d/90-microshift-inotify.conf`` - Increased inotify limits
+
+**Repositories:**
+
+The OpenShift mirror dependency repository (``microshift-deps-*.repo``) is
+retained in the image after build, allowing runtime package updates from
+``mirror.openshift.com``. The temporary local RPM repository used during
+build is cleaned up in ``post-install.d``.
+
+**Environment Variables:**
+
+- ``DIB_MICROSHIFT_VERSION`` (default: ``4.20``)
+  MicroShift major.minor version. Used for OpenShift mirror dependency
+  resolution and auto-discovery of the latest GitHub release.
+- ``DIB_MICROSHIFT_RPM_ARCHIVE`` (default: auto-discovered)
+  Direct URL to a MicroShift RPM archive (``.tgz``). When not set, the latest
+  release matching ``DIB_MICROSHIFT_VERSION`` is auto-discovered from the
+  ``microshift-io/microshift`` GitHub releases.
+
+**What's NOT Configured (Deferred to Runtime):**
+
+The image is intentionally minimal and requires cloud-init or manual setup:
+
+1. Firewall configuration - No firewall rules configured
+2. MicroShift service - NOT enabled (must be enabled at runtime)
+3. Kubeconfig symlink - ``/root/.kube/config`` not created
+4. LVM setup - TopoLVM volume group not created
+
+**Example Runtime Configuration:**
+
+.. code-block:: bash
+
+   # Setup firewall
+   firewall-offline-cmd --zone=trusted --add-source=10.42.0.0/16
+   firewall-offline-cmd --zone=trusted --add-source=169.254.169.1
+   firewall-offline-cmd --zone=public --add-port=6443/tcp
+   firewall-offline-cmd --zone=public --add-port=2379/tcp
+   firewall-offline-cmd --zone=public --add-port=2380/tcp
+   systemctl enable --now firewalld
+
+   # Setup LVM for TopoLVM
+   pvcreate /dev/vdb
+   vgcreate microshift /dev/vdb
+
+   # Setup kubeconfig
+   mkdir -p /root/.kube
+   ln -sf /var/lib/microshift/resources/kubeadmin/kubeconfig /root/.kube/config
+
+   # Enable and start MicroShift
+   systemctl enable --now microshift

images/dib/elements/hotstack-microshift/README.rst

@@ -0,0 +1,2 @@
+install-static
+package-installs

images/dib/elements/hotstack-microshift/element-deps

@@ -0,0 +1,18 @@
+# Copyright Red Hat, Inc.
+# All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+export DIB_MICROSHIFT_VERSION=${DIB_MICROSHIFT_VERSION:-4.20}
+# Auto-discovered from GitHub releases if not set.
+export DIB_MICROSHIFT_RPM_ARCHIVE=${DIB_MICROSHIFT_RPM_ARCHIVE:-}