Chapter 4. Installing a cluster on Azure Stack Hub with network customizations

Procedure

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

   1

   Copy to Clipboard Toggle word wrap

   1

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

2. View the public SSH key:

   $ cat <path>/<file_name>.pub

   Copy to Clipboard Toggle word wrap

   For example, run the following to view the ~/.ssh/id_ed25519.pub public key:

   $ cat ~/.ssh/id_ed25519.pub

   Copy to Clipboard Toggle word wrap

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

      Copy to Clipboard Toggle word wrap

      Example output

      Agent pid 31874

      Copy to Clipboard Toggle word wrap

      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.

4. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 

   1

   Copy to Clipboard Toggle word wrap

   1

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

   Copy to Clipboard Toggle word wrap

Procedure

1. Obtain the RHCOS VHD cluster image:

   1. Export the URL of the RHCOS VHD to an environment variable.

      $ export COMPRESSED_VHD_URL=$(openshift-install coreos print-stream-json | jq -r '.architectures.x86_64.artifacts.azurestack.formats."vhd.gz".disk.location')

      Copy to Clipboard Toggle word wrap

   2. Download the compressed RHCOS VHD file locally.

      $ curl -O -L ${COMPRESSED_VHD_URL}

      Copy to Clipboard Toggle word wrap

2. Decompress the VHD file.

   Note

   The decompressed VHD file is approximately 16 GB, so be sure that your host system has 16 GB of free space available. The VHD file can be deleted once you have uploaded it.

3. Upload the local VHD to the Azure Stack Hub environment, making sure that the blob is publicly available. For example, you can upload the VHD to a blob using the az cli or the web portal.

Procedure

1. 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.
2. Select your infrastructure provider from the Run it yourself section of the page.
3. Select your host operating system and architecture from the dropdown menus under OpenShift Installer and click Download Installer.

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

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

   Copy to Clipboard Toggle word wrap
6. 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.

Procedure

1. Create an installation directory to store your required installation assets in:

   $ mkdir <installation_directory>

   Copy to Clipboard Toggle word wrap
   Important

   You must create a directory. Some installation assets, such as bootstrap X.509 certificates have short expiration intervals, so you must not reuse an installation directory. If you want to reuse individual files from another cluster installation, you can copy them into your directory. However, the file names for the installation assets might change between releases. Use caution when copying installation files from an earlier OpenShift Container Platform version.

2. Customize the provided sample install-config.yaml file template and save the file in the <installation_directory>.

   Note

   You must name this configuration file install-config.yaml.

   Make the following modifications:

   1. Specify the required installation parameters.
   2. Update the platform.azure section to specify the parameters that are specific to Azure Stack Hub.

   3. Optional: Update one or more of the default configuration parameters to customize the installation.

      For more information about the parameters, see "Installation configuration parameters".

3. Back up the install-config.yaml file so that you can use it to install many clusters.

   Important

   Back up the install-config.yaml file now, because the installation process consumes the file in the next step.

Procedure

1. If you have not previously created installation manifest files, do so by running the following command:

   $ openshift-install create manifests --dir <installation_directory>

   Copy to Clipboard Toggle word wrap

   where <installation_directory> is the directory in which the installation program creates files.

2. Set a $RELEASE_IMAGE variable with the release image from your installation file by running the following command:

   $ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')

   Copy to Clipboard Toggle word wrap

3. Extract the list of CredentialsRequest custom resources (CRs) from the OpenShift Container Platform release image by running the following command:

   $ oc adm release extract \
     --from=$RELEASE_IMAGE \
     --credentials-requests \
     --included \

   1

   
     --install-config=<path_to_directory_with_installation_configuration>/install-config.yaml \

   2

   
     --to=<path_to_directory_for_credentials_requests> 

   3

   Copy to Clipboard Toggle word wrap

   1

   The --included parameter includes only the manifests that your specific cluster configuration requires.

   2

   Specify the location of the install-config.yaml file.

   3

   Specify the path to the directory where you want to store the CredentialsRequest objects. If the specified directory does not exist, this command creates it.

   This command creates a YAML file for each CredentialsRequest object.

   Sample CredentialsRequest object

   apiVersion: cloudcredential.openshift.io/v1
   kind: CredentialsRequest
   metadata:
     name: <component_credentials_request>
     namespace: openshift-cloud-credential-operator
     ...
   spec:
     providerSpec:
       apiVersion: cloudcredential.openshift.io/v1
       kind: AzureProviderSpec
       roleBindings:
       - role: Contributor
     ...

   Copy to Clipboard Toggle word wrap

4. Create YAML files for secrets in the openshift-install manifests directory that you generated previously. The secrets must be stored using the namespace and secret name defined in the spec.secretRef for each CredentialsRequest object.

   Sample CredentialsRequest object with secrets

   apiVersion: cloudcredential.openshift.io/v1
   kind: CredentialsRequest
   metadata:
     name: <component_credentials_request>
     namespace: openshift-cloud-credential-operator
     ...
   spec:
     providerSpec:
       apiVersion: cloudcredential.openshift.io/v1
       kind: AzureProviderSpec
       roleBindings:
       - role: Contributor
         ...
     secretRef:
       name: <component_secret>
       namespace: <component_namespace>
     ...

   Copy to Clipboard Toggle word wrap

   Sample Secret object

   apiVersion: v1
   kind: Secret
   metadata:
     name: <component_secret>
     namespace: <component_namespace>
   data:
     azure_subscription_id: <base64_encoded_azure_subscription_id>
     azure_client_id: <base64_encoded_azure_client_id>
     azure_client_secret: <base64_encoded_azure_client_secret>
     azure_tenant_id: <base64_encoded_azure_tenant_id>
     azure_resource_prefix: <base64_encoded_azure_resource_prefix>
     azure_resourcegroup: <base64_encoded_azure_resourcegroup>
     azure_region: <base64_encoded_azure_region>

   Copy to Clipboard Toggle word wrap

Procedure

1. From the directory in which the installation program creates files, go to the manifests directory.

2. Add user-ca-bundle to the spec.trustedCA.name field.

   Example cluster-proxy-01-config.yaml file

   apiVersion: config.openshift.io/v1
   kind: Proxy
   metadata:
     creationTimestamp: null
     name: cluster
   spec:
     trustedCA:
       name: user-ca-bundle
   status: {}

   Copy to Clipboard Toggle word wrap

3. Optional: Back up the manifests/ cluster-proxy-01-config.yaml file. The installation program consumes the manifests/ directory when you deploy the cluster.

Procedure

1. Change to the directory that contains the installation program and create the manifests:

   $ ./openshift-install create manifests --dir <installation_directory> 

   1

   Copy to Clipboard Toggle word wrap

   1

   <installation_directory> specifies the name of the directory that contains the install-config.yaml file for your cluster.

2. Create a stub manifest file for the advanced network configuration that is named cluster-network-03-config.yml in the <installation_directory>/manifests/ directory:

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:

   Copy to Clipboard Toggle word wrap

3. Specify the advanced network configuration for your cluster in the cluster-network-03-config.yml file, such as in the following examples:

   Specify a different VXLAN port for the OpenShift SDN network provider

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
     defaultNetwork:
       openshiftSDNConfig:
         vxlanPort: 4800

   Copy to Clipboard Toggle word wrap

   Enable IPsec for the OVN-Kubernetes network provider

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
     defaultNetwork:
       ovnKubernetesConfig:
         ipsecConfig: {}

   Copy to Clipboard Toggle word wrap

4. Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program consumes the manifests/ directory when you create the Ignition config files.

Procedure

1. Change to the directory that contains the installation program and create the manifests:

   $ ./openshift-install create manifests --dir <installation_directory>

   Copy to Clipboard Toggle word wrap

   where:

   <installation_directory>

   Specifies the name of the directory that contains the install-config.yaml file for your cluster.

2. Create a stub manifest file for the advanced network configuration that is named cluster-network-03-config.yml in the <installation_directory>/manifests/ directory:

   $ cat <<EOF > <installation_directory>/manifests/cluster-network-03-config.yml
   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
   EOF

   Copy to Clipboard Toggle word wrap

   where:

   <installation_directory>

   Specifies the directory name that contains the manifests/ directory for your cluster.

3. Open the cluster-network-03-config.yml file in an editor and configure OVN-Kubernetes with hybrid networking, as in the following example:

   Specify a hybrid networking configuration

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
     defaultNetwork:
       ovnKubernetesConfig:
         hybridOverlayConfig:
           hybridClusterNetwork: 

   1

   
           - cidr: 10.132.0.0/14
             hostPrefix: 23
           hybridOverlayVXLANPort: 9898 

   2

   Copy to Clipboard Toggle word wrap

   1

   Specify the CIDR configuration used for nodes on the additional overlay network. The hybridClusterNetwork CIDR must not overlap with the clusterNetwork CIDR.

   2

   Specify a custom VXLAN port for the additional overlay network. This is required for running Windows nodes in a cluster installed on vSphere, and must not be configured for any other cloud provider. The custom port can be any open port excluding the default 4789 port. For more information on this requirement, see the Microsoft documentation on Pod-to-pod connectivity between hosts is broken.

   Note

   Windows Server Long-Term Servicing Channel (LTSC): Windows Server 2019 is not supported on clusters with a custom hybridOverlayVXLANPort value because this Windows server version does not support selecting a custom VXLAN port.

4. Save the cluster-network-03-config.yml file and quit the text editor.
5. Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program deletes the manifests/ directory when creating the cluster.

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the architecture from the Product Variant drop-down list.
3. Select the appropriate version from the Version drop-down list.
4. Click Download Now next to the OpenShift v4.14 Linux Client entry and save the file.

5. Unpack the archive:

   $ tar xvf <file>

   Copy to Clipboard Toggle word wrap

6. Place the oc binary in a directory that is on your PATH.

   To check your PATH, execute the following command:

   $ echo $PATH

   Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the appropriate version from the Version drop-down list.
3. Click Download Now next to the OpenShift v4.14 Windows Client entry and save the file.
4. Unzip the archive with a ZIP program.

5. Move the oc binary to a directory that is on your PATH.

   To check your PATH, open the command prompt and execute the following command:

   C:\> path

   Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to the OpenShift Container Platform downloads page on the Red Hat Customer Portal.
2. Select the appropriate version from the Version drop-down list.

3. Click Download Now next to the OpenShift v4.14 macOS Client entry and save the file.

   Note

   For macOS arm64, choose the OpenShift v4.14 macOS arm64 Client entry.

4. Unpack and unzip the archive.

5. Move the oc binary to a directory on your PATH.

   To check your PATH, open a terminal and execute the following command:

   $ echo $PATH

   Copy to Clipboard Toggle word wrap

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 

   1

   Copy to Clipboard Toggle word wrap

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami

   Copy to Clipboard Toggle word wrap

   Example output

   system:admin

   Copy to Clipboard Toggle word wrap

Procedure

1. Obtain the password for the kubeadmin user from the kubeadmin-password file on the installation host:

   $ cat <installation_directory>/auth/kubeadmin-password

   Copy to Clipboard Toggle word wrap
   Note

   Alternatively, you can obtain the kubeadmin password from the <installation_directory>/.openshift_install.log log file on the installation host.

2. List the OpenShift Container Platform web console route:

   $ oc get routes -n openshift-console | grep 'console-openshift'

   Copy to Clipboard Toggle word wrap
   Note

   Alternatively, you can obtain the OpenShift Container Platform route from the <installation_directory>/.openshift_install.log log file on the installation host.

   Example output

   console     console-openshift-console.apps.<cluster_name>.<base_domain>            console     https   reencrypt/Redirect   None

   Copy to Clipboard Toggle word wrap

3. Navigate to the route detailed in the output of the preceding command in a web browser and log in as the kubeadmin user.