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:

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   $ echo ${OFFLINE_TOKEN}

Procedure

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

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

2. Confirm the API_TOKEN variable definition:

   Copy to Clipboard Toggle word wrap

   $ echo ${API_TOKEN}

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

   Copy to Clipboard Toggle word wrap

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

   Then, save the file.

4. Change the file mode to make it executable:

   Copy to Clipboard Toggle word wrap

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

5. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

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

   Copy to Clipboard Toggle word wrap

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

   Example output

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   $ 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"
       }
   ')"

   1

   Slurp the pull secret file.

   2

   Format the pull secret to escaped JSON format.

6. Confirm the PULL_SECRET variable definition:

   Copy to Clipboard Toggle word wrap

   $ echo ${PULL_SECRET}

Procedure

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

   Copy to Clipboard Toggle word wrap

   $ cat /root/.ssh/id_rsa.pub

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

   Copy to Clipboard Toggle word wrap

   $ CLUSTER_SSHKEY=<downloaded_ssh_key>

3. Confirm the CLUSTER_SSHKEY variable definition:

   Copy to Clipboard Toggle word wrap

   $ echo ${CLUSTER_SSHKEY}

Procedure

1. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

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

   • Register the cluster by referencing the pull secret file in the request:

     Copy to Clipboard Toggle word wrap

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

   • Register the cluster by doing the following:

     1. Writing the configuration to a JSON file:

        Copy to Clipboard Toggle word wrap

        $ 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

     2. Referencing it in the request:

        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'

        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

        Set the number of control plane nodes to 1 for a single-node OpenShift cluster, or to 3, 4, or 5 for a multi-node OpenShift Container Platform cluster. The option of 4 or 5 control plane nodes is available from OpenShift Container Platform 4.18 and higher. For details, see About specifying the number of control plane nodes.

        Note

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

        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:

   Copy to Clipboard Toggle word wrap

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

4. Check the status of the new cluster:

   Copy to Clipboard Toggle word wrap

   $ 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

Procedure

1. Follow the instructions for installing Assisted Installer using the Assisted Installer API.

2. When you reach the step for registering a new cluster, set the schedulable_masters attribute as follows:

   Copy to Clipboard Toggle word wrap

   $ 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 '
   {
     "schedulable_masters": true 

   1

   
   }
   ' | jq

   1

   Enables the scheduling of workloads on the control plane nodes.

Procedure

1. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

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

      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:

      Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

   $ export INFRA_ENV_ID=<id>

Procedure

1. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

2. Modify the infrastructure environment:

   Copy to Clipboard Toggle word wrap

   $ 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. Configure the discovery image if needed. For details, see Configuring the discovery image.

2. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

3. Get the download URL:

   Copy to Clipboard Toggle word wrap

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

   Example output

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

2. Get the host IDs:

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   $ 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

   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:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

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

   Copy to Clipboard Toggle word wrap

   $ 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

   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

   Copy to Clipboard Toggle word wrap

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

   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:

   Copy to Clipboard Toggle word wrap

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

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

Procedure

1. Refresh the API token:

   Copy to Clipboard Toggle word wrap

   $ source refresh-token

2. Install the cluster:

   Copy to Clipboard Toggle word wrap

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