--- title: Preparing installation assets for iSCSI booting --- # Preparing installation assets for iSCSI booting {#installing-using-iscsi} You can boot an OpenShift Container Platform 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 OpenShift Container Platform installation. You can use these procedures as a basis and modify configurations according to your requirements. ## Requirements for iSCSI booting {#iscsi-boot-requirements_installing-using-iscsi} Several configurations are necessary to enable iSCSI booting when using the Agent-based Installer. The following configurations are required: - 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 Red Hat Enterprise Linux CoreOS (RHCOS) image. You can also use a diskless environment for iSCSI booting, in which case you do not need to set the `rootDeviceHints` parameter. **Additional resources** {._additional-resources} - [DHCP](/openshift-docs-markdown/installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer#agent-install-networking-DHCP_preparing-to-install-with-agent-based-installer) - [About root device hints](/openshift-docs-markdown/installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer#root-device-hints_preparing-to-install-with-agent-based-installer) ## Prerequisites for installing a cluster with the Agent-based Installer {#prerequisites_installing-using-iscsi} Before beginning your cluster installation, you must complete prerequisite tasks that prepare your environment. - You reviewed details about the OpenShift Container Platform installation and update processes. For more information, see "Installation and update". - You read "Selecting a cluster installation method and preparing it for users". - If you use a firewall or proxy, you configured it to allow the sites that your cluster requires access to. For more information, see "Configuring your firewall". - You configured your firewall to allow TCP traffic on port `8090` from all hosts to the rendezvous host so that hosts can reach the Assisted Service API during discovery and bootstrap. For more information, see "Port requirements for the rendezvous host". **Additional resources** {._additional-resources} - [Installation and update](/openshift-docs-markdown/architecture/architecture-installation#architecture-installation) - [Selecting a cluster installation method and preparing it for users](/openshift-docs-markdown/installing/overview/installing-preparing#installing-preparing) - [Configuring your firewall](/openshift-docs-markdown/installing/install_config/configuring-firewall#configuring-firewall-module_configuring-firewall) - [Port requirements for the rendezvous host](/openshift-docs-markdown/installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer#agent-install-networking-ports_preparing-to-install-with-agent-based-installer) ## Downloading the Agent-based Installer {#installing-ocp-agent-retrieve_installing-using-iscsi} Begin the installation process by downloading the Agent-based Installer and the CLI needed for your installation. **Procedure** 1. Log in to the Red Hat Hybrid Cloud Console using your login credentials. 2. Navigate to [Datacenter](https://console.redhat.com/openshift/create/datacenter). 3. Click **Run Agent-based Installer locally**. 4. Select the operating system and architecture for the **OpenShift Installer** and **Command line interface**. 5. Click **Download Installer** to download and extract the install program. 6. Download or copy the pull secret by clicking on **Download pull secret** or **Copy pull secret**. 7. Click **Download command-line tools** and place the `openshift-install` binary in a directory that is on your `PATH`. ## Creating the preferred configuration inputs {#installing-ocp-agent-inputs_installing-using-iscsi} 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 GitOps ZTP manifests is optional. **Procedure** 1. Install the `nmstate` dependency by running the following command: ```terminal $ sudo dnf install /usr/bin/nmstatectl -y ``` 2. Place the `openshift-install` binary in a directory that is on your PATH. 3. Create a directory to store the install configuration by running the following command: ```terminal $ mkdir ~/ ``` 4. Create the `install-config.yaml` file by running the following command: ```terminal $ cat << EOF > .//install-config.yaml apiVersion: v1 baseDomain: test.example.com compute: - architecture: amd64 hyperthreading: Enabled name: worker replicas: 0 controlPlane: architecture: amd64 hyperthreading: Enabled name: master replicas: 1 metadata: name: sno-cluster networking: clusterNetwork: - cidr: 10.128.0.0/14 hostPrefix: 23 machineNetwork: - cidr: 192.168.0.0/16 networkType: OVNKubernetes serviceNetwork: - 172.30.0.0/16 platform: none: {} pullSecret: '' sshKey: '' additionalTrustBundle: | -----BEGIN CERTIFICATE----- ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ -----END CERTIFICATE----- imageContentSources: - mirrors: - //release source: quay.io/openshift-release-dev/ocp-release - mirrors: - //release source: quay.io/openshift-release-dev/ocp-v4.0-art-dev EOF ``` where: `compute.architecture` : Specifies the system architecture. Valid values are `amd64`, `arm64`, `ppc64le`, and `s390x`. If you are using the release image with the `multi` payload, you can install the cluster on different architectures such as `arm64`, `amd64`, `s390x`, and `ppc64le`. Otherwise, you can install the cluster only on the `release architecture` displayed in the output of the `openshift-install version` command. For more information, see "Verifying the supported architecture for installing an Agent-based Installer cluster". `metadata.name` : Specifies your cluster name. This value is required. `networking.networkingType` : Specifies the cluster network plugin to install. The default value `OVNKubernetes` is the only supported value. `platform` : Specifies your platform. If you set the platform to `vSphere`, `baremetal`, or `none`, you can configure IP address endpoints for cluster nodes in three ways: IPv4, IPv6, or IPv4 and IPv6 in parallel (dual-stack). ```yaml {title="Example of dual-stack networking"} networking: clusterNetwork: - cidr: 172.21.0.0/16 hostPrefix: 23 - cidr: fd02::/48 hostPrefix: 64 machineNetwork: - cidr: 192.168.11.0/16 - cidr: 2001:DB8::/32 serviceNetwork: - 172.22.0.0/16 - fd03::/112 networkType: OVNKubernetes platform: baremetal: apiVIPs: - 192.168.11.3 - 2001:DB8::4 ingressVIPs: - 192.168.11.4 - 2001:DB8::5 ``` > [!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. `pullSecret` : Specifies your pull secret. `sshKey` : Specifies your SSH public key. `additionalTrustBundle` : Specifies the contents of the certificate file that you used for your mirror registry. The certificate file can be an existing, trusted certificate authority or the self-signed certificate that you generated for the mirror registry. You must specify this parameter if you are using a disconnected mirror registry. `imageContentSources` : Specifies the `imageContentSources` section according to the output of the command that you used to mirror the repository. You must specify this parameter if you are using a disconnected mirror registry. > [!IMPORTANT] > - When using the `oc adm release mirror` command, use the output from the `imageContentSources` section. > - When using the `oc mirror` command, use the `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` file that results from running the command. > - The `ImageContentSourcePolicy` resource is deprecated. 5. Create the `agent-config.yaml` file by running the following command: ```terminal $ cat > agent-config.yaml << EOF apiVersion: v1beta1 kind: AgentConfig metadata: name: sno-cluster rendezvousIP: 192.168.111.80 hosts: - hostname: master-0 interfaces: - name: eno1 macAddress: 00:ef:44:21:e6:a5 rootDeviceHints: deviceName: /dev/sdb networkConfig: interfaces: - name: eno1 type: ethernet state: up mac-address: 00:ef:44:21:e6:a5 ipv4: enabled: true address: - ip: 192.168.111.80 prefix-length: 23 dhcp: false dns-resolver: config: server: - 192.168.111.1 routes: config: - destination: 0.0.0.0/0 next-hop-address: 192.168.111.2 next-hop-interface: eno1 table-id: 254 minimalISO: true EOF ``` where: `rendezvousIP` : Specifies the IP address used to determine which node performs the bootstrapping process as well as running the `assisted-service` component. You must provide the rendezvous IP address when you do not specify at least one host’s IP address in the `networkConfig` parameter. If this address is not provided, one IP address is selected from the provided hosts' `networkConfig`. `hosts` : Specifies host configuration. The number of hosts defined must not exceed the total number of hosts defined in the `install-config.yaml` file, which is the sum of the values of the `compute.replicas` and `controlPlane.replicas` parameters. This configuration is optional. `hosts.hostname` : Specifies a value that 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. This configuration is optional. `hosts.rootDeviceHints` : Specifies a configuration that enables provisioning of the Red Hat Enterprise Linux CoreOS (RHCOS) 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. > [!NOTE] > This parameter is mandatory for FCP multipath configurations on IBM Z. `hosts.networkConfig` : Specifies the network interface configuration of a host in NMState format. This configuration is optional. `minimalISO` : Specifies whether to generate an ISO image without the rootfs image file, instead providing details about where to pull the rootfs file from. You must set this parameter to `true` to enable iSCSI booting. **Additional resources** {._additional-resources} - [Deploying with dual-stack networking](/openshift-docs-markdown/installing/installing_bare_metal/ipi/ipi-install-installation-workflow#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow) - [Configuring the install-config yaml file](/openshift-docs-markdown/installing/installing_bare_metal/ipi/ipi-install-installation-workflow#configuring-the-install-config-file_ipi-install-installation-workflow) - [Configuring a three-node cluster](/openshift-docs-markdown/installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal#installation-three-node-cluster_installing-restricted-networks-bare-metal) - [About root device hints](/openshift-docs-markdown/installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer#root-device-hints_preparing-to-install-with-agent-based-installer) - [NMState state examples (NMState documentation)](https://nmstate.io/examples.html) - [Optional: Creating additional manifest files](/openshift-docs-markdown/installing/installing_with_agent_based_installer/installing-with-agent-based-installer#installing-ocp-agent-opt-manifests_installing-with-agent-based-installer) - [Verifying the supported architecture for an Agent-based installation](/openshift-docs-markdown/installing/installing_with_agent_based_installer/installing-with-agent-based-installer#agent-install-verifying-architectures_installing-with-agent-based-installer) ## Creating the installation files {#installing-ocp-agent-iscsi-files_installing-using-iscsi} Generate the ISO image and create an iPXE script to upload to your iSCSI target. **Procedure** 1. Create the agent image by running the following command: ```terminal $ openshift-install --dir agent create image ``` 2. Create an iPXE script by running the following command: ```terminal $ cat << EOF > agent.ipxe !ipxe set initiator-iqn :\${hostname} sanboot --keep iscsi:.1:::::\${hostname} EOF ``` where: `` : Specifies the iSCSI initiator name on the host that is booting the ISO. This name can also be used by the iSCSI target. `` : Specifies the IP address of the iSCSI target. `` : Specifies the iSCSI target name. This name can be the same as the initiator name. ```terminal {title="Example Command"} $ 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 ```