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.