diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc index bd0cd2ff80..a77e9f32d2 100644 --- 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 index f78443ff03..9a0235887a 100644 --- 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 new file mode 120000 index 0000000000..f27fd275ea --- /dev/null +++ b/microshift_install_kickstarts/_attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/microshift_install_kickstarts/images b/microshift_install_kickstarts/images new file mode 120000 index 0000000000..e4c5bd02a1 --- /dev/null +++ b/microshift_install_kickstarts/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc b/microshift_install_kickstarts/microshift-rhel-kickstarts.adoc new file mode 100644 index 0000000000..936f60212a --- /dev/null +++ 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] \ No newline at end of file diff --git a/microshift_install_kickstarts/modules b/microshift_install_kickstarts/modules new file mode 120000 index 0000000000..43aab75b53 --- /dev/null +++ b/microshift_install_kickstarts/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/microshift_install_kickstarts/snippets b/microshift_install_kickstarts/snippets new file mode 120000 index 0000000000..9d58b92e50 --- /dev/null +++ b/microshift_install_kickstarts/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc b/microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc index 51103b7237..e8e383b6e9 100644 --- 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 index b51af75bec..fb799ded1e 100644 --- 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 index 0fd364bc9b..c25990d699 100644 --- 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 index bbfc389905..0631727412 100644 --- 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 index 04d1dc8fc6..9c912abeee 100644 --- 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 `` 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 `` represents the PEM-encoded certificate. ==== .Prerequisites @@ -46,10 +46,10 @@ data = "" ---- $ 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 index 8b5343ff0d..9ee4fc79be 100644 --- 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,7 +36,7 @@ $ sudo composer-cli compose status ---- + .Example output of a running build - ++ [source,terminal] ---- ID Status Time Blueprint Version Type Size @@ -43,7 +44,7 @@ cc3377ec-4643-4483-b0e7-6b0ad0ae6332 RUNNING Wed Jun 7 12:26:23 2023 micro ---- + .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 index e42ee4b105..99d6757a17 100644 --- 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 index 8614bf8a34..d6dda97e16 100644 --- 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-provisioning-ostree.adoc b/modules/microshift-embed-kickstart-in-iso.adoc similarity index 56% rename from modules/microshift-provisioning-ostree.adoc rename to modules/microshift-embed-kickstart-in-iso.adoc index 8c4d4c93e1..5df45ea3b2 100644 --- a/modules/microshift-provisioning-ostree.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= \ . 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 new file mode 100644 index 0000000000..d18a66c8a8 --- /dev/null +++ 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=///microshift-image:tag # <1> +---- +<1> Replace __,__, and __ 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 new file mode 100644 index 0000000000..13acbadf7c --- /dev/null +++ b/modules/microshift-kickstart-ostree-install.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// microshift/microshift-.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-kickstart-ostree-install_{context}"] += Creating a Kickstart file for a {microshift-short} {op-system-ostree} installation + +Use the Kickstart file provided with {microshift-short} to provision a {op-system-ostree}-based virtual machine. + +.Prerequisites + +* You set up the {microshift-short} Kickstart file. +* You have the information needed to set required and optional variables. + +.Procedure + +. Add the following required variables to create an {op-system-ostree} Kickstart file: ++ +.Example commands setting required variables. ++ +* The `OSTREE_SERVER_URL` variable contains an `rpm-ostree` server URL that is passed to the `ostreesetup` Kickstart command. ++ +[source,terminal] +---- +$ export OSTREE_SERVER_URL="" # <1> +---- +<1> Replace __ with your server URL. ++ +* The `OSTREE_COMMIT_REF` variable contains an `rpm-ostree` commit reference that is installed from the server. ++ +[source,terminal] +---- +$ export OSTREE_COMMIT_REF="" # <1> +---- +<1> Replace __ with the `rpm-ostree` commit reference. + +. Optional. Add the following variable for server authentication: ++ +* The `AUTH_CONFIG` contents are copied to `/etc/ostree/auth.json` at the pre-install stage to authenticate access to the `OSTREE_SERVER_URL` server. If no server authentication is required, skip this setting. ++ +[source,terminal] +---- +$ export AUTH_CONFIG="$(cat ~/.ostree-auth.json)" +---- + +. Run the following command to create the `kickstart.ks` file to be used during the installation: ++ +[source,terminal] +---- +envsubst < \ + /usr/share/microshift/kickstart/kickstart-ostree.ks.template > \ + "${HOME}/kickstart.ks" +---- + +[NOTE] +==== +The {microshift-short} version specified in the `rpm-ostree` commit is installed. To change the version of {microshift-short}, you must create a new commit. +==== \ No newline at end of file diff --git a/modules/microshift-kickstart-prep.adoc b/modules/microshift-kickstart-prep.adoc new file mode 100644 index 0000000000..f34a0c0843 --- /dev/null +++ b/modules/microshift-kickstart-prep.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// microshift/microshift-kickstart-prep.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-kickstart-prep_{context}"] += Setting up the {microshift-short} Kickstart file + +You can use the Kickstart file provided with {microshift-short} to provision a host by following the instructions for your install type. The ISO you created in the previous steps then runs on the host that you provision with your Kickstart file. To get started with the {microshift-short} Kickstart file, begin with the following procedure. + +.Prerequisites + +* The host you are provisioning must meet the system requirements for installing {microshift-short}. +* A pull secret from `~/.pull-secret.json` must be present and have read permissions for the current user. + +.Procedure + +. Install the `microshift-release-info` RPM package containing the sample Kickstart files that are in the `/usr/share/microshift/kickstart` directory by running the following command: ++ +[source,terminal] +---- +$ sudo dnf install -y microshift-release-info +---- + +. Install the utilities used during the Kickstart file creation by running the following command: ++ +[source,terminal] +---- +$ sudo dnf install -y openssl gettext +---- + +. Set the variables pointing to secrets included in `kickstart.ks`. + +* The `PULL_SECRET` file contents are copied to the `/etc/crio/openshift-pull-secret` directory at the post-installation stage to authenticate {ocp} container registry access. ++ +.Example command setting the `PULL_SECRET` variable: +[source,terminal] +---- +$ export PULL_SECRET="$(cat ~/.pull-secret.json)" +---- + +* Set a password in the `PASSWD_TEXT` variable to use in the`USER_PASSWD` setting by running the following command: ++ +.Example command setting the `PASSWD_TEXT` variable. +[source,terminal] +---- +$ PASSWD_TEXT= <1> +---- +<1> Replace __ with the password you want to use. + +* The `USER_PASSWD` setting is used as an encrypted password for the `redhat` user for logging into the host. Encrypt your password string using the SHA-512 encryption standard. ++ +.Example command setting the `USER_PASSWD` variable. +[source,terminal] +---- +$ export USER_PASSWD="$(openssl passwd -6 "${PASSWD_TEXT}")" # <1> +---- +<1> Only the encrypted password is included in the Kickstart file. The plain text password is not. + +.Next steps +. Follow the instructions for your installation type to create a working Kickstart file from the provided template. Instructions for RPM-based, {op-system-ostree}, and {op-system-image} installations follow this procedure. + +. Optional. Create a virtual machine (VM) using the Kickstart file. Creating a VM allows you to test and validate the values in your Kickstart file. diff --git a/modules/microshift-kickstart-rpm-install.adoc b/modules/microshift-kickstart-rpm-install.adoc new file mode 100644 index 0000000000..ed9b3492f9 --- /dev/null +++ b/modules/microshift-kickstart-rpm-install.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// microshift/microshift-kickstart-prep.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-kickstart-rpm-install_{context}"] += Creating a Kickstart file for a {microshift-short} RPM installation + +Use the Kickstart file provided with {microshift-short} to provision an RPM-based virtual machine. + +.Prerequisites + +* You set up the {microshift-short} Kickstart file. +* You know the [Activation Keys](https://console.redhat.com/insights/connector/activation-keys) and organization ID to activate your Red Hat subscription. +* You have the information needed to set the `BOOTC_IMAGE_URL`, `AUTH_CONFIG`, and `REGISTRY_CONFIG` variables. + +[IMPORTANT] +==== +The subscription must include access to the `rhocp-4.x-for-rhel-9-$(uname -m)-rpms` and `fast-datapath-for-rhel-9-$(uname -m)-rpms` RPM repositories. +==== + +.Procedure + +. Add the following variables to create an RPM Kickstart file: ++ +.Example commands setting the Kickstart file variables. ++ +* The `RHSM_ORG` variable contains a Red Hat Subscription Manager organization ID for the subscription registration command in the Kickstart file. ++ +[source,terminal] +---- +$ export RHSM_ORG="$(cat ~/.rhsm-activation-org)" +---- ++ +* The `RHSM_KEY` variable contains a Red Hat Subscription Manager activation key for the subscription registration command in the Kickstart file. ++ +[source,terminal] +---- +$ export RHSM_KEY="$(cat ~/.rhsm-activation-key)" +---- ++ +* The `MICROSHIFT_VER` variable references the {microshift-short} version to install using the `4.y` format. The latest available `.z` version of the `4.y` version set in this variable is automatically installed. ++ +[source,terminal] +---- +$ export MICROSHIFT_VER=4.17 # <1> +---- +<1> For the minor version you set, the latest z-stream of that version is installed. + +. Run the following command to create the `kickstart.ks` file to be used during the virtual machine installation: ++ +[source,terminal] +---- +envsubst < \ + /usr/share/microshift/kickstart/kickstart-rpm.ks.template > \ + "${HOME}/kickstart.ks" +---- diff --git a/modules/microshift-preparing-for-image-building.adoc b/modules/microshift-preparing-for-image-building.adoc index 62fc7effb9..7708b29628 100644 --- a/modules/microshift-preparing-for-image-building.adoc +++ b/modules/microshift-preparing-for-image-building.adoc @@ -6,8 +6,12 @@ [id="preparing-for-image-building_{context}"] = Preparing for image building -Read link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images[Composing, installing, and managing RHEL for Edge images]. +Use the image builder tool to compose customized {op-system-ostree-first} images optimized for edge deployments. You can run a {microshift-short} cluster with your applications on a {op-system-ostree} virtual machine for development and testing first, then use your whole solution in edge production environments. -To build an {op-system-ostree-first} {op-system-version} image for a given CPU architecture, you need a {op-system-base} {op-system-version} build host of the same CPU architecture that meets the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements]. +Use the following {op-system-base} documentation to understand the full details of using {op-system-ostree}: -Follow the instructions in link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing image builder] to install image builder and the `composer-cli` tool. +* Read link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/introducing-rhel-for-edge-images_composing-installing-managing-rhel-for-edge-images[Introduction to RHEL for Edge images]. + +* To build an {op-system-ostree-first} {op-system-version} image for a given CPU architecture, you need a {op-system-base} {op-system-version} build host of the same CPU architecture that meets the link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image builder system requirements]. + +* Follow the instructions in link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing image builder] to install image builder and the `composer-cli` tool. diff --git a/modules/microshift-rhel-kickstarts-con.adoc b/modules/microshift-rhel-kickstarts-con.adoc new file mode 100644 index 0000000000..c40ae49ca6 --- /dev/null +++ b/modules/microshift-rhel-kickstarts-con.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// microshift/microshift-install-kickstarts.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-rhel-kickstart_{context}"] += Kickstart files for embedding {microshift-short} with a {op-system-base} installation + +By using a Kickstart file, you automate a typical {op-system-base-full} installation by creating a single file containing all of the information required for success. + +* You can also automate your {microshift-short} installation by including {microshift-short} in the Kickstart file for the {op-system-base} type that you choose. +* You can use a Kickstart file to provision virtual machines (VMs) or to complete a regular {op-system-base} installation for deployment on edge devices. + +For {microshift-short}, your Kickstart file must include information to provision the {op-system-base} system to meet the following requirements: + +* A {op-system-base} system you provision must meet the requirements for installing {microshift-short}. +* The {op-system-base} 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. \ No newline at end of file