Skip to content

Commit 4913404

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #80599 from ShaunaDiaz/OSDOCS-11158
OSDOCS-11158: adds image mode to MicroShift install
2 parents 318b675 + ab61e8b commit 4913404

14 files changed

+503
-0
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,13 @@ Topics:
5555
- Name: Troubleshooting installation issues
5656
File: microshift-installing-troubleshooting
5757
---
58+
Name: Installing with RHEL image mode
59+
Dir: microshift_install_bootc
60+
Distros: microshift
61+
Topics:
62+
- Name: Installing with RHEL image mode
63+
File: microshift-install-rhel-image-mode
64+
---
5865
Name: Updating
5966
Dir: microshift_updating
6067
Distros: microshift

‎microshift_install_bootc/_attributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_attributes/

‎microshift_install_bootc/images

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images/

‎microshift_install_bootc/microshift-install-rhel-image-mode.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="microshift-install-rhel-image-mode"]
3+
= Using image mode for RHEL with {microshift-short}
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-install-rhel-image-mode
6+
7+
toc::[]
8+
9+
You can embed {microshift-short} into an operating system image using image mode for {op-system-base-full}.
10+
11+
:FeatureName: Image mode for {op-system}
12+
13+
include::snippets/technology-preview.adoc[]
14+
15+
include::modules/microshift-install-rhel-image-mode-conc.adoc[leveloffset=+1]
16+
17+
include::modules/microshift-install-rhel-image-mode-build-image.adoc[leveloffset=+1]
18+
19+
include::modules/microshift-install-rhel-image-mode-publish-image.adoc[leveloffset=+1]
20+
21+
[id="microshift-install-rhel-image-mode-configure-nw-s_{context}"]
22+
== Configuring networking and storage to run {microshift-short} in a bootc container
23+
24+
include::modules/microshift-install-rhel-image-mode-cni.adoc[leveloffset=+2]
25+
26+
include::modules/microshift-install-rhel-image-mode-csi-vg.adoc[leveloffset=+2]
27+
28+
//additional resources for storage module
29+
[id="_additional-resources_{context}"]
30+
.Additional resources
31+
* xref:../microshift_storage/microshift-storage-plugin-overview.adoc#microshift-storage-plugin-overview[Dynamic storage using the LVMS plugin]
32+
33+
include::modules/microshift-install-rhel-image-mode-csi-vgloop.adoc[leveloffset=+2]
34+
35+
include::modules/microshift-install-rhel-image-mode-run-container.adoc[leveloffset=+1]
36+
37+
include::modules/microshift-install-rhel-image-mode-csi-vgcleanup.adoc[leveloffset=+1]
38+
39+
[id="_additional-resources_microshift-install-rhel-image-mode_{context}"]
40+
== Additional resources
41+
* link:https://developers.redhat.com/products/rhel-image-mode/getting-started[Image mode for Red Hat Enterprise Linux learning exercises]
42+
43+
* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/index[Using image mode for RHEL to build, deploy, and manage operating systems]

‎microshift_install_bootc/modules

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules/

‎microshift_install_bootc/snippets

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../snippets/

‎modules/microshift-install-rhel-image-mode-build-image.adoc

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_install_bootc/microshift-install-rhel-image-mode.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-rhel-image-mode-build-image_{context}"]
7+
= Building the bootc image
8+
9+
Build your {op-system-base-full} that contains {microshift-short} as a bootable container image by using a Containerfile.
10+
11+
[IMPORTANT]
12+
====
13+
Image mode for {op-system} is Technology Preview. Using a bootc image in production environments is not supported.
14+
====
15+
16+
.Prerequisites
17+
* A {op-system-base-full} 9.4 host with an active Red Hat subscription for building {microshift-short} bootc images and running containers.
18+
* You are logged into the {op-system} 9.4 host using the user credentials that have `sudo` permissions.
19+
* The `rhocp` and `fast-datapath` repositories are accessible in the host subscription. The repositories do not necessarily need to be enabled on the host.
20+
* You have a remote registry such as link:https://quay.io[Red Hat quay] for storing and accessing bootc images.
21+
22+
.Procedure
23+
24+
. Create a Containerfile that includes the following instructions:
25+
+
26+
.Example Containerfile for {op-system} image mode
27+
[source,text]
28+
----
29+
FROM registry.redhat.io/rhel9/rhel-bootc:9.4
30+
31+
ARG USHIFT_VER=4.16
32+
RUN dnf config-manager \
33+
--set-enabled rhocp-${USHIFT_VER}-for-rhel-9-$(uname -m)-rpms \
34+
--set-enabled fast-datapath-for-rhel-9-$(uname -m)-rpms
35+
RUN dnf install -y firewalld microshift && \
36+
systemctl enable microshift && \
37+
dnf clean all
38+
39+
# Create a default 'redhat' user with the specified password.
40+
# Add it to the 'wheel' group to allow for running sudo commands.
41+
ARG USER_PASSWD
42+
RUN if [ -z "${USER_PASSWD}" ] ; then \
43+
echo USER_PASSWD is a mandatory build argument && exit 1 ; \
44+
fi
45+
RUN useradd -m -d /var/home/redhat -G wheel redhat && \
46+
echo "redhat:${USER_PASSWD}" | chpasswd
47+
48+
# Mandatory firewall configuration
49+
RUN firewall-offline-cmd --zone=public --add-port=22/tcp && \
50+
firewall-offline-cmd --zone=trusted --add-source=10.42.0.0/16 && \
51+
firewall-offline-cmd --zone=trusted --add-source=169.254.169.1
52+
53+
# Create a systemd unit to recursively make the root filesystem subtree
54+
# shared as required by OVN images
55+
RUN cat > /etc/systemd/system/microshift-make-rshared.service <<'EOF'
56+
[Unit]
57+
Description=Make root filesystem shared
58+
Before=microshift.service
59+
ConditionVirtualization=container
60+
[Service]
61+
Type=oneshot
62+
ExecStart=/usr/bin/mount --make-rshared /
63+
[Install]
64+
WantedBy=multi-user.target
65+
EOF
66+
RUN systemctl enable microshift-make-rshared.service
67+
----
68+
+
69+
[IMPORTANT]
70+
====
71+
Podman uses the host subscription information and repositories inside the container when building the container image. If the `rhocp` and `fast-datapath` repositories are not available on the host, the build fails.
72+
====
73+
74+
. Create a local bootc image by running the following image build command:
75+
+
76+
[source,terminal]
77+
----
78+
PULL_SECRET=~/.pull-secret.json
79+
USER_PASSWD=<your_redhat_user_password> # <1>
80+
IMAGE_NAME=microshift-4.16-bootc
81+
82+
$ sudo podman build --authfile "${PULL_SECRET}" -t "${IMAGE_NAME}" \
83+
--build-arg USER_PASSWD="${USER_PASSWD}" \
84+
-f Containerfile
85+
----
86+
<1> Replace _<your_redhat_user_password>_ with your password.
87+
+
88+
[NOTE]
89+
====
90+
How secrets are used during the image build:
91+
92+
* The podman `--authfile` argument is required to pull the base `rhel-bootc:9.4` image from the `registry.redhat.io` registry.
93+
* The build `USER_PASSWD` argument is used to set a password for the `redhat` user.
94+
====
95+
96+
.Verification
97+
98+
. Verify that the local {microshift} bootc image was created by running the following command:
99+
+
100+
[source,terminal]
101+
----
102+
$ sudo podman images "${IMAGE_NAME}"
103+
----
104+
+
105+
.Example output
106+
[source,text]
107+
----
108+
REPOSITORY TAG IMAGE ID CREATED SIZE
109+
localhost/microshift-4.16-bootc latest 193425283c00 2 minutes ago 2.31 GB
110+
----

‎modules/microshift-install-rhel-image-mode-cni.adoc

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_install_bootc/microshift-install-rhel-image-mode.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-rhel-image-mode-run-image-cni_{context}"]
7+
= Configuring the {microshift-short} bootc image for the CNI
8+
9+
Configure a workaround for a kernel mismatch to enable the {microshift-short} OVN-Kubernetes (OVN-K) Container Network Interface (CNI).
10+
11+
[IMPORTANT]
12+
====
13+
The {microshift-short} OVN-K CNI requires the `openvswitch` kernel module to be available in the bootc image. A bootc image is started as a container that uses the host kernel. The host kernel might be different from the one used for building the image, resulting in a mismatch. A kernel version mismatch with the modules present in the `/lib/modules` directory means that the `openvswitch` module cannot be loaded in the container and the container fails to run. You can work around this problem by pre-loading the `openvswitch` module on the host.
14+
====
15+
16+
.Prerequisites
17+
18+
* A {op-system-base-full} 9.4 host with an active Red Hat subscription for building {microshift-short} bootc images and running containers.
19+
* You are logged into the {op-system} 9.4 host using the user credentials that have `sudo` permissions.
20+
21+
.Procedure
22+
23+
. Check if the `openvswitch` module is available for the current host kernel version by running the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ find /lib/modules/$(uname -r) -name "openvswitch*"
28+
----
29+
+
30+
.Example output
31+
[source,terminal]
32+
----
33+
/lib/modules/5.14.0-427.28.1.el9_4.x86_64/kernel/net/openvswitch
34+
/lib/modules/5.14.0-427.28.1.el9_4.x86_64/kernel/net/openvswitch/openvswitch.ko.xz
35+
----
36+
37+
. Set the `IMAGE_NAME` environment variable by running the following command:
38+
+
39+
[source,termimal]
40+
----
41+
$ IMAGE_NAME=microshift-4.16-bootc
42+
----
43+
44+
. Check the version of the kernel-core `package` used in the bootc image by running the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ sudo podman inspect "${IMAGE_NAME}" | grep kernel-core
49+
----
50+
+
51+
.Example output
52+
[source,terminal]
53+
----
54+
"created_by": "kernel-core-5.14.0-427.26.1.el9_4.x86_64" # <1>
55+
----
56+
<1> The kernel version does not match the output of the `/lib/modules` directory.
57+
+
58+
. Preinstall the `openvswitch` module on the host as a workaround by running the following command:
59+
+
60+
[source,terminal]
61+
----
62+
$ sudo modprobe openvswitch
63+
----

‎modules/microshift-install-rhel-image-mode-conc.adoc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_install_bootc/microshift-install-rhel-image-mode.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="microshift-rhel-image-mode-conc_{context}"]
7+
= Image mode for {op-system-base-full}
8+
9+
Image mode for {op-system-base-full} is a Technology Preview deployment method that uses a container-native approach to build, deploy, and manage the operating system as a bootc image. By using bootc, you can build, deploy, and manage the operating system as if it is any other container.
10+
11+
* This container image uses standard OCI or Docker containers as a transport and delivery format for base operating system updates.
12+
* A bootc image includes a Linux kernel that is used to start the operating system.
13+
* By using bootc containers, developers, operations administrators, and solution providers can all use the same container-native tools and techniques.
14+
15+
Image mode splits the creation and installation of software changes into two steps: one on a build system and one on a running target system.
16+
17+
* In the build-system step, a Podman build inspects the RPM files available for installation, determines any dependencies, and creates an ordered list of chained steps to complete, with the end result being a new operating system available to install.
18+
19+
* In the running-target-system step, a bootc update downloads, unpacks, and makes the new operating system bootable alongside the currently running system. Local configuration changes are carried forward to the new operating system, but do not take effect until the system is rebooted and the new operating system image replaces the running image.
20+
21+
[id="microshift-install-rhel-image-mode-conc_{context}"]
22+
== Using image mode for {op-system} with {microshift-short}
23+
24+
To use image mode for {op-system}, ensure that the following resources are available:
25+
26+
* A {op-system} 9.4 host with an active Red Hat subscription for building {microshift-short} bootc images.
27+
* A remote registry for storing and accessing bootc images.
28+
* You can use image mode for RHEL with a {microshift-short} cluster on AArch64 or x86_64 system architectures.
29+
30+
The workflow for using image mode with {microshift-short} includes the following steps:
31+
32+
. Build the {microshift-short} bootc image.
33+
. Publish the image.
34+
. Run the image. This step includes configuring {microshift-short} networking and storage.
35+
36+
[IMPORTANT]
37+
====
38+
The `rpm-ostree` file system is not supported in image mode and must not be used to make changes to deployments that use image mode.
39+
====

‎modules/microshift-install-rhel-image-mode-csi-vg.adoc

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Module included in the following assemblies:
2+
//
3+
// microshift_install_bootc/microshift-install-rhel-image-mode.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-rhel-image-mode-csi-vg_{context}"]
7+
= Checking the host configuration for the {microshift-short} CSI
8+
9+
If the host is already configured to have a volume group with free space, this configuration is inherited by the container. It can be used by the {microshift-short} Logical Volume Manager (LVM) Container Storage Interface (CSI) to allocate storage.
10+
11+
.Prerequisites
12+
13+
* A {op-system-base-full} 9.4 host with an active Red Hat subscription for building {microshift-short} bootc images and running containers.
14+
* You are logged into the {op-system} 9.4 host using the user credentials that have `sudo` permissions.
15+
16+
.Procedure
17+
18+
. Determine if the volume group exists and it has the necessary free space by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ sudo vgs
23+
----
24+
+
25+
.Example output for existing volume group
26+
[source,terminal]
27+
----
28+
VG #PV #LV #SN Attr VSize VFree # <1>
29+
rhel 1 1 0 wz--n- <91.02g <2.02g
30+
----
31+
<1> If no free volume group is present, the output is either empty or the `VFree` value is 0.
32+
+
33+
[NOTE]
34+
====
35+
If the host has a volume group with the available needed storage, you can run your container now. You do not need to configure the {microshift-short} CSI further.
36+
====
37+
+
38+
[IMPORTANT]
39+
====
40+
If you do not have a volume group, you must set one up for the LVM CSI to allocate storage in bootc {microshift-short} containers. See the additional resources for more information.
41+
====

0 commit comments

Comments
 (0)