Chapter 7. Installing a cluster on OpenStack in a restricted network

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

     .

   • 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 according to the CCM reference guide.

   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.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.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. Log in to the Red Hat Customer Portal’s Product Downloads page.

2. Under Version, select the most recent release of OpenShift Container Platform 4.12 for RHEL 8.

   Important

   The RHCOS images might not change with every release of OpenShift Container Platform. You must download images with the highest version that is less than or equal to the OpenShift Container Platform version that you install. Use the image versions that match your OpenShift Container Platform version if they are available.

3. Download the Red Hat Enterprise Linux CoreOS (RHCOS) - OpenStack Image (QCOW) image.

4. Decompress the image.

   Note

   You must decompress the image before the cluster can use it. The name of the downloaded file might not contain a compression extension, like

   .gz

   or

   .tgz

   . To find out if or how the file is compressed, in a command line, enter:

   $ file <name_of_downloaded_file>

5. Upload the image that you decompressed to a location that is accessible from the bastion server, like Glance. For example:

   $ openstack image create --file rhcos-44.81.202003110027-0-openstack.x86_64.qcow2 --disk-format qcow2 rhcos-${RHCOS_VERSION}

   Important

   Depending on your RHOSP environment, you might be able to upload the image in either .raw or .qcow2 formats. If you use Ceph, you must use the

   .raw

   format.

   Warning

   If the installation program finds multiple images with the same name, it chooses one of them at random. To avoid this behavior, create unique names for resources in RHOSP.

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

   install-config.yaml

   file, set the value of

   platform.openstack.clusterOSImage

   to the image location or name. For example:

   platform:
     openstack:
         clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-openstack.x86_64.qcow2.gz?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d

3. Edit the

   install-config.yaml

   file to give the additional information that is required for an installation in a restricted network.

   1. Update the

      pullSecret

      value to contain the authentication information for your registry:

      pullSecret: '{"auths":{"<mirror_host_name>:5000": {"auth": "<credentials>","email": "you@example.com"}}}'

      For

      <mirror_host_name>

      , specify the registry domain name that you specified in the certificate for your mirror registry, and for

      <credentials>

      , specify the base64-encoded user name and password for your mirror registry.

   2. Add the

      additionalTrustBundle

      parameter and value.

      additionalTrustBundle: |
        -----BEGIN CERTIFICATE-----
        ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
        -----END CERTIFICATE-----

      The value must be the contents of the certificate file that you used for your mirror registry. The certificate file can be an existing, trusted certificate authority, or the self-signed certificate that you generated for the mirror registry.

   3. Add the image content resources, which resemble the following YAML excerpt:

      imageContentSources:
      - mirrors:
        - <mirror_host_name>:5000/<repo_name>/release
        source: quay.io/openshift-release-dev/ocp-release
      - mirrors:
        - <mirror_host_name>:5000/<repo_name>/release
        source: registry.redhat.io/ocp/release

      For these values, use the

      imageContentSources

      that you recorded during mirror registry creation.

4. Make any other modifications to the

   install-config.yaml

   file that you require. You can find more information about the available parameters in the Installation configuration parameters section.

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

   ,

   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

   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