Chapter 19. Installing on OpenStack

Procedure

1. Save the following script to your machine:

   #!/usr/bin/env bash
   
   set -Eeuo pipefail
   
   declare catalog san
   catalog="$(mktemp)"
   san="$(mktemp)"
   readonly catalog san
   
   declare invalid=0
   
   openstack catalog list --format json --column Name --column Endpoints \
   	| jq -r '.[] | .Name as $name | .Endpoints[] | select(.interface=="public") | [$name, .interface, .url] | join(" ")' \
   	| sort \
   	> "$catalog"
   
   while read -r name interface url; do
   	# Ignore HTTP
   	if [[ ${url#"http://"} != "$url" ]]; then
   		continue
   	fi
   
   	# Remove the schema from the URL
   	noschema=${url#"https://"}
   
   	# If the schema was not HTTPS, error
   	if [[ "$noschema" == "$url" ]]; then
   		echo "ERROR (unknown schema): $name $interface $url"
   		exit 2
   	fi
   
   	# Remove the path and only keep host and port
   	noschema="${noschema%%/*}"
   	host="${noschema%%:*}"
   	port="${noschema##*:}"
   
   	# Add the port if was implicit
   	if [[ "$port" == "$host" ]]; then
   		port='443'
   	fi
   
   	# Get the SAN fields
   	openssl s_client -showcerts -servername "$host" -connect "$host:$port" </dev/null 2>/dev/null \
   		| openssl x509 -noout -ext subjectAltName \
   		> "$san"
   
   	# openssl returns the empty string if no SAN is found.
   	# If a SAN is found, openssl is expected to return something like:
   	#
   	#    X509v3 Subject Alternative Name:
   	#        DNS:standalone, DNS:osp1, IP Address:192.168.2.1, IP Address:10.254.1.2
   	if [[ "$(grep -c "Subject Alternative Name" "$san" || true)" -gt 0 ]]; then
   		echo "PASS: $name $interface $url"
   	else
   		invalid=$((invalid+1))
   		echo "INVALID: $name $interface $url"
   	fi
   done < "$catalog"
   
   # clean up temporary files
   rm "$catalog" "$san"
   
   if [[ $invalid -gt 0 ]]; then
   	echo "${invalid} legacy certificates were detected. Update your certificates to include a SAN field."
   	exit 1
   else
   	echo "All HTTPS certificates for this cloud are valid."
   fi

2. Run the script.
3. Replace any certificates that the script reports as

   INVALID

   with certificates that contain SAN fields.

1. As an administrator in the RHOSP CLI, add the

   swiftoperator

   role to the account that will access Swift:

   $ openstack role add --user <user> --project <project> swiftoperator

Procedure

1. Create a YAML file that specifies the storage class and availability zone to use. For example:

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: custom-csi-storageclass
   provisioner: cinder.csi.openstack.org
   volumeBindingMode: WaitForFirstConsumer
   allowVolumeExpansion: true
   parameters:
     availability: <availability_zone_name>

   Note

   OpenShift Container Platform does not verify the existence of the availability zone you choose. Verify the name of the availability zone before you apply the configuration.

2. From a command line, apply the configuration:

   $ oc apply -f <storage_class_file_name>

   Example output

   storageclass.storage.k8s.io/custom-csi-storageclass created

3. Create a YAML file that specifies a persistent volume claim (PVC) that uses your storage class and the

   openshift-image-registry

   namespace. For example:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: csi-pvc-imageregistry
     namespace: openshift-image-registry 

   1

   
     annotations:
       imageregistry.openshift.io: "true"
   spec:
     accessModes:
     - ReadWriteOnce
     volumeMode: Filesystem
     resources:
       requests:
         storage: 100Gi 

   2

   
     storageClassName: <your_custom_storage_class> 

   3

   1

   Enter the namespace openshift-image-registry. This namespace allows the Cluster Image Registry Operator to consume the PVC.

   2

   Optional: Adjust the volume size.

   3

   Enter the name of the storage class that you created.

4. From a command line, apply the configuration:

   $ oc apply -f <pvc_file_name>

   Example output

   persistentvolumeclaim/csi-pvc-imageregistry created

5. Replace the original persistent volume claim in the image registry configuration with the new claim:

   $ oc patch configs.imageregistry.operator.openshift.io/cluster --type 'json' -p='[{"op": "replace", "path": "/spec/storage/pvc/claim", "value": "csi-pvc-imageregistry"}]'

   Example output

   config.imageregistry.operator.openshift.io/cluster patched

   Over the next several minutes, the configuration is updated.

1. Verify that the PVC claim value is identical to the name that you provided in your PVC definition:

   $ oc get configs.imageregistry.operator.openshift.io/cluster -o yaml

   Example output

   ...
   status:
       ...
       managementState: Managed
       pvc:
         claim: csi-pvc-imageregistry
   ...

2. Verify that the status of the PVC is

   Bound

   :

   $ oc get pvc -n openshift-image-registry csi-pvc-imageregistry

   Example output

   NAME                   STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS             AGE
   csi-pvc-imageregistry  Bound    pvc-72a8f9c9-f462-11e8-b6b6-fa163e18b7b5   100Gi      RWO            custom-csi-storageclass  11m

Procedure

1. Using the RHOSP CLI, verify the name and ID of the 'External' network:

   $ openstack network list --long -c ID -c Name -c "Router Type"

   Example output

   +--------------------------------------+----------------+-------------+
   | ID                                   | Name           | Router Type |
   +--------------------------------------+----------------+-------------+
   | 148a8023-62a7-4672-b018-003462f8d7dc | public_network | External    |
   +--------------------------------------+----------------+-------------+

Procedure

1. Create the

   clouds.yaml

   file:

   • If your RHOSP distribution includes the Horizon web UI, generate a

     clouds.yaml

     file in it.
     Important

     Remember to add a password to the

     auth

     field. You can also keep secrets in a separate file from

     clouds.yaml

     . OpenShift Container Platform does not support application credentials.

   • If your RHOSP distribution does not include the Horizon web UI, or you do not want to use Horizon, create the file yourself. For detailed information about

     clouds.yaml

     , see Config files in the RHOSP documentation.

     clouds:
       shiftstack:
         auth:
           auth_url: http://10.10.14.42:5000/v3
           project_name: shiftstack
           username: <username>
           password: <password>
           user_domain_name: Default
           project_domain_name: Default
       dev-env:
         region_name: RegionOne
         auth:
           username: <username>
           password: <password>
           project_name: 'devonly'
           auth_url: 'https://10.10.14.22:5001/v2.0'

2. If your RHOSP installation uses self-signed certificate authority (CA) certificates for endpoint authentication:

   1. Copy the certificate authority file to your machine.

   2. Add the

      cacerts

      key to the

      clouds.yaml

      file. The value must be an absolute, non-root-accessible path to the CA certificate:

      clouds:
        shiftstack:
          ...
          cacert: "/etc/pki/ca-trust/source/anchors/ca.crt.pem"

      Tip

      After you run the installer with a custom CA certificate, you can update the certificate by editing the value of the

      ca-cert.pem

      key in the

      cloud-provider-config

      keymap. On a command line, run:

      $ oc edit configmap -n openshift-config cloud-provider-config

3. Place the

   clouds.yaml

   file in one of the following locations:
   1. The value of the

      OS_CLIENT_CONFIG_FILE

      environment variable
   2. The current directory
   3. A Unix-specific user configuration directory, for example

      ~/.config/openstack/clouds.yaml

   4. A Unix-specific site configuration directory, for example

      /etc/openstack/clouds.yaml

      The installation program searches for

      clouds.yaml

      in that order.

Procedure

1. If you have not already generated manifest files for your cluster, generate them by running the following command:

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

2. In a text editor, open the cloud-provider configuration manifest file. For example:

   $ vi openshift/manifests/cloud-provider-config.yaml

3. Modify the options based on the cloud configuration specification.

   Configuring Octavia for load balancing is a common case for clusters that do not use Kuryr. For example:

   #...
   [LoadBalancer]
   use-octavia=true 

   1

   
   lb-provider = "amphora" 

   2

   
   floating-network-id="d3deb660-4190-40a3-91f1-37326fe6ec4a" 

   3

   
   create-monitor = True 

   4

   
   monitor-delay = 10s 

   5

   
   monitor-timeout = 10s 

   6

   
   monitor-max-retries = 1 

   7

   
   #...

   1

   This property enables Octavia integration.

   2

   This property sets the Octavia provider that your load balancer uses. It accepts "ovn" or "amphora" as values. If you choose to use OVN, you must also set lb-method to SOURCE_IP_PORT.

   3

   This property is required if you want to use multiple external networks with your cluster. The cloud provider creates floating IP addresses on the network that is specified here.

   4

   This property controls whether the cloud provider creates health monitors for Octavia load balancers. Set the value to True to create health monitors. As of RHOSP 16.1 and 16.2, this feature is only available for the Amphora provider.

   5

   This property sets the frequency with which endpoints are monitored. The value must be in the time.ParseDuration() format. This property is required if the value of the create-monitor property is True.

   6

   This property sets the time that monitoring requests are open before timing out. The value must be in the time.ParseDuration() format. This property is required if the value of the create-monitor property is True.

   7

   This property defines how many successful monitoring requests are required before a load balancer is marked as online. The value must be an integer. This property is required if the value of the create-monitor property is True.

   Important

   Prior to saving your changes, verify that the file is structured correctly. Clusters might fail if properties are not placed in the appropriate section.

   Important

   You must set the value of the

   create-monitor

   property to

   True

   if you use services that have the value of the

   .spec.externalTrafficPolicy

   property set to

   Local

   . The OVN Octavia provider in RHOSP 16.1 and 16.2 does not support health monitors. Therefore, services that have

   ETP

   parameter values set to

   Local

   might not respond when the

   lb-provider

   value is set to

   "ovn"

   .

   Important

   For installations that use Kuryr, Kuryr handles relevant services. There is no need to configure Octavia load balancing in the cloud provider.

4. Save the changes to the file and proceed with installation.

   Tip

   You can update your cloud provider configuration after you run the installer. On a command line, run:

   $ oc edit configmap -n openshift-config cloud-provider-config

   After you save your changes, your cluster will take some time to reconfigure itself. The process is complete if none of your nodes have a

   SchedulingDisabled

   status.

Procedure

1. Access the Infrastructure Provider page on the OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.
2. Select your infrastructure provider.

3. Navigate to the page for your installation type, download the installation program that corresponds with your host operating system and architecture, and place the file in the directory where you will 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 files are required to delete the cluster.

   Important

   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.

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

5. Download your installation pull secret from the 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 the

   install-config.yaml

   file.

   1. Change to the directory that contains the installation program and run the following command:

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

      1

      1

      For <installation_directory>, specify the directory name to store the files that the installation program creates.

      When specifying the directory:

      • Verify that the directory has the

        execute

        permission. This permission is required to run Terraform binaries under the installation directory.
      • Use an empty directory. Some installation assets, such as bootstrap X.509 certificates, have short expiration intervals, therefore 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. At the prompts, provide the configuration details for your cloud:

      1. Optional: Select an SSH key to use to access your cluster machines.

         Note

         For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your

         ssh-agent

         process uses.

      2. Select openstack as the platform to target.
      3. Specify the Red Hat OpenStack Platform (RHOSP) external network name to use for installing the cluster.
      4. Specify the floating IP address to use for external access to the OpenShift API.
      5. Specify a RHOSP flavor with at least 16 GB RAM to use for control plane nodes and 8 GB RAM for compute nodes.
      6. Select the base domain to deploy the cluster to. All DNS records will be sub-domains of this base and will also include the cluster name.
      7. Enter a name for your cluster. The name must be 14 or fewer characters long.
      8. Paste the pull secret from the Red Hat OpenShift Cluster Manager.
2. Modify the

   install-config.yaml

   file. You can find more information about the available parameters in the "Installation configuration parameters" section.

3. Back up the

   install-config.yaml

   file so that you can use it to install multiple clusters.
   Important

   The

   install-config.yaml

   file is consumed during the installation process. If you want to reuse the file, you must back it up now.

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

   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 FIPS validated or Modules In Process cryptographic libraries on the

   x86_64

   architecture, 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

   For example, run the following to view the

   ~/.ssh/id_ed25519.pub

   public key:

   $ cat ~/.ssh/id_ed25519.pub

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

      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.

4. Add your SSH private key to the

   ssh-agent

   :

   $ ssh-add <path>/<file_name> 

   1

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

Procedure

1. In the cluster environment, export the administrator’s kubeconfig file:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 

   1

   1

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

   The

   kubeconfig

   file contains information about the cluster that is used by the CLI to connect a client to the correct cluster and API server.

2. View the control plane and compute machines created after a deployment:

   $ oc get nodes

3. View your cluster’s version:

   $ oc get clusterversion

4. View your Operators' status:

   $ oc get clusteroperator

5. View all running pods in the cluster:

   $ oc get pods -A

Procedure

1. Export the

   kubeadmin

   credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 

   1

   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

   Example output

   system:admin

1. As an administrator in the RHOSP CLI, add the

   swiftoperator

   role to the account that will access Swift:

   $ openstack role add --user <user> --project <project> swiftoperator

Procedure

1. Using the RHOSP CLI, verify the name and ID of the 'External' network:

   $ openstack network list --long -c ID -c Name -c "Router Type"

   Example output

   +--------------------------------------+----------------+-------------+
   | ID                                   | Name           | Router Type |
   +--------------------------------------+----------------+-------------+
   | 148a8023-62a7-4672-b018-003462f8d7dc | public_network | External    |
   +--------------------------------------+----------------+-------------+

Procedure

1. Create the

   clouds.yaml

   file:

   • If your RHOSP distribution includes the Horizon web UI, generate a

     clouds.yaml

     file in it.
     Important

     Remember to add a password to the

     auth

     field. You can also keep secrets in a separate file from

     clouds.yaml

     . OpenShift Container Platform does not support application credentials.

   • If your RHOSP distribution does not include the Horizon web UI, or you do not want to use Horizon, create the file yourself. For detailed information about

     clouds.yaml

     , see Config files in the RHOSP documentation.

     clouds:
       shiftstack:
         auth:
           auth_url: http://10.10.14.42:5000/v3
           project_name: shiftstack
           username: <username>
           password: <password>
           user_domain_name: Default
           project_domain_name: Default
       dev-env:
         region_name: RegionOne
         auth:
           username: <username>
           password: <password>
           project_name: 'devonly'
           auth_url: 'https://10.10.14.22:5001/v2.0'

2. If your RHOSP installation uses self-signed certificate authority (CA) certificates for endpoint authentication:

   1. Copy the certificate authority file to your machine.

   2. Add the

      cacerts

      key to the

      clouds.yaml

      file. The value must be an absolute, non-root-accessible path to the CA certificate:

      clouds:
        shiftstack:
          ...
          cacert: "/etc/pki/ca-trust/source/anchors/ca.crt.pem"

      Tip

      After you run the installer with a custom CA certificate, you can update the certificate by editing the value of the

      ca-cert.pem

      key in the

      cloud-provider-config

      keymap. On a command line, run:

      $ oc edit configmap -n openshift-config cloud-provider-config

3. Place the

   clouds.yaml

   file in one of the following locations:
   1. The value of the

      OS_CLIENT_CONFIG_FILE

      environment variable
   2. The current directory
   3. A Unix-specific user configuration directory, for example

      ~/.config/openstack/clouds.yaml

   4. A Unix-specific site configuration directory, for example

      /etc/openstack/clouds.yaml

      The installation program searches for

      clouds.yaml

      in that order.

Procedure

1. If you have not already generated manifest files for your cluster, generate them by running the following command:

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

2. In a text editor, open the cloud-provider configuration manifest file. For example:

   $ vi openshift/manifests/cloud-provider-config.yaml

3. Modify the options based on the cloud configuration specification.

   Configuring Octavia for load balancing is a common case for clusters that do not use Kuryr. For example:

   #...
   [LoadBalancer]
   use-octavia=true 

   1

   
   lb-provider = "amphora" 

   2

   
   floating-network-id="d3deb660-4190-40a3-91f1-37326fe6ec4a" 

   3

   
   create-monitor = True 

   4

   
   monitor-delay = 10s 

   5

   
   monitor-timeout = 10s 

   6

   
   monitor-max-retries = 1 

   7

   
   #...

   1

   This property enables Octavia integration.

   2

   This property sets the Octavia provider that your load balancer uses. It accepts "ovn" or "amphora" as values. If you choose to use OVN, you must also set lb-method to SOURCE_IP_PORT.

   3

   This property is required if you want to use multiple external networks with your cluster. The cloud provider creates floating IP addresses on the network that is specified here.

   4

   This property controls whether the cloud provider creates health monitors for Octavia load balancers. Set the value to True to create health monitors. As of RHOSP 16.1 and 16.2, this feature is only available for the Amphora provider.

   5

   This property sets the frequency with which endpoints are monitored. The value must be in the time.ParseDuration() format. This property is required if the value of the create-monitor property is True.

   6

   This property sets the time that monitoring requests are open before timing out. The value must be in the time.ParseDuration() format. This property is required if the value of the create-monitor property is True.

   7

   This property defines how many successful monitoring requests are required before a load balancer is marked as online. The value must be an integer. This property is required if the value of the create-monitor property is True.

   Important

   Prior to saving your changes, verify that the file is structured correctly. Clusters might fail if properties are not placed in the appropriate section.

   Important

   You must set the value of the

   create-monitor

   property to

   True

   if you use services that have the value of the

   .spec.externalTrafficPolicy

   property set to

   Local

   . The OVN Octavia provider in RHOSP 16.1 and 16.2 does not support health monitors. Therefore, services that have

   ETP

   parameter values set to

   Local

   might not respond when the

   lb-provider

   value is set to

   "ovn"

   .

   Important

   For installations that use Kuryr, Kuryr handles relevant services. There is no need to configure Octavia load balancing in the cloud provider.

4. Save the changes to the file and proceed with installation.

   Tip

   You can update your cloud provider configuration after you run the installer. On a command line, run:

   $ oc edit configmap -n openshift-config cloud-provider-config

   After you save your changes, your cluster will take some time to reconfigure itself. The process is complete if none of your nodes have a

   SchedulingDisabled

   status.

Procedure

1. Access the Infrastructure Provider page on the OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.
2. Select your infrastructure provider.

3. Navigate to the page for your installation type, download the installation program that corresponds with your host operating system and architecture, and place the file in the directory where you will 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 files are required to delete the cluster.

   Important

   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.

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

5. Download your installation pull secret from the 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 the

   install-config.yaml

   file.

   1. Change to the directory that contains the installation program and run the following command:

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

      1

      1

      For <installation_directory>, specify the directory name to store the files that the installation program creates.

      When specifying the directory:

      • Verify that the directory has the

        execute

        permission. This permission is required to run Terraform binaries under the installation directory.
      • Use an empty directory. Some installation assets, such as bootstrap X.509 certificates, have short expiration intervals, therefore 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. At the prompts, provide the configuration details for your cloud:

      1. Optional: Select an SSH key to use to access your cluster machines.

         Note

         For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your

         ssh-agent

         process uses.

      2. Select openstack as the platform to target.
      3. Specify the Red Hat OpenStack Platform (RHOSP) external network name to use for installing the cluster.
      4. Specify the floating IP address to use for external access to the OpenShift API.
      5. Specify a RHOSP flavor with at least 16 GB RAM to use for control plane nodes and 8 GB RAM for compute nodes.
      6. Select the base domain to deploy the cluster to. All DNS records will be sub-domains of this base and will also include the cluster name.
      7. Enter a name for your cluster. The name must be 14 or fewer characters long.
      8. Paste the pull secret from the Red Hat OpenShift Cluster Manager.
2. Modify the

   install-config.yaml

   file. You can find more information about the available parameters in the "Installation configuration parameters" section.

3. Back up the

   install-config.yaml

   file so that you can use it to install multiple clusters.
   Important

   The

   install-config.yaml

   file is consumed during the installation process. If you want to reuse the file, you must back it up now.