MicroShift is Developer Preview software only.
For more information about the support scope of Red Hat Developer Preview software, see Developer Preview Support Scope.Installing
Installing and configuring MicroShift clusters
Abstract
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.
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.
1.1. System requirements for installing Red Hat build of MicroShift
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.
1.2. Preparing to install Red Hat build of MicroShift from an RPM package
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
- In the graphical installer under Storage Configuration, select Custom → Done to open the dialog for configuring partitions and volumes.
- Under New Red Hat Enterprise Linux 8.x Installation, select Click here to create them automatically.
- Select the root partition, /, reduce Desired Capacity so that the VG has sufficient capacity for your PVs, and then click Update Settings.
Complete your installation.
NoteFor more options on partition configuration, see the guide linked in the Additional information section for Configuring Manual Partitioning.
As a root user, verify the VG capacity available on your system by running the following command:
$ sudo vgs
Example output:
VG #PV #LV #SN Attr VSize VFree rhel 1 2 0 wz--n- <127.00g 54.94g
Additional resources
- Download the pull secret from the Red Hat Hybrid Cloud Console.
- Configuring MicroShift.
- For more options on partition configuration, refer to Configuring Manual Partitioning.
- For more information about resizing your existing LVs to free up capacity in your VGs, refer to Managing LVM Volume Groups.
- For more information about creating VGs and PVs, read Overview of logical volume management.
1.3. Installing Red Hat build of MicroShift from an RPM package
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
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
Install Red Hat build of MicroShift by running the following command:
$ sudo dnf install -y microshift
-
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. 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
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
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
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
$ sudo firewall-cmd --permanent --zone=trusted --add-source=169.254.169.1
$ sudo firewall-cmd --reload
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.
Additional resources
1.4. Starting the Red Hat build of MicroShift service
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
As a root user, start the Red Hat build of MicroShift service by entering the following command:
$ sudo systemctl start microshift
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
Optional: To disable Red Hat build of MicroShift from automatically starting when your machine starts, enter the following command:
$ sudo systemctl disable microshift
NoteThe 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.
1.5. Stopping 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
Enter the following command to stop the Red Hat build of MicroShift service:
$ sudo systemctl stop microshift
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
Enter the following commands to stop the deployed workloads:
$ sudo systemctl stop kubepods.slice
1.6. How to access the Red Hat build of MicroShift cluster
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.
Additional resources
1.6.1. Accessing the Red Hat build of MicroShift cluster locally
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
Optional: to create a
~/.kube/
folder if your RHEL machine does not have one, run the following command:$ mkdir -p ~/.kube/
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
Update the permissions on your
~/.kube/config
file by running the following command:$ chmod go-r ~/.kube/config
Verify that Red Hat build of MicroShift is running by entering the following command:
$ oc get all -A
1.6.2. Opening the firewall for remote access to the Red Hat build of MicroShift cluster
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
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
Verify Red Hat build of MicroShift is running
As
user@microshift
, verify that Red Hat build of MicroShift is running by entering the following command:[user@microshift]$ oc get all -A
1.6.3. Accessing the Red Hat build of MicroShift cluster remotely
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 thatuser@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
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/
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>
As
user@workstation
, copy the generatedkubeconfig
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
As
user@workstation
, update the permissions on your~/.kube/config
file by running the following command:$ chmod go-r ~/.kube/config
Verify Red Hat build of MicroShift is running
As
user@workstation
, verify that Red Hat build of MicroShift is running by running the following command:[user@workstation]$ oc get all -A
Chapter 2. Embedding Red Hat build of MicroShift in a RHEL for Edge image
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.
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
Familiarize yourself with the documentation about Composing, installing, and managing RHEL for Edge images.
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.
2.2. Adding Red Hat build of MicroShift repositories to Image Builder
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
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
Install the
reposync
andcreaterepo
tools by running the following command:$ sudo yum install -y yum-utils createrepo
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
Remove
coreos
packages to avoid conflicts by running the following command:$ sudo find ${REPO_PATH}/microshift-local -name \*coreos\* -exec rm -f {} \;
Create a local RPM repository by running the following command:
$ sudo createrepo ${REPO_PATH}/microshift-local
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
Add this source file to Image Builder by running the following command:
$ sudo composer-cli sources add ${REPO_PATH}/microshift-local/microshift.toml
2.2.1. Adding the Red Hat build of MicroShift service
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"]
2.3. Provisioning for Red Hat build of MicroShift
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.
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
- You have created an RHEL for Edge Installer (ISO) image containing your RHEL for Edge commit with Red Hat build of MicroShift.
Create a Kickstart file or use an existing one. In the Kickstart file, you must include:
- Detailed instructions about how to create a user.
- How to fetch and deploy the RHEL for Edge image.
For more information, see "Additional resources."
Procedure
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
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
Install the
mkksiso
tool by running the following command:$ sudo yum install -y lorax
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
2.4. How to access the Red Hat build of MicroShift cluster
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.
2.4.1. Accessing the Red Hat build of MicroShift cluster locally
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
Optional: to create a
~/.kube/
folder if your RHEL machine does not have one, run the following command:$ mkdir -p ~/.kube/
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
Update the permissions on your
~/.kube/config
file by running the following command:$ chmod go-r ~/.kube/config
Verify that Red Hat build of MicroShift is running by entering the following command:
$ oc get all -A
2.4.2. Opening the firewall for remote access to the Red Hat build of MicroShift cluster
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
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
Verify Red Hat build of MicroShift is running
As
user@microshift
, verify that Red Hat build of MicroShift is running by entering the following command:[user@microshift]$ oc get all -A
2.4.3. Accessing the Red Hat build of MicroShift cluster remotely
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 thatuser@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
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/
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>
As
user@workstation
, copy the generatedkubeconfig
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
As
user@workstation
, update the permissions on your~/.kube/config
file by running the following command:$ chmod go-r ~/.kube/config
Verify Red Hat build of MicroShift is running
As
user@workstation
, verify that Red Hat build of MicroShift is running by running the following command:[user@workstation]$ oc get all -A