Prerequisites

Before beginning the installation process for the OpenShift Container Platform cluster on Oracle Cloud Infrastructure (OCI), ensure you have all the necessary accounts, resources, and configurations in place for a successful installation.

Accounts and Resources

Red Hat Account: A Red Hat account and access to either the Assisted Installer or the Agent-based Installer.
OCI Account: An OCI account with an Identity Domain and permissions to manage the following resources:

Additional Resources

You also need the following:

An internet domain to serve the OpenShift Container Platform Console that runs on cluster resources in OCI.
An SSH key pair for cluster installation.
A pull secret from the Red Hat Hybrid Cloud Console. For more information, see Using image pull secrets (Red Hat documentation).
(Optional) A dedicated compartment for the cluster resources. You can also use an existing compartment. For more information, see Understanding Compartments and Creating a Compartment.
(Optional) An Object Storage bucket to store the discovery ISO image. You can also use an existing bucket. For more information, see Creating an Object Storage Bucket.

Note

Firewall access (Disconnected or Restricted Environments): If you use a firewall in your OCI environment and plan to use a Telemetry service, ensure the firewall has allowlisted OpenShift Container Platform to access the sites required. For more information, see Configuring your firewall for OpenShift Container Platform (Red Hat documentation).
Supported instance shapes: Before creating an OCI instance for a cluster, verify which VM and bare metal shapes are certified for Red Hat Enterprise Linux (RHEL). For more information, see Supported Shapes and Cloud instance types on the Red Hat Ecosystem Catalog portal.
Permissions: OpenShift requires Manage permissions to perform operations on instances, volumes, and networking resources. Deploy OpenShift in a dedicated compartment to avoid conflicts with other applications that might be running in the same compartment.

Resource Attribution Tags

Before installing an OpenShift cluster on OCI, download and run the create-resource-attribution-tags stack from the OpenShift on OCI Releases page on GitHub. This stack creates the openshift-tags tag namespace and the openshift-resource defined tag that are used to tag OpenShift resources. These are required before using other Terraform stacks.

See Tags and Tag Namespace Concepts for instructions. For high-level tagging details, see the Terraform Defined Resources for OpenShift on OCI page on GitHub. For specific resource definitions, access the resource_attribution_tag folder in the shared_modules directory.

Note

Run the create-resource-attribution-tags stack before running the create-cluster stack to avoid installation failure.
The create-resource-attribution-tags stack only needs to be run once. If the tag namespace and defined-tags already exist, you can skip this step for future installations.
A tagging controller runs in the background to ensure the required OpenShift resource attribution tags are present on cluster resources during installation and ongoing reconciliation.

Configuration Files

The latest version of the stack with the required configuration files is automatically loaded when you open the Red Hat OpenShift plugin in the OCI Console.

To access an earlier version of the stack, navigate to the OpenShift on OCI Releases GitHub page and download the create-cluster.zip file from the Assets folder.

The create-cluster.zip file includes:

Custom Manifests: The manifest files needed for OpenShift cluster installation. For more information about the files, see Custom Manifests.
Terraform Stacks: The Terraform stack code for provisioning OCI infrastructure to create and manage OpenShift clusters. For more information, see Terraform Defined Resources for OpenShift.
Note

To make changes to the manifests or Terraform code, you can clone the oracle-quickstart / oci-openshift GitHub repository and access the custom_manifests and terraform-stacks directories directly. Review the documentation in the repository and generate new Terraform stack zip files by running the make command.

Prerequisites for Using an Existing VCN

Before selecting Use Existing Networking Infrastructure, prepare an existing VCN with the following resources:

An Internet Gateway, NAT Gateway, and Service Gateway required by the selected cluster configuration.
Public and private route tables with routes for the required gateways and cluster traffic.
Public and private security lists with the required ingress and egress rules.
Network security groups for the load balancers, control-plane nodes, and compute nodes.
A private OpenShift subnet, a separate private bare metal subnet, and a public subnet.

The resource names must satisfy Terraform discovery requirements. For required resource names, routes, and security rules, see Bring Your Own Network requirements.

Prerequisites for Autoscaling

Autoscaling is supported on OpenShift Container Platform 4.22 and later. For post-cluster installation configuration, use the latest create-autoscaler-operator stack. The RHCOS image used for autoscaled workers must match the OpenShift Container Platform minor version of the cluster. You can use images from different z-streams of the same minor version. Don't use a 4.23 worker image with a 4.22 cluster.

In addition to other prerequisites, if you want to create an autoscaling stack, you need to download a Terraform stack (for adding autoscaling to an existing cluster), prepare an autoscaling Red Hat Enterprise Linux CoreOS (RHCOS) source image, and get a Pre-Authenticated Request (PAR) URL. You also need to install the Red Hat OpenShift CLI, oc.

If you want to add autoscaling to an existing cluster, download an Autoscaler Operator stack from https://github.com/oracle-quickstart/oci-openshift/releases. Download the latest version of create-autoscaler-operator.

Note

You don't need to download a Terraform if you're creating a new cluster with Autoscaling.

Download an OpenShift RHCOS image. Select the image from https://mirror.openshift.com/pub/openshift-v4/x86_64/dependencies/rhcos/.

For example, for OpenShift 4.19.0:

curl -LO https://mirror.openshift.com/pub/openshift-v4/x86_64/dependencies/rhcos/4.19/4.19.0/rhcos-4.19.0-x86_64-openstack.x86_64.qcow2.gz
gzip -d rhcos-4.19.0-x86_64-openstack.x86_64.qcow2.gz

Select either Virtual Machine or Bare metal.

For Virtual Machine: Use the downloaded qcow2 directly:
1. Upload the qcow2 to Object Storage.
2. Create a Read PAR URL for that object, with Pre-authenticated request target: Object and Access type: Permit object reads. See: Creating a Pre-Authenticated Request in Object Storage.
3. Store this PAR URL for the Terraform Stack.
For Bare metal: Patch the downloaded qcow2 with iSCSI kargs using the iscsi.sh shell script:
1. Copy the iscsi.sh script from https://github.com/oracle-quickstart/oci-openshift/blob/main/assets/autoscaler/iscsi.sh.
2. Run the script on the qcow2. For example:
```
cd /path/to/iscsi.sh
colima ssh
sudo ./iscsi.sh /path/to/rhcos-4.19.0-x86_64-openstack.x86_64.qcow2
```
This creates: rhcos-4.19.0-x86_64-openstack.x86_64-iscsi.qcow2
Upload the -iscsi.qcow2 to Object Storage.
Create a Read PAR URL for that object, with Pre-authenticated request target: Object and Access type: Permit object reads. See: Creating a Pre-Authenticated Request in Object Storage.
Store this PAR URL for the Terraform Stack. You will need to paste it into the Autoscaler Image Source URI field when configuring your deployment with the Assisted or Agent-based installer.
Install the Red Hat OpenShift CLI, oc. For the latest instructions, check the Red Hat documentation. For example, for 4.22: https://docs.redhat.com/en/documentation/openshift_container_platform/4.22/html/cli_tools/openshift-cli-oc

Prepare the RHCOS Image for Bare Metal Workers

On a RHEL-compatible Linux host, install the required packages:
```
sudo dnf install -y qemu-img ostree util-linux
```
Copy iscsi.sh from the OpenShift on OCI GitHub repository and make it executable:
```
chmod +x iscsi.sh
```

Run the script against the uncompressed RHCOS QCOW2 image:

sudo ./iscsi.sh ./rhcos-4.22.0-x86_64-openstack.x86_64.qcow2

Upload the generated *-iscsi.qcow2 image to Object Storage and create a pre-authenticated request URL.