Installing a cluster on OpenStack with Kuryr

In OKD version 4.6, you can install a customized cluster on Red Hat OpenStack Platform (RHOSP) that uses Kuryr SDN. To customize the installation, modify parameters in the install-config.yaml before you install the cluster.

Prerequisites

• Review details about the OKD installation and update processes.

  • Verify that OKD 4.6 is compatible with your RHOSP version in the Available platforms section. You can also compare platform support across different versions by viewing the OKD on RHOSP support matrix.

• Verify that your network configuration does not rely on a provider network. Provider networks are not supported.

• Have a storage service installed in RHOSP, like block storage (Cinder) or object storage (Swift). Object storage is the recommended storage technology for OKD registry cluster deployment. For more information, see Optimizing storage.

About Kuryr SDN

Kuryr is a container network interface (CNI) plug-in solution that uses the Neutron and Octavia Red Hat OpenStack Platform (RHOSP) services to provide networking for pods and Services.

Kuryr and OKD integration is primarily designed for OKD clusters running on RHOSP VMs. Kuryr improves the network performance by plugging OKD pods into RHOSP SDN. In addition, it provides interconnectivity between pods and RHOSP virtual instances.

Kuryr components are installed as pods in OKD using the openshift-kuryr namespace:

• kuryr-controller - a single service instance installed on a master node. This is modeled in OKD as a Deployment object.

• kuryr-cni - a container installing and configuring Kuryr as a CNI driver on each OKD node. This is modeled in OKD as a DaemonSet object.

The Kuryr controller watches the OKD API server for pod, service, and namespace create, update, and delete events. It maps the OKD API calls to corresponding objects in Neutron and Octavia. This means that every network solution that implements the Neutron trunk port functionality can be used to back OKD via Kuryr. This includes open source solutions such as Open vSwitch (OVS) and Open Virtual Network (OVN) as well as Neutron-compatible commercial SDNs.

Kuryr is recommended for OKD deployments on encapsulated RHOSP tenant networks to avoid double encapsulation, such as running an encapsulated OKD SDN over an RHOSP network.

If you use provider networks or tenant VLANs, you do not need to use Kuryr to avoid double encapsulation. The performance benefit is negligible. Depending on your configuration, though, using Kuryr to avoid having two overlays might still be beneficial.

Kuryr is not recommended in deployments where all of the following criteria are true:

• The RHOSP version is less than 16.

• The deployment uses UDP services, or a large number of TCP services on few hypervisors.

or

• The ovn-octavia Octavia driver is disabled.

• The deployment uses a large number of TCP services on few hypervisors.

Resource guidelines for installing OKD on RHOSP with Kuryr

When using Kuryr SDN, the pods, services, namespaces, and network policies are using resources from the RHOSP quota; this increases the minimum requirements. Kuryr also has some additional requirements on top of what a default install requires.

Use the following quota to satisfy a default cluster’s minimum requirements:

A cluster might function with fewer than recommended resources, but its performance is not guaranteed.

Take the following notes into consideration when setting resources:

• The number of ports that are required is larger than the number of pods. Kuryr uses ports pools to have pre-created ports ready to be used by pods and speed up the pods’ booting time.

• Each network policy is mapped into an RHOSP security group, and depending on the NetworkPolicy spec, one or more rules are added to the security group.

• Each service is mapped to an RHOSP load balancer. Consider this requirement when estimating the number of security groups required for the quota.

  If you are using RHOSP version 15 or earlier, or the ovn-octavia driver, each load balancer has a security group with the user project.

• The quota does not account for load balancer resources (such as VM resources), but you must consider these resources when you decide the RHOSP deployment’s size. The default installation will have more than 50 load balancers; the clusters must be able to accommodate them.

  If you are using RHOSP version 16 with the OVN Octavia driver enabled, only one load balancer VM is generated; services are load balanced through OVN flows.

An OKD deployment comprises control plane machines, compute machines, and a bootstrap machine.

To enable Kuryr SDN, your environment must meet the following requirements:

• Run RHOSP 13+.

• Have Overcloud with Octavia.

• Use Neutron Trunk ports extension.

• Use openvswitch firewall driver if ML2/OVS Neutron driver is used instead of ovs-hybrid.

Increasing quota

When using Kuryr SDN, you must increase quotas to satisfy the Red Hat OpenStack Platform (RHOSP) resources used by pods, services, namespaces, and network policies.

Procedure

• Increase the quotas for a project by running the following command:

  $ sudo openstack quota set --secgroups 250 --secgroup-rules 1000 --ports 1500 --subnets 250 --networks 250 <project>

Configuring Neutron

Kuryr CNI leverages the Neutron Trunks extension to plug containers into the Red Hat OpenStack Platform (RHOSP) SDN, so you must use the trunks extension for Kuryr to properly work.

In addition, if you leverage the default ML2/OVS Neutron driver, the firewall must be set to openvswitch instead of ovs_hybrid so that security groups are enforced on trunk subports and Kuryr can properly handle network policies.

Configuring Octavia

Kuryr SDN uses Red Hat OpenStack Platform (RHOSP)’s Octavia LBaaS to implement OKD services. Thus, you must install and configure Octavia components in RHOSP to use Kuryr SDN.

To enable Octavia, you must include the Octavia service during the installation of the RHOSP Overcloud, or upgrade the Octavia service if the Overcloud already exists. The following steps for enabling Octavia apply to both a clean install of the Overcloud or an Overcloud update.

Procedure

1. If you are using the local registry, create a template to upload the images to the registry. For example:

   (undercloud) $ openstack overcloud container image prepare \
   -e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/octavia.yaml \
   --namespace=registry.access.redhat.com/rhosp13 \
   --push-destination=<local-ip-from-undercloud.conf>:8787 \
   --prefix=openstack- \
   --tag-from-label {version}-{release} \
   --output-env-file=/home/stack/templates/overcloud_images.yaml \
   --output-images-file /home/stack/local_registry_images.yaml

2. Verify that the local_registry_images.yaml file contains the Octavia images. For example:

   ...
   - imagename: registry.access.redhat.com/rhosp13/openstack-octavia-api:13.0-43
     push_destination: <local-ip-from-undercloud.conf>:8787
   - imagename: registry.access.redhat.com/rhosp13/openstack-octavia-health-manager:13.0-45
     push_destination: <local-ip-from-undercloud.conf>:8787
   - imagename: registry.access.redhat.com/rhosp13/openstack-octavia-housekeeping:13.0-45
     push_destination: <local-ip-from-undercloud.conf>:8787
   - imagename: registry.access.redhat.com/rhosp13/openstack-octavia-worker:13.0-44
     push_destination: <local-ip-from-undercloud.conf>:8787

   The Octavia container versions vary depending upon the specific RHOSP release installed.

3. Pull the container images from registry.redhat.io to the Undercloud node:

   (undercloud) $ sudo openstack overcloud container image upload \
     --config-file  /home/stack/local_registry_images.yaml \
     --verbose

   This may take some time depending on the speed of your network and Undercloud disk.

4. Since an Octavia load balancer is used to access the OKD API, you must increase their listeners’ default timeouts for the connections. The default timeout is 50 seconds. Increase the timeout to 20 minutes by passing the following file to the Overcloud deploy command:

   (undercloud) $ cat octavia_timeouts.yaml
   parameter_defaults:
     OctaviaTimeoutClientData: 1200000
     OctaviaTimeoutMemberData: 1200000

   This is not needed for RHOSP 13.0.13+.

5. Install or update your Overcloud environment with Octavia:

   $ openstack overcloud deploy --templates \
     -e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/octavia.yaml \
     -e octavia_timeouts.yaml

   This command only includes the files associated with Octavia; it varies based on your specific installation of RHOSP. See the RHOSP documentation for further information. For more information on customizing your Octavia installation, see installation of Octavia using Director.

   When leveraging Kuryr SDN, the Overcloud installation requires the Neutron trunk extension. This is available by default on director deployments. Use the openvswitch firewall instead of the default ovs-hybrid when the Neutron backend is ML2/OVS. There is no need for modifications if the backend is ML2/OVN.

6. In RHOSP versions earlier than 13.0.13, add the project ID to the octavia.conf configuration file after you create the project.

   • To enforce network policies across services, like when traffic goes through the Octavia load balancer, you must ensure Octavia creates the Amphora VM security groups on the user project.

     This change ensures that required load balancer security groups belong to that project, and that they can be updated to enforce services isolation.

     This task is unnecessary in RHOSP version 13.0.13 or later. Octavia implements a new ACL API that restricts access to the load balancers VIP.

     1. Get the project ID

        $ openstack project show <project>

        Example output

        +-------------+----------------------------------+
        | Field       | Value                            |
        +-------------+----------------------------------+
        | description |                                  |
        | domain_id   | default                          |
        | enabled     | True                             |
        | id          | PROJECT_ID                       |
        | is_domain   | False                            |
        | name        | *<project>*                      |
        | parent_id   | default                          |
        | tags        | []                               |
        +-------------+----------------------------------+

     2. Add the project ID to octavia.conf for the controllers.

        1. Source the stackrc file:

           $ source stackrc  # Undercloud credentials

        2. List the Overcloud controllers:

           $ openstack server list

           Example output

           +--------------------------------------+--------------+--------+-----------------------+----------------+------------+
           │
           | ID                                   | Name         | Status | Networks
           | Image          | Flavor     |
           │
           +--------------------------------------+--------------+--------+-----------------------+----------------+------------+
           │
           | 6bef8e73-2ba5-4860-a0b1-3937f8ca7e01 | controller-0 | ACTIVE |
           ctlplane=192.168.24.8 | overcloud-full | controller |
           │
           | dda3173a-ab26-47f8-a2dc-8473b4a67ab9 | compute-0    | ACTIVE |
           ctlplane=192.168.24.6 | overcloud-full | compute    |
           │
           +--------------------------------------+--------------+--------+-----------------------+----------------+------------+

        3. SSH into the controller(s).

           $ ssh heat-admin@192.168.24.8

        4. Edit the octavia.conf file to add the project into the list of projects where Amphora security groups are on the user’s account.

           # List of project IDs that are allowed to have Load balancer security groups
           # belonging to them.
           amp_secgroup_allowed_projects = PROJECT_ID

     3. Restart the Octavia worker so the new configuration loads.

        controller-0$ sudo docker restart octavia_worker

The Octavia OVN Driver

Octavia supports multiple provider drivers through the Octavia API.

To see all available Octavia provider drivers, on a command line, enter:

$ openstack loadbalancer provider list

Example output

+---------+-------------------------------------------------+
| name    | description                                     |
+---------+-------------------------------------------------+
| amphora | The Octavia Amphora driver.                     |
| octavia | Deprecated alias of the Octavia Amphora driver. |
| ovn     | Octavia OVN driver.                             |
+---------+-------------------------------------------------+

Beginning with RHOSP version 16, the Octavia OVN provider driver (ovn) is supported on OKD on RHOSP deployments.

ovn is an integration driver for the load balancing that Octavia and OVN provide. It supports basic load balancing capabilities, and is based on OpenFlow rules. The driver is automatically enabled in Octavia by Director on deployments that use OVN Neutron ML2.

The Amphora provider driver is the default driver. If ovn is enabled, however, Kuryr uses it.

If Kuryr uses ovn instead of Amphora, it offers the following benefits:

• Decreased resource requirements. Kuryr does not require a load balancer VM for each service.

• Reduced network latency.

• Increased service creation speed by using OpenFlow rules instead of a VM for each service.

• Distributed load balancing actions across all nodes instead of centralized on Amphora VMs.

You can configure your cluster to use the Octavia OVN driver after your RHOSP cloud is upgraded from version 13 to version 16.

Known limitations of installing with Kuryr

Using OKD with Kuryr SDN has several known limitations.

RHOSP general limitations

OKD with Kuryr SDN does not support Service objects with type NodePort.

If the machines subnet is not connected to a router, or if the subnet is connected, but the router has no external gateway set, Kuryr cannot create floating IPs for Service objects with type LoadBalancer.

RHOSP version limitations

Using OKD with Kuryr SDN has several limitations that depend on the RHOSP version.

• RHOSP versions before 16 use the default Octavia load balancer driver (Amphora). This driver requires that one Amphora load balancer VM is deployed per OKD service. Creating too many services can cause you to run out of resources.

  Deployments of later versions of RHOSP that have the OVN Octavia driver disabled also use the Amphora driver. They are subject to the same resource concerns as earlier versions of RHOSP.

• Octavia RHOSP versions before 13.0.13 do not support UDP listeners. Therefore, OKD UDP services are not supported.

• Octavia RHOSP versions before 13.0.13 cannot listen to multiple protocols on the same port. Services that expose the same port to different protocols, like TCP and UDP, are not supported.

RHOSP environment limitations

There are limitations when using Kuryr SDN that depend on your deployment environment.

Because of Octavia’s lack of support for the UDP protocol and multiple listeners, if the RHOSP version is earlier than 13.0.13, Kuryr forces pods to use TCP for DNS resolution.

In Go versions 1.12 and earlier, applications that are compiled with CGO support disabled use UDP only. In this case, the native Go resolver does not recognize the use-vc option in resolv.conf, which controls whether TCP is forced for DNS resolution. As a result, UDP is still used for DNS resolution, which fails.

To ensure that TCP forcing is allowed, compile applications either with the environment variable CGO_ENABLED set to 1, i.e. CGO_ENABLED=1, or ensure that the variable is absent.

In Go versions 1.13 and later, TCP is used automatically if DNS resolution using UDP fails.

RHOSP upgrade limitations

As a result of the RHOSP upgrade process, the Octavia API might be changed, and upgrades to the Amphora images that are used for load balancers might be required.

You can address API changes on an individual basis.

If the Amphora image is upgraded, the RHOSP operator can handle existing load balancer VMs in two ways:

• Upgrade each VM by triggering a load balancer failover.

• Leave responsibility for upgrading the VMs to users.

If the operator takes the first option, there might be short downtimes during failovers.

If the operator takes the second option, the existing load balancers will not support upgraded Octavia API features, like UDP listeners. In this case, users must recreate their Services to use these features.

Control plane and compute machines

By default, the OKD installation process stands up three control plane and three compute machines.

Each machine requires:

• An instance from the RHOSP quota

• A port from the RHOSP quota

• A flavor with at least 16 GB memory, 4 vCPUs, and 25 GB storage space

Bootstrap machine

During installation, a bootstrap machine is temporarily provisioned to stand up the control plane. After the production control plane is ready, the bootstrap machine is deprovisioned.

The bootstrap machine requires:

• An instance from the RHOSP quota

• A port from the RHOSP quota

• A flavor with at least 16 GB memory, 4 vCPUs, and 25 GB storage space

Enabling Swift on RHOSP

Swift is operated by a user account with the swiftoperator role. Add the role to an account before you run the installation program.

Prerequisites

• You have a RHOSP administrator account on the target environment.

• The Swift service is installed.

• On Ceph RGW, the account in url option is enabled.

Procedure

To enable Swift on RHOSP:

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

Your RHOSP deployment can now use Swift for the image registry.

Verifying external network access

The OKD installation process requires external network access. You must provide an external network value to it, or deployment fails. Before you begin the process, verify that a network with the external router type exists in Red Hat OpenStack Platform (RHOSP).

Prerequisites

• Configure OpenStack’s networking service to have DHCP agents forward instances’ DNS queries

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

A network with an external router type appears in the network list. If at least one does not, see Creating a default floating IP network and Creating a default provider network.

Defining parameters for the installation program

The OKD installation program relies on a file that is called clouds.yaml. The file describes Red Hat OpenStack Platform (RHOSP) configuration parameters, including the project name, log in information, and authorization service URLs.

Procedure

1. Create the clouds.yaml file:

   • If your RHOSP distribution includes the Horizon web UI, generate a clouds.yaml file in it.

     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: shiftstack_user
           password: XXX
           user_domain_name: Default
           project_domain_name: Default
       dev-env:
         region_name: RegionOne
         auth:
           username: 'devuser'
           password: XXX
           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 machine to the certificate authority trust bundle:

      $ sudo cp ca.crt.pem /etc/pki/ca-trust/source/anchors/

   3. Update the trust bundle:

      $ sudo update-ca-trust extract

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

      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.

Obtaining the installation program

Before you install OKD, download the installation file on a local computer.

Prerequisites

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

Procedure

1. Download installer from https://github.com/openshift/okd/releases

   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.

   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 OKD uninstallation procedures for your specific cloud provider.

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

3. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. 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 OKD components.

   Using a pull secret from the Red Hat OpenShift Cluster Manager site is not required. You can use a pull secret for another private registry. Or, if you do not need the cluster to pull images from a private registry, you can use {"auths":{"fake":{"auth":"aWQ6cGFzcwo="}}} as the pull secret when prompted during the installation.

   If you do not use the pull secret from the Red Hat OpenShift Cluster Manager site:

   • Red Hat Operators are not available.

   • The Telemetry and Insights operators do not send data to Red Hat.

   • Content from the Red Hat Container Catalog registry, such as image streams and Operators, are not available.

Creating the installation configuration file

You can customize the OKD cluster you install on Red Hat OpenStack Platform (RHOSP).

Prerequisites

• Obtain the OKD installation program and the pull secret for your cluster.

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.

      Specify an empty directory. Some installation assets, like 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 OKD 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.

         For production OKD 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 and 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 that you obtained from the Pull Secret page on the Red Hat OpenShift Cluster Manager site. This field is optional.

1. Modify the install-config.yaml file. You can find more information about the available parameters in the Installation configuration parameters section.

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

   The install-config.yaml file is consumed during the installation process. If you want to reuse the file, you must back it up now.

Configuring the cluster-wide proxy during installation

Production environments can deny direct access to the Internet and instead have an HTTP or HTTPS proxy available. You can configure a new OKD cluster to use a proxy by configuring the proxy settings in the install-config.yaml file.

Prerequisites

• You have an existing install-config.yaml file.

• You reviewed the sites that your cluster requires access to and determined whether any of them need to bypass the proxy. By default, all cluster egress traffic is proxied, including calls to hosting cloud provider APIs. You added sites to the Proxy object’s spec.noProxy field to bypass the proxy if necessary.

  The Proxy object status.noProxy field is populated with the values of the networking.machineNetwork[].cidr, networking.clusterNetwork[].cidr, and networking.serviceNetwork[] fields from your installation configuration. For installations on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and Red Hat OpenStack Platform (RHOSP), the Proxy object status.noProxy field is also populated with the instance metadata endpoint (169.254.169.254).

• If your cluster is on AWS, you added the ec2.<region>.amazonaws.com, elasticloadbalancing.<region>.amazonaws.com, and s3.<region>.amazonaws.com endpoints to your VPC endpoint. These endpoints are required to complete requests from the nodes to the AWS EC2 API. Because the proxy works on the container level, not the node level, you must route these requests to the AWS EC2 API through the AWS private network. Adding the public IP address of the EC2 API to your allowlist in your proxy server is not sufficient.

Procedure

1. Edit your install-config.yaml file and add the proxy settings. For example:

   apiVersion: v1
   baseDomain: my.domain.com
   proxy:
     httpProxy: http://<username>:<pswd>@<ip>:<port> (1)
     httpsProxy: https://<username>:<pswd>@<ip>:<port> (2)
     noProxy: example.com (3)
   additionalTrustBundle: | (4)
       -----BEGIN CERTIFICATE-----
       <MY_TRUSTED_CA_CERT>
       -----END CERTIFICATE-----
   ...

   1	A proxy URL to use for creating HTTP connections outside the cluster. The URL scheme must be http. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must not specify an httpProxy value.
   2	A proxy URL to use for creating HTTPS connections outside the cluster. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must not specify an httpsProxy value.
   3	A comma-separated list of destination domain names, domains, IP addresses, or other network CIDRs to exclude proxying. Preface a domain with . to match subdomains only. For example, .y.com matches x.y.com, but not y.com. Use * to bypass proxy for all destinations.
   4	If provided, the installation program generates a config map that is named user-ca-bundle in the openshift-config namespace that contains one or more additional CA certificates that are required for proxying HTTPS connections. The Cluster Network Operator then creates a trusted-ca-bundle config map that merges these contents with the Fedora CoreOS (FCOS) trust bundle, and this config map is referenced in the Proxy object’s trustedCA field. The additionalTrustBundle field is required unless the proxy’s identity certificate is signed by an authority from the FCOS trust bundle. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must provide the MITM CA certificate.

   The installation program does not support the proxy readinessEndpoints field.

2. Save the file and reference it when installing OKD.

The installation program creates a cluster-wide proxy that is named cluster that uses the proxy settings in the provided install-config.yaml file. If no proxy settings are provided, a cluster Proxy object is still created, but it will have a nil spec.

Installation configuration parameters

Before you deploy an OKD cluster, you provide parameter values to describe your account on the cloud platform that hosts your cluster and optionally customize your cluster’s platform. When you create the install-config.yaml installation configuration file, you provide values for the required parameters through the command line. If you customize your cluster, you can modify the install-config.yaml file to provide more details about the platform.

Required configuration parameters

Required installation configuration parameters are described in the following table:

Network configuration parameters

You can customize your installation configuration based on the requirements of your existing network infrastructure. For example, you can expand the IP address block for the cluster network or provide different IP address blocks than the defaults.

Only IPv4 addresses are supported.

networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23

networking:
  serviceNetwork:
   - 172.30.0.0/16

networking:
  machineNetwork:
  - cidr: 10.0.0.0/16

Optional configuration parameters

Optional installation configuration parameters are described in the following table:

sshKey:
  <key1>
  <key2>
  <key3>

Additional Red Hat OpenStack Platform (RHOSP) configuration parameters

Additional RHOSP configuration parameters are described in the following table:

Optional RHOSP configuration parameters

Optional RHOSP configuration parameters are described in the following table:

{
   “type”: “ml.large”,
   “rootVolume”: {
      “size”: 30,
      “type”: “performance”
   }
}

Custom subnets in RHOSP deployments

Optionally, you can deploy a cluster on a Red Hat OpenStack Platform (RHOSP) subnet of your choice. The subnet’s GUID is passed as the value of platform.openstack.machinesSubnet in the install-config.yaml file.

This subnet is used as the cluster’s primary subnet; nodes and ports are created on it.

Before you run the OKD installer with a custom subnet, verify that:

• The target network and subnet are available.

• DHCP is enabled on the target subnet.

• You can provide installer credentials that have permission to create ports on the target network.

• If your network configuration requires a router, it is created in RHOSP. Some configurations rely on routers for floating IP address translation.

• Your network configuration does not rely on a provider network. Provider networks are not supported.

Sample customized install-config.yaml file for RHOSP with Kuryr

To deploy with Kuryr SDN instead of the default OpenShift SDN, you must modify the install-config.yaml file to include Kuryr as the desired networking.networkType and proceed with the default OKD SDN installation steps. This sample install-config.yaml demonstrates all of the possible Red Hat OpenStack Platform (RHOSP) customization options.

apiVersion: v1
baseDomain: example.com
clusterID: os-test
controlPlane:
  name: master
  platform: {}
  replicas: 3
compute:
- name: worker
  platform:
    openstack:
      type: ml.large
  replicas: 3
metadata:
  name: example
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  machineNetwork:
  - cidr: 10.0.0.0/16
  serviceNetwork:
  - 172.30.0.0/16 (1)
  networkType: Kuryr
platform:
  openstack:
    cloud: mycloud
    externalNetwork: external
    computeFlavor: m1.xlarge
    lbFloatingIP: 128.0.0.1
    trunkSupport: true (2)
    octaviaSupport: true (2)
pullSecret: '{"auths": ...}'
sshKey: ssh-ed25519 AAAA...

Kuryr ports pools

A Kuryr ports pool maintains a number of ports on standby for pod creation.

Keeping ports on standby minimizes pod creation time. Without ports pools, Kuryr must explicitly request port creation or deletion whenever a pod is created or deleted.

The Neutron ports that Kuryr uses are created in subnets that are tied to namespaces. These pod ports are also added as subports to the primary port of OKD cluster nodes.

Because Kuryr keeps each namespace in a separate subnet, a separate ports pool is maintained for each namespace-worker pair.

Prior to installing a cluster, you can set the following parameters in the cluster-network-03-config.yml manifest file to configure ports pool behavior:

• The enablePortPoolsPrepopulation parameter controls pool prepopulation, which forces Kuryr to add ports to the pool when it is created, such as when a new host is added, or a new namespace is created. The default value is false.

• The poolMinPorts parameter is the minimum number of free ports that are kept in the pool. The default value is 1.

• The poolMaxPorts parameter is the maximum number of free ports that are kept in the pool. A value of 0 disables that upper bound. This is the default setting.

  If your OpenStack port quota is low, or you have a limited number of IP addresses on the pod network, consider setting this option to ensure that unneeded ports are deleted.

• The poolBatchPorts parameter defines the maximum number of Neutron ports that can be created at once. The default value is 3.

Adjusting Kuryr ports pools during installation

During installation, you can configure how Kuryr manages Red Hat OpenStack Platform (RHOSP) Neutron ports to control the speed and efficiency of pod creation.

Prerequisites

• Create and modify the install-config.yaml file.

Procedure

1. From a command line, create the manifest files:

   $ ./openshift-install create manifests --dir=<installation_directory> (1)

   1	For <installation_directory>, specify the name of the directory that contains the install-config.yaml file for your cluster.

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

   $ touch <installation_directory>/manifests/cluster-network-03-config.yml (1)

   1	For <installation_directory>, specify the directory name that contains the manifests/ directory for your cluster.

   After creating the file, several network configuration files are in the manifests/ directory, as shown:

   $ ls <installation_directory>/manifests/cluster-network-*

   Example output

   cluster-network-01-crd.yml
   cluster-network-02-config.yml
   cluster-network-03-config.yml

3. Open the cluster-network-03-config.yml file in an editor, and enter a custom resource (CR) that describes the Cluster Network Operator configuration that you want:

   $ oc edit networks.operator.openshift.io cluster

4. Edit the settings to meet your requirements. The following file is provided as an example:

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec:
     clusterNetwork:
     - cidr: 10.128.0.0/14
       hostPrefix: 23
     serviceNetwork:
     - 172.30.0.0/16
     defaultNetwork:
       type: Kuryr
       kuryrConfig:
         enablePortPoolsPrepopulation: false (1)
         poolMinPorts: 1 (2)
         poolBatchPorts: 3 (3)
         poolMaxPorts: 5 (4)
         openstackServiceNetwork: 172.30.0.0/15 (5)

   1	Set the value of enablePortPoolsPrepopulation to true to make Kuryr create new Neutron ports after a namespace is created or a new node is added to the cluster. This setting raises the Neutron ports quota but can reduce the time that is required to spawn pods. The default value is false.
   2	Kuryr creates new ports for a pool if the number of free ports in that pool is lower than the value of poolMinPorts. The default value is 1.
   3	poolBatchPorts controls the number of new ports that are created if the number of free ports is lower than the value of poolMinPorts. The default value is 3.
   4	If the number of free ports in a pool is higher than the value of poolMaxPorts, Kuryr deletes them until the number matches that value. Setting this value to 0 disables this upper bound, preventing pools from shrinking. The default value is 0.
   5	The openStackServiceNetwork parameter defines the CIDR range of the network from which IP addresses are allocated to RHOSP Octavia’s LoadBalancers.

   If this parameter is used with the Amphora driver, Octavia takes two IP addresses from this network for each load balancer: one for OpenShift and the other for VRRP connections. Because these IP addresses are managed by OKD and Neutron respectively, they must come from different pools. Therefore, the value of openStackServiceNetwork must be at least twice the size of the value of serviceNetwork, and the value of serviceNetwork must overlap entirely with the range that is defined by openStackServiceNetwork.

   The CNO verifies that VRRP IP addresses that are taken from the range that is defined by this parameter do not overlap with the range that is defined by the serviceNetwork parameter.

   If this parameter is not set, the CNO uses an expanded value of serviceNetwork that is determined by decrementing the prefix size by 1.

5. Save the cluster-network-03-config.yml file, and exit the text editor.

6. Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program deletes the manifests/ directory while creating the cluster.

Generating an SSH private key and adding it to the agent

If you want to perform installation debugging or disaster recovery on your cluster, you must provide an SSH key to both your ssh-agent and the installation program. You can use this key to access the bootstrap machine in a public cluster to troubleshoot installation issues.

You can use this key to SSH into the master nodes as the user core. When you deploy the cluster, the key is added to the core user’s ~/.ssh/authorized_keys list.

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, 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_rsa, of the new SSH key. If you have an existing key pair, ensure your public key is in the your ~/.ssh directory.

   Running this command generates an SSH key that does not require a password in the location that you specified.

   If you plan to install an OKD cluster that uses FIPS Validated / 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. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"

   Example output

   Agent pid 31874

   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.

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

   $ ssh-add <path>/<file_name> (1)

   Example output

   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1	Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Next steps

• When you install OKD, provide the SSH public key to the installation program.

Enabling access to the environment

At deployment, all OKD machines are created in a Red Hat OpenStack Platform (RHOSP)-tenant network. Therefore, they are not accessible directly in most RHOSP deployments.

You can configure OKD API and application access by using floating IP addresses (FIPs) during installation. You can also complete an installation without configuring FIPs, but the installer will not configure a way to reach the API or applications externally.

Enabling access with floating IP addresses

Create floating IP (FIP) addresses for external access to the OKD API and cluster applications.

Procedure

1. Using the Red Hat OpenStack Platform (RHOSP) CLI, create the API FIP:

   $ openstack floating ip create --description "API <cluster_name>.<base_domain>" <external_network>

2. Using the Red Hat OpenStack Platform (RHOSP) CLI, create the apps, or Ingress, FIP:

   $ openstack floating ip create --description "Ingress <cluster_name>.<base_domain>" <external_network>

3. Add records that follow these patterns to your DNS server for the API and Ingress FIPs:

   api.<cluster_name>.<base_domain>.  IN  A  <API_FIP>
   *.apps.<cluster_name>.<base_domain>. IN  A <apps_FIP>

   If you do not control the DNS server, you can add the record to your /etc/hosts file. This action makes the API accessible to only you, which is not suitable for production deployment but does allow installation for development and testing.

4. Add the FIPs to the install-config.yaml file as the values of the following parameters:

   • platform.openstack.ingressFloatingIP

   • platform.openstack.lbFloatingIP

If you use these values, you must also enter an external network as the value of the platform.openstack.externalNetwork parameter in the install-config.yaml file.

Completing installation without floating IP addresses

You can install OKD on Red Hat OpenStack Platform (RHOSP) without providing floating IP addresses.

In the install-config.yaml file, do not define the following parameters:

• platform.openstack.ingressFloatingIP

• platform.openstack.lbFloatingIP

If you cannot provide an external network, you can also leave platform.openstack.externalNetwork blank. If you do not provide a value for platform.openstack.externalNetwork, a router is not created for you, and, without additional action, the installer will fail to retrieve an image from Glance. You must configure external connectivity on your own.

If you run the installer from a system that cannot reach the cluster API due to a lack of floating IP addresses or name resolution, installation fails. To prevent installation failure in these cases, you can use a proxy network or run the installer from a system that is on the same network as your machines.

api.<cluster_name>.<base_domain>.  IN  A  <api_port_IP>
*.apps.<cluster_name>.<base_domain>. IN  A <ingress_port_IP>

Deploying the cluster

You can install OKD on a compatible cloud platform.

Prerequisites

• Obtain the OKD installation program and the pull secret for your cluster.

Procedure

1. Change to the directory that contains the installation program and initialize the cluster deployment:

   $ ./openshift-install create cluster --dir=<installation_directory> \ (1)
       --log-level=info (2)

   1	For <installation_directory>, specify the location of your customized ./install-config.yaml file.
   2	To view different installation details, specify warn, debug, or error instead of info.

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Example output

   ...
   INFO Install complete!
   INFO To access the cluster as the system:admin user when using 'oc', run 'export KUBECONFIG=/home/myuser/install_dir/auth/kubeconfig'
   INFO Access the OpenShift web-console here: https://console-openshift-console.apps.mycluster.example.com
   INFO Login to the console with user: "kubeadmin", and password: "4vYBz-Ee6gm-ymBZj-Wt5AL"
   INFO Time elapsed: 36m22s

   The cluster access and credential information also outputs to <installation_directory>/.openshift_install.log when an installation succeeds.

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

Verifying cluster status

You can verify your OKD cluster’s status during or after installation.

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

Logging in to the cluster by using the CLI

You can log in to your cluster as a default system user by exporting the cluster kubeconfig file. 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. The file is specific to a cluster and is created during OKD installation.

Prerequisites

• You deployed an OKD cluster.

• You installed the oc CLI.

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

Additional resources

• See Accessing the web console for more details about accessing and understanding the OKD web console.

Additional resources

• See About remote health monitoring for more information about the Telemetry service

Next steps

• Customize your cluster.

• If necessary, you can opt out of remote health reporting.

• If you need to enable external access to node ports, configure ingress cluster traffic by using a node port.

• If you did not configure RHOSP to accept application traffic over floating IP addresses, configure RHOSP access with floating IP addresses.