Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Installing

Red Hat build of MicroShift 4.12

Installing and configuring MicroShift clusters

Red Hat OpenShift Documentation Team

Abstract

This document provides information about installing MicroShift and details about some configuration processes.

You can install Red Hat build of MicroShift from an RPM package on a machine with Red Hat Enterprise Linux (RHEL) 8.7.

Important

Red Hat does not support an update path from Developer Preview and Technology Preview versions to later versions of Red Hat build of MicroShift. A new installation is necessary.

The following conditions must be met prior to installing Red Hat build of MicroShift:

  • RHEL 8.7
  • 2 CPU cores
  • 2 GB of RAM
  • 10 GB of storage
  • You have an active Red Hat build of MicroShift subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information.
  • You have a subscription that includes Red Hat build of MicroShift RPMs.
  • You have a Logical Volume Manager (LVM) Volume Group (VG) with sufficient capacity for the Persistent Volumes (PVs) of your workload.

Before installing Red Hat build of MicroShift from an RPM package, you must configure your RHEL machine to have a logical volume manager (LVM) volume group (VG) with sufficient capacity for the persistent volumes (PVs) of your workload.

Red Hat build of MicroShift uses the logical volume manager storage (LVMS) Container Storage Interface (CSI) provider for storing PVs. LVMS relies on Linux’s LVM to dynamically manage the backing storage for PVs. For this reason, your machine must have an LVM VG with unused space in which LVMS can create the LVM logical volumes (LVs) for your workload’s PVs.

To configure a volume group (VG) that allows LVMS to create the LVs for your workload’s PVs, adjust your root volume’s size during the installation of RHEL. Adjusting your root volume’s size provides free space for additional LVs created by LVMS at runtime.

The default name of the VG is rhel. You can change the VG name during your RHEL configuration and use it during your Red Hat build of MicroShift installation.

Prerequisites

  • The system requirements for installing Red Hat build of MicroShift have been met.
  • You have root user access to your machine.

Procedure

  1. In the graphical installer under Storage Configuration, select Custom → Done to open the dialog for configuring partitions and volumes.
  2. Under New Red Hat Enterprise Linux 8.x Installation, select Click here to create them automatically.
  3. Select the root partition, /, reduce Desired Capacity so that the VG has sufficient capacity for your PVs, and then click Update Settings.

  4. Complete your installation.

    Note

    For more options on partition configuration, see the guide linked in the Additional information section for Configuring Manual Partitioning.

  5. As a root user, verify the VG capacity available on your system by running the following command: 

    $ sudo vgs
    Copy to Clipboard Toggle word wrap

    Example output: 

    VG   #PV #LV #SN Attr   VSize    VFree
rhel   1   2   0 wz--n- <127.00g 54.94g
    Copy to Clipboard Toggle word wrap

Use the following procedure to install Red Hat build of MicroShift from an RPM package.

Prerequisites

  • The system requirements for installing Red Hat build of MicroShift have been met.
  • You have completed the steps of preparing to install Red Hat build of MicroShift from an RPM package.

Procedure

  1. As a root user, enable the Red Hat build of MicroShift repositories by running the following command: 

    $ sudo subscription-manager repos \
    --enable rhocp-4.12-for-rhel-8-$(uname -i)-rpms \
    --enable fast-datapath-for-rhel-8-$(uname -i)-rpms
    Copy to Clipboard Toggle word wrap

  2. Install Red Hat build of MicroShift by running the following command: 

    $ sudo dnf install -y microshift
    Copy to Clipboard Toggle word wrap
  3. Download your installation pull secret from the Red Hat Hybrid Cloud Console to a temporary folder, for example, $HOME/openshift-pull-secret. This pull secret allows you to authenticate with the container registries that serve the container images used by Red Hat build of MicroShift.

  4. To copy the pull secret to the /etc/crio folder of your RHEL machine, run the following command: 

    $ sudo cp $HOME/openshift-pull-secret /etc/crio/openshift-pull-secret
    Copy to Clipboard Toggle word wrap

  5. Make the root user the owner of the /etc/crio/openshift-pull-secret file by running the following command: 

    $ sudo chown root:root /etc/crio/openshift-pull-secret
    Copy to Clipboard Toggle word wrap

  6. Make the /etc/crio/openshift-pull-secret file readable and writeable by the root user only by running the following command: 

    $ sudo chmod 600 /etc/crio/openshift-pull-secret
    Copy to Clipboard Toggle word wrap

  7. If your RHEL machine has a firewall enabled, you must configure a few mandatory firewall rules. For firewalld, run the following commands: 

    $ sudo firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16
    Copy to Clipboard Toggle word wrap 
    $ sudo firewall-cmd --permanent --zone=trusted --add-source=169.254.169.1
    Copy to Clipboard Toggle word wrap 
    $ sudo firewall-cmd --reload
    Copy to Clipboard Toggle word wrap

If the Volume Group (VG) that you have prepared for Red Hat build of MicroShift used the default name rhel, no further configuration is necessary. If you have used a different name, or if you want to change more configuration settings, see the Configuring Red Hat build of MicroShift section.

Use the following procedure to start the Red Hat build of MicroShift service.

Prerequisites

  • You have installed Red Hat build of MicroShift from an RPM package.

Procedure

  1. As a root user, start the Red Hat build of MicroShift service by entering the following command: 

    $ sudo systemctl start microshift
    Copy to Clipboard Toggle word wrap

  2. Optional: To configure your RHEL machine to start Red Hat build of MicroShift when your machine starts, enter the following command: 

    $ sudo systemctl enable microshift
    Copy to Clipboard Toggle word wrap

  3. Optional: To disable Red Hat build of MicroShift from automatically starting when your machine starts, enter the following command: 

    $ sudo systemctl disable microshift
    Copy to Clipboard Toggle word wrap
    Note

    The first time that the Red Hat build of MicroShift service starts, it downloads and initializes Red Hat build of MicroShift’s container images. As a result, it can take several minutes for Red Hat build of MicroShift to start the first time that the service is deployed. Boot time is reduced for subsequent starts of the Red Hat build of MicroShift service.

Use the following procedure to stop the Red Hat build of MicroShift service.

Prerequisites

  • The Red Hat build of MicroShift service is running.

Procedure

  1. Enter the following command to stop the Red Hat build of MicroShift service: 

    $ sudo systemctl stop microshift
    Copy to Clipboard Toggle word wrap

  2. Workloads deployed on Red Hat build of MicroShift will continue running even after the Red Hat build of MicroShift service has been stopped. Enter the following command to display running workloads: 

    $ sudo crictl ps -a
    Copy to Clipboard Toggle word wrap

  3. Enter the following commands to stop the deployed workloads: 

    $ sudo systemctl stop kubepods.slice
    Copy to Clipboard Toggle word wrap

Use the procedures in this section to access the Red Hat build of MicroShift cluster, either from the same machine running the Red Hat build of MicroShift service or remotely from a workstation. You can use this access to observe and administrate workloads. When using these steps, choose the kubeconfig file that contains the host name or IP address you want to connect with and place it in the relevant directory. The OpenShift Container Platform CLI tool (oc) is employed for cluster activities.

Use the following procedure to access the Red Hat build of MicroShift cluster locally by using a kubeconfig file.

Prerequisites

  • You have installed the oc binary.

Procedure

  1. Optional: to create a ~/.kube/ folder if your RHEL machine does not have one, run the following command: 

    $ mkdir -p ~/.kube/
    Copy to Clipboard Toggle word wrap

  2. Copy the generated local access kubeconfig file to the ~/.kube/ directory by running the following command: 

    $ sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
    Copy to Clipboard Toggle word wrap

  3. Update the permissions on your ~/.kube/config file by running the following command: 

    $ chmod go-r ~/.kube/config
    Copy to Clipboard Toggle word wrap

  4. Verify that Red Hat build of MicroShift is running by entering the following command: 

    $ oc get all -A
    Copy to Clipboard Toggle word wrap

Use the following procedure to open the firewall so that a remote user can access the Red Hat build of MicroShift cluster. Your account must have cluster admin privileges. This procedure must be completed before a workstation user can access the cluster remotely.

  • user@microshift, is the user on the Red Hat build of MicroShift host machine and is responsible for setting up that machine so that it can be accessed by a remote user on a separate workstation.

Prerequisites

  • You have installed the oc binary.

Procedure

  1. As user@microshift on the Red Hat build of MicroShift host, open the firewall port for the Kubernetes API server (6443/tcp) by running the following command: 

    [user@microshift]$ sudo firewall-cmd --permanent --zone=public --add-port=6443/tcp && sudo firewall-cmd --reload
    Copy to Clipboard Toggle word wrap

Verify Red Hat build of MicroShift is running

  1. As user@microshift, verify that Red Hat build of MicroShift is running by entering the following command: 

    [user@microshift]$ oc get all -A
    Copy to Clipboard Toggle word wrap

Use the following procedure to access the Red Hat build of MicroShift cluster from a remote workstation by using a kubeconfig file.

  • The user@workstation login is used to access the host machine remotely. The <user> value in the procedure is the name of the user that user@workstation logs in with to the Red Hat build of MicroShift host.

Prerequisites

  • You have installed the oc binary.
  • The @user@microshift has opened the firewall from the local host.

Procedure

  1. As user@workstation, create a ~/.kube/ folder if your RHEL machine does not have one by running the following command: 

    [user@workstation]$ mkdir -p ~/.kube/
    Copy to Clipboard Toggle word wrap

  2. As user@workstation, set a variable for the hostname of your Red Hat build of MicroShift host by running the following command: 

    [user@workstation]$ MICROSHIFT_MACHINE=<name or IP address of Red Hat build of MicroShift machine>
    Copy to Clipboard Toggle word wrap

  3. As user@workstation, copy the generated kubeconfig file that contains the host name or IP address you want to connect with from the RHEL machine running Red Hat build of MicroShift to your local machine by running the following command: 

    [user@workstation]$ ssh <user>@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/$MICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config
    Copy to Clipboard Toggle word wrap

  4. As user@workstation, update the permissions on your ~/.kube/config file by running the following command: 

    $ chmod go-r ~/.kube/config
    Copy to Clipboard Toggle word wrap

Verify Red Hat build of MicroShift is running

  1. As user@workstation, verify that Red Hat build of MicroShift is running by running the following command: 

    [user@workstation]$ oc get all -A
    Copy to Clipboard Toggle word wrap

You can embed Red Hat build of MicroShift into a Red Hat Enterprise Linux (RHEL) for Edge 8.7 image. Use the content within this section to build a RHEL image containing Red Hat build of MicroShift.

Important

Red Hat does not support an update path from Developer Preview and Technology Preview versions to later versions of Red Hat build of MicroShift. A new installation is necessary.

2.1. Preparing for image building
Copy link

Familiarize yourself with the documentation about Composing, installing, and managing RHEL for Edge images.

Important

Red Hat build of MicroShift deployments have only been tested with Red Hat Enterprise Linux (RHEL) for Edge 8.7. Other versions of RHEL are not recommended.

To build an Red Hat Enterprise Linux (RHEL) for Edge 8.7 image for a given CPU architecture, you need a RHEL 8.7 build host of the same CPU architecture that meets the Image Builder system requirements.

Follow the instructions in Installing Image Builder to install Image Builder and the composer-cli tool.

Use the following procedure to add the Red Hat build of MicroShift repositories to Image Builder on your build host.

Prerequisites

  • Your build host meets the Image Builder system requirements.
  • You have installed and set up Image Builder and the composer-cli tool.
  • You have root user access to your build host.

Procedure

  1. Enable the Red Hat build of MicroShift RPM repositories on the build host by running the following command: 

    $ sudo subscription-manager repos
    --enable rhocp-4.12-for-rhel-8-$(uname -i)-rpms
    --enable fast-datapath-for-rhel-8-$(uname -i)-rpms
    Copy to Clipboard Toggle word wrap

  2. Install the reposync and createrepo tools by running the following command: 

    $ sudo yum install -y yum-utils createrepo
    Copy to Clipboard Toggle word wrap

  3. Sync the Red Hat build of MicroShift RPM packages to your build host by running the following command: 

    $ sudo reposync --arch=$(uname -i) --arch=noarch --gpgcheck \
    --download-path /var/repos/microshift-local \
    --repo=rhocp-4.12-for-rhel-8-$(uname -i)-rpms \
    --repo=fast-datapath-for-rhel-8-$(uname -i)-rpms
    Copy to Clipboard Toggle word wrap

  4. Remove coreos packages to avoid conflicts by running the following command: 

    $ sudo find ${REPO_PATH}/microshift-local -name \*coreos\* -exec rm -f {} \;
    Copy to Clipboard Toggle word wrap

  5. Create a local RPM repository by running the following command: 

    $ sudo createrepo ${REPO_PATH}/microshift-local
    Copy to Clipboard Toggle word wrap

  6. Create an Image Builder source file for this repository by running the following command: 

    $ sudo tee ${REPO_PATH}/microshift-local/microshift.toml > /dev/null <<EOF
id = "microshift-local"
name = "MicroShift local repo"
type = "yum-baseurl"
url = "file:///${REPO_PATH}/microshift-local/"
check_gpg = false
check_ssl = false
system = false
EOF
    Copy to Clipboard Toggle word wrap

  7. Add this source file to Image Builder by running the following command: 

    $ sudo composer-cli sources add ${REPO_PATH}/microshift-local/microshift.toml
    Copy to Clipboard Toggle word wrap

Add the Red Hat build of MicroShift RPM package to a blueprint and enable the Red Hat build of MicroShift service to build an RHEL for Edge image with Red Hat build of MicroShift.

Image Builder blueprint example

name = "minimal-microshift"

description = ""
version = "0.0.1"
modules = []
groups = []

[[packages]]
name = "microshift"
version = "4.12.0-1"

[customizations.services]
enabled = ["microshift"]
Copy to Clipboard Toggle word wrap

2.3. Provisioning for Red Hat build of MicroShift
Copy link

Provision a machine with your RHEL for Edge image by using the procedures from the RHEL for Edge documentation.

To use Red Hat build of MicroShift, you must provision the system so that it meets the following requirements:

  • The machine you are provisioning must meet the system requirements for installing Red Hat build of MicroShift.
  • The file system must have a logical volume manager (LVM) volume group (VG) with sufficient capacity for the persistent volumes (PVs) of your workload.
  • A pull secret from the Red Hat Hybrid Cloud Console must be present as /etc/crio/openshift-pull-secret and have root user-only read/write permissions.
  • The firewall must be configured with Red Hat build of MicroShift’s required firewall settings.
Note

If you are using a Kickstart such as the RHEL for Edge Installer (iso) image, you can update your Kickstart file to meet the above requirements.

Prerequisites

  1. You have created an RHEL for Edge Installer (ISO) image containing your RHEL for Edge commit with Red Hat build of MicroShift.

  2. Create a Kickstart file or use an existing one. In the Kickstart file, you must include:

    1. Detailed instructions about how to create a user.
    2. How to fetch and deploy the RHEL for Edge image.

For more information, see "Additional resources."

Procedure

  1. In the main section of the Kickstart file, update the setup of the filesystem such that it contains an LVM volume group called rhel with at least 10GB system root. Leave free space for the LVMS CSI driver to use for storing the data for your workloads.

    Example kickstart snippet for configuring the filesystem

    # Partition disk such that it contains an LVM volume group called `rhel` with a
# 10GB+ system root but leaving free space for the LVMS CSI driver for storing data.
#
# For example, a 20GB disk would be partitioned in the following way:
#
# NAME          MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
# sda             8:0    0  20G  0 disk
# ├─sda1          8:1    0 200M  0 part /boot/efi
# ├─sda1          8:1    0 800M  0 part /boot
# └─sda2          8:2    0  19G  0 part
#  └─rhel-root  253:0    0  10G  0 lvm  /sysroot
#
zerombr
clearpart --all --initlabel
part /boot/efi --fstype=efi --size=200
part /boot --fstype=xfs --asprimary --size=800
# Uncomment this line to add a SWAP partition of the recommended size
#part swap --fstype=swap --recommended
part pv.01 --grow
volgroup rhel pv.01
logvol / --vgname=rhel --fstype=xfs --size=10000 --name=root
    Copy to Clipboard Toggle word wrap

  2. In the %post section of the Kickstart file, add your pull secret and the mandatory firewall rules.

    Example Kickstart snippet for adding the pull secret and firewall rules

    %post --log=/var/log/anaconda/post-install.log --erroronfail

# Add the pull secret to CRI-O and set root user-only read/write permissions
cat > /etc/crio/openshift-pull-secret << EOF
YOUR_OPENSHIFT_PULL_SECRET_HERE
EOF
chmod 600 /etc/crio/openshift-pull-secret

# Configure the firewall with the mandatory rules for MicroShift
firewall-offline-cmd --zone=trusted --add-source=10.42.0.0/16
firewall-offline-cmd --zone=trusted --add-source=169.254.169.1

%end
    Copy to Clipboard Toggle word wrap

  3. Install the mkksiso tool by running the following command: 

    $ sudo yum install -y lorax
    Copy to Clipboard Toggle word wrap

  4. Update the Kickstart file in the ISO with your new Kickstart file by running the following command: 

    $ sudo mkksiso <your_kickstart>.ks <your_installer>.iso <updated_installer>.iso
    Copy to Clipboard Toggle word wrap

Use the procedures in this section to access the Red Hat build of MicroShift cluster, either from the same machine running the Red Hat build of MicroShift service or remotely from a workstation. You can use this access to observe and administrate workloads. When using these steps, choose the kubeconfig file that contains the host name or IP address you want to connect with and place it in the relevant directory. The OpenShift Container Platform CLI tool (oc) is employed for cluster activities.

Use the following procedure to access the Red Hat build of MicroShift cluster locally by using a kubeconfig file.

Prerequisites

  • You have installed the oc binary.

Procedure

  1. Optional: to create a ~/.kube/ folder if your RHEL machine does not have one, run the following command: 

    $ mkdir -p ~/.kube/
    Copy to Clipboard Toggle word wrap

  2. Copy the generated local access kubeconfig file to the ~/.kube/ directory by running the following command: 

    $ sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
    Copy to Clipboard Toggle word wrap

  3. Update the permissions on your ~/.kube/config file by running the following command: 

    $ chmod go-r ~/.kube/config
    Copy to Clipboard Toggle word wrap

  4. Verify that Red Hat build of MicroShift is running by entering the following command: 

    $ oc get all -A
    Copy to Clipboard Toggle word wrap

Use the following procedure to open the firewall so that a remote user can access the Red Hat build of MicroShift cluster. Your account must have cluster admin privileges. This procedure must be completed before a workstation user can access the cluster remotely.

  • user@microshift, is the user on the Red Hat build of MicroShift host machine and is responsible for setting up that machine so that it can be accessed by a remote user on a separate workstation.

Prerequisites

  • You have installed the oc binary.

Procedure

  1. As user@microshift on the Red Hat build of MicroShift host, open the firewall port for the Kubernetes API server (6443/tcp) by running the following command: 

    [user@microshift]$ sudo firewall-cmd --permanent --zone=public --add-port=6443/tcp && sudo firewall-cmd --reload
    Copy to Clipboard Toggle word wrap

Verify Red Hat build of MicroShift is running

  1. As user@microshift, verify that Red Hat build of MicroShift is running by entering the following command: 

    [user@microshift]$ oc get all -A
    Copy to Clipboard Toggle word wrap

Use the following procedure to access the Red Hat build of MicroShift cluster from a remote workstation by using a kubeconfig file.

  • The user@workstation login is used to access the host machine remotely. The <user> value in the procedure is the name of the user that user@workstation logs in with to the Red Hat build of MicroShift host.

Prerequisites

  • You have installed the oc binary.
  • The @user@microshift has opened the firewall from the local host.

Procedure

  1. As user@workstation, create a ~/.kube/ folder if your RHEL machine does not have one by running the following command: 

    [user@workstation]$ mkdir -p ~/.kube/
    Copy to Clipboard Toggle word wrap

  2. As user@workstation, set a variable for the hostname of your Red Hat build of MicroShift host by running the following command: 

    [user@workstation]$ MICROSHIFT_MACHINE=<name or IP address of Red Hat build of MicroShift machine>
    Copy to Clipboard Toggle word wrap

  3. As user@workstation, copy the generated kubeconfig file that contains the host name or IP address you want to connect with from the RHEL machine running Red Hat build of MicroShift to your local machine by running the following command: 

    [user@workstation]$ ssh <user>@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/$MICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config
    Copy to Clipboard Toggle word wrap

  4. As user@workstation, update the permissions on your ~/.kube/config file by running the following command: 

    $ chmod go-r ~/.kube/config
    Copy to Clipboard Toggle word wrap

Verify Red Hat build of MicroShift is running

  1. As user@workstation, verify that Red Hat build of MicroShift is running by running the following command: 

    [user@workstation]$ oc get all -A
    Copy to Clipboard Toggle word wrap

Legal Notice
Copy link

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat