# ROSA with HCP Getting Started Guide > Getting started guide for ROSA with hosted control planes. Terraform and CLI-based workflow for provisioning ROSA clusters. Rendered version: https://codyanthony.dev/case-studies/architecture-guides/rosa-getting-started/ Author: Cody Anthony (https://codyanthony.dev/about/) --- 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](https://docs.aws.amazon.com/rosa/latest/userguide/getting-started-hcp.html) --- **Note on authorship and excerpt selection:** The complete ROSA with HCP Getting Started guide includes alternative paths for VPC creation, IAM resource creation, and application deployment. This excerpt focuses on the Terraform-based VPC setup, ROSA CLI cluster creation, and AWS-owned infrastructure phases to show the core deployment path I authored and validated. --- ## 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](https://docs.aws.amazon.com/rosa/latest/userguide/set-up.html). ## 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](https://docs.aws.amazon.com/vpc/latest/userguide/configure-your-vpc.html#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](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli). 2. Open a terminal session and clone the Terraform VPC repository. ```bash git clone https://github.com/openshift-cs/terraform-vpc-example ``` 3. Navigate to the created directory. ```bash cd terraform-vpc-example ``` 4. Initiate the Terraform file. ```bash 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. ```bash terraform plan -out rosa.tfplan -var 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](https://github.com/openshift-cs/terraform-vpc-example/blob/main/README.md). 6. Apply the plan file to build the VPC. ```bash 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. ```bash export SUBNET_IDS=$(terraform output -raw cluster-subnets-string) ``` b. (Optional) Verify that the environment variables were correctly set. ```bash 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= --region --output text | egrep ""`. ## 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. ```bash 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](https://docs.aws.amazon.com/rosa/latest/userguide/troubleshooting-rosa.html#rosa-cli-expired-token). ### 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). ```bash 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 `` with the OIDC config ID copied previously. **Important:** You must supply a prefix in `` when creating the Operator roles. Failing to do so produces an error. ```bash rosa create operator-roles --prefix --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. ```bash rosa create cluster --cluster-name= --sts --mode=auto --hosted-cp --operator-roles-prefix --oidc-config-id --subnet-ids=, ``` 2. Check the status of your cluster. ```bash rosa describe cluster --cluster= ``` 3. Track the progress of the cluster creation by watching the OpenShift installer logs. ```bash rosa logs install --cluster= --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](https://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](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). 3. Using the ROSA CLI's interactive mode, configure an identity provider for your cluster. ```bash rosa create idp --cluster= --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. ```bash rosa list idps --cluster= ``` **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 `` and `` with your user and cluster name. ```bash rosa grant user cluster-admin --user= --cluster= ``` 2. Verify that the user is listed as a member of the `cluster-admins` group. ```bash rosa list users --cluster= ``` ## 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](https://docs.aws.amazon.com/rosa/latest/userguide/getting-started-hcp.html#deploy-app-hcp-cli), 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.