Merge pull request #88177 from skopacz1/OSDOCS-12787

OSDOCS-12787: iSCSI booting for Agent

Author: skopacz1

_topic_maps/_topic_map.yml

@@ -415,6 +415,8 @@ Topics:
     File: installing-with-agent-based-installer
   - Name: Preparing PXE assets for OCP
     File: prepare-pxe-assets-agent
+  - Name: Preparing installation assets for iSCSI booting
+    File: installing-using-iscsi
   - Name: Preparing an Agent-based installed cluster for the multicluster engine for Kubernetes
     File: preparing-an-agent-based-installed-cluster-for-mce
   - Name: Installation configuration parameters for the Agent-based Installer

installing/installing_with_agent_based_installer/installing-using-iscsi.adoc

@@ -0,0 +1,47 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="installing-using-iscsi"]
+= Preparing installation assets for iSCSI booting
+include::_attributes/common-attributes.adoc[]
+:context: installing-using-iscsi
+
+toc::[]
+
+You can boot an {product-title} cluster through Internet Small Computer System Interface (iSCSI) by using an ISO image generated by the Agent-based Installer.
+The following procedures describe how to prepare the necessary installation resources to boot from an iSCSI target.
+
+The assets you create in these procedures deploy a single-node {product-title} installation.
+You can use these procedures as a basis and modify configurations according to your requirements.
+
+// Downloading the Agent-based Installer
+include::modules/installing-ocp-agent-iscsi-requirements.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#agent-install-networking-DHCP_preparing-to-install-with-agent-based-installer[DHCP]
+* xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints]
+
+[id="prerequisites_{context}"]
+== Prerequisites
+
+* You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
+* You read the documentation on xref:../../installing/overview/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
+* If you use a firewall or proxy, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
+
+// Downloading the Agent-based Installer
+include::modules/installing-ocp-agent-download.adoc[leveloffset=+1]
+
+// Creating the preferred configuration inputs
+include::modules/installing-ocp-agent-inputs.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow[Deploying with dual-stack networking]
+* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-the-install-config-file_ipi-install-installation-workflow[Configuring the install-config yaml file]
+* xref:../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster]
+* xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints]
+* link:https://nmstate.io/examples.html[NMState state examples] (NMState documentation)
+* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#installing-ocp-agent-opt-manifests_installing-with-agent-based-installer[Optional: Creating additional manifest files]
+* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#agent-install-verifying-architectures_installing-with-agent-based-installer[Verifying the supported architecture for an Agent-based installation]
+
+// Creating the installation files
+include::modules/installing-ocp-agent-iscsi-files.adoc[leveloffset=+1]

installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc

@@ -83,7 +83,7 @@ include::modules/installing-ocp-agent-verify.adoc[leveloffset=+2]
 .Additional resources
 * See xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow[Deploying with dual-stack networking].
 * See xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-the-install-config-file_ipi-install-installation-workflow[Configuring the install-config yaml file].
-* See xref:../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster] to deploy three-node clusters in bare metal environments.
+* See xref:../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster] to deploy three-node clusters in bare-metal environments.
 * See xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints].
 * See link:https://nmstate.io/examples.html[NMState state examples].
 

modules/installing-ocp-agent-download.adoc

@@ -2,6 +2,7 @@
 //
 // * installing/installing-with-agent-based-installer/installing-with-agent-based-installer.adoc
 // * installing/installing_with_agent_based_installer/prepare-pxe-infra-agent.adoc
+// * installing/installing_with_agent_based_installer/installing-using-iscsi.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="installing-ocp-agent-retrieve_{context}"]

modules/installing-ocp-agent-inputs.adoc

@@ -2,25 +2,40 @@
 //
 // * installing/installing-with-agent-based-installer/installing-with-agent-based-installer.adoc
 // *installing/installing_with_agent_based_installer/prepare-pxe-infra-agent.adoc
+// * installing/installing_with_agent_based_installer/installing-using-iscsi.adoc
 
 ifeval::["{context}" == "prepare-pxe-assets-agent"]
 :pxe-boot:
 endif::[]
 
+ifeval::["{context}" == "installing-using-iscsi"]
+:iscsi-boot:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="installing-ocp-agent-inputs_{context}"]
 = Creating the preferred configuration inputs
 
 ifndef::pxe-boot[]
 Use this procedure to create the preferred configuration inputs used to create the agent image.
+
+[NOTE]
+====
+Configuring the `install-config.yaml` and `agent-config.yaml` files is the preferred method for using the Agent-based Installer. Using {ztp} manifests is optional.
+====
 endif::pxe-boot[]
 ifdef::pxe-boot[]
 Use this procedure to create the preferred configuration inputs used to create the PXE files.
+
+[NOTE]
+====
+Configuring the `install-config.yaml` and `agent-config.yaml` files is the preferred method for using the Agent-based Installer. Using {ztp} manifests is optional.
+====
 endif::pxe-boot[]
 
 .Procedure
 
-. Install `nmstate` dependency by running the following command:
+. Install the `nmstate` dependency by running the following command:
 +
 [source,terminal]
 ----
@@ -36,12 +51,6 @@ $ sudo dnf install /usr/bin/nmstatectl -y
 $ mkdir ~/<directory_name>
 ----
 
-+
-[NOTE]
-====
-This is the preferred method for the Agent-based installation. Using {ztp} manifests is optional.
-====
-
 . Create the `install-config.yaml` file by running the following command:
 +
 --
@@ -86,7 +95,7 @@ If you are using the release image with the `multi` payload, you can install the
 +
 [NOTE]
 ====
-For bare metal platforms, host settings made in the platform section of the `install-config.yaml` file are used by default, unless they are overridden by configurations made in the `agent-config.yaml` file.
+For bare-metal platforms, host settings made in the platform section of the `install-config.yaml` file are used by default, unless they are overridden by configurations made in the `agent-config.yaml` file.
 ====
 <5> Specify your pull secret.
 <6> Specify your SSH public key.
@@ -173,6 +182,7 @@ hosts: // <2>
             next-hop-address: 192.168.111.2
             next-hop-interface: eno1
             table-id: 254
+ifdef::iscsi-boot[minimalISO: true <6>]
 EOF
 ----
 +
@@ -182,6 +192,10 @@ You must provide the rendezvous IP address when you do not specify at least one
 <3> Optional: Overrides the hostname obtained from either the Dynamic Host Configuration Protocol (DHCP) or a reverse DNS lookup. Each host must have a unique hostname supplied by one of these methods.
 <4> Enables provisioning of the {op-system-first} image to a particular device. The installation program examines the devices in the order it discovers them, and compares the discovered values with the hint values. It uses the first discovered device that matches the hint value.
 <5> Optional: Configures the network interface of a host in NMState format.
+ifdef::iscsi-boot[]
+<6> Generates an ISO image without the rootfs image file, and instead provides details about where to pull the rootfs file from.
+You must set this parameter to `true` to enable iSCSI booting.
+endif::iscsi-boot[]
 
 ifdef::pxe-boot[]
 
@@ -203,3 +217,7 @@ endif::pxe-boot[]
 ifeval::["{context}" == "prepare-pxe-assets-agent"]
 :!pxe-boot:
 endif::[]
+
+ifeval::["{context}" == "installing-using-iscsi"]
+:!iscsi-boot:
+endif::[]

modules/installing-ocp-agent-iscsi-files.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_with_agent_based_installer/installing-using-iscsi.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installing-ocp-agent-iscsi-files_{context}"]
+= Creating the installation files
+
+Use the following procedure to generate the ISO image and create an iPXE script to upload to your iSCSI target.
+
+.Procedure
+
+. Create the agent image by running the following command:
++
+[source,terminal]
+----
+$ openshift-install --dir <install_directory> agent create image
+----
+
+. Create an iPXE script by running the following command:
++
+[source,terminal]
+----
+$ cat << EOF > agent.ipxe
+!ipxe
+set initiator-iqn <iscsi_initiator_base>:\${hostname}
+sanboot --keep iscsi:<iscsi_network_subnet>.1::::<iscsi_target_base>:\${hostname}
+EOF
+----
++
+--
+where:
+
+<iscsi_initiator_base>:: Specifies the iSCSI initiator name on the host that is booting the ISO.
+This name can also be used by the iSCSI target.
+<iscsi_network_subnet>:: Specifies the IP address of the iSCSI target.
+<iscsi_target_base>:: Specifies the iSCSI target name.
+This name can be the same as the initiator name.
+--
++
+.Example Command
+[source,terminal]
+----
+$ cat << EOF > agent.ipxe
+!ipxe
+set initiator-iqn iqn.2023-01.com.example:\${hostname}
+sanboot --keep iscsi:192.168.45.1::::iqn.2023-01.com.example:\${hostname}
+EOF
+----

modules/installing-ocp-agent-iscsi-requirements.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_with_agent_based_installer/installing-using-iscsi.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="iscsi-boot-requirements_{context}"]
+= Requirements for iSCSI booting
+
+The following configurations are necessary to enable iSCSI booting when using the Agent-based Installer:
+
+* Dynamic Host Configuration Protocol (DHCP) must be configured.
+Static networking is not supported.
+* You must create an additional network for iSCSI that is separate from the machine network of the cluster.
+The machine network is rebooted during cluster installation and cannot be used for the iSCSI session.
+* If the host on which you are booting the agent ISO image also has an installed disk, it might be necessary to specify the iSCSI disk name in the `rootDeviceHints` parameter to ensure that it is chosen as the boot disk for the final {op-system-first} image.
+You can also use a diskless environment for iSCSI booting, in which case you do not need to set the `rootDeviceHints` parameter.