Preparing to install a cluster on Azure

To prepare for installation of an OpenShift Container Platform cluster on Azure, complete the following steps:

You have selected a cluster installation method.
You configured an Azure account to host the cluster and determined the tested and validated region to deploy the cluster to.
If you use a firewall, you have configured it to allow the sites that your cluster requires access to.

Internet access for OpenShift Container Platform

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

You must have internet access to perform the following actions:

Access OpenShift Cluster Manager 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.

Generating a key pair for cluster node SSH access

To enable secure, passwordless SSH access to your cluster nodes, provide an SSH public key during the OpenShift Container Platform installation. This ensures that the installation program automatically configures the Red Hat Enterprise Linux CoreOS (RHCOS) nodes for remote authentication through the core user.

The SSH public key gets added to the ~/.ssh/authorized_keys list for the core user on each node. After the key is passed to the Red Hat Enterprise Linux CoreOS (RHCOS) nodes through their Ignition config files, 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.

Important

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

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.
Important
- 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, install the OpenShift CLI (oc) binary on Linux.

Important

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.19 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, execute 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, install OpenShift CLI (oc) binary on Windows.

Important

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.19 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 execute 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, install the OpenShift CLI (oc) binary on macOS.

Important

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.19 macOS Clients entry and save the file.

Note

For macOS arm64, choose the OpenShift v4.19 macOS arm64 Client entry.
Unpack and unzip the archive.
Move the oc binary to a directory on your PATH variable.

To check your PATH variable, open a terminal and execute 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

For more information about the Telemetry service, see 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

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

Procedure

Set the environment variables for the Azure resource group by running the following command:
```
$ export RESOURCEGROUP="<resource_group>" \
    LOCATION="<location>" 
```
1. Specifies the name of the Azure resource group where the Disk Encryption Set and encryption key are to be created. To prevent losing access to your keys when you destroy the cluster, create the Disk Encryption Set in a separate resource group from the one where you install the cluster.
2. Specifies the Azure location where the resource group is to be created.
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>" 
```
1. Specifies the name of the Azure Key Vault to be created.
2. Specifies the name of the encryption key to be created.
3. Specifies the name of the disk encryption set to be created.
Set the environment variable for the ID of your Azure service principal by running the following command:
```
$ export CLUSTER_SP_ID="<service_principal_id>" 
```
1. Specifies the ID of the service principal to be used 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
```
1. 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.

Next steps

Install an OpenShift Container Platform cluster: