Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 2. Embedding MicroShift in a RHEL for Edge image

You can embed MicroShift into a Red Hat Enterprise Linux (RHEL) for Edge 9.2 image. Use this guide to build a RHEL image containing MicroShift.

Important

MicroShift is Technology Preview only. This Technology Preview software is not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using MicroShift in production. Technology Preview provides early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

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

For more information about the support scope of Red Hat Technology Preview features, read Technology Preview Features Support Scope.

2.1. Preparing for image building
Link kopieren

Read Composing, installing, and managing RHEL for Edge images.

Important

MicroShift 4.13 deployments have only been tested with Red Hat Enterprise Linux (RHEL) for Edge 9.2. Other versions of RHEL are not supported.

To build an Red Hat Enterprise Linux (RHEL) for Edge 9.2 image for a given CPU architecture, you need a RHEL 9.2 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 MicroShift repositories to Image Builder
Link kopieren

Use the following procedure to add the 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. Create an Image Builder configuration file for adding the rhocp-4.13 RPM repository source required to pull MicroShift RPMs by running the following command: 

    $ cat > rhocp-4.13.toml <<EOF
id = "rhocp-4.13"
name = "Red Hat OpenShift Container Platform 4.13 for RHEL 9"
type = "yum-baseurl"
url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/rhocp/4.13/os"
check_gpg = true
check_ssl = true
system = false
rhsm = true
EOF
    Copy to Clipboard Toggle word wrap

  2. Create an Image Builder configuration file for adding the fast-datapath RPM repository by running the following command: 

    $ cat > fast-datapath.toml <<EOF
id = "fast-datapath"
name = "Fast Datapath for RHEL 9"
type = "yum-baseurl"
url = "https://cdn.redhat.com/content/dist/layered/rhel9/$(uname -m)/fast-datapath/os"
check_gpg = true
check_ssl = true
system = false
rhsm = true
EOF
    Copy to Clipboard Toggle word wrap

  3. Add the sources to the Image Builder by running the following commands: 

    $ sudo composer-cli sources add rhocp-4.13.toml
    Copy to Clipboard Toggle word wrap 
    $ sudo composer-cli sources add fast-datapath.toml
    Copy to Clipboard Toggle word wrap

Verification

  • Confirm that the sources were added properly by running the following command: 

    $ sudo composer-cli sources list
    Copy to Clipboard Toggle word wrap

    Example output

    appstream
baseos
fast-datapath
rhocp-4.13
    Copy to Clipboard Toggle word wrap

2.3. Adding the MicroShift service to a blueprint
Link kopieren

Adding the MicroShift RPM package to an Image Builder blueprint enables the build of a RHEL for Edge image with MicroShift embedded.

Procedure

  1. Use the following example to create your blueprint:

    Image Builder blueprint example

    $ cat > minimal-microshift.toml <<EOF
name = "minimal-microshift"

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

[[packages]]
name = "microshift"
version = "*"

[[packages]]
name = "microshift-greenboot"
    1 
    
version = "*"

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

    1
    Optional microshift-greenboot RPM. For more information, read the "Greenboot health check" guide in the "Running Applications" section.
    Note

    The wildcard * in the commands uses the latest MicroShift RPMs. If you need a specific version, substitute the wildcard for the version you want. For example, insert 4.13.1 to download the MicroShift 4.13.1 RPMs.

  2. Add the blueprint to the Image Builder by running the following command: 

    $ sudo composer-cli blueprints push minimal-microshift.toml
    Copy to Clipboard Toggle word wrap

Verification

  1. Verify the Image Builder configuration listing only MicroShift packages by running the following command: 

    $ sudo composer-cli blueprints depsolve minimal-microshift | grep microshift
    Copy to Clipboard Toggle word wrap

    Example output

    blueprint: minimal-microshift v0.0.1
    microshift-greenboot-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch
    microshift-networking-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.x86_64
    microshift-release-info-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch
    microshift-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.x86_64
    microshift-selinux-4.13.1-202305250827.p0.g4105d3b.assembly.4.13.1.el9.noarch
    Copy to Clipboard Toggle word wrap

  2. Optional: Verify the Image Builder configuration listing all components to be installed by running the following command: 

    $ sudo composer-cli blueprints depsolve minimal-microshift
    Copy to Clipboard Toggle word wrap

2.4. Creating the Red Hat Enterprise Linux (RHEL) for Edge image
Link kopieren

Use the following procedure to create the ISO. The RHEL for Edge Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded OSTree commit.

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.
  • You have the podman tool.

Procedure

  1. Start an ostree container image build by running the following command: 

    $ BUILDID=$(sudo composer-cli compose start-ostree --ref "rhel/9/$(uname -m)/edge" minimal-microshift edge-container | awk '{print $2}')
    Copy to Clipboard Toggle word wrap

    This command also returns the identification (ID) of the build for monitoring.

  2. You can check the status of the build periodically by running the following command: 

    $ sudo composer-cli compose status
    Copy to Clipboard Toggle word wrap

    Example output of a running build

    ID                                     Status     Time                      Blueprint            Version   Type               Size
cc3377ec-4643-4483-b0e7-6b0ad0ae6332   RUNNING    Wed Jun 7 12:26:23 2023   minimal-microshift   0.0.1     edge-container
    Copy to Clipboard Toggle word wrap

    Example output of a completed build

    ID                                     Status     Time                      Blueprint            Version   Type               Size
cc3377ec-4643-4483-b0e7-6b0ad0ae6332   FINISHED   Wed Jun 7 12:32:37 2023   minimal-microshift   0.0.1     edge-container
    Copy to Clipboard Toggle word wrap

    Note

    You can use the watch command to monitor your build if you are familiar with how to start and stop it.

  3. Download the container image using the ID and get the image ready for use by running the following command: 

    $ sudo composer-cli compose image ${BUILDID}
    Copy to Clipboard Toggle word wrap

  4. Change the ownership of the downloaded container image to the current user by running the following command: 

    $ sudo chown $(whoami). ${BUILDID}-container.tar
    Copy to Clipboard Toggle word wrap

  5. Add read permissions for the current user to the image by running the following command: 

    $ sudo chmod a+r ${BUILDID}-container.tar
    Copy to Clipboard Toggle word wrap

  6. Bootstrap a server on port 8085 for the ostree container image to be consumed by the ISO build by completing the following steps:

    1. Get the IMAGEID variable result by running the following command: 

      $ IMAGEID=$(cat < "./${BUILDID}-container.tar" | sudo podman load | grep -o -P '(?<=sha256[@:])[a-z0-9]*')
      Copy to Clipboard Toggle word wrap

    2. Use the IMAGEID variable result to execute the podman command step by running the following command: 

      $ sudo podman run -d --name=minimal-microshift-server -p 8085:8080 ${IMAGEID}
      Copy to Clipboard Toggle word wrap

      This command also returns the ID of the container saved in the IMAGEID variable for monitoring.

  7. Generate the installer blueprint file by running the following command: 

    $ cat > microshift-installer.toml <<EOF
name = "microshift-installer"

description = ""
version = "0.0.0"
modules = []
groups = []
packages = []
EOF
    Copy to Clipboard Toggle word wrap

2.5. Add the blueprint to Image Builder and build the ISO
Link kopieren

  1. Add the blueprint to the Image Builder by running the following command: 

    $ sudo composer-cli blueprints push microshift-installer.toml
    Copy to Clipboard Toggle word wrap

  2. Start the ostree ISO build by running the following command: 

    $ BUILDID=$(sudo composer-cli compose start-ostree --url http://localhost:8085/repo/ --ref "rhel/9/$(uname -m)/edge" microshift-installer edge-installer | awk '{print $2}')
    Copy to Clipboard Toggle word wrap

    This command also returns the identification (ID) of the build for monitoring.

  3. You can check the status of the build periodically by running the following command: 

    $ sudo composer-cli compose status
    Copy to Clipboard Toggle word wrap

    Example output for a running build

    ID                                     Status     Time                      Blueprint              Version   Type               Size
c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   RUNNING    Wed Jun 7 13:22:20 2023   microshift-installer   0.0.0     edge-installer
    Copy to Clipboard Toggle word wrap

    Example output for a completed build

    ID                                     Status     Time                      Blueprint              Version   Type               Size
c793c24f-ca2c-4c79-b5b7-ba36f5078e8d   FINISHED   Wed Jun 7 13:34:49 2023   microshift-installer   0.0.0     edge-installer
    Copy to Clipboard Toggle word wrap

2.6. Download the ISO and prepare it for use
Link kopieren

  1. Download the ISO using the ID by running the following command: 

    $ sudo composer-cli compose image ${BUILDID}
    Copy to Clipboard Toggle word wrap

  2. Change the ownership of the downloaded container image to the current user by running the following command: 

    $ sudo chown $(whoami). ${BUILDID}-installer.iso
    Copy to Clipboard Toggle word wrap

  3. Add read permissions for the current user to the image by running the following command: 

    $ sudo chmod a+r ${BUILDID}-installer.iso
    Copy to Clipboard Toggle word wrap

2.7. Provisioning a machine for MicroShift
Link kopieren

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

To use 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 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 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 provisioning requirements.

Prerequisites

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

    1. This requirement includes the steps of composing an RFE Container image, creating the RFE Installer blueprint, starting the RFE container, and composing the RFE Installer image.

  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, read "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
#
ostreesetup --nogpg --osname=rhel --remote=edge \
--url=file:///run/install/repo/ostree/repo --ref=rhel/<RHEL VERSION NUMBER>/x86_64/edge
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
# To add users, use a line such as the following
user --name=<YOUR_USER_NAME> \
--password=<YOUR_HASHED_PASSWORD> \
--iscrypted --groups=<YOUR_USER_GROUPS>
    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

2.8. How to access the MicroShift cluster
Link kopieren

Use the procedures in this section to access the MicroShift cluster, either from the same machine running the 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. As listed in each procedure, you use the OpenShift Container Platform CLI tool (oc) for cluster activities.

2.8.1. Accessing the MicroShift cluster locally
Link kopieren

Use the following procedure to access the 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

Verification

  • Verify that MicroShift is running by entering the following command: 

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

2.8.2. Opening the firewall for remote access to the MicroShift cluster
Link kopieren

Use the following procedure to open the firewall so that a remote user can access the MicroShift cluster. This procedure must be completed before a workstation user can access the cluster remotely.

For this procedure, user@microshift is the user on the 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.
  • Your account has cluster administration privileges.

Procedure

  • As user@microshift on the 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

Verification

  • As user@microshift, verify that MicroShift is running by entering the following command: 

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

2.8.3. Accessing the MicroShift cluster remotely
Link kopieren

Use the following procedure to access the 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 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 MicroShift host by running the following command: 

    [user@workstation]$ MICROSHIFT_MACHINE=<name or IP address 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 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

Verification

  • As user@workstation, verify that MicroShift is running by entering the following command: 

    [user@workstation]$ oc get all -A
    Copy to Clipboard Toggle word wrap
Nach oben
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2025 Red Hat