ROSA with HCP Getting Started Guide

This Getting Started guide for Red Hat OpenShift Service on AWS (ROSA) with hosted control planes demonstrates CLI-based cluster deployment. The guide addresses a dual-audience challenge: AWS cloud architects need Kubernetes/OpenShift context, while Red Hat customers need AWS-specific infrastructure guidance (VPC architecture, IAM roles, AWS STS integration). I worked with AWS and Red Hat product leadership in Q2 2023 to standardize ROSA with hosted control planes product naming conventions and document VPC configuration requirements upfront, addressing customer friction where architecture mismatches were discovered late in deployment workflows. The documentation strategy prioritizes Infrastructure-as-Code approaches (Terraform + ROSA CLI automation) over manual workflows, reflecting how most customers deploy ROSA with HCP clusters that provision in 10 minutes rather than the 40+ minutes required for legacy ROSA classic deployments.

Deliverables & Impact

Documentation produced:

• Getting Started guide with VPC architecture requirements
• IAM roles and OIDC configuration using AWS STS
• ROSA CLI cluster creation workflow
• Identity provider setup procedures
• Application deployment verification

Impact: Enabled 10-minute cluster creation with upfront VPC requirement documentation to reduce configuration failures

Documentation Samples

Live Documentation:

• Create a ROSA with HCP cluster using the ROSA CLI

---

Author’s Note for Portfolio Review

The complete ROSA with HCP Getting Started guide includes alternative approaches for VPC creation (AWS CLI commands, console wizard), IAM resource creation (manual mode for review-before-execute workflows), and application deployment workflows on the Red Hat Hybrid Cloud Console. This sample focuses on the Infrastructure-as-Code deployment path (Terraform + ROSA CLI with auto mode) and AWS-owned infrastructure and platform deployment phases to demonstrate streamlined workflows and cross-company tooling collaboration. I selected these sections to showcase:

• Cross-company documentation collaboration (AWS + Red Hat joint tooling)
• Architectural constraint documentation (VPC requirements, AZ instance type availability)
• Modern Infrastructure-as-Code approach (Terraform)
• End-to-end customer journey (VPC → Cluster → Verification)

---

Documentation excerpt (curated)

Create a ROSA with HCP cluster using the ROSA CLI

Prerequisites

Complete the prerequisite actions listed in Set up to use ROSA.

Create Amazon VPC architecture

The following procedure creates Amazon VPC architecture using Terraform that can be used to host a cluster. All cluster resources are hosted in the private subnet. The public subnet routes outbound traffic from the private subnet through a NAT gateway to the public internet. This example uses the CIDR block 10.0.0.0/16 for the Amazon VPC. However, you can choose a different CIDR block. For more information, see VPC sizing.

Important

If Amazon VPC requirements are not met, cluster creation fails.

Terraform

1. Install the Terraform CLI. For more information, see the install instructions in the Terraform documentation.

2. Open a terminal session and clone the Terraform VPC repository.

   git clone https://github.com/openshift-cs/terraform-vpc-example

3. Navigate to the created directory.

   cd terraform-vpc-example

4. Initiate the Terraform file.

   terraform init

   Once complete, the CLI returns a message that Terraform has been successfully initialized.

5. To build a Terraform plan based on the existing template, run the following command. The AWS Region must be specified. Optionally, you can choose to specify a cluster name.

   terraform plan -out rosa.tfplan -var region=<region>

   Once the command has run, a rosa.tfplan file is added to the hypershift-tf directory. For more detailed options, see the Terraform VPC repository’s README file.

6. Apply the plan file to build the VPC.

   terraform apply rosa.tfplan

   Once complete, the CLI returned a success message that verifies the added resources.

   a. (Optional) Create environment variables for the Terraform-provisioned private, public, and machinepool subnet IDs to use when creating your ROSA with HCP cluster.

   export SUBNET_IDS=$(terraform output -raw cluster-subnets-string)

   b. (Optional) Verify that the environment variables were correctly set.

   echo $SUBNET_IDS

Note

ROSA with HCP requires that customers configure at least one public and private subnet per Availability Zone used to create clusters.

Note

Some ROSA instance types are only available in select Availability Zones. You can use the ROSA CLI command rosa list instance-types command to list all ROSA instance types available. To check if an instance type is available for a given Availability Zone, use the AWS CLI command aws ec2 describe-instance-type-offerings --location-type availability-zone --filters Name=location,Values=<availability_zone> --region <region> --output text | egrep "<instance_type>".

Create the required IAM roles and OpenID Connect configuration

The ROSA CLI uses auto mode or manual mode to create the IAM resources and OpenID Connect (OIDC) configuration required to create a ROSA cluster. auto mode automatically creates the required IAM roles and policies and OIDC provider. manual mode outputs the AWS CLI commands that are needed to create the IAM resources manually. By using manual mode, you can review the generated AWS CLI commands before running them manually. With manual mode, you can also pass the commands to another administrator or group in your organization so they can create the resources.

The procedures in this document use the auto mode of the ROSA CLI to create the required IAM resources and OIDC configuration for ROSA with HCP.

Create the IAM account roles and policies

Create the required IAM account roles and policies. The --force-policy-creation flag updates any existing roles and policies that are present. If no roles and policies are present, the command creates these resources instead.

rosa create account-roles --force-policy-creation

Note

If your offline access token has expired, the ROSA CLI outputs an error message stating that your authorization token needs updated. For steps to troubleshoot, see Troubleshoot ROSA CLI expired offline access tokens.

Create the OpenID Connect configuration

1. Create the OpenID Connect (OIDC) configuration that enables user authentication to the cluster. This configuration is registered to be used with OpenShift Cluster Manager (OCM).

   rosa create oidc-config --mode auto

2. Copy the OIDC config ID for use in the next step.

Create the IAM operator roles and policies

Create the required IAM operator roles, replacing <OIDC_CONFIG_ID> with the OIDC config ID copied previously.

Important

You must supply a prefix in <PREFIX_NAME> when creating the Operator roles. Failing to do so produces an error.

rosa create operator-roles --prefix <PREFIX_NAME> --oidc-config-id <OIDC_CONFIG_ID> --hosted-cp

Create a ROSA with HCP cluster using the ROSA CLI and AWS STS

1. Use the ROSA CLI to create a ROSA with HCP cluster with AWS STS. Specify the cluster name, operator role prefix, OIDC config ID, and public and private subnet IDs from the Terraform-created VPC.

rosa create cluster --cluster-name=<CLUSTER_NAME> --sts --mode=auto --hosted-cp --operator-roles-prefix <OPERATOR_ROLE_PREFIX> --oidc-config-id <OIDC_CONFIG_ID> --subnet-ids=<PUBLIC_SUBNET_ID>,<PRIVATE_SUBNET_ID>

2. Check the status of your cluster.

   rosa describe cluster --cluster=<CLUSTER_NAME>

3. Track the progress of the cluster creation by watching the OpenShift installer logs.

   rosa logs install --cluster=<CLUSTER_NAME> --watch

   Note

   It takes approximately 10 minutes for the cluster to be ready for use.

Configure an identity provider and grant cluster access

After the cluster is created, you must configure an identity provider to authenticate users. The following procedure configures a GitHub identity provider as an example.

Configure GitHub identity provider

1. Navigate to github.com and log in to your GitHub account.

2. If you don’t have a GitHub organization to use for identity provisioning for your cluster, create one. For more information, see the steps in the GitHub documentation.

3. Using the ROSA CLI’s interactive mode, configure an identity provider for your cluster.

   rosa create idp --cluster=<CLUSTER_NAME> --interactive

4. Follow the configuration prompts in the output to restrict cluster access to members of your GitHub organization. The prompts will guide you through:

   • Selecting GitHub as the identity provider type
   • Entering your GitHub organization name
   • Registering an OAuth application in GitHub
   • Providing the OAuth Client ID and Client Secret

5. Verify that the identity provider is configured correctly.

   rosa list idps --cluster=<CLUSTER_NAME>

   Note

   It takes approximately two minutes for the identity provider configuration to become active.

Grant user access to the cluster

You can grant cluster-admin or dedicated-admin permissions to users through the configured identity provider.

Configure cluster-admin permissions

1. Run the following command to grant cluster-admin permissions to a user. Replace <IDP_USER_NAME> and <CLUSTER_NAME> with your user and cluster name.

   rosa grant user cluster-admin --user=<IDP_USER_NAME> --cluster=<CLUSTER_NAME>

2. Verify that the user is listed as a member of the cluster-admins group.

   rosa list users --cluster=<CLUSTER_NAME>

Verify cluster with application deployment

To verify cluster functionality, deploy a sample application from the Red Hat Hybrid Cloud Console’s Developer Catalog. The complete workflow for application deployment is documented in the ROSA with HCP Getting Started guide, including:

• Creating a project in the Administrator perspective
• Deploying a Node.js sample application from the Developer Catalog
• Verifying deployment through the application route

This verification step confirms end-to-end cluster functionality and completes the initial ROSA with HCP deployment workflow.