Skip to content

USHIFT-6151: Refactor MicroShift build and run procedure #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 22, 2025
Merged

USHIFT-6151: Refactor MicroShift build and run procedure #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
51020a5
Update top-level readme file
ggiguash Sep 20, 2025
d4ec03c
Update build RPM and image instructions
ggiguash Sep 20, 2025
823a476
Update instructions for running MicroShift
ggiguash Sep 20, 2025
996423a
Add make rules for build and run
ggiguash Sep 21, 2025
69c73fd
Allow for RPM_OUTDIR override in make rpm command
ggiguash Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
#
# The following variables can be overriden from the command line
# using NAME=value make arguments
#
USHIFT_BRANCH ?= main
OKD_VERSION_TAG ?=
RPM_OUTDIR ?=
WITH_KINDNET ?= 1
WITH_TOPOLVM ?= 1
WITH_OLM ?= 0
EMBED_CONTAINER_IMAGES ?= 0

#
# Define the main targets
#
.PHONY: all
all:
@echo "make <rpm | image | run | login | stop | clean>"
@echo " rpm: build the MicroShift RPMs"
@echo " image: build the MicroShift bootc container image"
@echo " run: run the MicroShift bootc container"
@echo " login: login to the MicroShift bootc container"
@echo " stop: stop the MicroShift bootc container"
@echo " clean: clean up the MicroShift container"
@echo ""

.PHONY: rpm
rpm:
ifndef OKD_VERSION_TAG
$(error Run 'make rpm USHIFT_BRANCH=value OKD_VERSION_TAG=value')
endif
@echo "Building the MicroShift RPMs"
sudo podman build --target builder \
--build-arg USHIFT_BRANCH="${USHIFT_BRANCH}" \
--build-arg OKD_VERSION_TAG="${OKD_VERSION_TAG}" \
--env WITH_KINDNET="${WITH_KINDNET}" \
--env WITH_TOPOLVM="${WITH_TOPOLVM}" \
--env WITH_OLM="${WITH_OLM}" \
-t microshift-okd -f packaging/microshift-cos9.Containerfile . && \
outdir="$${RPM_OUTDIR:-$$(mktemp -d /tmp/microshift-rpms-XXXXXX)}" && \
mntdir="$$(sudo podman image mount microshift-okd)" && \
sudo cp -r "$${mntdir}/microshift/_output/rpmbuild/RPMS/." "$${outdir}" && \
sudo podman image umount microshift-okd && \
echo "" && \
echo "Build completed successfully" && \
echo "RPMs are available in '$${outdir}'"

.PHONY: image
image:
ifndef OKD_VERSION_TAG
$(error Run 'make image USHIFT_BRANCH=value OKD_VERSION_TAG=value')
endif
@echo "Building the MicroShift bootc container image"
sudo podman build \
--build-arg USHIFT_BRANCH="${USHIFT_BRANCH}" \
--build-arg OKD_VERSION_TAG="${OKD_VERSION_TAG}" \
--env WITH_KINDNET="${WITH_KINDNET}" \
--env WITH_TOPOLVM="${WITH_TOPOLVM}" \
--env WITH_OLM="${WITH_OLM}" \
--env EMBED_CONTAINER_IMAGES="${EMBED_CONTAINER_IMAGES}" \
-t microshift-okd -f packaging/microshift-cos9.Containerfile .

# Prerequisites for running the MicroShift container:
# - If the OVN-K CNI driver is used (`WITH_KINDNET=0` non-default build option),
# the `openvswitch` module must be loaded on the host.
# - If the TopoLVM CSI driver is used (`WITH_TOPOLVM=1` default build option),
# the /dev/dm-* device must be shared with the container.
.PHONY: run
run:
@echo "Running the MicroShift container"
sudo modprobe openvswitch
sudo podman run --privileged --rm -d \
--name microshift-okd \
--volume /dev:/dev:rslave \
microshift-okd

.PHONY: login
login:
@echo "Logging into the MicroShift container"
sudo podman exec -it microshift-okd bash

.PHONY: stop
stop:
@echo "Stopping the MicroShift container"
sudo podman stop --time 0 microshift-okd || true

.PHONY: clean
clean:
@echo "Cleaning up the MicroShift container"
sudo podman rmi -f microshift-okd || true
sudo rmmod openvswitch || true
134 changes: 15 additions & 119 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,125 +1,21 @@
# MicroShift upstream Build and Run Scripts
This repository provides scripts to build and run [MicroShift](https://github.com/openshift/microshift/) upstream.
# MicroShift Upstream

## Overview

MicroShift is a project that optimizes OpenShift Kubernetes for small form factor and edge computing.
It is intended for upstream development and testing by building MicroShift directly from the original OpenShift MicroShift sources, while replacing the default payload images with OKD (the community distribution of Kubernetes that powers OpenShift).

The goal is to enable contributors and testers to work with a fully open-source MicroShift setup using OKD components, making it easier to develop, verify, and iterate on features outside the downstream Red Hat payloads.

## MicroShift Upstream Build Process

The RPM/container build process includes the following steps:

1. Replace the MicroShift payload/images with the OKD [released images](https://github.com/okd-project/okd-scos/releases).
2. Build the MicroShift RPMs and repository from the MicroShift source.
3. Build the `microshift-okd` Bootc container based on `centos-bootc:stream9`.
4. Apply upstream customizations (see below).

## Build and Run Microshift upstream without subscription/pull-secret
- Use a specific microshift branch (default main)
```
sudo podman build --build-arg USHIFT_BRANCH=release-4.19 -f microshift-okd-multi-build.Containerfile . -t microshift-okd
```
- Only build the RPMs
```bash
sudo podman build --target builder --env WITH_KINDNET=1 --env WITH_TOPOLVM=1 -f microshift-okd-multi-build.Containerfile . -t microshift-okd
```
- Build the RPMs & container locally using podman
This repository provides scripts to build and run [MicroShift](https://github.com/openshift/microshift/)
upstream (i.e. without Red Hat subscriptions or a pull secrets).

- use `ovn-kubernetes` as CNI (default)
```bash
sudo podman build -f microshift-okd-multi-build.Containerfile . -t microshift-okd
```
- To use kindnet as CNI
```bash
sudo podman build --env WITH_KINDNET=1 -f microshift-upstream/microshift-okd-multi-build.Containerfile . -t microshift-okd-4.19
```
- To install OLM as part of image
```bash
sudo podman build --env WITH_OLM=1 -f microshift-upstream/microshift-okd-multi-build.Containerfile . -t microshift-okd-4.19
```
- To embed all component images
```bash
sudo podman build --env EMBED_CONTAINER_IMAGES=1 -f microshift-upstream/microshift-okd-multi-build.Containerfile . -t microshift-okd
```
- To use kindnet CNI with [TopoLVM](https://github.com/topolvm/topolvm) upstream as CSI
```bash
sudo podman build --env WITH_KINDNET=1 --env WITH_TOPOLVM=1 -f okd/src/microshift-okd-multi-build.Containerfile . -t microshift-okd
```

- running the container with ovn-kubernetes
- make sure to load the openvswitch kernel module :
> `sudo modprobe openvswitch`

- run the container :
> `sudo podman run --privileged --rm --name microshift-okd -d microshift-okd`

- running the container with TopoLVM upstream

1. Prepare the LVM backend on the host (example only)
```bash
sudo truncate --size=20G /tmp/lvmdisk
sudo losetup -f /tmp/lvmdisk
device_name=$(losetup -j /tmp/lvmdisk | cut -d: -f1)
sudo vgcreate -f -y myvg1 ${device_name}
sudo lvcreate -T myvg1/thinpool -L 6G
```

1. Run microshift in container and wait for it to be ready
```bash
sudo podman run --privileged --rm --name microshift-okd \
--volume /dev:/dev:rslave \
-d localhost/microshift-okd
```
Note: We need to mount the entire /dev directory here, as LVM management requires full visibility of new volumes under /dev/dm-*.
1. Wait for all the components to come up
```bash
> sudo podman exec microshift-okd bash -c "microshift healthcheck --namespace topolvm-system --deployments topolvm-controller "
??? I0331 14:38:46.838208 5894 service.go:29] microshift.service is enabled
??? I0331 14:38:46.838235 5894 service.go:31] Waiting 5m0s for microshift.service to be ready
??? I0331 14:38:46.839291 5894 service.go:38] microshift.service is ready
??? I0331 14:38:46.840014 5894 workloads.go:94] Waiting 5m0s for deployment/topolvm-controller in topolvm-system
??? I0331 14:38:46.844984 5894 workloads.go:132] Deployment/topolvm-controller in topolvm-system is ready
??? I0331 14:38:46.845003 5894 healthcheck.go:75] Workloads are ready
## Overview

> oc get pods -A
NAMESPACE NAME READY STATUS RESTARTS AGE
cert-manager cert-manager-5f864bbfd-bpd6h 1/1 Running 0 4m49s
cert-manager cert-manager-cainjector-589dc747b5-cfwjf 1/1 Running 0 4m49s
cert-manager cert-manager-webhook-5987c7ff58-mzq6l 1/1 Running 0 4m49s
kube-kindnet kube-kindnet-ds-6nvq6 1/1 Running 0 4m12s
kube-proxy kube-proxy-zlvb2 1/1 Running 0 4m12s
kube-system csi-snapshot-controller-75d84cb97c-nkfsz 1/1 Running 0 4m50s
openshift-dns dns-default-dbjh4 2/2 Running 0 4m1s
openshift-dns node-resolver-mt8m7 1/1 Running 0 4m12s
openshift-ingress router-default-59cbb858cc-6mzbx 1/1 Running 0 4m49s
openshift-service-ca service-ca-df6759f9d-24d2n 1/1 Running 0 4m49s
topolvm-system topolvm-controller-9cd8649c9-5tcln 5/5 Running 0 4m49s
topolvm-system topolvm-lvmd-0-2bmjq 1/1 Running 0 4m1s
topolvm-system topolvm-node-lwxz5 3/3 Running 1 (3m36s ago) 4m1s
```
- connect to the container
> `sudo podman exec -ti microshift-okd /bin/bash`
MicroShift is a project that optimizes OpenShift Kubernetes for small form factor
and edge computing. MicroShift Upstream is intended for upstream development and
testing by allowing to build MicroShift directly from the original OpenShift MicroShift
sources, while replacing the default payload images with OKD (the community distribution
of Kubernetes that powers OpenShift).

- verify everything is working:
```bash
export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig
> oc get nodes
NAME STATUS ROLES AGE VERSION
d2877aa41787 Ready control-plane,master,worker 7m39s v1.30.3

> oc get pods
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system csi-snapshot-controller-7d6c78bc58-5p7tb 1/1 Running 0 8m52s
openshift-dns dns-default-2q89q 2/2 Running 0 7m34s
openshift-dns node-resolver-k2c5h 1/1 Running 0 8m54s
openshift-ingress router-default-db4b598b9-x8lvb 1/1 Running 0 8m52s
openshift-ovn-kubernetes ovnkube-master-c75c7 4/4 Running 1 (7m36s ago) 8m54s
openshift-ovn-kubernetes ovnkube-node-jfx86 1/1 Running 0 8m54s
openshift-service-ca service-ca-68d58669f8-rns2p 1/1 Running 0 8m51s
The goal is to enable contributors and testers to work with an upstream build of MicroShift
set up using OKD components, making it easier to develop, verify, and iterate on features
outside the downstream Red Hat payloads.

## Build and Run

```
* [Build MicroShift Upstream](./docs/build.md)
* [Run MicroShift Upstream](./docs/run.md)
70 changes: 70 additions & 0 deletions docs/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
## Build MicroShift Upstream

### Overview
The build process is containerized and it includes the following steps:

1. Replace the MicroShift payload/images with the OKD [released images](https://github.com/okd-project/okd-scos/releases).
1. Build the MicroShift RPMs and repository from the MicroShift sources.
1. Build the `microshift-okd` Bootc container based on CentOS Stream.

### Build Options

Building MicroShift artifacts is performed by running `make rpm` or `make image`
commands.

The following options can be specified in the make command line using the
`NAME=VAL` format.

|Name |Required|Default |Comments
|----------------------|--------|--------|--------
|USHIFT_BRANCH |no |main |[List of branches](https://github.com/openshift/microshift/branches)
|OKD_VERSION_TAG |yes | |[List of tags](https://quay.io/repository/okd/scos-release?tab=tags)
|RPM_OUTDIR |no |/tmp/...|RPM repository output directory for `make rpm`
|WITH_KINDNET |no |1 |OVK-K CNI is used when Kindnet is disabled
|WITH_TOPOLVM |no |1 |Enable [TopoLVM](https://github.com/topolvm/topolvm) CSI
|WITH_OLM |no |0 |Enable OLM support
|EMBED_CONTAINER_IMAGES|no |0 |Embed all component container dependencies in Bootc images

### Build MicroShift RPMs

Run the `make rpm` command to build MicroShift RPMs based on CentOS Stream 9
operating system.

```
USHIFT_BRANCH=release-4.19
OKD_VERSION_TAG=4.19.0-okd-scos.19

make rpm \
USHIFT_BRANCH="${USHIFT_BRANCH}" \
OKD_VERSION_TAG="${OKD_VERSION_TAG}"
```

If the build completes successfully, the MicroShift RPM repository is copied to
the `RPM_OUTDIR` directory on the host. The packages from this repository can be
used to install MicroShift on the supported operating systems.

Note: The path to the `RPM_OUTDIR` directory (either temporary or specified in
the `make rpm` command line) is displayed in the end of the build procedure.

```
...
...
Build completed successfully
RPMs are available in '/tmp/microshift-rpms-EI3IXg'
```

### Build MicroShift Bootc Image

Run the `make image` command to build a MicroShift Bootc image based on CentOS
Stream 9 operating system with the default options.

```bash
USHIFT_BRANCH=release-4.19
OKD_VERSION_TAG=4.19.0-okd-scos.19

make image \
USHIFT_BRANCH="${USHIFT_BRANCH}" \
OKD_VERSION_TAG="${OKD_VERSION_TAG}"
```

If the build completes successfully, the `microshift-okd` image is created.
Loading