Chapter 4. Installing with the Assisted Installer API

Procedure

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

4. Click Load Token.

   Important

   Disable pop-up blockers.

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

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

   $ export OFFLINE_TOKEN=<copied_api_token>

   Copy to Clipboard Toggle word wrap
   Tip

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

7. Click Download ocm CLI.
8. Copy the downloaded file to your path. For example, copy the file to /usr/bin or ~/.local/bin and create an ocm symbolic link.

9. Copy and paste the authentication command to your terminal and press Enter to login:

   $ ocm login --token="${OFFLINE_TOKEN}"

   Copy to Clipboard Toggle word wrap

Procedure

1. Set the API_TOKEN variable using the OFFLINE_TOKEN to validate the user.

   1. (Optional) On the command line terminal, execute the following command:

      $ 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. (Optional) On the command line terminal, login to the ocm client:

      $ ocm login --token="${OFFLINE_TOKEN}"

      Copy to Clipboard Toggle word wrap

      Then, generate an API token:

      $ export API_TOKEN=$(ocm token)

      Copy to Clipboard Toggle word wrap

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

3. Change the file mode to make it executable:

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

   Copy to Clipboard Toggle word wrap

4. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

5. 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",
           "high_availability_mode": "None",
           "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.

Procedure

1. Refresh the API token:

   $ source refresh-token

   Copy to Clipboard Toggle word wrap

2. Register a new cluster.

   1. Optional: You can register a new cluster by slurping 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.11",
          "cpu_architecture" : "<architecture_name>" 

      1

      
          "high_availability_mode": <cluster_type>, 

      2

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

      Copy to Clipboard Toggle word wrap
      Note

      1

      Use any of the following values: x86_64, arm64, ppc64le, s390x, multi. For a mixed-architecture cluster, only use multi.

      2

      Use the default value full to represent a multi-node OpenShift cluster, or none to represent a single-node OpenShift cluster.

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

      cat << EOF > cluster.json
      {
        "name": "testcluster",
        "openshift_version": "4.11",
        "high_availability_mode": "<cluster_type>",
        "base_dns_domain": "example.com",
        "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

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:

   $ 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

      Indicates the valid values. They are: x86_64, arm64, ppc64le, s390x, 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-infra-env",
       "image_type": "full-iso",
       "cluster_id": "$CLUSTER_ID",
       "pull_secret": $PULL_SECRET
      }
      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

Procedure

1. Configure the discovery image if needed. See Booting hosts using iPXE in Additional Resources.

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

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. If you are installing on a platform and want to integrate with the platform, see the following additional resource for details:
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. For installations on IBM Z (s390x) with z/VM, additional kernel arguments are required.

   1. To retrieve the hostIDs for the matching nodes, run the following command:

      curl https://api.openshift.com/api/assisted-install/v2/infra-envs/$INFRA_ENV_ID/hosts -H "Authorization: Bearer ${API_TOKEN}" | jq '.[]|[.id,.requested_hostname] | join("|")'

      Copy to Clipboard Toggle word wrap

   2. To specify the necessary kernel arguments, run the following command:

      curl https://api.stage.openshift.com/api/assisted-install/v2/infra-envs/${INFRA_ENV_ID}/hosts/$1/installer-args \
      -X PATCH \
      -H "Authorization: Bearer ${API_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '
      {
      "args": [
      "--append-karg", "rd.neednet=1",
      "--append-karg", "ip=10.14.6.3::10.14.6.1:255.255.255.0:master-0.boea3e06.lnxero1.boe:encbdd0:none",
      "--append-karg", "nameserver=10.14.6.1",
      "--append-karg", "ip=[fd00::3]::[fd00::1]:64::encbdd0:none",
      "--append-karg", "nameserver=[fd00::1]",
      "--append-karg", "zfcp.allow_lun_scan=0",
      "--append-karg", "rd.znet=qeth,0.0.bdd0,0.0.bdd1,0.0.bdd2,layer2=1",
      "--append-karg", "rd.dasd=0.0.5235"
      ]
      }
      ' | jq

      Copy to Clipboard Toggle word wrap
      Note

      Each host might have specific kernel arguments.

      Example output

      [
        "1062663e-7989-8b2d-7fbb-e6f4d5bb28e5"
      ]

      Copy to Clipboard Toggle word wrap

4. Modify the host:

   $ 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. 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 post-installation platform integration steps.