Chapter 4. Installing with the Assisted Installer API

After you ensure the cluster nodes and network requirements are met, you can begin installing the cluster using the Assisted Installer API. To use the API, you must perform the following procedures:

  • Set up the API authentication.
  • Configure the pull secret.
  • Register a new cluster definition.
  • Create an infrastructure environment for the cluster.

Once you perform these steps, you can modify the cluster definition, create discovery ISOs, add hosts to the cluster, and install the cluster. This document does not cover every endpoint of the Assisted Installer API, but you can review all of the endpoints in the API viewer or the swagger.yaml file.

4.1. Optional: Installing the OpenShift Cluster Manager CLI

The OpenShift Cluster Manager (ocm) CLI tool enables you to interact with the OpenShift Cluster Manager from the command line. You can execute REST GET, POST, PATCH, and DELETE operations, generate API tokens, and list clusters among other features.

Important

OpenShift Cluster Manager CLI is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA.

Prerequisites

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

4.2. Authenticating with the REST API

API calls require authentication with the API token. Assuming you use API_TOKEN as a variable name, add -H "Authorization: Bearer ${API_TOKEN}" to API calls to authenticate with the REST API.

Note

The API token expires after 15 minutes.

Prerequisites

  • (Optional) You have installed the OpenShift Cluster Manager (ocm) CLI tool.

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)

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

  2. Change the file mode to make it executable: 

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

  3. Refresh the API token: 

    $ source refresh-token

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

4.3. Configuring the pull secret

Many of the Assisted Installer API calls require the pull secret. Download the pull secret to a file so that you can reference it in API calls. The pull secret is a JSON object that will be included as a value within the request’s JSON object. The pull secret JSON must be formatted to escape the quotes. For example:

Before

{"auths":{"cloud.openshift.com": ...

After

{\"auths\":{\"cloud.openshift.com\": ...

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.

4.4. Registering a new cluster

To register a new cluster definition with the API, use the /v2/clusters endpoint. Registering a new cluster requires the following settings:

  • name
  • openshift-version
  • pull_secret
  • cpu_architecture

See the cluster-create-params model in the API viewer for details on the fields you can set when regisetering a new cluster. After you create the cluster definition, you can modify the cluster definition and provide values for additional settings.

Prerequisites

  • You have generated a valid API_TOKEN. Tokens expire every 15 minutes.
  • You have downloaded the pull secret.
  • Optional: You have assigned the pull secret to the $PULL_SECRET variable.

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

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.

4.5. Modifying a cluster

To modify a cluster definition with the API, use the /v2/clusters/{cluster_id} endpoint. Modifying a cluster resource is a common operation for adding settings such as changing the network type or enabling user-managed networking. See the v2-cluster-update-params model in the API viewer for details on the fields you can set when modifying a cluster definition.

Prerequisites

  • You have created a new cluster resource.

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

4.6. Registering a new infrastructure environment

Once you register a new cluster definition with the Assisted Installer API, create an infrastructure environment using the v2/infra-envs endpoint. Registering a new infrastructure environment requires the following settings:

  • name
  • pull_secret
  • cpu_architecture

See the infra-env-create-params model in the API viewer for details on the fields you can set when registering a new infrastructure environment. You can modify an infrastructure environment after you create it. As a best practice, consider including the cluster_id when creating a new infrastructure environment. The cluster_id will associate the infrastructure environment with a cluster definition. When creating the new infrastructure environment, the Assisted Installer will also generate a discovery ISO.

Prerequisites

  • You have generated a valid API_TOKEN. Tokens expire every 15 minutes.
  • You have downloaded the pull secret.
  • Optional: You have registered a new cluster definition and exported the cluster_id.

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

4.7. Modifying an infrastructure environment

You can modify an infrastructure environment using the /v2/infra-envs/{infra_env_id} endpoint. Modifying an infrastructure environment is a common operation for adding settings such as networking, SSH keys, or ignition configuration overrides.

See the infra-env-update-params model in the API viewer for details on the fields you can set when modifying an infrastructure environment. When modifying the new infrastructure environment, the Assisted Installer will also re-generate the discovery ISO.

Prerequisites

  • You have created a new infrastructure environment.

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

4.8. Adding hosts

After configuring the cluster resource and infrastructure environment, download the discovery ISO image. You can choose from two images:

  • Full ISO image: Use the full ISO image when booting must be self-contained. The image includes everything needed to boot and start the Assisted Installer agent. The ISO image is about 1GB in size.
  • Minimal ISO image: Use the minimal ISO image when bandwidth over the virtual media connection is limited. This is the default setting. The image includes only what is required to boot a host with networking. The majority of the content is downloaded upon boot. The ISO image is about 100MB in size.

Both images lead to the same installation procedure. To change the image type, modify the image_type setting in the infrastructure environment before performing this procedure.

Prerequisites

  • You have created a cluster.
  • You have created an infrastructure environment.
  • You have completed the configuration.
  • If the cluster hosts are behind a firewall that requires the use of a proxy, you have configured the username, password, IP address and port for the HTTP and HTTPS URLs of the proxy server.
  • You have selected an image type or will use the default minimal-iso.

Procedure

  1. Configure the discovery image if needed.

  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 additional resources below for details.
  6. Assign a role to host(s).

Additional resources

4.9. Modifying hosts

After adding hosts, modify the hosts as needed. The most common modifications are to the host_name and the host_role parameters.

You can modify a host using the /v2/infra-envs/{infra_env_id}/hosts/{host_id} endpoint. See the host-update-params model in the API viewer for details on the fields you can set when modifying a host.

A host may be one of two roles:

  • master: A host with the master role will operate as a control plane host.
  • worker: A host with the worker role will operate as a worker host.

By default, the Assisted Installer sets a host to auto-assign, which means the installer will determine whether the host is a master or worker role automatically. Use this procedure to set the host’s role.

Prerequisites

  • You have added hosts to the cluster.

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'

    Example output

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

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

4.10. Pre-installation validation

The Assisted Installer ensures the cluster meets the prerequisites before installation, because it eliminates complex post-installation troubleshooting, thereby saving significant amounts of time and effort. Before installing the cluster, ensure the cluster and each host pass pre-installation validation.

Additional resources

4.11. Installing the cluster

Once the cluster hosts past validation, you can install the cluster.

Prerequisites

  • You have created a cluster and infrastructure environment.
  • You have added hosts to the infrastructure environment.
  • The hosts have passed validation.

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.

Additional resources