ROSA with HCP Getting Started Guide

This Getting Started guide for ROSA with hosted control planes demonstrates CLI-based cluster deployment using AWS infrastructure, Terraform, the ROSA CLI, AWS STS, and the Red Hat Hybrid Cloud Console.

Project context

ROSA with hosted control planes introduced a faster cluster deployment model, reducing cluster creation time to about 10 minutes compared with the 40-plus minutes required for ROSA Classic. That speed changed the documentation challenge: setup guidance had to keep infrastructure prerequisites, IAM configuration, and cluster creation from becoming the new bottleneck.

The guide addresses a dual-audience workflow. AWS cloud architects need enough OpenShift context to understand the cluster lifecycle, while OpenShift administrators need AWS-specific infrastructure guidance for VPC architecture, IAM roles, AWS STS integration, and subnet requirements. The documentation needed to bridge those mental models while keeping the deployment path executable end to end.

My role and ownership

I authored the AWS-side getting-started guide and worked with AWS and Red Hat product, engineering, and documentation stakeholders to align the workflow. I helped standardize ROSA with hosted control planes terminology, documented VPC requirements before the deployment steps, and validated the workflow through hands-on testing so architecture mismatches surfaced in the guide rather than late in customer deployments.

What the work solved

Gave customers an end-to-end deployment path from VPC setup through cluster creation and verification
Surfaced VPC, subnet, IAM, OIDC, and AWS STS requirements before the cluster creation command
Bridged AWS and OpenShift mental models in one workflow
Reduced late-stage deployment friction by documenting architecture constraints before customers started provisioning

What this sample demonstrates

Dual-audience getting-started documentation that bridges AWS and OpenShift mental models
End-to-end procedural writing across Terraform, ROSA CLI, AWS STS, IAM, OIDC, and the Red Hat Hybrid Cloud Console
Cross-company documentation collaboration across AWS and Red Hat
Upfront architectural constraint documentation for VPC requirements, subnet design, and Availability Zone instance-type availability
Verification-oriented guidance that takes customers beyond cluster creation into confirming the deployment works

Live documentation

Create a ROSA with HCP cluster using the ROSA CLI

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.

Terraform

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

Open a terminal session and clone the Terraform VPC repository.

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

Navigate to the created directory.
```
cd terraform-vpc-example
```
Initiate the Terraform file.
```
terraform init
```
Once complete, the CLI returns a message that Terraform has been successfully initialized.
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.
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
```

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

Create the OpenID Connect configuration

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

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

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>

Check the status of your cluster.

rosa describe cluster --cluster=<CLUSTER_NAME>

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

Navigate to github.com and log in to your GitHub account.
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.
Using the ROSA CLI’s interactive mode, configure an identity provider for your cluster.
```
rosa create idp --cluster=<CLUSTER_NAME> --interactive
```
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
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

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