Chapter 1. Installing a cluster on Oracle Cloud Infrastructure (OCI) by using the Assisted Installer
Chapter 1. Installing a cluster on Oracle Cloud Infrastructure (OCI) by using the Assisted Installer You can use the Assisted Installer to install a cluster on Oracle(R) Cloud Infrastructure (OCI). This method is recommended for most users, and requires an internet connection. If you want to set up the cluster manually or using other automation tools, or if you are working in a disconnected environment, you can use the Red Hat Agent-based Installer for the installation. For details, see Installing a cluster on Oracle Cloud Infrastructure (OCI) by using the Agent-based Installer . Note You can deploy OpenShift Container Platform on a Dedicated Region (Oracle documentation) the same as any region from Oracle Cloud Infrastructure (OCI). 1.1. About the Assisted Installer and OCI integration You can run cluster workloads on Oracle(R) Cloud Infrastructure (OCI) infrastructure that supports dedicated, hybrid, public, and multiple cloud environments. Both Red Hat and Oracle test, validate, and support running OCI in an OpenShift Container Platform cluster on OCI. This section explains how to use the Assisted Installer to install an OpenShift Container Platform cluster on the OCI platform. The installation deploys cloud-native components such as Oracle Cloud Controller Manager (CCM) and Oracle Container Storage Interface (CSI), and integrates your cluster with OCI API resources such as instance node, load balancer, and storage. The installation process uses the OpenShift Container Platform discovery ISO image provided by Red Hat, together with the scripts and manifests provided and maintained by OCI. 1.1.1. Preinstallation considerations Before installing OpenShift Container Platform on Oracle Cloud Infrastructure (OCI), you must consider the following configuration choices. Deployment platforms The integration between OpenShift Container Platform and Oracle Cloud Infrastructure (OCI) is certified on both virtual machines (VMs) and bare-metal (BM) machines. Bare-metal installations using iSCSI boot drives require a secondary vNIC that is automatically created in the Terraform stack provided by Oracle. Before you create a virtual machine (VM) or bare-metal (BM) machine, you must identify the relevant OCI shape. For details, see the following resource: Cloud instance types (Red Hat Ecosystem Catalog portal) . VPU sizing recommendations To ensure the best performance conditions for your cluster workloads that operate on OCI, ensure that volume performance units (VPUs) for your block volume are sized for your workloads. The following list provides guidance for selecting the VPUs needed for specific performance needs: Test or proof of concept environment: 100 GB, and 20 to 30 VPUs. Basic environment: 500 GB, and 60 VPUs. Heavy production environment: More than 500 GB, and 100 or more VPUs. Consider reserving additional VPUs to provide sufficient capacity for updates and scaling activities. For more information about VPUs, see Volume Performance Units (Oracle documentation) . Instance sizing recommendations Find recommended values for compute instance CPU, memory, VPU, and volume size for OpenShift Container Platform nodes. For details, see Instance Sizing Recommendations for OpenShift Container Platform on OCI Nodes (Oracle documentation) . 1.1.2. Workflow The procedure for using the Assisted Installer in a connected environment to install a cluster on OCI is outlined below: In the OCI console, configure an OCI account to host the cluster: Create a new child compartment under an existing compartment. Create a new object storage bucket or use one provided by OCI. Download the stack file template stored locally. In the Assisted Installer console, set up a cluster: Enter the cluster configurations. Generate and download the discovery ISO image. In the OCI console, create the infrastructure: Upload the discovery ISO image to the OCI bucket. Create a Pre-Authenticated Request (PAR) for the ISO image. Upload the stack file template, and use it to create and apply the stack. Copy the custom manifest YAML file from the stack. In the Assisted Installer console, complete the cluster installation: Set roles for the cluster nodes. Upload the manifests provided by Oracle. Install the cluster. Important The steps for provisioning OCI resources are provided as an example only. You can also choose to create the required resources through other methods; the scripts are just an example. Installing a cluster with infrastructure that you provide requires knowledge of the cloud provider and the installation process on OpenShift Container Platform. You can access OCI configurations to complete these steps, or use the configurations to model your own custom script. Additional resources Assisted Installer for OpenShift Container Platform Installing a Cluster with Red Hat's Assisted Installer (Oracle documentation) Internet access for OpenShift Container Platform 1.2. Preparing the OCI environment Before installing OpenShift Container Platform using Assisted Installer, create the necessary resources and download the configuration file in the OCI environment. Prerequisites You have an OCI account to host the cluster. If you use a firewall and you plan to use a Telemetry service, you configured your firewall to allow OpenShift Container Platform to access the sites required. Procedure Log in to your Oracle Cloud Infrastructure (OCI) account with administrator privileges. Configure the account by defining the Cloud Accounts and Resources (Oracle documentation) . Ensure that you create the following resources: Create a child compartment for organizing, restricting access, and setting usage limits to OCI resources. For the full procedure, see Creating a Compartment (Oracle documentation) . Create a new object storage bucket into which you will upload the discovery ISO image. For the full procedure, see Creating an Object Storage Bucket (Oracle documentation) . Download the latest version of the create-cluster-vX.X.X.zip configuration file from the oracle-quickstart/oci-openshift repository. This file provides the infrastructure for the cluster and contains configurations for the following: Terraform Stacks : The Terraform stack code for provisioning OCI resources to create and manage OpenShift Container Platform clusters on OCI. Custom Manifests : The manifest files needed for the installation of OpenShift Container Platform clusters on OCI. Note To make any changes to the manifests, you can clone the entire Oracle GitHub repository and access the custom_manifests and terraform-stacks directories directly. For details, see Configuration Files (Oracle documentation) . 1.3. Using the Assisted Installer to generate an OCI-compatible discovery ISO image Create the cluster configuration and generate the discovery ISO image in the Assisted Installer web console. Prerequisites You created a child compartment and an object storage bucket on OCI. For details, see Preparing the OCI environment . You reviewed details about the OpenShift Container Platform installation and update processes. 1.3.1. Creating the cluster Set the cluster details. Procedure Log into Assisted Installer web console with your credentials. In the Red Hat OpenShift tile, select OpenShift . In the Red Hat OpenShift Container Platform tile, select Create Cluster . On the Cluster Type page, scroll down to the end of the Cloud tab, and select Oracle Cloud Infrastructure (virtual machines) . On the Create an OpenShift Cluster page, select the Interactive tile. On the Cluster Details page, complete the following fields: Field Action required Cluster name Specify the name of your cluster, such as oci . This is the same value as the cluster name in OCI. Base domain Specify the base domain of the cluster, such as openshift-demo.devcluster.openshift.com . This must be the same value as the zone DNS server in OCI. OpenShift version * For installations on virtual machines only, specify OpenShift 4.14 or a later version. * For installations that include bare metal machines, specify OpenShift 4.16 or a later version. CPU architecture Specify x86_64 or Arm64 . Integrate with external partner platforms Specify Oracle Cloud Infrastructure . After you specify this value, the Include custom manifests checkbox is selected by default and the Custom manifests page is added to the wizard. Leave the default settings for the remaining fields, and click . On the Operators page, click . 1.3.2. Generating the Discovery ISO image Generate and download the Discovery ISO image. Procedure On the Host Discovery page, click Add hosts and complete the following steps: For the Provisioning type field, select Minimal image file . For the SSH public key field, add the SSH public key from your local system, by copying the output of the following command: USD cat ~/.ssh/id_rsa.put The SSH public key will be installed on all OpenShift Container Platform control plane and compute nodes. Click Generate Discovery ISO to generate the discovery ISO image file. Click Download Discovery ISO to save the file to your local system. Additional resources Installation and update Configuring your firewall 1.4. Provisioning OCI infrastructure for your cluster When using the Assisted Installer to create details for your OpenShift Container Platform cluster, you specify these details in a Terraform stack. A stack is an OCI feature that automates the provisioning of all necessary OCI infrastructure resources that are required for installing an OpenShift Container Platform cluster on OCI. Prerequisites You downloaded the discovery ISO image to a local directory. For details, see "Using the Assisted Installer to generate an OCI-compatible discovery ISO image". You downloaded the Terraform stack template to a local directory. For details, see "Preparing the OCI environment". Procedure Log in to your Oracle Cloud Infrastructure (OCI) account. Upload the discovery ISO image from your local drive to the new object storage bucket you created. For the full procedure, see Uploading an Object Storage Object to a Bucket (Oracle documentation) . Locate the uploaded discovery ISO, and complete the following steps: Create a Pre-Authenticated Request (PAR) for the ISO from the adjacent options menu. Copy the generated URL to use as the OpenShift Image Source URI in the step. For the full procedure, see Creating a Pre-Authenticated Requests in Object Storage (Oracle documentation) . Create and apply the Terraform stack: Important The Terraform stack includes files for creating cluster resources and custom manifests. The stack also includes a script, and when you apply the stack, the script creates OCI resources, such as DNS records, an instance, and so on. For a list of the resources, see Terraform Defined Resources for OpenShift on OCI README file . Upload the Terraform stack template create-cluster-vX.X.X.zip to the new object storage bucket. Complete the stack information and click . Important Make sure that Cluster Name matches Cluster Name in Assisted Installer, and Zone DNS matches Base Domain in Assisted Installer. In the OpenShift Image Source URI field, paste the Pre-Authenticated Request URL link that you generated in the step. Ensure that the correct Compute Shape field value is defined, depending on whether you are installing on bare metal or a virtual machine. If not, select a different shape from the list. For details, see Compute Shapes (Oracle documentation) . Click Apply to apply the stack. For the full procedure, see Creating OpenShift Container Platform Infrastructure Using Resource Manager (Oracle documentation) . Copy the dynamic_custom_manifest.yml file from the Outputs page of the Terraform stack. Note The YAML file contains all the required manifests, concatenated and preformatted with the configuration values. For details, see the Custom Manifests README file . For the full procedure, see Getting the OpenShift Container Platform Custom Manifests for Installation (Oracle documentation) . 1.5. Completing the remaining Assisted Installer steps After you provision Oracle(R) Cloud Infrastructure (OCI) resources and upload OpenShift Container Platform custom manifest configuration files to OCI, you must complete the remaining cluster installation steps on the Assisted Installer before you can create an instance OCI. These steps include assigning node roles and adding custom manifests. 1.5.1. Assigning node roles Following host discovery, the role of all nodes appears as Auto-assign by default. Change each of the node roles to either Control Plane node or Worker . Prerequisites You created and applied the Terraform stack in OCI. For details, see "Provisioning OCI infrastructure for your cluster". Procedure From the Assisted Installer user interface, go to the Host discovery page. Under the Role column, select either Control plane node or Worker for each targeted hostname. Then click . Note Before continuing to the step, wait for each node to reach Ready status. Expand the node to verify that the hardware type is bare metal. Accept the default settings for the Storage and Networking pages. Then click . 1.5.2. Adding custom manifests Add the mandatory custom manifests provided by Oracle. For details, see Custom Manifests (Oracle documentation). Prerequisites You copied the dynamic_custom_manifest.yml file from the Terraform stack in OCI. For details, see "Provisioning OCI infrastructure for your cluster". Procedure On the Custom manifests page, in the Folder field, select manifests . This is the Assisted Installer folder where you want to save the custom manifest file. In the File name field, enter a filename, for example, dynamic_custom_manifest.yml . Paste the contents of the dynamic_custom_manifest.yml file that you copied from OCI: In the Content section, click the Paste content icon. If you are using Firefox, click OK to close the dialog box, and then press Ctrl+V . Otherwise, skip this step. Click to save the custom manifest. From the Review and create page, click Install cluster to create your OpenShift Container Platform cluster on OCI. After the cluster installation and initialization operations, the Assisted Installer indicates the completion of the cluster installation operation. For more information, see "Completing the installation" section in the Assisted Installer for OpenShift Container Platform document. Additional resources Assisted Installer for OpenShift Container Platform 1.6. Verifying a successful cluster installation on OCI Verify that your cluster was installed and is running effectively on Oracle(R) Cloud Infrastructure (OCI). Procedure From the Red Hat Hybrid Cloud Console , go to Clusters > Assisted Clusters and select your cluster's name. On the Installation Progress page, check that the Installation progress bar is at 100% and a message displays indicating Installation completed successfully . Under Host inventory , confirm that the status of all control plane and compute nodes is Installed . Note OpenShift Container Platform designates one of the control plane nodes as the bootstrap virtual machine, eliminating the need for a separate bootstrap machine. Click the Web Console URL, to access the OpenShift Container Platform web console. From the menu, select Compute > Nodes . Locate your node from the Nodes table. From the Terminal tab, verify that iSCSI appears to the serial number. From the Overview tab, check that your node has a Ready status. Select the YAML tab. Check the labels parameter, and verify that the listed labels apply to your configuration. For example, the topology.kubernetes.io/region=us-sanjose-1 label indicates in what OCI region the node was deployed. 1.7. Adding hosts to the cluster following the installation After creating a cluster with the Assisted Installer, you can use the Red Hat Hybrid Cloud Console to add new host nodes to the cluster and approve their certificate signing requests (CRSs). For details, see Adding Nodes to a Cluster (Oracle documentation) . 1.8. Troubleshooting the installation of a cluster on OCI If you experience issues with using the Assisted Installer to install an OpenShift Container Platform cluster on Oracle(R) Cloud Infrastructure (OCI), read the following sections to troubleshoot common problems. The Ingress Load Balancer in OCI is not at a healthy status This issue is classed as a Warning because by using OCI to create a stack, you created a pool of compute nodes, 3 by default, that are automatically added as backend listeners for the Ingress Load Balancer. By default, the OpenShift Container Platform deploys 2 router pods, which are based on the default values from the OpenShift Container Platform manifest files. The Warning is expected because a mismatch exists with the number of router pods available, two, to run on the three compute nodes. Figure 1.1. Example of a Warning message that is under the Backend set information tab on OCI You do not need to modify the Ingress Load Balancer configuration. Instead, you can point the Ingress Load Balancer to specific compute nodes that operate in your cluster on OpenShift Container Platform. To do this, use placement mechanisms, such as annotations, on OpenShift Container Platform to ensure router pods only run on the compute nodes that you originally configured on the Ingress Load Balancer as backend listeners. OCI create stack operation fails with an Error: 400-InvalidParameter message On attempting to create a stack on OCI, you identified that the Logs section of the job outputs an error message. For example: Error: 400-InvalidParameter, DNS Label oci-demo does not follow Oracle requirements Suggestion: Please update the parameter(s) in the Terraform config as per error message DNS Label oci-demo does not follow Oracle requirements Documentation: https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/core_vcn Go to the Install OpenShift with the Assisted Installer page on the Hybrid Cloud Console, and check the Cluster name field on the Cluster Details step. Remove any special characters, such as a hyphen ( - ), from the name, because these special characters are not compatible with the OCI naming conventions. For example, change oci-demo to ocidemo . Additional resources Troubleshooting OpenShift Container Platform on OCI (Oracle documentation) Installing an on-premise cluster using the Assisted Installer
cat ~/.ssh/id_rsa.put Error: 400-InvalidParameter, DNS Label oci-demo does not follow Oracle requirements Suggestion: Please update the parameter(s) in the Terraform config as per error message DNS Label oci-demo does not follow Oracle requirements Documentation: https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/core_vcn