Installing a cluster on VMC in a restricted network

In OKD version 4.7, you can install a cluster on VMware vSphere infrastructure in a restricted network by deploying it to VMware Cloud (VMC) on AWS.

Once you configure your VMC environment for OKD deployment, you use the OKD installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the OKD cluster.

Setting up VMC for vSphere

You can install OKD on VMware Cloud (VMC) on AWS hosted vSphere clusters to enable applications to be deployed and managed both on-premise and off-premise, across the hybrid cloud.

You must configure several options in your VMC environment prior to installing OKD on VMware vSphere. Ensure your VMC environment has the following prerequisites:

• Create a non-exclusive, DHCP-enabled, NSX-T network segment and subnet. Other virtual machines (VMs) can be hosted on the subnet, but at least eight IP addresses must be available for the OKD deployment.

• Allocate two IP addresses, outside the DHCP range, and configure them with reverse DNS records.

  • A DNS record for api.<cluster_name>.<base_domain> pointing to the allocated IP address.

  • A DNS record for *.apps.<cluster_name>.<base_domain> pointing to the allocated IP address.

• Configure the following firewall rules:

  • An ANY:ANY firewall rule between the installation host and the software-defined data center (SDDC) management network on port 443. This allows you to upload the Fedora CoreOS (FCOS) OVA during deployment.

  • An HTTPS firewall rule between the OKD compute network and vCenter. This connection allows OKD to communicate with vCenter for provisioning and managing nodes, persistent volume claims (PVCs), and other resources.

• You must have the following information to deploy OKD:

  • The OKD cluster name, such as vmc-prod-1.

  • The base DNS name, such as companyname.com.

  • If not using the default, the pod network CIDR and services network CIDR must be identified, which are set by default to 10.128.0.0/14 and 172.30.0.0/16, respectively. These CIDRs are used for pod-to-pod and pod-to-service communication and are not accessible externally; however, they must not overlap with existing subnets in your organization.

  • The following vCenter information:

    • vCenter hostname, username, and password

    • Datacenter name, such as SDDC-Datacenter

    • Cluster name, such as Cluster-1

    • Network name

    • Datastore name, such as WorkloadDatastore

      It is recommended to move your vSphere cluster to the VMC Compute-ResourcePool resource pool after your cluster installation is finished.

• A Linux-based host deployed to VMC as a bastion.

  • The bastion host can be Fedora or any another Linux-based host; it must have Internet connectivity and the ability to upload an OVA to the ESXi hosts.

  • Download and install the OpenShift CLI tools to the bastion host.

    • The openshift-install installation program

    • The OpenShift CLI (oc) tool

VMC Sizer tool

VMware Cloud on AWS is built on top of AWS bare metal infrastructure; this is the same bare metal infrastructure which runs AWS native services. When a VMware cloud on AWS software-defined data center (SDDC) is deployed, you consume these physical server nodes and run the VMware ESXi hypervisor in a single tenant fashion. This means the physical infrastructure is not accessible to anyone else using VMC. It is important to consider how many physical hosts you will need to host your virtual infrastructure.

To determine this, VMware provides the VMC on AWS Sizer. With this tool, you can define the resources you intend to host on VMC:

• Types of workloads

• Total number of virtual machines

• Specification information such as:

  • Storage requirements

  • vCPUs

  • vRAM

  • Overcommit ratios

With these details, the sizer tool can generate a report, based on VMware best practices, and recommend your cluster configuration and the number of hosts you will need.

vSphere prerequisites

• Create a registry on your mirror host and obtain the imageContentSources data for your version of OKD.

  Because the installation media is on the mirror host, you can use that computer to complete all installation steps.

• Provision block registry storage. For more information on persistent storage, see Understanding persistent storage.

• Review details about the OKD installation and update processes.

• If you use a firewall and plan to use telemetry, you must configure the firewall to allow the sites that your cluster requires access to.

  If you are configuring a proxy, be sure to also review this site list.

About installations in restricted networks

In OKD 4.7, you can perform an installation that does not require an active connection to the Internet to obtain software components. Restricted network installations can be completed using installer-provisioned infrastructure or user-provisioned infrastructure, depending on the cloud platform to which you are installing the cluster.

If you choose to perform a restricted network installation on a cloud platform, you still require access to its cloud APIs. Some cloud functions, like Amazon Web Service’s IAM service, require Internet access, so you might still require Internet access. Depending on your network, you might require less Internet access for an installation on bare metal hardware or on VMware vSphere.

To complete a restricted network installation, you must create a registry that mirrors the contents of the OKD registry and contains the installation media. You can create this registry on a mirror host, which can access both the Internet and your closed network, or by using other methods that meet your restrictions.

Additional limits

Clusters in restricted networks have the following additional limitations and restrictions:

• The ClusterVersion status includes an Unable to retrieve available updates error.

• By default, you cannot use the contents of the Developer Catalog because you cannot access the required image stream tags.

VMware vSphere infrastructure requirements

You must install the OKD cluster on a VMware vSphere version 6 or 7 instance that meets the requirements for the components that you use.

If you use a vSphere version 6.5 instance, consider upgrading to 6.7U3 or 7.0 before you install OKD.

vCenter requirements

Before you install an OKD cluster on your vCenter that uses infrastructure that the installer provisions, you must prepare your environment.

Required vCenter account privileges

To install an OKD cluster in a vCenter, the installation program requires access to an account with privileges to read and create the required resources. Using an account that has global administrative privileges is the simplest way to access all of the necessary permissions.

If you cannot use an account with global adminstrative privileges, you must create roles to grant the privileges necessary for OKD cluster installation. While most of the privileges are always required, some are required only if you plan for the installation program to provision a folder to contain the OKD cluster on your vCenter instance, which is the default behavior. You must create or amend vSphere roles for the specified objects to grant the required privileges.

An additional role is required if the installation program is to create a vSphere virtual machine folder.

Roles and privileges required for installation

Additionally, the user requires some ReadOnly permissions, and some of the roles require permission to propogate the permissions to child objects. These settings vary depending on whether or not you install the cluster into an existing folder.

Required permissions and propagation settings

For more information about creating an account with only the required privileges, see vSphere Permissions and User Management Tasks in the vSphere documentation.

Using OKD with vMotion

If you are using vSphere volumes in your pods, migrating a VM across datastores either manually or through Storage vMotion causes invalid references within OKD persistent volume (PV) objects. These references prevent affected pods from starting up and can result in data loss.

Similarly, OKD does not support selective migration of VMDKs across datastores, using datastore clusters for VM provisioning or for dynamic or static provisioning of PVs, or using a datastore that is part of a datastore cluster for dynamic or static provisioning of PVs.

Cluster resources

When you deploy an OKD cluster that uses installer-provisioned infrastructure, the installation program must be able to create several resources in your vCenter instance.

A standard OKD installation creates the following vCenter resources:

• 1 Folder

• 1 Tag category

• 1 Tag

• Virtual machines:

  • 1 template

  • 1 temporary bootstrap node

  • 3 control plane nodes

  • 3 compute machines

Although these resources use 856 GB of storage, the bootstrap node is destroyed during the cluster installation process. A minimum of 800 GB of storage is required to use a standard cluster.

If you deploy more compute machines, the OKD cluster will use more storage.

Cluster limits

Available resources vary between clusters. The number of possible clusters within a vCenter is limited primarily by available storage space and any limitations on the number of required resources. Be sure to consider both limitations to the vCenter resources that the cluster creates and the resources that you require to deploy a cluster, such as IP addresses and networks.

Networking requirements

You must use DHCP for the network and ensure that the DHCP server is configured to provide persistent IP addresses to the cluster machines. The VM in your restricted network must have access to vCenter so that it can provision and manage nodes, persistent volume claims (PVCs), and other resources. Additionally, you must create the following networking resources before you install the OKD cluster:

Required IP Addresses

An installer-provisioned vSphere installation requires two static IP addresses:

• The API address is used to access the cluster API.

• The Ingress address is used for cluster ingress traffic.

You must provide these IP addresses to the installation program when you install the OKD cluster.

DNS records

You must create DNS records for two static IP addresses in the appropriate DNS server for the vCenter instance that hosts your OKD cluster. In each record, <cluster_name> is the cluster name and <base_domain> is the cluster base domain that you specify when you install the cluster. A complete DNS record takes the form: <component>.<cluster_name>.<base_domain>..

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.

Adding vCenter root CA certificates to your system trust

Because the installation program requires access to your vCenter’s API, you must add your vCenter’s trusted root CA certificates to your system trust before you install an OKD cluster.

Procedure

1. From the vCenter home page, download the vCenter’s root CA certificates. Click Download trusted root CA certificates in the vSphere Web Services SDK section. The <vCenter>/certs/download.zip file downloads.

2. Extract the compressed file that contains the vCenter root CA certificates. The contents of the compressed file resemble the following file structure:

   certs
   ├── lin
   │   ├── 108f4d17.0
   │   ├── 108f4d17.r1
   │   ├── 7e757f6a.0
   │   ├── 8e4f8471.0
   │   └── 8e4f8471.r0
   ├── mac
   │   ├── 108f4d17.0
   │   ├── 108f4d17.r1
   │   ├── 7e757f6a.0
   │   ├── 8e4f8471.0
   │   └── 8e4f8471.r0
   └── win
       ├── 108f4d17.0.crt
       ├── 108f4d17.r1.crl
       ├── 7e757f6a.0.crt
       ├── 8e4f8471.0.crt
       └── 8e4f8471.r0.crl
   3 directories, 15 files

3. Add the files for your operating system to the system trust. For example, on a Fedora operating system, run the following command:

   # cp certs/lin/* /etc/pki/ca-trust/source/anchors

4. Update your system trust. For example, on a Fedora operating system, run the following command:

   # update-ca-trust extract

Creating the FCOS image for restricted network installations

Download the Fedora CoreOS (FCOS) image to install OKD on a restricted network VMware vSphere environment.

Prerequisites

• Obtain the OKD installation program. For a restricted network installation, the program is on your mirror registry host.

Procedure

1. Log in to the Red Hat Customer Portal’s Product Downloads page.

2. Under Version, select the most recent release of OKD 4.7 for RHEL 8.

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

3. Download the Fedora CoreOS (FCOS) - vSphere image.

4. Upload the image you downloaded to a location that is accessible from the bastion server.

The image is now available for a restricted installation. Note the image name or location for use in OKD deployment.

Creating the installation configuration file

You can customize the OKD cluster you install on VMware vSphere.

Prerequisites

• Obtain the OKD installation program and the pull secret for your cluster. For a restricted network installation, these files are on your mirror host.

• Have the imageContentSources values that were generated during mirror registry creation.

• Obtain the contents of the certificate for your mirror registry.

• Retrieve a Fedora CoreOS (FCOS) image and upload it to an accessible location.

• Obtain service principal permissions at the subscription level.

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 vsphere as the platform to target.

      3. Specify the name of your vCenter instance.

      4. Specify the user name and password for the vCenter account that has the required permissions to create the cluster.

         The installation program connects to your vCenter instance.

      5. Select the datacenter in your vCenter instance to connect to.

      6. Select the default vCenter datastore to use.

      7. Select the vCenter cluster to install the OKD cluster in. The installation program uses the root resource pool of the vSphere cluster as the default resource pool.

      8. Select the network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured.

      9. Enter the virtual IP address that you configured for control plane API access.

      10. Enter the virtual IP address that you configured for cluster ingress.

      11. Enter the base domain. This base domain must be the same one that you used in the DNS records that you configured.

      12. Enter a descriptive name for your cluster. The cluster name must be the same one that you used in the DNS records that you configured.

      13. 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. In the install-config.yaml file, set the value of platform.vsphere.clusterOSImage to the image location or name. For example:

   platform:
     vsphere:
         clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-vmware.x86_64.ova?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d

2. Edit the install-config.yaml file to provide 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, which 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 look like this excerpt:

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

      To complete these values, use the imageContentSources that you recorded during mirror registry creation.

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

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

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 VMware vSphere configuration parameters

Additional VMware vSphere configuration parameters are described in the following table:

Optional VMware vSphere machine pool configuration parameters

Optional VMware vSphere machine pool configuration parameters are described in the following table:

Sample install-config.yaml file for an installer-provisioned VMware vSphere cluster

You can customize the install-config.yaml file to specify more details about your OKD cluster’s platform or modify the values of the required parameters.

apiVersion: v1
baseDomain: example.com (1)
compute: (2)
- hyperthreading: Enabled (3)
  name: worker
  replicas: 3
  platform:
    vsphere: (4)
      cpus: 2
      coresPerSocket: 2
      memoryMB: 8196
      osDisk:
        diskSizeGB: 120
controlPlane: (2)
  hyperthreading: Enabled (3)
  name: master
  replicas: 3
  platform:
    vsphere: (4)
      cpus: 4
      coresPerSocket: 2
      memoryMB: 16384
      osDisk:
        diskSizeGB: 120
metadata:
  name: cluster (5)
platform:
  vsphere:
    vcenter: your.vcenter.server
    username: username
    password: password
    datacenter: datacenter
    defaultDatastore: datastore
    folder: folder
    network: VM_Network
    cluster: vsphere_cluster_name (6)
    apiVIP: api_vip
    ingressVIP: ingress_vip
    clusterOSImage: http://mirror.example.com/images/rhcos-48.83.202103221318-0-vmware.x86_64.ova (7)
pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' (8)
sshKey: 'ssh-ed25519 AAAA...'
additionalTrustBundle: | (9)
  -----BEGIN CERTIFICATE-----
  ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
  -----END CERTIFICATE-----
imageContentSources: (10)
- mirrors:
  - <local_registry>/<local_repository_name>/release
  source: quay.io/openshift-release-dev/ocp-release
- mirrors:
  - <local_registry>/<local_repository_name>/release
  source: quay.io/openshift-release-dev/ocp-v4.0-art-dev

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. You must include vCenter’s IP address and the IP range that you use for its machines.
   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.

Deploying the cluster

You can install OKD on a compatible cloud platform.

Prerequisites

• Configure an account with the cloud platform that hosts your cluster.

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

   Use the openshift-install command from the bastion hosted in the VMC environment.

   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.

Installing the OpenShift CLI by downloading the binary

You can install the OpenShift CLI (oc) to interact with OKD from a command-line interface. You can install oc on Linux, Windows, or macOS.

Installing the OpenShift CLI on Linux

You can install the OpenShift CLI (oc) binary on Linux by using the following procedure.

Procedure

1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

2. Download oc.tar.gz.

3. Unpack the archive:

   $ tar xvzf <file>

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

   To check your PATH, execute the following command:

   $ echo $PATH

After you install the OpenShift CLI, it is available using the oc command:

$ oc <command>

Installing the OpenShift CLI on Windows

You can install the OpenShift CLI (oc) binary on Windows by using the following procedure.

Procedure

1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

2. Download oc.zip.

3. Unzip the archive with a ZIP program.

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

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

   C:\> path

After you install the OpenShift CLI, it is available using the oc command:

C:\> oc <command>

Installing the OpenShift CLI on macOS

You can install the OpenShift CLI (oc) binary on macOS by using the following procedure.

Procedure

1. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.

2. Download oc.tar.gz.

3. Unpack and unzip the archive.

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

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

   $ echo $PATH

After you install the OpenShift CLI, it is available using the oc command:

$ oc <command>

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

Disabling the default OperatorHub sources

Operator catalogs that source content provided by Red Hat and community projects are configured for OperatorHub by default during an OKD installation. In a restricted network environment, you must disable the default catalogs as a cluster administrator.

Procedure

• Disable the sources for the default catalogs by adding disableAllDefaultSources: true to the OperatorHub object:

  $ oc patch OperatorHub cluster --type json \
      -p '[{"op": "add", "path": "/spec/disableAllDefaultSources", "value": true}]'

Creating registry storage

After you install the cluster, you must create storage for the Registry Operator.

Image registry removed during installation

On platforms that do not provide shareable object storage, the OpenShift Image Registry Operator bootstraps itself as Removed. This allows openshift-installer to complete installations on these platform types.

After installation, you must edit the Image Registry Operator configuration to switch the managementState from Removed to Managed.

Image registry storage configuration

The Image Registry Operator is not initially available for platforms that do not provide default storage. After installation, you must configure your registry to use storage so that the Registry Operator is made available.

Instructions are shown for configuring a persistent volume, which is required for production clusters. Where applicable, instructions are shown for configuring an empty directory as the storage location, which is available for only non-production clusters.

Additional instructions are provided for allowing the image registry to use block storage types by using the Recreate rollout strategy during upgrades.

Configuring registry storage for VMware vSphere

As a cluster administrator, following installation you must configure your registry to use storage.

Prerequisites

• Cluster administrator permissions.

• A cluster on VMware vSphere.

• Persistent storage provisioned for your cluster, such as Red Hat OpenShift Container Storage.

  OKD supports ReadWriteOnce access for image registry storage when you have only one replica. To deploy an image registry that supports high availability with two or more replicas, ReadWriteMany access is required.

• Must have “100Gi” capacity.

Procedure

1. To configure your registry to use storage, change the spec.storage.pvc in the configs.imageregistry/cluster resource.

   When using shared storage, review your security settings to prevent outside access.

2. Verify that you do not have a registry pod:

   $ oc get pod -n openshift-image-registry

   If the storage type is emptyDIR, the replica number cannot be greater than 1.

3. Check the registry configuration:

   $ oc edit configs.imageregistry.operator.openshift.io

   Example output

   storage:
     pvc:
       claim: (1)

   1	Leave the claim field blank to allow the automatic creation of an image-registry-storage PVC.

4. Check the clusteroperator status:

   $ oc get clusteroperator image-registry

Additional resources

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

Next steps

• Customize your cluster.

• Configure image streams for the Cluster Samples Operator and the must-gather tool.

• Learn how to use Operator Lifecycle Manager (OLM) on restricted networks.

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

• Set up your registry and configure registry storage.