OSDOCS-11273: adds kickstart examples MicroShift

ShaunaDiaz · ShaunaDiaz · commit 3f857c1cd640 · 2025-01-31T06:39:05.000-05:00
diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc
@@ -19,6 +19,7 @@
 :op-system-ostree: RHEL for Edge
 :op-system-rt-kernel: Red Hat Enterprise Linux for Real Time (real-time kernel)
 :op-system-rtk: real-time kernel
+:op-system-image: image mode for RHEL
 :op-system-version: 9.4
 :op-system-version-major: 9
 :op-system-bundle: Red Hat Device Edge
diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml
@@ -79,6 +79,13 @@ Topics:
 - Name: Installing with RHEL image mode
   File: microshift-install-rhel-image-mode
 ---
+Name: Using RHEL Kickstarts
+Dir: microshift_install_kickstarts
+Distros: microshift
+Topics:
+- Name: Using a Kickstart file for automating installation
+  File: microshift-rhel-kickstarts
+---
 Name: Updating
 Dir: microshift_updating
 Distros: microshift
diff --git a/microshift_install_kickstarts/_attributes b/microshift_install_kickstarts/_attributes
@@ -0,0 +1 @@
+../_attributes/
diff --git a/microshift_install_kickstarts/images b/microshift_install_kickstarts/images
@@ -0,0 +1 @@
+../images/
diff --git a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc
@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/attributes-microshift.adoc[]
+[id="microshift-rhel-kickstarts"]
+= Using Kickstart files for installing {microshift-short} in {op-system-base}
+:context: microshift-rhel-kickstarts
+
+toc::[]
+
+Use a Kickstart file that automates the installation of an {op-system-base} image with {microshift-short}.
+
+include::modules/microshift-rhel-kickstarts-con.adoc[leveloffset=+1]
+
+include::modules/microshift-kickstart-prep.adoc[leveloffset=+2]
+
+include::modules/microshift-kickstart-rpm-install.adoc[leveloffset=+2]
+
+include::modules/microshift-kickstart-ostree-install.adoc[leveloffset=+2]
+
+include::modules/microshift-kickstart-bootc-install.adoc[leveloffset=+2]
diff --git a/microshift_install_kickstarts/modules b/microshift_install_kickstarts/modules
@@ -0,0 +1 @@
+../modules/
diff --git a/microshift_install_kickstarts/snippets b/microshift_install_kickstarts/snippets
@@ -0,0 +1 @@
+../snippets/
diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc
@@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can embed {microshift-short} into a {op-system-ostree-first} image. Use this guide to build a {op-system-base} image containing {microshift-short}.
+Use this guide to build a {op-system-base} image containing {microshift-short}.
 
 include::modules/microshift-preparing-for-image-building.adoc[leveloffset=+1]
 
@@ -47,18 +47,22 @@ include::modules/microshift-add-blueprint-build-iso.adoc[leveloffset=+1]
 
 include::modules/microshift-download-iso-prep-for-use.adoc[leveloffset=+1]
 
-include::modules/microshift-provisioning-ostree.adoc[leveloffset=+1]
+include::modules/microshift-embed-kickstart-in-iso.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index[{op-system-ostree} documentation]
-* xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing MicroShift]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/composing_installing_and_managing_rhel_for_edge_images/index[Composing, installing, and managing RHEL for Edge images]
+* xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing {microshift-short}]
 * link:https://console.redhat.com/openshift/install/pull-secret[Red Hat Hybrid Cloud Console pull secret]
 * xref:../microshift_networking/microshift-firewall.adoc#microshift-firewall-req-settings_microshift-firewall[Required firewall settings]
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/performing_an_advanced_rhel_9_installation/creating-kickstart-files_installing-rhel-as-an-experienced-user[Creating a Kickstart file]
+//* xref:../microshift_install_kickstarts/microshift-rhel-kickstarts.adoc#microshift-rhel-kickstarts[Using Kickstart files for embedding {microshift-short} in {op-system-base} installation]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/creating-kickstart-files_rhel-installer[Creating Kickstart files]
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/automatically_installing_rhel/kickstart-script-file-format-reference_rhel-installer#kickstart-file-format_kickstart-script-file-format-reference[A.1. Kickstart file format]
 * link:https://access.redhat.com/solutions/60959[How to embed a Kickstart file into an ISO image]
 
+//Add modules about using the VM and getting the ISO up and running, then starting MicroShift...
+
 include::modules/microshift-accessing.adoc[leveloffset=+1]
 
 include::modules/microshift-accessing-cluster-locally.adoc[leveloffset=+2]
diff --git a/microshift_running_apps/microshift-embed-apps-offline-use.adoc b/microshift_running_apps/microshift-embed-apps-offline-use.adoc
@@ -19,7 +19,7 @@ include::modules/microshift-embed-images-offline-use.adoc[leveloffset=+1]
 
 * xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the {op-system-ostree} image]
 
-* xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-add-blueprint-build-iso_microshift-embed-in-rpm-ostree[Add the blueprint to Image Builder and build the ISO]
+* xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-add-blueprint-build-iso_microshift-embed-in-rpm-ostree[Add the blueprint to image builder and build the ISO]
 
 * xref:../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-download-iso-prep-for-use_microshift-embed-in-rpm-ostree[Download the ISO and prepare it for use]
 
diff --git a/microshift_running_apps/microshift-embedding-apps-tutorial.adoc b/microshift_running_apps/microshift-embedding-apps-tutorial.adoc
@@ -19,7 +19,7 @@ include::modules/microshift-adding-app-rpms-to-blueprint.adoc[leveloffset=+2]
 //additional resources for adding app rpms to blueprint
 [role="_additional-resources"]
 .Additional resources
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#doc-wrapper[Composing a {op-system-ostree} image using the Image Builder CLI]
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#doc-wrapper[Composing a {op-system-ostree} image using the image builder CLI]
 
 * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#network_based_deployments_workflow[Network-based deployments workflow]
 
@@ -41,4 +41,4 @@ include::modules/microshift-adding-app-rpms-to-blueprint.adoc[leveloffset=+2]
 
 * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images[Composing a {op-system-ostree} image using image builder command-line]
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#edge-image-builder-system-requirements_setting-up-image-builder[Image Builder system requirements]
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html-single/composing_installing_and_managing_rhel_for_edge_images/index#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements]
diff --git a/modules/microshift-adding-app-rpms-to-blueprint.adoc b/modules/microshift-adding-app-rpms-to-blueprint.adoc
@@ -6,7 +6,7 @@
 [id="microshift-adding-app-rpms-to-blueprint_{context}"]
 = Adding application RPMs to a blueprint
 
-To add application RPMs to a blueprint, you must create a local repository that Image Builder can use to create the ISO. With this procedure, the required container images for your workload can be pulled over the network.
+To add application RPMs to a blueprint, you must create a local repository that image builder can use to create the ISO. With this procedure, the required container images for your workload can be pulled over the network.
 
 .Prerequisites
 
diff --git a/modules/microshift-ca-adding-bundle-ostree.adoc b/modules/microshift-ca-adding-bundle-ostree.adoc
@@ -10,7 +10,7 @@ You can include additional trusted certificate authorities (CAs) to the {op-syst
 
 [NOTE]
 ====
-This procedure requires you to configure the CA bundle customizations in the blueprint, and then add steps to your kickstart file to enable the bundle. In the following steps, `data` is the key, and `<value>` represents the PEM-encoded certificate.
+This procedure requires you to configure the CA bundle customizations in the blueprint, and then add steps to your Kickstart file to enable the bundle. In the following steps, `data` is the key, and `<value>` represents the PEM-encoded certificate.
 ====
 
 .Prerequisites
@@ -46,10 +46,10 @@ data = "<value>"
 ----
 $ sudo update-ca-trust
 ----
-
++
 [NOTE]
 ====
-The `update-ca-trust` command might be included in the `%post` section of a kickstart file used for MicroShift host installation so that all the necessary certificate trust is enabled on the first boot. You must configure the CA bundle customizations in the blueprint before adding steps to your kickstart file to enable the bundle.
+The `update-ca-trust` command might be included in the `%post` section of a Kickstart file used for {microshift-short} host installation so that all the necessary certificate trust is enabled on the first boot. You must configure the CA bundle customizations in the blueprint before adding steps to your Kickstart file to enable the bundle.
 
 [source,terminal]
 ----
diff --git a/modules/microshift-creating-ostree-iso.adoc b/modules/microshift-creating-ostree-iso.adoc
@@ -5,15 +5,16 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-creating-ostree-iso_{context}"]
-= Creating the {op-system-ostree} image
+= Creating the {op-system-ostree} image with image builder
 
 Use the following procedure to create the ISO. The {op-system-ostree} Installer image pulls the commit from the running container and creates an installable boot ISO with a Kickstart file configured to use the embedded `rpm-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 installed the `podman` tool.
+
+* Your build host meets the image builder system requirements.
+* You installed and set up image builder and the `composer-cli` tool.
+* You root-user access to your build host.
+* You installed the `podman` tool.
 
 .Procedure
 
@@ -35,15 +36,15 @@ $ sudo composer-cli compose status
 ----
 +
 .Example output of a running build
-
++
 [source,terminal]
 ----
 ID                                     Status     Time                     Blueprint                 Version   Type               Size
 cc3377ec-4643-4483-b0e7-6b0ad0ae6332   RUNNING    Wed Jun 7 12:26:23 2023  microshift_blueprint      0.0.1     edge-container
 ----
 +
 .Example output of a completed build
-
++
 [source,terminal]
 ----
 ID                                     Status     Time                      Blueprint              Version   Type               Size
diff --git a/modules/microshift-download-iso-prep-for-use.adoc b/modules/microshift-download-iso-prep-for-use.adoc
@@ -27,3 +27,8 @@ $ sudo chown $(whoami). ${BUILDID}-installer.iso
 ----
 $ sudo chmod a+r ${BUILDID}-installer.iso
 ----
+
+.Next steps
+
+* Provision a virtual machine with a Kickstart file.
+//Q: We don't actually finish the procedures showing launching the virtual machine and using this ISO. Should we include those procedure or link to them more constructively?
diff --git a/modules/microshift-embed-app-rpms-tutorial.adoc b/modules/microshift-embed-app-rpms-tutorial.adoc
@@ -21,20 +21,20 @@ image:468_RHbM_install_workflow_1023_1.png[title="Embedding MicroShift in a RHEL
 
 Reviewing these steps can help you understand the steps needed to embed an application:
 
-. To embed {microshift-short} on {op-system-ostree}, you added the {microshift-short} repositories to Image Builder.
+. To embed {microshift-short} on {op-system-ostree}, you added the {microshift-short} repositories to image builder.
 
 . You created a blueprint that declared all the RPMs, container images, files and customizations you needed, including the addition of {microshift-short}.
 
-. You added the blueprint to Image Builder and ran a build with the Image Builder CLI tool (`composer-cli`). This step created `rpm-ostree` commits, which were used to create the container image. This image contained {op-system-ostree}.
+. You added the blueprint to image builder and ran a build with the image builder CLI tool (`composer-cli`). This step created `rpm-ostree` commits, which were used to create the container image. This image contained {op-system-ostree}.
 
-. You added the installer blueprint to Image Builder to create an `rpm-ostree` image (ISO) to boot from. This build contained both {op-system-ostree} and {microshift-short}.
+. You added the installer blueprint to image builder to create an `rpm-ostree` image (ISO) to boot from. This build contained both {op-system-ostree} and {microshift-short}.
 
 . You downloaded the ISO with {microshift-short} embedded, prepared it for use, provisioned it, then installed it onto your edge devices.
 
 [id="microshift-embed-app-rpms-workflow_{context}"]
 == Embed application RPMs workflow
 
-After you have set up a build host that meets the Image Builder requirements, you can add your application in the form of a directory of manifests to the image. After those steps, the simplest way to embed your application or workload into a new ISO is to create your own RPMs that include the manifests. Your application RPMs contain all of the configuration files describing your deployment.
+After you have set up a build host that meets the image builder requirements, you can add your application in the form of a directory of manifests to the image. After those steps, the simplest way to embed your application or workload into a new ISO is to create your own RPMs that include the manifests. Your application RPMs contain all of the configuration files describing your deployment.
 
 The following "Embedding applications workflow" image shows how Kubernetes application manifests and RPM spec files are combined in a single application RPM build. This build becomes the RPM artifact included in the workflow for embedding {microshift-short} in an ostree commit.
 
diff --git a/modules/microshift-embed-kickstart-in-iso.adoc b/modules/microshift-embed-kickstart-in-iso.adoc
@@ -1,40 +1,24 @@
 // Module included in the following assemblies:
 //
-// microshift/microshift-embed-into-rpm-ostree.adoc
+// microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="provisioning-a-machine_{context}"]
-= Provisioning a machine for {microshift-short}
+[id="microshift-embed-kickstart-iso_{context}"]
+= Embedding a Kickstart file in an ISO
 
-Provision a machine with your {op-system-ostree} image by using the procedures from the {op-system-ostree} documentation.
-
-To use {microshift-short}, 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-short}.
-* 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 https://console.redhat.com/openshift/install/pull-secret[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 the required settings.
-
-[NOTE]
-====
-If you are using a Kickstart such as the {op-system-ostree} Installer (ISO) image, you can update your Kickstart file to meet the provisioning requirements.
-====
+You can use the Kickstart file provided with {microshift-short}, or you can update an existing {op-system-ostree} Installer (ISO) Kickstart file. When ready, embed the Kickstart file into the ISO. Your Kickstart file must include detailed instructions about how to create a user and how to fetch and deploy the {op-system-ostree} image.
 
 .Prerequisites
 
-. You have created a {op-system-ostree} Installer (ISO) image containing your {op-system-ostree} commit with {product-title}.
-.. 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.
-. 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 {op-system-ostree} image.
+* You created a {op-system-ostree} Installer (ISO) image containing your {op-system-ostree} commit with {microshift-short}.
 
-For more information, read "Additional resources."
+* You have an existing Kickstart file ready for updating. You can use the `microshift-starter.ks` Kickstart file provided with the {microshift-short} RPMs.
 
 .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
+.Example Kickstart file snippet for configuring the filesystem
 [source,text]
 ----
 # Partition disk such that it contains an LVM volume group called `rhel` with a
@@ -68,7 +52,7 @@ user --name=<YOUR_USER_NAME> \
 
 . 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
+.Example Kickstart file snippet for adding the pull secret and firewall rules
 [source,terminal]
 ----
 %post --log=/var/log/anaconda/post-install.log --erroronfail
@@ -93,7 +77,7 @@ firewall-offline-cmd --zone=trusted --add-source=169.254.169.1
 $ sudo yum install -y lorax
 ----
 
-. Update the Kickstart file in the ISO with your new Kickstart file by running the following command:
+. Update the ISO with your new Kickstart file by running the following command:
 +
 [source,terminal]
 ----
diff --git a/modules/microshift-kickstart-bootc-install.adoc b/modules/microshift-kickstart-bootc-install.adoc
@@ -0,0 +1,55 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-kickstart-bootc-install_{context}"]
+= Creating a Kickstart file for installing {microshift-short} on image mode for RHEL
+
+You can use the Kickstart file provided with {microshift-short} for an image mode for RHEL installation.
+
+.Prerequisites
+
+* You set up the {microshift-short} Kickstart file.
+* You have the information needed to set required and optional variables.
+
+.Procedure
+
+. Set the required `BOOTC_IMAGE_URL` variable value to point to an image used in the RHEL Kickstart file installation process by running the following command:
++
+[source,terminal]
+----
+$ export BOOTC_IMAGE_URL=<myregistry>/<myorg>/<mypath>/microshift-image:tag # <1>
+----
+<1> Replace _<myregistry>_,_<myorg>_, and _<mypath>_ with your information.
+
+* The `BOOTC_IMAGE_URL` variable contains a reference to the image that is installed with the `ostreecontainer` command. You can specify a z-stream release other than the latest by using the tag if required.
+
+. Optional. Add variables and values for registry authentication and configuration by using the following commands:
++
+.Example commands setting optional variables
++
+* Set the `AUTH_CONFIG` variable to authenticate access to the `BOOTC_IMAGE_URL` image by running the following command:
++
+[source,terminal]
+----
+$ export AUTH_CONFIG="$(cat ~/.quay-auth.json)" # <1>
+----
+<1> See the `containers-auth.json(5)` manual page for more information about this file format.
++
+* Set the `REGISTRY_CONFIG` variable to configure access to the registry containing the `BOOTC_IMAGE_URL` image by running the following command:
++
+[source,terminal]
+----
+$ export REGISTRY_CONFIG="$(cat ~/.quay-config.conf)" # <1>
+----
+<1> See the `containers-registries.conf(5)` manual page for more information about this file format.
+
+. Create the `kickstart.ks` file to be used during the installation by running the following command:
++
+[source,terminal]
+----
+envsubst < \
+    /usr/share/microshift/kickstart/kickstart-bootc.ks.template > \
+    "${HOME}/kickstart.ks"
+----
diff --git a/modules/microshift-kickstart-ostree-install.adoc b/modules/microshift-kickstart-ostree-install.adoc
diff --git a/modules/microshift-kickstart-prep.adoc b/modules/microshift-kickstart-prep.adoc
diff --git a/modules/microshift-kickstart-rpm-install.adoc b/modules/microshift-kickstart-rpm-install.adoc
diff --git a/modules/microshift-preparing-for-image-building.adoc b/modules/microshift-preparing-for-image-building.adoc
diff --git a/modules/microshift-rhel-kickstarts-con.adoc b/modules/microshift-rhel-kickstarts-con.adoc
