This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting Started

MicroShift system requirements and deployment

System Requirements

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

  • a supported 64-bit2 CPU architecture (amd64/x86_64, 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

sudo 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
sudo 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

The following steps will deploy MicroShift and enable firewalld. It is always best practice to have firewalls enabled and only to allow the minimum set of ports necessary for MicroShift to operate. Iptables can be used in place of firewalld if desired.

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 firewall-cmd --zone=trusted --add-source=10.42.0.0/16 --permanent
sudo firewall-cmd --zone=public --add-port=80/tcp --permanent
sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
sudo firewall-cmd --zone=public --add-port=5353/udp --permanent
sudo firewall-cmd --reload
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
sudo firewall-cmd --zone=trusted --add-source=10.42.0.0/16 --permanent
sudo firewall-cmd --zone=public --add-port=80/tcp --permanent
sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
sudo firewall-cmd --zone=public --add-port=5353/udp --permanent
sudo firewall-cmd --reload
sudo systemctl enable microshift --now

For more details on MicroShift ports and firewall settings, please see the firewall documentation.

Install Clients

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

curl -O https://mirror.openshift.com/pub/openshift-v4/$(uname -m)/clients/ocp/stable/openshift-client-linux.tar.gz
sudo tar -xf openshift-client-linux.tar.gz -C /usr/local/bin oc kubectl

Copy Kubeconfig

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

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

mkdir ~/.kube
sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.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

As a developer, you might want to stop for the day and continue your work later. Stopping and restarting the MicroShift all-in-one container will bring some know issues with the CNI. This is why we recommend developers to use the pause and unpause Podman/Docker command.

podman pause microshift
podman unpause microshift

MicroShift on OSTree based systems

As mentioned aboved, MicroShift has been designed to be deployed on edge computing devices. Looking at security standards, an edge optimized operating system will most likely be inmutable and based in transactions for upgrades and rollbacks. OSTree provides these capabilities.

Fedora IoT and RHEL for Edge are both OSTree based systems and MicroShift can be shipped as part of the base rpm-ostree. The recommended way to embed MicroShift in these operating systems is to build your own rpm-ostree with tools like Image Builder. This project will allow you to create your own customized version of Fedora IoT or RHEL for Edge in order to include MicroShift and all the required dependencies like CRI-O.

However, developers might need to manually install RPMs on the system for faster iterations. It is important to highlight that the base layer of an rpm-ostree is an atomic entity, so when installing a local package, any dependency that is part of the ostree with an older version will not be updated. This is the reason why it is mandatory to perform an upgrade before manually installing MicroShift.

Let's see an example of a Fedora IoT 35 system:

curl -L -o /etc/yum.repos.d/fedora-modular.repo https://src.fedoraproject.org/rpms/fedora-repos/raw/rawhide/f/fedora-modular.repo
curl -L -o /etc/yum.repos.d/fedora-updates-modular.repo https://src.fedoraproject.org/rpms/fedora-repos/raw/rawhide/f/fedora-updates-modular.repo
curl -L -o /etc/yum.repos.d/group_redhat-et-microshift-fedora-35.repo https://copr.fedorainfracloud.org/coprs/g/redhat-et/microshift/repo/fedora-35/group_redhat-et-microshift-fedora-35.repo
rpm-ostree ex module enable cri-o:1.21

rpm-ostree upgrade
rpm-ostree install cri-o cri-tools microshift

systemctl reboot

Now MicroShift and its dependencies will be part of the rpm-ostree and ready to function.