Installing OpenShift Container Platform with the Assisted Installer

Procedure

1. Log in to the Red Hat Hybrid Cloud Console.
2. On the Red Hat OpenShift tile, click OpenShift.
3. On the Red Hat OpenShift Container Platform tile, click Create cluster.
4. Click the Datacenter tab.
5. Under Assisted Installer, click Create cluster.

6. Enable the I’m installing on a disconnected/air-gapped/secured environment toggle to deploy an OpenShift Container Platform cluster by using a self-contained ISO image. The image includes a simplified user interface together with all necessary artifacts. This method supports installations in both connected and disconnected environments without requiring an external or local registry. It currently addresses Red Hat OpenShift Virtualization Engine use cases.

   This installation method is outside the scope of this guide. For details and installation instructions, see Installing a cluster without an external registry in the OpenShift Container Platform documentation.

   Important

   Installing a Red Hat OpenShift Virtualization Engine cluster using this method is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

   For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

7. Enter a name for the cluster in the Cluster name field.

8. Enter a base domain for the cluster in the Base domain field. All subdomains for the cluster will use this base domain.

   Note

   The base domain must be a valid DNS name. You must not have a wildcard domain set up for the base domain.

9. From the OpenShift version dropdown list, select the version that you want to install and click Select. By default, the dropdown lists the latest OpenShift version. If you need an older version that is not displayed, click Show all available versions at the bottom of the list, and use the search box to find it.

   Important
   • For a multi-architecture compute cluster installation, select OpenShift Container Platform 4.12 or later, and use the -multi option. For instructions on installing a multi-architecture compute cluster, see Installing multi-architecture compute clusters.
   • For IBM Power® and IBM Z® platforms, only OpenShift Container Platform 4.13 and later is supported.
   • If you are booting from an iSCSI drive, select OpenShift Container Platform version 4.15 or later.

10. Optional: The Assisted Installer defaults to using x86_64 CPU architecture. If you are installing OpenShift Container Platform on a different architecture, select the architecture to use. Valid values are arm64, ppc64le, and s390x. Remember that some features are not available with arm64, ppc64le, and s390x CPU architectures.

    Important

    For a multi-architecture compute cluster installation, you can use x86_64 or 64-bit ARM CPU architecture for the control plane nodes. Automatic conversion from x86_64 to 64-bit ARM is only supported on Amazon Web Services (AWS). For instructions on installing a multi-architecture compute cluster, see Installing multi-architecture compute clusters.

11. Optional: The Assisted Installer already has the pull secret associated to your account. If you want to use a different pull secret, select Edit pull secret.

12. Optional: If you are installing OpenShift Container Platform on a third-party platform, select the platform from the Integrate with external partner platforms list. Valid values are Nutanix, vSphere or Oracle Cloud Infrastructure. The Assisted Installer defaults to having no platform integration.

    Note
    • The Assisted Installer supports Oracle Cloud Infrastructure (OCI) integration from OpenShift Container Platform 4.14 and later.
    • For details on external partner integrations, see Additional resources.

13. From the Number of control plane nodes field, optionally change the default value of three control plane nodes for your installation. The possible options are 1 (single-node OpenShift), 2, 3, 4, or 5.

    Important

    The Assisted Installer supports the following control plane node configurations:

    • 4 or 5 control plane nodes from OpenShift Container Platform 4.18 and later, on a bare metal or user-managed networking platform with an x86_64 CPU architecture.
    • 2 control plane nodes from OpenShift Container Platform 4.19 and later, for a Two-Node OpenShift with Arbiter cluster topology. If the number of control plane nodes for a cluster is 2, then it must have at least one additional arbiter host.
    • Currently, single-node OpenShift is not supported on IBM Power® platform.

    For details, see Control plane count.

14. Optional: Select Include custom manifests if you have at least one custom manifest to include in the installation. A custom manifest has additional configurations not currently supported in the Assisted Installer. Selecting the checkbox adds the Custom manifests step to the wizard, where you upload the manifests.

    Important
    • If you are installing OpenShift Container Platform on the Oracle Cloud Infrastructure (OCI) third-party platform, it is mandatory to add the custom manifests provided by Oracle.
    • If you have already added custom manifests, clearing the Include custom manifests checkbox automatically deletes them all. You must confirm the deletion.

15. Optional: The Assisted Installer defaults to DHCP networking. If you are using a static IP configuration, bridges or bonds for the cluster nodes instead of DHCP reservations, select Static IP, bridges, and bonds. Selecting the checkbox adds the Static network configurations step to the wizard. For details, see Configuring static networks.

    Important

    A static IP configuration is not supported in the following scenarios:

    • OpenShift Container Platform installations on Oracle Cloud Infrastructure.
    • OpenShift Container Platform installations on iSCSI boot volumes.

16. Optional: If you want to enable encryption of the installation disks, under Enable encryption of installation disks you can select one of the following:

    • For single-node OpenShift, select Control plane node, worker.

    • For multi-node clusters, select Control plane nodes to encrypt the control plane node installation disks. Select Workers to encrypt worker node installation disks. Select Arbiter to encrypt the arbiter node installation disks.

      Important

      You cannot change the base domain, the single-node OpenShift checkbox, the CPU architecture, the host’s network configuration, or the disk-encryption after installation begins.

Procedure

1. In the Host discovery step, click the Add hosts button and select the provisioning type.

   1. Select Minimal image file: Provision with virtual media to download a smaller image that will fetch the data needed to boot. The nodes must have virtual media capability. This is the recommended method for x86_64 and arm64 architectures.

      Important

      This option is mandatory in the following scenarios:

      • If you are installing OpenShift Container Platform on Oracle Cloud Infrastructure.
      • If you are installing OpenShift Container Platform on iSCSI boot volumes.
   2. Select Full image file: Provision with physical media to download the larger full image. This is the recommended method for the ppc64le architecture and for the s390x architecture when installing with RHEL KVM.

   3. Select iPXE: Provision from your network server to boot the hosts using iPXE. This is the recommended method on IBM Z® with z/VM nodes and LPAR (both static and DPM). ISO boot is the recommended method on the RHEL KVM installation.

      Note

      If you are installing OpenShift Container Platform on RHEL KVM, in some circumstances, the VMs on the KVM host are not rebooted on first boot and need to be restarted manually.

2. Optional: Activate the Run workloads on control plane nodes switch to schedule workloads to run on control plane nodes, in addition to the default worker nodes.

   Note

   This option is available for clusters of five or more nodes. For clusters of under five nodes, the system runs workloads on the control plane nodes only, by default. For more details, see Control plane workload scheduling.

3. Optional: If the cluster hosts require the use of a proxy, select Configure cluster-wide proxy settings. Enter the username, password, required domains or IP addresses, and port for the HTTP and HTTPS URLs of the proxy server. If the cluster hosts are behind a firewall, allow the nodes to access the required domains or IP addresses through the firewall. For details, see Configuring your firewall for OpenShift Container Platform.

   Note

   The proxy username and password must be URL-encoded.

4. Optional: Add an SSH public key so that you can connect to the cluster nodes as the core user. Having a login to the cluster nodes can provide you with debugging information during the installation.

   Important

   Do not skip this procedure in production environments, where disaster recovery and debugging is required.

   1. If you do not have an existing SSH key pair on your local machine, follow the steps in Generating a key pair for cluster node SSH access.
   2. In the SSH public key field, click Browse to upload the id_rsa.pub file containing the SSH public key. Alternatively, drag and drop the file into the field from the file manager. To see the file in the file manager, select Show hidden files in the menu.
5. Optional: If the cluster hosts are in a network with a re-encrypting man-in-the-middle (MITM) proxy, or if the cluster needs to trust certificates for other purposes such as container image registries, select Configure cluster-wide trusted certificates. Add additional certificates in X.509 format.
6. Configure the discovery image if needed. For details, see Configuring the discovery image.
7. Optional: If you are installing on a platform and want to integrate with the platform, select Integrate with your virtualization platform. You must boot all hosts and ensure they appear in the host inventory. All the hosts must be on the same platform. For more details, see the relevant platform in Additional resources.
8. Click Generate Discovery ISO or Generate Script File.
9. Download the discovery ISO or iPXE script.
10. Boot the host(s) with the discovery image or iPXE script. For details, see Booting hosts with the discovery image.

Procedure

1. Go to the Host Discovery tab.

2. In multi-host clusters, you can select a role for each host after host discovery:

   1. In the Role column, expand the Auto-assign arrow for the host.

   2. Choose one of the following options:

      • Auto-assign - Automatically determines whether the host is a control plane, worker or arbiter node. This is the default setting.
      • Control plane node - Assigns the control plane (master) role to the host, allowing the host to manage and coordinate the cluster.
      • Worker - Assigns the compute (worker) role to the host, enabling the host to run application workloads.
      • Arbiter - Assigns the arbiter role to a host, providing a cost-effective solution for components that require a quorum.

      The minimum hardware requirements for control plane nodes exceed that of worker nodes. If you assign a role to a host, ensure that you assign the control plane role to hosts that meet the minimum hardware requirements.

      For more details about the different host roles, see Supported host roles.

3. Click the Status link to view hardware, network, and operator validations for the host.
4. Optionally select or deselect all hosts by clicking the <number> selected checkbox or alternatively by selecting Select all or Select none from the dropdown list.

5. Optionally change one or more hostnames:

   1. To rename a single host, from the Options (⋮) menu for the host, select Change hostname. If necessary, enter a new name for the host and click Change. You must ensure that each host has a valid and unique hostname.

   2. To rename multiple selected hosts, from the Actions list, select Change hostname. In the Change Hostname dialog, type the new name and include {{n}} to make each hostname unique. Then click Change.

      Note

      You can see the new names appearing in the Preview pane as you type. The name will be identical for all selected hosts, with the exception of a single-digit increment per host.

6. Optionally remove one or more hosts:

   1. To remove a single host, from the Options (⋮) menu for the host, select Remove host. Click Remove host to confirm the deletion.
   2. To remove multiple selected hosts at the same time, from the Actions list, select Remove. Click Remove hosts to confirm the deletion.
   Note

   In a regular deployment, a cluster can have three or more hosts, and at least three of these must be control plane nodes. If you delete a host that is also a control plane node, or if there are only two hosts, you will get a message saying that the system is not ready. To restore a host, you must reboot it from the discovery ISO.

7. From the Options (⋮) menu for the host, optionally select View host events. The events in the list are presented chronologically.

8. Click the arrow to the left of a host name to expand the host details.

   Once all cluster hosts appear with a status of Ready, proceed to the next step.

Procedure

1. In the Networking step, select one of the following network management types if it is not already selected for you:

   • Cluster-Managed Networking: Selecting cluster-managed networking means that the Assisted Installer will configure a standard network topology. This configuration includes an integrated load balancer and virtual routing for managing the API and Ingress VIP addresses. For details, see Cluster-managed networking.

     Note
     • Currently, cluster-managed networking is not supported on IBM Z® and IBM Power®.
     • Cluster-managed networking is not supported on single-node OpenShift.

   • User-Managed Networking: Selecting user-managed networking deploys OpenShift Container Platform with a non-standard network topology. Select user-managed networking if you want to deploy with an external load balancer and DNS, or if you intend to deploy the cluster nodes across many distinct subnets. For details, see User-managed networking.

     Note

     Oracle Cloud Infrastructure (OCI) is available for OpenShift Container Platform 4.14 with a user-managed networking configuration only.

   Important

   The Assisted Installer supports a third network management type called Cluster-Managed Networking with a User-Managed Load Balancer. This network management type provides automated cluster networking with an external load balancer. Currently you can configure this network management type through the API only. For details, see Installing cluster-managed networking with a user-managed load balancer.

2. For cluster-managed networking, configure the following settings:

   1. Select your Networking stack type:

      • IPv4: Select this type when your hosts are only using IPv4.

      • Dual-stack: Select dual-stack when your hosts use IPv4 with IPv6, with either stack set as primary.

        Note
        • IPv6 is not currently supported for single stack.
        • IPv4 networking with SDN is supported up to OpenShift Container Platform 4.14.
        • IPv4 and dual-stack IPv4/IPv6 networking with OVN only are supported in OpenShift Container Platform 4.15 and later.
        Important

        Support for IPv6 as the primary stack in a dual-stack configuration is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

        For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

   2. Define the Machine network. You can use the default network or select a subnet from the dropdown list.

      For a dual-stack implementation, specify both a primary and a secondary machine network, ensuring that one is IPv4 and the other IPv6. When you select IPv6 as the primary network, the secondary network dropdown list shows only IPv4 options, and vice versa.

      Important

      For iSCSI boot volumes, the hosts connect over two machine networks: one designated for the OpenShift Container Platform installation and the other for iSCSI traffic. Ensure you select the OpenShift Container Platform network from the dropdown list. The iSCSI host IP address should not be on the machine network. Choosing the iSCSI network will result in an Insufficient status for the host in the Networking step.

   3. Define an API virtual IP. An API virtual IP provides an endpoint for all users to interact with and configure the platform.

      For a dual-stack implementation, define the API virtual IP for both the primary and secondary stack. The IP family (IPv4 or IPv6) must match the corresponding machine network family.

   4. Define an Ingress virtual IP. An Ingress virtual IP provides an endpoint for application traffic flowing from outside the cluster.

      For a dual-stack implementation, define the Ingress virtual IP for both the primary and secondary stack. The IP family (IPv4 or IPv6) must match the corresponding machine network family.

3. Configure the advanced networking properties:

   • For an IPv4 implementation, optionally select Use advanced networking to configure the following properties:

     • Cluster network CIDR: Define an IP address block to assign pod IP addresses.
     • Cluster network host prefix: Define a subnet prefix length to assign to each node.
     • Service network CIDR: Define an IP address block to assign service IP addresses.
   • For a dual-stack implementation, these fields are mandatory and populated automatically for both primary and secondary stacks, according to the machine networks selected. You can change these values as required.
4. Optional: Select Host SSH Public Key for troubleshooting after installation to connect to hosts using a public SSH key for troubleshooting after installation.
5. Wait for the validations to complete, and then click Next. The Review and create page presents a summary of your configurations in the Networking section.

Procedure

1. In the Review and create step, click Install cluster.
2. Click the link in the Status column of the Host Inventory list to see the installation status of a particular host.

Procedure

1. Make a copy of the kubeadmin username and password.

2. Download the kubeconfig file and copy it to the auth directory under your working directory:

   $ mkdir -p <working_directory>/auth

   $ cp kubeconfig <working_directory>/auth

   Note

   The kubeconfig file is available for download for 20 days after completing the installation.

3. Add the kubeconfig file to your environment:

   $ export KUBECONFIG=<your working directory>/auth/kubeconfig

4. Login with the oc CLI tool:

   $ oc login -u kubeadmin -p <password>

   Replace <password> with the password of the kubeadmin user.

5. Click the web console URL or click Launch OpenShift Console to open the console.
6. Enter the kubeadmin username and password. Follow the instructions in the OpenShift Container Platform console to configure an identity provider and configure alert receivers.
7. Add a bookmark of the OpenShift Container Platform console.
8. Complete any postinstallation platform integration steps.

Procedure

1. In the menu, click Downloads.
2. In the Tokens section under OpenShift Cluster Manager API Token, click View API Token.

3. Click Load Token.

   Important

   Disable pop-up blockers.

4. In the Your API token section, copy the offline token.

5. In your terminal, set the offline token to the OFFLINE_TOKEN variable:

   $ export OFFLINE_TOKEN=<copied_token>

   Tip

   To make the offline token permanent, add it to your profile.

6. (Optional) Confirm the OFFLINE_TOKEN variable definition.

   $ echo ${OFFLINE_TOKEN}

Procedure

1. On the command line terminal, set the API_TOKEN variable using the OFFLINE_TOKEN to validate the user.

   $ export API_TOKEN=$( \
     curl \
     --silent \
     --header "Accept: application/json" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=refresh_token" \
     --data-urlencode "client_id=cloud-services" \
     --data-urlencode "refresh_token=${OFFLINE_TOKEN}" \
     "https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token" \
     | jq --raw-output ".access_token" \
   )

2. Confirm the API_TOKEN variable definition:

   $ echo ${API_TOKEN}

3. Create a script in your path for one of the token generating methods. For example:

   $ vim ~/.local/bin/refresh-token

   export API_TOKEN=$( \
     curl \
     --silent \
     --header "Accept: application/json" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=refresh_token" \
     --data-urlencode "client_id=cloud-services" \
     --data-urlencode "refresh_token=${OFFLINE_TOKEN}" \
     "https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token" \
     | jq --raw-output ".access_token" \
   )

   Then, save the file.

4. Change the file mode to make it executable:

   $ chmod +x ~/.local/bin/refresh-token

5. Refresh the API token:

   $ source refresh-token

6. Verify that you can access the API by running the following command:

   $ curl -s https://api.openshift.com/api/assisted-install/v2/component-versions -H "Authorization: Bearer ${API_TOKEN}" | jq

   Result

   {
     "release_tag": "v2.11.3",
     "versions": {
       "assisted-installer": "registry.redhat.io/rhai-tech-preview/assisted-installer-rhel8:v1.0.0-211",
       "assisted-installer-controller": "registry.redhat.io/rhai-tech-preview/assisted-installer-reporter-rhel8:v1.0.0-266",
       "assisted-installer-service": "quay.io/app-sre/assisted-service:78d113a",
       "discovery-agent": "registry.redhat.io/rhai-tech-preview/assisted-installer-agent-rhel8:v1.0.0-195"
     }
   }

Procedure

1. In the menu, click OpenShift.
2. In the submenu, click Downloads.
3. In the Tokens section under Pull secret, click Download.

4. To use the pull secret from a shell variable, execute the following command:

   $ export PULL_SECRET=$(cat ~/Downloads/pull-secret.txt | jq -R .)

5. To slurp the pull secret file using jq, reference it in the pull_secret variable, piping the value to tojson to ensure that it is properly formatted as escaped JSON. For example:

   $ curl https://api.openshift.com/api/assisted-install/v2/clusters \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -H "Content-Type: application/json" \
   -d "$(jq --null-input \
           --slurpfile pull_secret ~/Downloads/pull-secret.txt '
       {
           "name": "testcluster",
           "control_plane_count": "3",
           "openshift_version": "4.11",
           "pull_secret": $pull_secret[0] | tojson,
           "base_dns_domain": "example.com"
       }
   ')"

   where:

   • --slurpfile pull_secret ~/Downloads/pull-secret.txt slurps the pull secret file.
   • "pull_secret": $pull_secret[0] | tojson formats the pull secret to escaped JSON format.

6. Confirm the PULL_SECRET variable definition:

   $ echo ${PULL_SECRET}

Procedure

1. From the root user in your terminal, get the SSH public key:

   $ cat /root/.ssh/id_rsa.pub

2. Set the SSH public key to the CLUSTER_SSHKEY variable:

   $ CLUSTER_SSHKEY=<downloaded_ssh_key>

3. Confirm the CLUSTER_SSHKEY variable definition:

   $ echo ${CLUSTER_SSHKEY}

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Register a new cluster by using one of the following methods:

   • Reference the pull secret file in the request:

     $ curl -s -X POST https://api.openshift.com/api/assisted-install/v2/clusters \
       -H "Authorization: Bearer ${API_TOKEN}" \
       -H "Content-Type: application/json" \
       -d "$(jq --null-input \
           --slurpfile pull_secret ~/Downloads/pull-secret.txt ' \
       { \
           "name": "testcluster", \
           "openshift_version": "<version>", \
           "control_plane_count": "<number>", \
           "cpu_architecture" : "<architecture_name>", \
           "base_dns_domain": "example.com", \
           "pull_secret": $pull_secret[0] | tojson \
       } \
       ')" | jq '.id'

   • Write the configuration to a JSON file and then reference it in the request:

     $ cat << EOF > cluster.json
     {
       "name": "testcluster",
       "openshift_version": "<version>",
       "control_plane_count": "<number>",
       "base_dns_domain": "example.com",
       "network_type": "examplenetwork",
       "cluster_network_cidr":"11.111.1.0/14"
       "cluster_network_host_prefix": 11,
       "service_network_cidr": "111.11.1.0/16",
       "api_vips":[{"ip": ""}],
       "ingress_vips": [{"ip": ""}],
       "vip_dhcp_allocation": false,
       "additional_ntp_source": "clock.redhat.com,clock2.redhat.com",
       "ssh_public_key": "$CLUSTER_SSHKEY",
       "pull_secret": $PULL_SECRET
     }
     EOF

     $ curl -s -X POST "https://api.openshift.com/api/assisted-install/v2/clusters" \
       -d @./cluster.json \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $API_TOKEN" \
       | jq '.id'

3. Set the values as follows:

   • Replace <version> with the OpenShift Container Platform version:

     • To install the latest OpenShift version, use the x.y format, such as 4.16 for version 4.16.10. To install a specific OpenShift version, use the x.y.z format, such as 4.16.3.
     • To install a multi-architecture compute cluster, add the -multi extension, such as 4.16-multi for the latest version or 4.16.3-multi for a specific version.
     • If you are booting from an iSCSI drive, enter OpenShift Container Platform version 4.15 or later.

   • Replace <number> with the number of control planes in your cluster. Possible values are as follows:

     • 1 for a single-node OpenShift cluster. Currently, single-node OpenShift is not supported on IBM Power® platform.
     • 2 or more for a Two-Node OpenShift with Arbiter cluster. This option is supported from OpenShift Container Platform 4.19 and later on a Two-Node OpenShift with Arbiter cluster topology. A cluster with 2 control plane nodes must have at least one additional arbiter host. For details, see Two-Node OpenShift with Arbiter resource requirements.
     • 3, 4, or 5 for a multi-node OpenShift Container Platform cluster. If control_plane_count is omitted, the default setting is 3. The Assisted Installer supports 4 or 5 control plane nodes from OpenShift Container Platform 4.18 and later, on a bare metal or user-managed networking platform with an x86_64 CPU architecture. For details, see Control plane count.

   • If you are referencing the pull secret, replace <architecture_name> with the CPU architecture. Options include x86_64, arm64, ppc64le, s390x, or multi. Specify multi for a multi-architecture compute cluster.

     Note

     The control_plane_count field replaces the high_availability_mode field, which is deprecated. For details, see API deprecation notice.

4. Assign the returned cluster_id to the CLUSTER_ID variable and export it:

   $ export CLUSTER_ID=<cluster_id>

   Note

   If you close your terminal session, you need to export the CLUSTER_ID variable again in a new terminal session.

5. Check the status of the new cluster:

   $ curl -s -X GET "https://api.openshift.com/api/assisted-install/v2/clusters/$CLUSTER_ID" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $API_TOKEN" \
     | jq

   Once you register a new cluster definition, create the infrastructure environment for the cluster.

   Note

   You cannot see the cluster configuration settings in the Assisted Installer user interface until you create the infrastructure environment.

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Modify the cluster. For example, change the SSH key:

   $ curl https://api.openshift.com/api/assisted-install/v2/clusters/${CLUSTER_ID} \
   -X PATCH \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -H "Content-Type: application/json" \
   -d '
   {
       "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDZrD4LMkAEeoU2vShhF8VM+cCZtVRgB7tqtsMxms2q3TOJZAgfuqReKYWm+OLOZTD+DO3Hn1pah/mU3u7uJfTUg4wEX0Le8zBu9xJVym0BVmSFkzHfIJVTn6SfZ81NqcalisGWkpmkKXVCdnVAX6RsbHfpGKk9YPQarmRCn5KzkelJK4hrSWpBPjdzkFXaIpf64JBZtew9XVYA3QeXkIcFuq7NBuUH9BonroPEmIXNOa41PUP1IWq3mERNgzHZiuU8Ks/pFuU5HCMvv4qbTOIhiig7vidImHPpqYT/TCkuVi5w0ZZgkkBeLnxWxH0ldrfzgFBYAxnpTU8Ih/4VhG538Ix1hxPaM6cXds2ic71mBbtbSrk+zjtNPaeYk1O7UpcCw4jjHspU/rVV/DY51D5gSiiuaFPBMucnYPgUxy4FMBFfGrmGLIzTKiLzcz0DiSz1jBeTQOX++1nz+KDLBD8CPdi5k4dq7lLkapRk85qdEvgaG5RlHMSPSS3wDrQ51fD8= user@hostname"
   }
   ' | jq

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Register a new infrastructure environment. Provide a name, preferably something including the cluster name. This example provides the cluster ID to associate the infrastructure environment with the cluster resource. The following example specifies the image_type. You can specify either full-iso or minimal-iso. The default value is minimal-iso.

   1. Optional: You can register a new infrastructure environment by slurping the pull secret file in the request:

      $ curl https://api.openshift.com/api/assisted-install/v2/infra-envs \
      -H "Authorization: Bearer ${API_TOKEN}" \
      -H "Content-Type: application/json" \
      -d "$(jq --null-input \
        --slurpfile pull_secret ~/Downloads/pull-secret.txt \
        --arg cluster_id ${CLUSTER_ID} '
          {
            "name": "testcluster-infra-env",
            "image_type":"full-iso",
            "cluster_id": $cluster_id,
            "cpu_architecture" : "<architecture_name>",
            "pull_secret": $pull_secret[0] | tojson
          }
      ')" | jq '.id'

      Replace <architecture_name> with one of the following CPU architectures: x86_64, arm64, ppc64le, s390x, or multi.

   2. Optional: You can register a new infrastructure environment by writing the configuration to a JSON file and then referencing it in the request:

      $ cat << EOF > infra-envs.json
      {
       "name": "testcluster",
       "pull_secret": $PULL_SECRET,
       "proxy": {
          "http_proxy": "",
          "https_proxy": "",
          "no_proxy": ""
        },
        "ssh_authorized_key": "$CLUSTER_SSHKEY",
        "image_type": "full-iso",
        "cluster_id": "${CLUSTER_ID}",
        "openshift_version": "4.11"
      }
      EOF

      $ curl -s -X POST "https://api.openshift.com/api/assisted-install/v2/infra-envs"
       -d @./infra-envs.json
       -H "Content-Type: application/json"
       -H "Authorization: Bearer $API_TOKEN"
       | jq '.id'

3. Assign the returned id to the INFRA_ENV_ID variable and export it:

   $ export INFRA_ENV_ID=<id>

   Note

   Once you create an infrastructure environment and associate it to a cluster definition via the cluster_id, you can see the cluster settings in the Assisted Installer web user interface. If you close your terminal session, you need to re-export the id in a new terminal session.

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Modify the infrastructure environment:

   $ curl https://api.openshift.com/api/assisted-install/v2/infra-envs/${INFRA_ENV_ID} \
   -X PATCH \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -H "Content-Type: application/json" \
   -d "$(jq --null-input \
     --slurpfile pull_secret ~/Downloads/pull-secret.txt '
       {
         "image_type":"minimal-iso",
         "pull_secret": $pull_secret[0] | tojson
       }
   ')" | jq

Procedure

1. Create YAML files with a static network configuration available as server-a.yaml and server-b.yaml. For guidance, see NMState configuration examples.

2. Optional: Get the MAC address of the host by running the following command:

   $ ip addr

   You will need this information for the MAC to interface name mapping in the next step.

3. Create a temporary file /tmp/request-body.txt with the API request and the MAC to interface mapping, as in the example below:

   $ jq -n --arg NMSTATE_YAML1 "$(cat server-a.yaml)" --arg NMSTATE_YAML2 "$(cat server-b.yaml)" \
   '{
     "static_network_config": [
       {
         "network_yaml": $NMSTATE_YAML1,
         "mac_interface_map": [{"mac_address": "02:00:00:2c:23:a5", "logical_nic_name": "eth0"}, {"mac_address": "02:00:00:68:73:dc", "logical_nic_name": "eth1"}]
       },
       {
         "network_yaml": $NMSTATE_YAML2,
         "mac_interface_map": [{"mac_address": "02:00:00:9f:85:eb", "logical_nic_name": "eth1"}, {"mac_address": "02:00:00:c8:be:9b", "logical_nic_name": "eth0"}]
        }
     ]
   }' >> /tmp/request-body.txt

   For more details, see MAC to interface mapping.

4. Refresh the API token:

   $ source refresh-token

5. Send the request to the Assisted Service API endpoint:

   $ curl -H "Content-Type: application/json" \
   -X PATCH -d @/tmp/request-body.txt \
   -H "Authorization: Bearer ${API_TOKEN}" \
   https://api.openshift.com/api/assisted-install/v2/infra-envs/$INFRA_ENV_ID

Procedure

1. Configure the discovery image if needed. For details, see Configuring the discovery image.

2. Refresh the API token:

   $ source refresh-token

3. Get the download URL:

   $ curl -H "Authorization: Bearer ${API_TOKEN}" \
   https://api.openshift.com/api/assisted-install/v2/infra-envs/${INFRA_ENV_ID}/downloads/image-url

   Example output:

   {
     "expires_at": "2024-02-07T20:20:23.000Z",
     "url": "https://api.openshift.com/api/assisted-images/bytoken/<TOKEN>/<OCP_VERSION>/<CPU_ARCHITECTURE>/<FULL_OR_MINIMAL_IMAGE>.iso"
   }

4. Download the discovery image:

   $ wget -O discovery.iso <url>

   Replace <url> with the download URL from the previous step.

5. Boot the host(s) with the discovery image.
6. Assign a role to host(s).

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Get the host IDs:

   $ curl -s -X GET "https://api.openshift.com/api/assisted-install/v2/clusters/$CLUSTER_ID" \
   --header "Content-Type: application/json" \
     -H "Authorization: Bearer $API_TOKEN" \
   | jq '.host_networks[].host_ids'

3. Modify the host settings by using the example below:

   $ curl https://api.openshift.com/api/assisted-install/v2/infra-envs/${INFRA_ENV_ID}/hosts/<host_id> \
   -X PATCH \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -H "Content-Type: application/json" \
   -d '
       {
         "host_role":"worker"
         "host_name" : "worker-1"
       }
   ' | jq

   Replace <host_id> with the ID of the host.

Procedure

1. Refresh the API token:

   $ source refresh-token

2. Install the cluster:

   $ curl -H "Authorization: Bearer $API_TOKEN" \
   -X POST \
   https://api.openshift.com/api/assisted-install/v2/clusters/$CLUSTER_ID/actions/install | jq

3. Complete any postinstallation platform integration steps.