From 8c15db4f8c1adf987c3a3bc95aea2f268a9153fc Mon Sep 17 00:00:00 2001 From: aravipra Date: Mon, 27 Jan 2025 19:20:05 +0530 Subject: [PATCH] OSDOCS-12318-v2: adds bootc image use to MicroShift --- _topic_maps/_topic_map_ms.yml | 8 +- ... => microshift-about-rhel-image-mode.adoc} | 14 +-- .../microshift-install-bootc-image.adoc | 26 ++++++ ...oshift-install-running-bootc-image-vm.adoc | 17 ++++ ...microshift-install-bootc-build-image.adoc} | 42 ++++++--- ...doc => microshift-install-bootc-conc.adoc} | 26 +----- .../microshift-install-bootc-creating-vm.adoc | 81 ++++++++++++++++ ...ift-install-bootc-get-published-image.adoc | 41 +++++++++ ...shift-install-bootc-prepare-kickstart.adoc | 92 +++++++++++++++++++ ...croshift-install-bootc-publish-image.adoc} | 10 +- .../microshift-install-bootc-workflow.adoc | 24 +++++ 11 files changed, 330 insertions(+), 51 deletions(-) rename microshift_install_bootc/{microshift-install-rhel-image-mode.adoc => microshift-about-rhel-image-mode.adoc} (51%) create mode 100644 microshift_install_bootc/microshift-install-bootc-image.adoc create mode 100644 microshift_install_bootc/microshift-install-running-bootc-image-vm.adoc rename modules/{microshift-install-rhel-image-mode-build-image.adoc => microshift-install-bootc-build-image.adoc} (77%) rename modules/{microshift-install-rhel-image-mode-conc.adoc => microshift-install-bootc-conc.adoc} (58%) create mode 100644 modules/microshift-install-bootc-creating-vm.adoc create mode 100644 modules/microshift-install-bootc-get-published-image.adoc create mode 100644 modules/microshift-install-bootc-prepare-kickstart.adoc rename modules/{microshift-install-rhel-image-mode-publish-image.adoc => microshift-install-bootc-publish-image.adoc} (88%) create mode 100644 modules/microshift-install-bootc-workflow.adoc diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index 32fc506967..c75992c36d 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -76,8 +76,12 @@ Name: Installing with RHEL image mode Dir: microshift_install_bootc Distros: microshift Topics: -- Name: Installing with RHEL image mode - File: microshift-install-rhel-image-mode +- Name: Understanding image mode for RHEL + File: microshift-about-rhel-image-mode +- Name: Installing a bootc image + File: microshift-install-bootc-image +- Name: Running the bootc image + File: microshift-install-running-bootc-image-vm --- Name: Using RHEL Kickstarts Dir: microshift_install_kickstarts diff --git a/microshift_install_bootc/microshift-install-rhel-image-mode.adoc b/microshift_install_bootc/microshift-about-rhel-image-mode.adoc similarity index 51% rename from microshift_install_bootc/microshift-install-rhel-image-mode.adoc rename to microshift_install_bootc/microshift-about-rhel-image-mode.adoc index f7ce061517..f8349bdb09 100644 --- a/microshift_install_bootc/microshift-install-rhel-image-mode.adoc +++ b/microshift_install_bootc/microshift-about-rhel-image-mode.adoc @@ -1,8 +1,8 @@ :_mod-docs-content-type: ASSEMBLY -[id="microshift-install-rhel-image-mode"] +[id="microshift-about-rhel-image-mode"] include::_attributes/attributes-microshift.adoc[] -= Using image mode for RHEL with {microshift-short} -:context: microshift-install-rhel-image-mode += Understanding image mode for RHEL with {microshift-short} +:context: microshift-about-rhel-image-mode toc::[] @@ -12,14 +12,10 @@ You can embed {microshift-short} into an operating system image using image mode include::snippets/technology-preview.adoc[] -include::modules/microshift-install-rhel-image-mode-conc.adoc[leveloffset=+1] - -include::modules/microshift-install-rhel-image-mode-build-image.adoc[leveloffset=+1] - -include::modules/microshift-install-rhel-image-mode-publish-image.adoc[leveloffset=+1] +include::modules/microshift-install-bootc-conc.adoc[leveloffset=+1] [id="_additional-resources_microshift-install-rhel-image-mode_{context}"] == Additional resources * link:https://developers.redhat.com/products/rhel-image-mode/getting-started[Image mode for Red Hat Enterprise Linux learning exercises] -* 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] \ No newline at end of file +* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/{op-system-version-major}/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] \ No newline at end of file diff --git a/microshift_install_bootc/microshift-install-bootc-image.adoc b/microshift_install_bootc/microshift-install-bootc-image.adoc new file mode 100644 index 0000000000..f9956983e6 --- /dev/null +++ b/microshift_install_bootc/microshift-install-bootc-image.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-install-publish-bootc-image"] +include::_attributes/attributes-microshift.adoc[] += Installing and publishing a bootc image to a registry +:context: microshift-install-rhel-bootc-image + +toc::[] + +{microshift-short} is built and published as image mode containers. When installing a {op-system-base-full} bootable container image with {microshift-short}, use either a prebuilt bootable container image or build your own custom bootable container image. + +:FeatureName: Image mode for {op-system-base} + +include::snippets/technology-preview.adoc[] + +include::modules/microshift-install-bootc-workflow.adoc[leveloffset=+1] + +[id="microshift-get-build-bootc-image_{context}"] +== Get or build your bootc image + +Either get an existing bootc image or create one, then you can publish that image to a remote registry for use. + +include::modules/microshift-install-bootc-get-published-image.adoc[leveloffset=+2] + +include::modules/microshift-install-bootc-build-image.adoc[leveloffset=+2] + +include::modules/microshift-install-bootc-publish-image.adoc[leveloffset=+1] diff --git a/microshift_install_bootc/microshift-install-running-bootc-image-vm.adoc b/microshift_install_bootc/microshift-install-running-bootc-image-vm.adoc new file mode 100644 index 0000000000..fa27c090e1 --- /dev/null +++ b/microshift_install_bootc/microshift-install-running-bootc-image-vm.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-install-running-bootc-image-in-vm"] +include::_attributes/attributes-microshift.adoc[] += Running the bootc image in a virtual machine +:context: microshift-install-running-bootc-image-in-vm + +toc::[] + +Use the bootable container image as an installation source to set up a {op-system-base-full} virtual machine. + +:FeatureName: Image mode for {op-system-base} + +include::snippets/technology-preview.adoc[] + +include::modules/microshift-install-bootc-prepare-kickstart.adoc[leveloffset=+1] + +include::modules/microshift-install-bootc-creating-vm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/microshift-install-rhel-image-mode-build-image.adoc b/modules/microshift-install-bootc-build-image.adoc similarity index 77% rename from modules/microshift-install-rhel-image-mode-build-image.adoc rename to modules/microshift-install-bootc-build-image.adoc index e6af4b6d31..915ee9d2f5 100644 --- a/modules/microshift-install-rhel-image-mode-build-image.adoc +++ b/modules/microshift-install-bootc-build-image.adoc @@ -1,9 +1,9 @@ // Module included in the following assemblies: // -// microshift_install_bootc/microshift-install-rhel-image-mode.adoc +// microshift_install_bootc/microshift-install-rhel-bootc-image.adoc :_mod-docs-content-type: PROCEDURE -[id="microshift-rhel-image-mode-build-image_{context}"] +[id="microshift-install-bootc-build-image_{context}"] = Building the bootc image Build your {op-system-base-full} that contains {microshift-short} as a bootable container image by using a Containerfile. @@ -14,8 +14,9 @@ Image mode for {op-system-base} is Technology Preview. Using a bootc image in pr ==== .Prerequisites -* A {op-system-base-full} {op-system-version} host with an active Red Hat subscription for building {microshift-short} bootc images and running containers. -* You are logged into the {op-system-base} {op-system-version} host using the user credentials that have `sudo` permissions. + +* A {op-system-base} {op-system-version} host with an active Red{nbsp}Hat subscription for building {microshift-short} bootc images and running containers. +* You logged into the {op-system-base} {op-system-version} host by using the user credentials that have `sudo` permissions. * The `rhocp` and `fast-datapath` repositories are accessible in the host subscription. The repositories do not necessarily need to be enabled on the host. * You have a remote registry such as link:https://quay.io[Red Hat quay] for storing and accessing bootc images. @@ -71,19 +72,36 @@ RUN systemctl enable microshift-make-rshared.service 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. ==== +. Set the `PULL_SECRET` environment variable: ++ +[source,terminal] +---- +PULL_SECRET=~/.pull-secret.json +---- + +. Configure the `USER_PASSWD` environment variable: ++ +[source,terminal,subs="+quotes"] +---- +USER_PASSWD=__ <1> +---- +<1> Replace __ with your password. + +. Configure the `IMAGE_NAME` environment variable: ++ +[source,terminal,subs="attributes+"] +---- +IMAGE_NAME=microshift-{product-version}-bootc +---- + . Create a local bootc image by running the following image build command: + [source,terminal,subs="+quotes"] ---- -PULL_SECRET=~/.pull-secret.json -USER_PASSWD=__ # <1> -IMAGE_NAME=microshift-{product-version}-bootc - $ sudo podman build --authfile "${PULL_SECRET}" -t "${IMAGE_NAME}" \ --build-arg USER_PASSWD="${USER_PASSWD}" \ -f Containerfile ---- -<1> Replace __ with your password. + [NOTE] ==== @@ -95,7 +113,7 @@ How secrets are used during the image build: .Verification -. Verify that the local {microshift} bootc image was created by running the following command: +. Verify that the local {microshift-short} bootc image was created by running the following command: + [source,terminal] ---- @@ -103,8 +121,8 @@ $ sudo podman images "${IMAGE_NAME}" ---- + .Example output -[source,text] +[source,text,subs="attributes+"] ---- REPOSITORY TAG IMAGE ID CREATED SIZE -localhost/microshift-4.19-bootc latest 193425283c00 2 minutes ago 2.31 GB +localhost/microshift-{product-version}-bootc latest 193425283c00 2 minutes ago 2.31 GB ---- diff --git a/modules/microshift-install-rhel-image-mode-conc.adoc b/modules/microshift-install-bootc-conc.adoc similarity index 58% rename from modules/microshift-install-rhel-image-mode-conc.adoc rename to modules/microshift-install-bootc-conc.adoc index c6b0406ef2..3dd6e145f9 100644 --- a/modules/microshift-install-rhel-image-mode-conc.adoc +++ b/modules/microshift-install-bootc-conc.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: // -// microshift_install_bootc/microshift-install-rhel-image-mode.adoc +// microshift_install_bootc/microshift-about-rhel-image-mode :_mod-docs-content-type: CONCEPT -[id="microshift-rhel-image-mode-conc_{context}"] -= Image mode for {op-system-base-full} +[id="microshift-bootc-conc_{context}"] += About image mode for {op-system-base-full} 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. @@ -17,23 +17,3 @@ Image mode splits the creation and installation of software changes into two ste * 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. * 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. - -[id="microshift-install-rhel-image-mode-conc_{context}"] -== Using image mode for {op-system-base} with {microshift-short} - -To use image mode for {op-system-base}, ensure that the following resources are available: - -* A {op-system-base} {op-system-version} host with an active Red Hat subscription for building {microshift-short} bootc images. -* A remote registry for storing and accessing bootc images. -* You can use image mode for RHEL with a {microshift-short} cluster on AArch64 or x86_64 system architectures. - -The workflow for using image mode with {microshift-short} includes the following steps: - -. Build the {microshift-short} bootc image. -. Publish the image. -. Run the image. This step includes configuring {microshift-short} networking and storage. - -[IMPORTANT] -==== -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. -==== diff --git a/modules/microshift-install-bootc-creating-vm.adoc b/modules/microshift-install-bootc-creating-vm.adoc new file mode 100644 index 0000000000..0eb6942f94 --- /dev/null +++ b/modules/microshift-install-bootc-creating-vm.adoc @@ -0,0 +1,81 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-install-running-bootc-image-in-VM.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-install-bootc-creating-vm_{context}"] += Creating a virtual machine + +You can create a virtual machine by using the {op-system-base-full} boot ISO image. + +.Prerequisites + +* You created the Kickstart file. + +* You installed the {oc-first}. + +* You have `redhat` credentials. + +.Procedure + +. Download the {op-system-base-full} boot ISO image from the link:https://developers.redhat.com/products/rhel/download[Download Red{nbsp}Hat Enterprise Linux]. + +. Copy the downloaded file to the `/var/lib/libvirt/images` directory. + +. Use your values to configure the following environment variables: ++ +[source,terminal,subs="attributes+"] +---- +VMNAME=microshift-{product-version}-bootc +NETNAME=default +---- + +. Create a {op-system-base-full} virtual machine with 2 cores, 2GB of RAM and 20GB of storage by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ sudo virt-install \ + --name ${VMNAME} \ + --vcpus 2 \ + --memory 2048 \ + --disk path=/var/lib/libvirt/images/${VMNAME}.qcow2,size=20 \ + --network network=${NETNAME},model=virtio \ + --events on_reboot=restart \ + --location /var/lib/libvirt/images/rhel-{op-system-version}-$(uname -m)-boot.iso \ + --initrd-inject kickstart.ks \ + --extra-args "inst.ks=file://kickstart.ks" \ + --wait +---- ++ +[NOTE] +==== +The `sudo virt-install` command uses the Kickstart file to pull a bootc image from the remote registry and install the {op-system-base-full} operating system. +==== + +. Log in to the virtual machine by using your `redhat` credentials. + +.Verification + +. Verify that all the {microshift-short} pods are running without error, by running the following command: ++ +[source,terminal] +---- +$ watch sudo oc get pods -A \ + --kubeconfig /var/lib/microshift/resources/kubeadmin/kubeconfig +---- ++ +.Example output +[source,text] +---- +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system csi-snapshot-controller-7cfb9df49c-kc9dx 1/1 Running 0 31s +kube-system csi-snapshot-webhook-5c6b978878-jzk5r 1/1 Running 0 28s +openshift-dns dns-default-rpnlt 2/2 Running 0 14s +openshift-dns node-resolver-rxvdk 1/1 Running 0 31s +openshift-ingress router-default-69cd7b5545-7zcw7 1/1 Running 0 29s +openshift-ovn-kubernetes ovnkube-master-c7hlh 4/4 Running 1 (16s ago) 31s +openshift-ovn-kubernetes ovnkube-node-mkpht 1/1 Running 1 (17s ago) 31s +openshift-service-ca service-ca-5d5d96459d-5pd5s 1/1 Running 0 28s +openshift-storage topolvm-controller-677cbfcdb9-28dqr 5/5 Running 0 31s +openshift-storage topolvm-node-6fzbl 3/3 Running 0 14s +---- \ No newline at end of file diff --git a/modules/microshift-install-bootc-get-published-image.adoc b/modules/microshift-install-bootc-get-published-image.adoc new file mode 100644 index 0000000000..e007a2cf55 --- /dev/null +++ b/modules/microshift-install-bootc-get-published-image.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-install-rhel-bootc-image.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-install-bootc-get-published-image_{context}"] += Getting the published bootc image for {microshift-short} + +You can find and use the {microshift-short} container images to install {op-system-base-full}. + +.Prerequisites + +* You have an x86_64 or AArch64 platform. + +* You have access to the `registry.redhat.io` registry. + +.Procedure + +. Navigate to the link:https://catalog.redhat.com/[Red{nbsp}Hat Ecosystem Catalog]. + +. Search for the {microshift-short} container image by using the `microshift-bootc` keyword. + +. Open the container image page of the {microshift-short} container image. + +. See the `Overview` and `Technical Information` tabs to get more details about the image. + +. Select the `Get this image` tab to view instructions for downloading the image. + +. Get access to the latest image on x86_64 and AArch64 platforms by logging into the registry using the following command: ++ +[source,terminal] +---- +$ sudo podman login registry.redhat.io +---- + +. Download the bootc image by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ podman pull registry.redhat.io/openshift4/microshift-bootc-rhel{op-system-version-major}:v{product-version} +---- diff --git a/modules/microshift-install-bootc-prepare-kickstart.adoc b/modules/microshift-install-bootc-prepare-kickstart.adoc new file mode 100644 index 0000000000..19a35e1197 --- /dev/null +++ b/modules/microshift-install-bootc-prepare-kickstart.adoc @@ -0,0 +1,92 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-install-running-bootc-image-in-VM.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-install-bootc-prepare-kickstart_{context}"] += Creating the Kickstart file + +You must create the Kickstart file to use during installation. + +.Prerequisites + +* You have root-user access. +* You are logged in to the physical hypervisor host. + +.Procedure + +. Set the `AUTH_CONFIG` environment variable to reference the secret file in the `kickstart.ks` file to authenticate private container registry access by running the following command: ++ +[source,terminal] +---- +$ AUTH_CONFIG=~/.quay-auth.json +---- + +. Set the `PULL_SECRET` environment variable to reference the secret files in the `kickstart.ks` file to authenticate the {OCP} registry access by running the following command: ++ +[source,terminal] +---- +$ PULL_SECRET=~/.pull-secret.json +---- + +. Set the `IMAGE_REF` environment variable to reference the image mode for your container image to use during installation by running the following command: ++ +[source,terminal,subs="attributes+,quotes"] +---- +$ IMAGE_REF="quay.io/_/_/microshift-{product-version}-bootc" <1> +---- +<1> Replace __ with your remote registry organization name and path. + +. Create the `kickstart.ks` file to use during installation by running the following script: ++ +[source,terminal] +---- +$ cat > kickstart.ks < /etc/ostree/auth.json <<'EOF' +$(cat "${AUTH_CONFIG}") +EOF + +%end + +# Pull a 'bootc' image from a remote registry +ostreecontainer --url "${IMAGE_REF}" + +%post --log=/dev/console --erroronfail + +# Create an OpenShift pull secret file +cat > /etc/crio/openshift-pull-secret <<'EOF' +$(cat "${PULL_SECRET}") +EOF +chmod 600 /etc/crio/openshift-pull-secret + +%end +EOFKS +---- diff --git a/modules/microshift-install-rhel-image-mode-publish-image.adoc b/modules/microshift-install-bootc-publish-image.adoc similarity index 88% rename from modules/microshift-install-rhel-image-mode-publish-image.adoc rename to modules/microshift-install-bootc-publish-image.adoc index 1a42521862..68f1fa7f26 100644 --- a/modules/microshift-install-rhel-image-mode-publish-image.adoc +++ b/modules/microshift-install-bootc-publish-image.adoc @@ -1,9 +1,9 @@ // Module included in the following assemblies: // -// microshift_install_bootc/microshift-install-rhel-image-mode.adoc +// microshift_install_bootc/microshift-install-rhel-bootc-image.adoc :_mod-docs-content-type: PROCEDURE -[id="microshift-rhel-image-mode-publish-image_{context}"] +[id="microshift-bootc-publish-image_{context}"] = Publishing the bootc image to the remote registry Publish your bootc image to the remote registry so that the image can be used for running the container on another host, or for when you want to install a new operating system with the bootc image layer. @@ -28,12 +28,12 @@ $ REGISTRY_URL=__ # <1> + [source,terminal,subs="+quotes"] ---- -$ sudo podman login "${REGISTRY-URL}" +$ sudo podman login "${REGISTRY_URL}" ---- . Set the `IMAGE_NAME` variable for the image by running the following command: + -[source,terminal,subs="+quotes"] +[source,terminal,subs="attributes+,quotes"] ---- $ IMAGE_NAME=__ # <1> ---- @@ -49,7 +49,7 @@ $ REGISTRY_IMG=__/"${IMAGE_NAME}" # <1> . Publish the image by running the following command: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- $ sudo podman push localhost/"${IMAGE_NAME}" "${REGISTRY_URL}/${REGISTRY_IMG}" ---- diff --git a/modules/microshift-install-bootc-workflow.adoc b/modules/microshift-install-bootc-workflow.adoc new file mode 100644 index 0000000000..b5f4247868 --- /dev/null +++ b/modules/microshift-install-bootc-workflow.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// microshift_install_bootc/microshift-about-rhel-image-mode + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-rhel-image-mode-conc_{context}"] += The image mode for {op-system-base} with {microshift-short} workflow + +To use image mode for {op-system-base}, ensure that the following resources are available: + +* A {op-system-base} {op-system-version} host with an active Red{nbsp}Hat subscription for building {microshift-short} bootc images. +* A remote registry for storing and accessing bootc images. +* You can use image mode for RHEL with a {microshift-short} cluster on AArch64 or x86_64 system architectures. + +The workflow for using image mode with {microshift-short} includes the following steps: + +. Find and use a prebuilt {microshift-short} container image to install {op-system-base-full}. +. Build a custom {microshift-short} container image if the prebuilt {microshift-short} container image requires customization. +. Run the container image. + +[IMPORTANT] +==== +The `rpm-ostree` file system is not supported in image mode. Do not use the `rpm-ostree` file system to modify deployments that use image mode. +====