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>

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

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

   2. (Optional) On the command line terminal, login to the ocm client:

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

      Then, generate an API token:

      $ export API_TOKEN=$(ocm token)

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

3. Change the file mode to make it executable:

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

4. Refresh the API token:

   $ source refresh-token

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

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

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 ' 1
       {
           "name": "testcluster",
           "high_availability_mode": "None",
           "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.

Procedure

1. Refresh the API token:

   $ source refresh-token

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'

      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

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

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

Procedure

1. Refresh the API token:

   $ source refresh-token

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

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>" 1
            "pull_secret": $pull_secret[0] | tojson
          }
      ')" | jq '.id'

      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

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

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. Configure the discovery image if needed. See Booting hosts using iPXE in Additional Resources.

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

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

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. 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("|")'

   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

      Note

      Each host might have specific kernel arguments.

      Example output

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

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

   1

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