Preparing to install a cluster on Azure¶

Before you install an OpenShift Container Platform cluster on Azure with installer-provisioned infrastructure, you must configure your account, obtain the installation program and oc CLI, and optionally prepare disk encryption sets.

Prerequisites for installing a cluster on Azure¶

Before you install an OpenShift Container Platform cluster on Azure, ensure that you have selected a cluster installation method and configured an Azure account to host the cluster and determine the tested and validated region to deploy the cluster to.

If you use a firewall, you must configure it to allow the sites that your cluster requires access to.

Additional resources

Internet access for OpenShift Container Platform¶

In OpenShift Container Platform 4.22, you require access to the internet to install your cluster.

You must have internet access to perform the following actions:

Access Red Hat Hybrid Cloud Console to download the installation program and perform subscription management. If the cluster has internet access and you do not disable Telemetry, that service automatically entitles your cluster.
Access Quay.io to obtain the packages that are required to install your cluster.
Obtain the packages that are required to perform cluster updates.

Warning

If your cluster cannot have direct internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the required content and use it to populate a mirror registry with the installation packages. With some installation types, the environment that you install your cluster in will not require internet access. Before you update the cluster, you update the content of the mirror registry.

Generating a key pair for cluster node SSH access¶

During an OpenShift Container Platform installation, you can provide an SSH public key to the installation program. The key is passed to the Red Hat Enterprise Linux CoreOS (RHCOS) nodes through their Ignition config files and is used to authenticate SSH access to the nodes. The key is added to the ~/.ssh/authorized_keys list for the core user on each node, which enables password-less authentication.

The key is added to the ~/.ssh/authorized_keys list for the core user on each node, which enables password-less authentication. After the key is passed to the nodes, you can use the key pair to SSH in to the RHCOS nodes as the user core. To access the nodes through SSH, the private key identity must be managed by SSH for your local user.

If you want to SSH in to your cluster nodes to perform installation debugging or disaster recovery, you must provide the SSH public key during the installation process. The ./openshift-install gather command also requires the SSH public key to be in place on the cluster nodes.

Warning

Do not skip this procedure in production environments, where disaster recovery and debugging is required.

Note

You must use a local key, not one that you configured with platform-specific approaches.

Procedure

If you do not have an existing SSH key pair on your local machine to use for authentication onto your cluster nodes, create one. For example, on a computer that uses a Linux operating system, run the following command:
```
$ ssh-keygen -t ed25519 -N '' -f <path>/<file_name>
```
Specifies the path and file name, such as ~/.ssh/id_ed25519, of the new SSH key. If you have an existing key pair, ensure your public key is in the your ~/.ssh directory.

Note

If you plan to install an OpenShift Container Platform cluster that uses the RHEL cryptographic libraries that have been submitted to NIST for FIPS 140-2/140-3 Validation on only the x86_64, ppc64le, and s390x architectures, do not create a key that uses the ed25519 algorithm. Instead, create a key that uses the rsa or ecdsa algorithm.
View the public SSH key:
```
$ cat <path>/<file_name>.pub
```
For example, run the following to view the ~/.ssh/id_ed25519.pub public key:
```
$ cat ~/.ssh/id_ed25519.pub
```
Add the SSH private key identity to the SSH agent for your local user, if it has not already been added. SSH agent management of the key is required for password-less SSH authentication onto your cluster nodes, or if you want to use the ./openshift-install gather command.

Note

On some distributions, default SSH private key identities such as ~/.ssh/id_rsa and ~/.ssh/id_dsa are managed automatically.
1. If the ssh-agent process is not already running for your local user, start it as a background task:
```
$ eval "$(ssh-agent -s)"
```
  Example output
```
Agent pid 31874
```
  Note
  
  If your cluster is in FIPS mode, only use FIPS-compliant algorithms to generate the SSH key. The key must be either RSA or ECDSA.
Add your SSH private key to the ssh-agent:
```
$ ssh-add <path>/<file_name>
```
Specify the path and file name for your SSH private key, such as ~/.ssh/id_ed25519.
Example output
```
Identity added: /home/<you>/<path>/<file_name> (<computer_name>)
```

Next steps

When you install OpenShift Container Platform, provide the SSH public key to the installation program.

Obtaining the installation program¶

Before you install OpenShift Container Platform, download the installation file on the host you are using for installation, so that installation assets exist for deployment in your environment.

Prerequisites

You have a computer that runs Linux or macOS, with 500 MB of local disk space.

Procedure

Go to the Cluster Type page on the Red Hat Hybrid Cloud Console. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

Tip

You can also download the binaries for a specific OpenShift Container Platform release.
Select your infrastructure provider from the Run it yourself section of the page.
Select your host operating system and architecture from the dropdown menus under OpenShift Installer and click Download Installer.
Place the downloaded file in the directory where you want to store the installation configuration files.
Warning
- The installation program creates several files on the computer that you use to install your cluster. You must keep the installation program and the files that the installation program creates after you finish installing the cluster. Both of the files are required to delete the cluster.
- Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. To remove your cluster, complete the OpenShift Container Platform uninstallation procedures for your specific cloud provider.
Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:
```
$ tar -xvf openshift-install-linux.tar.gz
```
Download your installation pull secret from Red Hat OpenShift Cluster Manager. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Tip

Alternatively, you can retrieve the installation program from the Red Hat Customer Portal, where you can specify a version of the installation program to download. However, you must have an active subscription to access this page.

Installing the OpenShift CLI on Linux¶

To manage your cluster and deploy applications from the command line on Linux, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the architecture from the Product Variant list.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 Linux Clients entry and save the file.
Unpack the archive:
```
$ tar xvf <file>
```
Place the oc binary in a directory that is on your PATH.

To check your PATH, run the following command:
```
$ echo $PATH
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
$ oc <command>
```

Installing the OpenShift CLI on Windows¶

To manage your cluster and deploy applications from the command line on Windows, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 Windows Client entry and save the file.
Extract the archive with a ZIP program.
Move the oc binary to a directory that is on your PATH variable.

To check your PATH variable, open the Command Prompt and run the following command:
```
C:\> path
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
C:\> oc <command>
```

Installing the OpenShift CLI on macOS¶

To manage your cluster and deploy applications from the command line on macOS, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

Warning

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OpenShift Container Platform.

Download and install the new version of oc.

Procedure

Navigate to the Download OpenShift Container Platform page on the Red Hat Customer Portal.
Select the architecture from the Product Variant list.
Select the appropriate version from the Version list.
Click Download Now next to the OpenShift v4.22 macOS Clients entry and save the file.

Note

For macOS arm64, choose the OpenShift v4.22 macOS arm64 Client entry.
Extract the archive.
Move the oc binary to a directory on your PATH variable.

To check your PATH variable, open a terminal and run the following command:
```
$ echo $PATH
```

Verification

Verify your installation by using an oc command:
```
$ oc <command>
```

Telemetry access for OpenShift Container Platform¶

To provide metrics about cluster health and the success of updates, the Telemetry service requires internet access. When connected, this service runs automatically by default and registers your cluster to OpenShift Cluster Manager.

After you confirm that your OpenShift Cluster Manager inventory is correct, either maintained automatically by Telemetry or manually by using OpenShift Cluster Manager,use subscription watch to track your OpenShift Container Platform subscriptions at the account or multi-cluster level. For more information about subscription watch, see "Data Gathered and Used by Red Hat’s subscription services" in the Additional resources section.

Additional resources

About remote health monitoring

Preparing an Azure Disk Encryption Set for Day2 Operator¶

The OpenShift Container Platform installation program can use an existing Disk Encryption Set with a user-managed key. To enable this feature, create a DiskEncryptionSet object in Azure and provide the key to the installation program.

Prerequisite

You enabled the EncryptionAtHost feature in your Azure subscription. For more information, see "Use the Azure portal to enable end-to-end encryption using encryption at host". .Procedure
1. Mark the node from the encyptionAtHost cluster resource group as unschedulable by using the following command:
```
$ oc adm cordon <node_name>
```
2. Evacuate the pods from the compute node. There are several ways to do this. For example, you can evacuate all the pods or the selected pods on a node:
```
$ oc adm drain <compute_node> [--pod-selector=<pod_selector>]
```
  Note
  
  For other options to evacuate pods from a node, see the "Understanding how to evacuate pods on nodes" section.
3. De-allocate the node by running the following command:
```
$ az vm deallocate -n <node_name> -g <cluster_resource_group>
```
4. Set the encryptionAtHost property to true by running the following command:
```
$ az vm update -n <node_name> -g <cluster_resource_group> --set securityProfile.encryptionAtHost=true
```
5. Start the node by running the following commands:
```
$ az vm start -n <node_name> -g <cluster_resource_group>
```
6. Mark the node as schedulable by using the following command:
```
$ oc adm uncordon <node_name>
```
7. Verify that all cluster Operators are available:
```
$ oc get clusteroperators
```
  All Operators should show AVAILABLE=True, PROGRESSING=False, and DEGRADED=False.
8. Repeat the above steps on all the nodes that run encryptionAtHost.
  Note
  
  If you want to enable encryption for your host during cluster installation, specify the following parameters in the install-config.yaml file:
  - compute.platform.azure.encryptionAtHost
  - controlPlane.platform.azure.encryptionAtHost
  - platform.azure.defaultMachinePlatform.encryptionAtHost

Preparing an Azure Disk Encryption Set¶

To use an existing Disk Encryption Set with a user-managed key in OpenShift Container Platform on Azure, you must create a Disk Encryption Set in Azure and provide the key to the installation program.

Procedure

Set the environment variables for the Azure resource group by running the following command:
```
$ export RESOURCEGROUP="<resource_group>" \
    LOCATION="<location>"
```
where:

<resource_group>

Specifies the name of the Azure resource group where you create the Disk Encryption Set and encryption key. To prevent losing access to your keys when you delete the cluster, create the Disk Encryption Set in a separate resource group from the one where you install the cluster.

<location>

Specifies the Azure location where you create the resource group.
Set the environment variables for the Azure Key Vault and Disk Encryption Set by running the following command:
```
$ export KEYVAULT_NAME="<keyvault_name>" \
    KEYVAULT_KEY_NAME="<keyvault_key_name>" \
    DISK_ENCRYPTION_SET_NAME="<disk_encryption_set_name>"
```
where:

<keyvault_name>

Specifies the name of the Azure Key Vault that you create.

<keyvault_key_name>

Specifies the name of the encryption key that you create.

<disk_encryption_set_name>

Specifies the name of the disk encryption set that you create.
Set the environment variable for the ID of your Azure service principal by running the following command:
```
$ export CLUSTER_SP_ID="<service_principal_id>"
```
<service_principal_id>

Specifies the ID of the service principal that you use for installation.

Enable host-level encryption in Azure by running the following command:

$ az feature register --namespace "Microsoft.Compute" --name "EncryptionAtHost"

$ az feature show --namespace Microsoft.Compute --name EncryptionAtHost

$ az provider register -n Microsoft.Compute

Create an Azure resource group to hold the disk encryption set and associated resources by running the following command:
```
$ az group create --name $RESOURCEGROUP --location $LOCATION
```

Create an Azure Key Vault by running the following command:

$ az keyvault create -n $KEYVAULT_NAME -g $RESOURCEGROUP -l $LOCATION \
    --enable-purge-protection true

Create an encryption key in the key vault by running the following command:

$ az keyvault key create --vault-name $KEYVAULT_NAME -n $KEYVAULT_KEY_NAME \
    --protection software

Capture the ID of the key vault by running the following command:

$ KEYVAULT_ID=$(az keyvault show --name $KEYVAULT_NAME --query "[id]" -o tsv)

Capture the key URL in the key vault by running the following command:

$ KEYVAULT_KEY_URL=$(az keyvault key show --vault-name $KEYVAULT_NAME --name \
    $KEYVAULT_KEY_NAME --query "[key.kid]" -o tsv)

Create a disk encryption set by running the following command:

$ az disk-encryption-set create -n $DISK_ENCRYPTION_SET_NAME -l $LOCATION -g \
    $RESOURCEGROUP --source-vault $KEYVAULT_ID --key-url $KEYVAULT_KEY_URL

Grant the DiskEncryptionSet resource access to the key vault by running the following commands:

$ DES_IDENTITY=$(az disk-encryption-set show -n $DISK_ENCRYPTION_SET_NAME -g \
    $RESOURCEGROUP --query "[identity.principalId]" -o tsv)

$ az keyvault set-policy -n $KEYVAULT_NAME -g $RESOURCEGROUP --object-id \
    $DES_IDENTITY --key-permissions wrapkey unwrapkey get

Grant the Azure service principal permission to read the Disk Encryption Set by running the following commands:
```
$ DES_RESOURCE_ID=$(az disk-encryption-set show -n $DISK_ENCRYPTION_SET_NAME -g \
    $RESOURCEGROUP --query "[id]" -o tsv)
```
```
$ az role assignment create --assignee $CLUSTER_SP_ID --role "<reader_role>" \
    --scope $DES_RESOURCE_ID -o jsonc
```
<reader_role>

Specifies an Azure role with read permissions to the disk encryption set. You can use the Owner role or a custom role with the necessary permissions.

Additional resources