Ansible MicroShift

August 24, 2026 · View on GitHub

The purpose of this Ansible automation is to help gain insight into the footprint and start times of MicroShift. At present, we are capturing the first start, the second start (with cached images), disk usage data from a number of points in time as well as performance data for each of the two starts.

Prerequisites

We are using Prometheus and process-exporter to capture a wide array of performance tool data.

It is necessary to have two hosts configured for running the benchmarks:

Ansible control node used to start the automation scripts
MicroShift server used to execute the performance tests

GPU Support Requirements

For GPU-enabled workloads, the MicroShift server must have:

NVIDIA GPU hardware
RHEL 9.x operating system
Sufficient disk space for NVIDIA drivers and CUDA toolkit (~2GB)

The GPU support roles will automatically:

Install NVIDIA drivers (defaults to version 575-open)
Install NVIDIA Container Toolkit for container GPU access
Deploy the NVIDIA device plugin for Kubernetes
Configure SELinux policies for GPU container access
Optionally deploy a test workload to validate GPU functionality

Run the following command on the Ansible control node to install the Ansible package.

sudo dnf install -y ansible

setup-node.yml always captures the install, boot, and footprint data described below. Kube-burner performance workloads are optional and run only when run_workloads: true is set in vars/all.yml or when -e run_workloads_arg=true is passed on the command line.

Running

Follow the instructions below depending on whether the MicroShift server is set up as a clean, development or RHEL for Edge host.

Clean Host

If the user has a fresh RHEL host to be used for running MicroShift performance benchmarks, it is necessary to first follow the instructions in Clean Host Example Variables for editing the vars/all.yml file.

Run the playbook using the following commands, making sure that the values of the MicroShift server host and user variables are appropriate for your environment.

USHIFT_HOST=microshift-clean
USHIFT_USER=microshift

ssh-copy-id ${USHIFT_USER}@${USHIFT_HOST}
time ansible-playbook -v \
    -e ansible_host_var=${USHIFT_HOST} -e ansible_user_var=${USHIFT_USER} \
    -i inventory/inventory setup-node.yml

Development Host

If the user has an existing host used as the MicroShift development environment, the default settings in the vars/all.yml file can be used.

Review the instructions in Development Host Example Variables for more information on the configuration settings.

Run the playbook using the following commands, making sure that the values of the MicroShift server host and user variables are appropriate for your environment.

USHIFT_HOST=microshift-dev
USHIFT_USER=microshift

ssh-copy-id ${USHIFT_USER}@${USHIFT_HOST}
time ansible-playbook -v \
    -e ansible_host_var=${USHIFT_HOST} -e ansible_user_var=${USHIFT_USER} \
    -e install_microshift_arg=true \
    -i inventory/inventory setup-node.yml

RHEL for Edge Host

If the user has deployed a RHEL for Edge image built with MicroShift, the default settings in the vars/all.yml file can be used. The image must be built with the -prometheus option to enable benchmark information collection as described in the Building Installer section.

Review the instructions in RHEL for Edge Host Example Variables for more information on the configuration settings.

Run the playbook using the following commands, making sure that the values of the MicroShift server host and user variables are appropriate for your environment.

USHIFT_HOST=microshift-edge
USHIFT_USER=redhat

ssh-copy-id ${USHIFT_USER}@${USHIFT_HOST}
time ansible-playbook -v \
    -e ansible_host_var=${USHIFT_HOST} -e ansible_user_var=${USHIFT_USER} \
    -e prometheus_logging_arg=false \
    -i inventory/inventory setup-node.yml

GPU-Enabled Host

For hosts with NVIDIA GPUs, you can enable GPU support and optionally deploy a test workload to validate GPU functionality.

Setup with GPU Support

Run the playbook with GPU support enabled:

USHIFT_HOST=microshift-gpu
USHIFT_USER=microshift

ssh-copy-id ${USHIFT_USER}@${USHIFT_HOST}
time ansible-playbook -v \
    -e ansible_host_var=${USHIFT_HOST} -e ansible_user_var=${USHIFT_USER} \
    -e enable_gpu_arg=true \
    -i inventory/inventory setup-node.yml

GPU Support Without Test Workload

To install GPU support without running the test workload:

time ansible-playbook -v \
    -e ansible_host_var=${USHIFT_HOST} -e ansible_user_var=${USHIFT_USER} \
    -e enable_gpu_arg=true \
    -e deploy_gpu_test_arg=false \
    -i inventory/inventory setup-node.yml

Output

The playbook stores results on the Ansible control node under results/<microshift_version>/<timestamp>/.

The following text files are created for each run:

boot0.txt — cold start time (first boot, images pulled from registry)
boot1.txt — warm start time (second boot, images cached locally)
disk0.txt — disk usage baseline after cleanup, before install
disk1.txt — disk usage post-install, post-reboot, before MicroShift starts
disk2.txt — disk usage with MicroShift fully running
images.txt — container image sizes (compressed and uncompressed)
network.txt — network transfer (RX/TX) via Prometheus when prometheus_logging is enabled

When Prometheus is enabled, it runs on the logging host in a Podman container managed by Quadlet. Captured metrics can be queried through the Prometheus web UI at http://<logging-host-ip>:9091.

Configuration Overview

There are a few configuration files that can be configured before execution of the playbook.

Certain Ansible playbook variables can be overridden using --extra-vars or -e.

Variables

Most of the following variables are defined in vars/all.yml. The source-build variables and rhel_target_version are provided by role defaults and can be set in vars/all.yml or passed directly with -e.

Variable Name	Description	Default
`create_devenv`	Create development VM environment	`false`
`manage_subscription`	Use subscription-manager to entitle host and attach to pool	`false`
`rhel_username`	Red Hat subscription account username (string)	`null`
`rhel_password`	Red Hat subscription account password (string)	`null`
`rhel_pool_id`	Red Hat subscription pool id (string)	`null`
`manage_repos`	Enable necessary repos to install MicroShift and dependencies	`false`
`setup_microshift_host`	Complete initial setup of MicroShift host (packages, firewall, etc)	`false`
`prometheus_logging`	Set up logging and exporters on the nodes	`true`
`install_microshift`	Install MicroShift (from packages or source)	`false`
`build_microshift`	Build MicroShift from source instead of installing packages	`false`
`microshift_source_dir`	Existing MicroShift Git worktree on the managed host to build instead of updating the default checkout	`""`
`microshift_git_revision`	Git revision to check out when building MicroShift from source	`"release-<major.minor>"`
`microshift_git_refspec`	Additional Git refspec to fetch when building MicroShift from source (e.g. `+refs/pull/123/head:refs/remotes/origin/pr-123`)	`""`
`build_etcd_binary`	Build and deploy a separate etcd process	`false`
`microshift_version`	MicroShift version to install (supports EC/RC prereleases)	`"4.20"`
`enable_gpu`	Install NVIDIA GPU drivers and container toolkit for GPU workloads	`false`
`deploy_gpu_test`	Deploy a test GPU workload to validate GPU functionality	`true`
`run_workloads`	Run kube-burner performance workloads	`false`
`rhel_target_version`	Pin RHEL to a specific version during upgrades (e.g., "9.8")	`undefined`

Source builds update the existing checkout in microshift_dir to microshift_git_revision. By default, the revision is the release branch derived from microshift_version; for example, both 4.21.0 and latest-4.21 select release-4.21. Set it explicitly to build another branch, tag, or commit. A commit SHA may require microshift_git_refspec when the commit is not reachable from a branch or tag fetched by default. Checking out a SHA leaves the repository in detached HEAD state until a later branch-based run updates it.

Set microshift_source_dir to build a complete Git worktree that is already present on the managed host. The caller is responsible for staging and updating the worktree, including its .git metadata. When set, the Git checkout task is skipped and the Git revision and refspec variables are ignored.

When repository management is enabled, source builds provision runtime dependencies from the stream's OpenShift repository when it is available. If that repository is unavailable, or microshift_version identifies a prerelease, dependencies are provided by the dependencies/rpms/<major.minor>-el9-beta mirror instead. Package-based repository selection is unchanged. Repository probes verify that cri-o is present; installation of the built RPMs enforces version compatibility. If the OpenShift repository becomes usable on a later run, the corresponding fallback mirror is removed.

Inventory Configuration

The inventory configuration file is located at inventory/inventory.

The MicroShift host name or IP address must be configured to match the current environment. If the user account available on the MicroShift server is not microshift, it should be changed as well.

The following Ansible command line options can be used instead of editing the inventory/inventory file.

-e ansible_host_var=<hostname>

-e ansible_user_var=<username>

Sample Inventory File

[microshift]
microshift-dev ansible_host=microshift-dev

[microshift:vars]
ansible_user=microshift

[logging]
localhost ansible_connection=local

Global Variables Configuration

The global variables file is located at vars/all.yml.

The following Ansible command line options can be used instead of editing the vars/all.yml file.

-e install_microshift_arg=<true | false>

-e prometheus_logging_arg=<true | false>

-e enable_gpu_arg=<true | false>

-e deploy_gpu_test_arg=<true | false>

-e run_workloads_arg=<true | false>

-e rhel_target_version=<version>

Clean Host Example Variables

If the user has a fresh RHEL host to be used for running MicroShift performance benchmarks, the scripts can manage the initial host setup and configuration in addition to the performance capture.

As we can read from the following configuration, we have selected to manage_subscription and this requires the subsequent rhel_* vars to be set. The other initial configuration steps are toggled with the setup_microshift_host variable, which we have set to true for this configuration.

On a clean system, the playbook will also copy the user-provided pull-secret from roles/install-microshift/files/pull-secret.txt to the correct location on the host.

Sample vars/all.yml File

manage_subscription: true
rhel_username: <subscription manager username>
rhel_password: <subscription manager password>
rhel_pool_id: <subscription manager pool-id>
manage_repos: true

setup_microshift_host: true
prometheus_logging: true
install_microshift: true
build_etcd_binary: false

Development Host Example Variables

If the user has an existing host used as the MicroShift development environment, the scripts can be run without the initial configuration steps.

Such host can be created using the instructions from the MicroShift Development Environment document.

The manage_subscription, manage_repos and setup_microshift_host variables have been set to false.

Sample vars/all.yml File

manage_subscription: false
rhel_username:
rhel_password:
rhel_pool_id:
manage_repos: false

setup_microshift_host: false
prometheus_logging: true
install_microshift: true
build_etcd_binary: false

RHEL for Edge Host Example Variables

If the user has deployed a RHEL for Edge image built with MicroShift, the scripts can be run with a few more variables disabled as the host is fully configured out of the box.

Such host can be created using the instructions from the Install MicroShift on RHEL for Edge document.

The manage_subscription, manage_repos, setup_microshift_host, prometheus_logging and install_microshift variables have been set to false.

Sample vars/all.yml File

manage_subscription: false
rhel_username:
rhel_password:
rhel_pool_id:
manage_repos: false

setup_microshift_host: false
prometheus_logging: false
install_microshift: false
build_etcd_binary: false

GPU-Enabled Host Example Variables

For hosts with NVIDIA GPUs that require GPU workload support, enable the GPU-specific variables.

The enable_gpu variable installs NVIDIA drivers, CUDA toolkit, and the container toolkit. The deploy_gpu_test variable (defaults to true when GPU is enabled) deploys a test workload to validate GPU functionality.

Sample vars/all.yml File

manage_subscription: true
rhel_username: <subscription manager username>
rhel_password: <subscription manager password>
rhel_pool_id: <subscription manager pool-id>
manage_repos: true

setup_microshift_host: true
prometheus_logging: true
install_microshift: true
build_etcd_binary: false

# NVIDIA GPU support
enable_gpu: true
deploy_gpu_test: true  # Optional, defaults to true when enable_gpu is true