Chapter 5. Installing with the Assisted Installer API

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>

   Copy to Clipboard Toggle word wrap
   Tip

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

6. (Optional) Confirm the OFFLINE_TOKEN variable definition.

   $ echo ${OFFLINE_TOKEN}

   Copy to Clipboard Toggle word wrap

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" \
   )

   Copy to Clipboard Toggle word wrap

2. Confirm the API_TOKEN variable definition:

   $ echo ${API_TOKEN}

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   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" \
   )

   Copy to Clipboard Toggle word wrap

   Then, save the file.

4. Change the file mode to make it executable:

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

   Copy to Clipboard Toggle word wrap

5. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   Example output

   {
     "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"
     }
   }

   Copy to Clipboard Toggle word wrap

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 .)

   Copy to Clipboard Toggle word wrap

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 ' 

   1

   
       {
           "name": "testcluster",
           "control_plane_count": "3",
           "openshift_version": "4.11",
           "pull_secret": $pull_secret[0] | tojson, 

   2

   
           "base_dns_domain": "example.com"
       }
   ')"

   Copy to Clipboard Toggle word wrap

   1

   Slurp the pull secret file.

   2

   Format the pull secret to escaped JSON format.

6. Confirm the PULL_SECRET variable definition:

   $ echo ${PULL_SECRET}

   Copy to Clipboard Toggle word wrap

Procedure

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

   $ cat /root/.ssh/id_rsa.pub

   Copy to Clipboard Toggle word wrap

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

   $ CLUSTER_SSHKEY=<downloaded_ssh_key>

   Copy to Clipboard Toggle word wrap

3. Confirm the CLUSTER_SSHKEY variable definition:

   $ echo ${CLUSTER_SSHKEY}

   Copy to Clipboard Toggle word wrap

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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": "4.16", \ 

     1

     
           "control_plane_count": "<number>", \ 

     2

     
           "cpu_architecture" : "<architecture_name>", \ 

     3

     
           "base_dns_domain": "example.com", \
           "pull_secret": $pull_secret[0] | tojson \
       } \
       ')" | jq '.id'

     Copy to Clipboard Toggle word wrap

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

     $ cat << EOF > cluster.json
     {
       "name": "testcluster",
       "openshift_version": "4.16", 

     1

     
       "control_plane_count": "<number>",

     2

     
       "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

     Copy to Clipboard Toggle word wrap

     $ 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'

     Copy to Clipboard Toggle word wrap

     1 1

     Pay attention to the following:

     • 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 for version 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.

     2 2

     Optionally set the number of control plane nodes to 1 for a single-node OpenShift cluster, to 2 or more for a Two-Node OpenShift with Arbiter cluster, or to 3, 4, or 5 for a multi-node OpenShift Container Platform cluster. If this setting is omitted, the Assisted Installer sets 3 as the default.

     Note

     • The control_plane_count field replaces the high_availability_mode field, which is deprecated. For details, see API deprecation notice.
     • Currently, single-node OpenShift is not supported on IBM Z® and IBM Power® platforms.
     • 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 About specifying the number of control plane nodes.
     • The Assisted Installer supports 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. For details, see Two-Node OpenShift with Arbiter resource requirements.

     3

     Valid values are x86_64, arm64, ppc64le, s390x, or multi. Specify multi for a multi-architecture compute cluster.

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

   $ export CLUSTER_ID=<cluster_id>

   Copy to Clipboard Toggle word wrap
   Note

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

4. 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

   Copy to Clipboard Toggle word wrap

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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>", 

      1

      
            "pull_secret": $pull_secret[0] | tojson
          }
      ')" | jq '.id'

      Copy to Clipboard Toggle word wrap
      Note

      1

      Valid values are x86_64, arm64, ppc64le, s390x, and 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

      Copy to Clipboard Toggle word wrap

      $ 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'

      Copy to Clipboard Toggle word wrap

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

   $ export INFRA_ENV_ID=<id>

   Copy to Clipboard Toggle word wrap

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

Prerequisites

1. You have created an infrastructure environment using the API or have created a cluster using the web console.
2. You have your infrastructure environment ID exported in your shell as $INFRA_ENV_ID.
3. You have credentials to use when accessing the API and have exported a token as $API_TOKEN in your shell.
4. You have YAML files with a static network configuration available as server-a.yaml and server-b.yaml.

Procedure

1. Create a temporary file /tmp/request-body.txt with the API request:

   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

   Copy to Clipboard Toggle word wrap

2. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

3. 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

   Copy to Clipboard Toggle word wrap

Procedure

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

2. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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"
   }

   Copy to Clipboard Toggle word wrap

4. Download the discovery image:

   $ wget -O discovery.iso <url>

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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'

   Copy to Clipboard Toggle word wrap

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> \ 

   1

   
   -X PATCH \
   -H "Authorization: Bearer ${API_TOKEN}" \
   -H "Content-Type: application/json" \
   -d '
       {
         "host_role":"worker"
         "host_name" : "worker-1"
       }
   ' | jq

   Copy to Clipboard Toggle word wrap

   1

   Replace <host_id> with the ID of the host.

Procedure

1. Create a custom manifest file.
2. Save the custom manifest file using the appropriate extension for the file format.

3. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

4. Add the custom manifest to the cluster by executing the following command:

   $ curl -X POST "https://api.openshift.com/api/assisted-install/v2/clusters/$CLUSTER_ID/manifests" \
       -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
               "file_name":"manifest.json",
               "folder":"manifests",
               "content":"'"$(base64 -w 0 ~/manifest.json)"'"
       }' | jq

   Copy to Clipboard Toggle word wrap

   Replace manifest.json with the name of your manifest file. The second instance of manifest.json is the path to the file. Ensure the path is correct.

   Example output

   {
     "file_name": "manifest.json",
     "folder": "manifests"
   }

   Copy to Clipboard Toggle word wrap

   Note

   The base64 -w 0 command base64-encodes the manifest as a string and omits carriage returns. Encoding with carriage returns will generate an exception.

5. Verify that the Assisted Installer added the manifest:

   $ curl -X GET "https://api.openshift.com/api/assisted-install/v2/clusters/$CLUSTER_ID/manifests/files?folder=manifests&file_name=manifest.json" -H "Authorization: Bearer $API_TOKEN"

   Copy to Clipboard Toggle word wrap

   Replace manifest.json with the name of your manifest file.

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap
3. Complete any postinstallation platform integration steps.