1. Documentation
×

Installing a cluster on Oracle Cloud Infrastructure (OCI) by using the Assisted Installer

The Assisted Installer and OCI overview

You can run cluster workloads on Oracle® 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 OKD cluster on OCI.

The Assisted Installer supports the OCI platform, and you can use the Assisted Installer to access an intuitive interactive workflow for the purposes of automating cluster installation tasks on OCI.

Using the Assisted Installer to install an OKD cluster on OCI is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

OCI provides services that can meet your needs for regulatory compliance, performance, and cost-effectiveness. You can access OCI Resource Manager configurations to provision and configure OCI resources.

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 OKD. You can access OCI Resource Manager configurations to complete these steps, or use the configurations to model your own custom script.

Follow the steps in this document to understand how to use the Assisted Installer to install a OKD cluster on OCI. The document demonstrates the use of the OCI Manager (CCM) and Oracle’s Container Storage Interface (CSI) objects to link your OKD cluster with the OCI API.

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 in the Oracle documentation.

If you are unfamiliar with the OKD Assisted Installer, see "Assisted Installer for OKD".

Additional resources

Creating OCI resources and services

Create Oracle® Cloud Infrastructure (OCI) resources and services so that you can establish infrastructure with governance standards that meets your organization’s requirements.

By creating a compartment, you can better organize, restrict access, and set usage limits to OCI resources. Additionally, by creating an object storage bucket, you can safely and securely store the ISO image. You can access the image at a later stage for the purposes of booting the instances, so that you can then create your cluster.

Prerequisites
Procedure

  1. Log in to your Oracle Cloud Infrastructure account with administrator privileges.

  2. Create a child compartment. See Create a compartment in the Oracle documentation.

    When creating the child compartment, specify the default parent compartment or any other parent compartment from the list.

  3. Record the name and the Oracle® Cloud Identifier (OCID) of the compartment.

  4. Create a bucket resource for your child compartment. Ensure that you specify your child compartment in the Create in compartment field for the bucket resource.

  5. Go to Object Storage & Archive Storage → Buckets and create a bucket, where Bucket name refers to your cluster’s name.

Additional resources

Using the Assisted Installer to generate an OCI-compatible discovery ISO image

Generate a discovery ISO image and upload the image to Oracle® Cloud Infrastructure (OCI), so that the agent can perform hardware and network validation checks before you install an OKD cluster on OCI.

Prerequisites

  • You created a child compartment and an object storage bucket on OCI. See the "Creating OCI resources and services" section.

  • You reviewed details about the OKD installation and update processes.

  • If you use a firewall and you plan to use a Telemetry service, you configured your firewall to allow OKD to access the sites required.

  • Before you create a virtual machines (VM), refer to Fedora certified shapes, instance types, to identify the supported OCI VM shapes. See Cloud instance types on Red Hat Ecosystem Catalog portal.

Procedure

  1. From the Install OpenShift with the Assisted Installer page on the Hybrid Cloud Console, generate the discovery ISO image by completing all the required Assisted Installer steps.

    1. In the Cluster Details step, complete the following fields:

      Field Action required

      Cluster name

      Specify the name of your cluster, such as ocidemo.

      Base domain

      Specify the base domain of the cluster, such as splat-oci.devcluster.openshift.com. Provided you previously created a compartment on OCI, you can get this information by going to DNS management → Zones → List scope and then selecting the parent compartment. Your base domain should show under the Public zones tab.

      OpenShift version

      Specify OpenShift 4.15 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.

    2. On the Operators page, click Next.

    3. On the Host Discovery page, click Add hosts.

    4. For the SSH public key field, add your SSH key from your local system.

      You can create an SSH authentication key pair by using the ssh-keygen tool.

    5. Click Generate Discovery ISO to generate the discovery ISO image file.

    6. Download the file to your local system.

  2. Upload the discovery ISO image to the bucket by completing the steps in the Uploading an Object Storage Object to a Bucket section of the Oracle documentation.

  3. From the Objects menu, locate your uploaded image, and then click the overflow menu.

  4. From the Create Pre-Authenticated Request window, select the Object tile.

  5. After you create the request, copy the URL from the Pre-Authenticated Request URL field. See Creating a Pre-Authenticated Request in the Oracle documentation.

Additional resources

Downloading manifest files and deployment resources

You must download the archive file that includes files for creating cluster resources and custom manifests. After you extract the contents of the archive file, you must upload the extracted files to an Oracle® Cloud Infrastructure (OCI) stack. The archive file contains a script that when run creates OCI resources, such as DNS records, an instance, and so on.

A stack is an OCI feature where you can automate the provisioning of all necessary OCI infrastructure resources, such as the custom image, that are required for installing an OKD cluster on OCI.

The script uses the Oracle® Cloud Infrastructure (OCI) Compute Service to create a virtual machine (VM) instance on OCI. This instance can then automatically attach to a virtual network interface controller (vNIC) in the virtual cloud network (VNC) subnet. On specifying the IP address of your OKD cluster in the custom manifest template files, the OCI instance can communicate with your cluster over the VNC.

Prerequisites

  • You uploaded a generated discovery ISO image to OCI. For more information, see "Using the Assisted Installer to generate an OCI-compatible discovery ISO image".

  • You have permissions to access the oracle-quickstart / oci-openshift GitHub repository.

  • You logged in to your Oracle® Cloud Infrastructure (OCI) account with administrator privileges.

Procedure

  1. From the oracle-quickstart / oci-openshift GitHub web page, click the Code button and then click Download ZIP. The following list details these resources:

  2. Create a stack by completing the Creating a Stack from an Existing Compartment procedure in the Oracle documentation. Ensure that you also complete the following subtasks:

    1. Upload the archive file, .zip, that you downloaded previously from the oracle-quickstart / oci-openshift repository. This file contains a script and after you upload the script to OCI, the script creates OCI resources within your child compartment.

    2. From the Stack information section, specify a name for your stack.

    3. From the Configure variables section, complete the following fields. Ensure you replace the examples with your actual values.

      Field Value

      cluster_name:

      Specify the name of your cluster, such as ocicluster.

      compartment_ocid:

      Specify the OCID from the parent compartment. For example, ocid1.compartment.oc1..aaaaaaaa6r2iu3qndqgz5ogqkgnh2u2ajy5iou5ugkjr2ksmkrtdqrvxsvyq.

      home_region:

      Specify a region, such as us-sanjose-1.

      zone_dns:

      Specify the DNS name server that stores DNS records for a zone, such as openshift-demo.devcluster.openshift.com.

      enable_private_dns:

      Set the DNS zone to public or private. Specifying a value of true, creates a private DNS zone; specifying a value of false creates a public DNS zone. For a private DNS zone, you must configure your local /etc/hosts file to reach the cluster.

      openshift_image_source_url:

      Specify the URL that you copied from a previous step of the quick-start procedure.

  3. Click the Apply button to start an apply job. Check the Logs section to confirm that your stack is successfully created.

  4. Copy the oci_ccm_config cloud configuration from the Outputs section of the log.

  5. Extract the archive file that you downloaded in a previous step from the oracle-quickstart / oci-openshift repository. A new directory displays on your file explorer. Open the directory in your preferred code editor.

  6. Open the custom manifest template, oci-ccm.yml, and replace the cloud configuration section of the template file with the configuration that you previously copied from the Logs section on OCI. Perform the same steps to update the configuration of the CSI driver in the oci-csi.yml file.

    The following example replaces the region: to rateLimitBucketWrite parameters of the oci-csi.yml file with the configuration from the oci_ccm_config cloud configuration on OCI:

    # …
config.yaml: |
   auth:
     region: <region_name>
     useInstancePrincipals: true
     compartment: <compartment_ocid>
   vcn: <virtual_cloud_network_ocid>
   loadBalancer:
      subnet1: <subnet_ocid>
      securityListManagementMode: Frontend
   rateLimiter:
     rateLimitQPSRead: 20.0
     rateLimitBucketRead: 5
     rateLimitQPSWrite: 20.0
     rateLimitBucketWrite: 5
# …

Completing the remaining Assisted Installer steps

After you provision Oracle® Cloud Infrastructure (OCI) resources and upload OKD 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.

Prerequisites

  • You created a resource stack on OCI that includes the custom manifest configuration files and OCI Resource Manager configuration resources. See the "Downloading manifest files and deployment resources" section.

Procedure

  1. From the Red Hat Hybrid Cloud Console web console, go to the Host discovery page.

  2. Under the Role column, select either Control plane node or Worker for each targeted hostname.

    Before, you can continue to the next steps, wait for each node to reach the Ready status.

  3. Accept the default settings for the Storage and Networking steps, and then click Next.

  4. On the Custom manifests page, in the Folder field, select manifest. This is the Assisted Installer folder where you want to save the custom manifest file.

    1. In the File name field, enter a value such as oci-ccm.yml.

    2. From the Content section, click Browse, and select the CCM manifest from your drive located in custom_manifest/manifests/oci-ccm.yml.

  5. Expand the next Custom manifest section and repeat the same steps for the following manifests:

    • CSI driver manifest: custom_manifest/manifests/oci-csi.yml

    • CCM machine configuration: custom_manifest/openshift/machineconfig-ccm.yml

    • CSI driver machine configuration: custom_manifest/openshift/machineconfig-csi.yml

  6. From the Review and create page, click Install cluster to create your OKD cluster on OCI.

Verifying a successful cluster installation on OCI

Verify that your cluster was installed and is running effectively on Oracle® Cloud Infrastructure (OCI).

Procedure

  1. From the Hybrid Cloud Console, go to Clusters > Assisted Clusters and select your cluster’s name.

  2. Check that the Installation progress bar is at 100% and a message displays indicating “Installation completed successfully”.

  3. To access the OKD web console, click the provided Web Console URL.

  4. Go to the Nodes menu page.

  5. Locate your node from the Nodes table.

  6. From the Overview tab, check that your node has a Ready status.

  7. Select the YAML tab.

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

Troubleshooting installation of a cluster on OCI

If you experience issues with using the Assisted Installer to install an OKD cluster on Oracle® 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 the Resource Manager 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 OKD deploys 2 router pods, which are based on the default values from the OKD 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.

Example of an warning message that is under the Backend set information tab on OCI
Figure 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 OKD. To do this, use placement mechanisms, such as annotations, on OKD 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