Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Installing Red Hat build of MicroShift from an RPM package

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