System Requirements

To run MicroShift, you need a machine with at least:

  • a supported 64-bit2 CPU architecture (amd64, arm64, or riscv64)
  • a supported OS (see below)
  • 2 CPU cores
  • 2GB of RAM
  • 1GB of free storage space for MicroShift

2) 32-bit is technically possible, if you're up for the challenge.

Deploying MicroShift on Edge Devices

For production deployments, we recommend (and only test) deploying MicroShift on RHEL 8, CentOS Stream 8, or Fedora 34+ using one of two methods:

  • running containerized with Podman
  • installing via .rpm (e.g. for embedding MicroShift into an rpm-ostree image)

Both methods feature a minimal resource footprint, a strong security posture, the ability to restart/update without disrupting workloads, and optionally auto-updates.

Install CRI-O

MicroShift requires CRI-O to be installed and running on the host:

command -v subscription-manager &> /dev/null \
    && subscription-manager repos --enable rhocp-4.8-for-rhel-8-x86_64-rpms
sudo dnf install -y cri-o cri-tools
sudo systemctl enable crio --now

sudo dnf module enable -y cri-o:1.21
sudo dnf install -y cri-o cri-tools
sudo systemctl enable crio --now

curl -L -o /etc/yum.repos.d/devel:kubic:libcontainers:stable.repo https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/CentOS_8_Stream/devel:kubic:libcontainers:stable.repo
curl -L -o /etc/yum.repos.d/devel:kubic:libcontainers:stable:cri-o:1.21.repo https://download.opensuse.org/repositories/devel:kubic:libcontainers:stable:cri-o:1.21/CentOS_8_Stream/devel:kubic:libcontainers:stable:cri-o:1.21.repo
sudo dnf install -y cri-o cri-tools
sudo systemctl enable crio --now

Deploying MicroShift

To have systemd start and manage MicroShift on Podman, run:

sudo dnf install -y podman
sudo curl -o /etc/systemd/system/microshift.service \
     https://raw.githubusercontent.com/redhat-et/microshift/main/packaging/systemd/microshift-containerized.service
sudo systemctl enable microshift --now

To have systemd start and manage MicroShift on an rpm-based host, run:

sudo dnf copr enable -y @redhat-et/microshift
sudo dnf install -y microshift firewalld
sudo systemctl enable microshift --now

Install Clients

To access the cluster, install the OpenShift client or kubectl.

curl -o oc.tar.gz https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz
sudo tar -C /usr/local/bin -xzvf oc.tar.gz
sudo install -t /usr/local/bin {kubectl,oc}

Copy Kubeconfig

Copy the kubeconfig to the default location that can be accessed without administrator privilege.

mkdir ~/.kube
sudo cp /var/lib/microshift/resources/kubeadmin/kubeconfig ~/.kube/config
sudo chown `whoami`: ~/.kube/config

It is now possible to run kubectl or oc commands against the MicroShift environment. Verify that MicroShift is running:

oc get pods -A

Using MicroShift for Application Development

For trying out MicroShift or using it as development tool, we provide a MicroShift image that bundles host dependencies like CRI-O and useful tools like the oc client, so it can run on most modern Linux distros, on MacOS, and on Windows with podman or docker installed. This bundled image is referred to as aio or all-in-one since it provides everything necessary to run MicroShift. The all-in-one image is meant for ephemeral test environments only. There is no way to update the image without disruption of workloads and loss of data. For production workloads, it is recommended to run with MicroShift Containerized.

Install podman if necessary, then run MicroShift using:

command -v setsebool >/dev/null 2>&1 || sudo setsebool -P container_manage_cgroup true
sudo podman run -d --rm --name microshift --privileged -v microshift-data:/var/lib -p 6443:6443 quay.io/microshift/microshift-aio:latest

You can then access your cluster either via the bundled oc (resp. kubectl) command

sudo podman exec -ti microshift oc get all -A

or via an oc (resp. kubectl) client installed on the host:

sudo podman cp microshift:/var/lib/microshift/resources/kubeadmin/kubeconfig ./kubeconfig
oc get all -A --kubeconfig ./kubeconfig

Install docker if necessary, then run MicroShift using:

docker run -d --rm --name microshift --privileged -v microshift-data:/var/lib -p 6443:6443 quay.io/microshift/microshift-aio:latest

You can then access your cluster either via the bundled oc (resp. kubectl) command

docker exec -ti microshift oc get all -A

or via an oc (resp. kubectl) client installed on the host:

docker cp microshift:/var/lib/microshift/resources/kubeadmin/kubeconfig ./kubeconfig
oc get all -A --kubeconfig ./kubeconfig

Install docker if necessary, then run MicroShift using:

docker.exe run -d --rm --name microshift --privileged -v microshift-data:/var/lib -p 6443:6443 quay.io/microshift/microshift-aio:latest

You can then access your cluster either via the bundled oc (resp. kubectl) command

docker.exe exec -ti microshift oc get all -A

or via an oc (resp. kubectl) client installed on the host:

docker.exe cp microshift:/var/lib/microshift/resources/kubeadmin/kubeconfig .\kubeconfig
oc.exe get all -A --kubeconfig .\kubeconfig
Last modified January 18, 2022 at 5:51 AM PST : Doc typo fix on MacOS Getting Started (#115) (05020dc)