This document describes how to create a Red Hat OpenShift Service on AWS (ROSA) with hosted control planes (HCP) private cluster.

Creating an AWS private cluster

You can create a private cluster with multiple availability zones (Multi-AZ) on ROSA with HCP using the ROSA command line interface (CLI), rosa.

  • You have available AWS service quotas.

  • You have enabled the ROSA service in the AWS Console.

  • You have installed and configured the latest version of the ROSA CLI on your installation host.


Creating a cluster with hosted control planes can take around 10 minutes.

  1. Create a VPC with at least one private subnet. Ensure that your machine’s classless inter-domain routing (CIDR) matches your virtual private cloud’s CIDR. For more information, see Requirements for using your own VPC and VPC Validation.

    If you use a firewall, you must configure it so that ROSA can access the sites that required to function.

    For more information, see the "AWS PrivateLink firewall prerequisites" section.

  2. Create the account-wide IAM roles by running the following command:

    $ rosa create account-roles --hosted-cp
  3. Create the OIDC configuration by running the following command:

    $ rosa create oidc-config --mode=auto --yes

    Save the OIDC configuration ID because you need it to create the Operator roles.

    Example output
    I: Setting up managed OIDC configuration
    I: To create Operator Roles for this OIDC Configuration, run the following command and remember to replace <user-defined> with a prefix of your choice:
    	rosa create operator-roles --prefix <user-defined> --oidc-config-id 28s4avcdt2l318r1jbk3ifmimkurk384
    If you are going to create a Hosted Control Plane cluster please include '--hosted-cp'
    I: Creating OIDC provider using 'arn:aws:iam::46545644412:user/user'
    I: Created OIDC provider with ARN 'arn:aws:iam::46545644412:oidc-provider/oidc.op1.openshiftapps.com/28s4avcdt2l318r1jbk3ifmimkurk384'
  4. Create the Operator roles by running the following command:

    $ rosa create operator-roles --hosted-cp --prefix <operator_roles_prefix> --oidc-config-id <oidc_config_id> --installer-role-arn arn:aws:iam::$<account_roles_prefix>:role/$<account_roles_prefix>-HCP-ROSA-Installer-Role
  5. Create a private ROSA with HCP cluster by running the following command:

    $ rosa create cluster --private --cluster-name=<cluster-name> --sts --mode=auto --hosted-cp --operator-roles-prefix <operator_role_prefix> --oidc-config-id <oidc_config_id> [--machine-cidr=<VPC CIDR>/16] --subnet-ids=<private-subnet-id1>[,<private-subnet-id2>,<private-subnet-id3>]
  6. Enter the following command to check the status of your cluster. During cluster creation, the State field from the output will transition from pending to installing, and finally, to ready.

    $ rosa describe cluster --cluster=<cluster_name>

    If installation fails or the State field does not change to ready after 10 minutes, see the "Troubleshooting Red Hat OpenShift Service on AWS installations" documentation in the Additional resources section.

  7. Enter the following command to follow the OpenShift installer logs to track the progress of your cluster:

    $ rosa logs install --cluster=<cluster_name> --watch

Configuring AWS security groups to access the API

With ROSA with HCP private clusters, the AWS PrivateLink endpoint exposed in the customer’s VPC has a default security group. This security group has access to the PrivateLink endpoint that is limited to only those resources that exist within the VPC or resources that are present with an IP address associated with the VPC CIDR range. In order to grant access to any entities outside of the VPC, through VPC peering and transit gateway, you must create and attach another security group to the PrivateLink endpoint to grant the necessary access.

  • Your corporate network or other VPC has connectivity.

  • You have permission to create and attach security groups within the VPC.

  1. Set your cluster name as an environmental variable by running the following command:

    $ export CLUSTER_NAME=<cluster_name>

    You can verify that the variable has been set by running the following command:

    $ echo $CLUSTER_NAME
    Example output
  2. Find the VPC endpoint (VPCE) ID and VPC ID by running the following command:

    $ read -r VPCE_ID VPC_ID <<< $(aws ec2 describe-vpc-endpoints --filters "Name=tag:api.openshift.com/id,Values=$(rosa describe cluster -c ${CLUSTER_NAME} -o yaml | grep '^id: ' | cut -d' ' -f2)" --query 'VpcEndpoints[].[VpcEndpointId,VpcId]' --output text)
  3. Create your security group by running the following command:

    $ export SG_ID=$(aws ec2 create-security-group --description "Granting API access to ${CLUSTER_NAME} from outside of VPC" --group-name "${CLUSTER_NAME}-api-sg" --vpc-id $VPC_ID --output text)
  4. Add an ingress rule to the security group by running the following command:

    $ aws ec2 authorize-security-group-ingress --group-id $SG_ID --ip-permissions FromPort=443,ToPort=443,IpProtocol=tcp,IpRanges=[{CidrIp=}]
  5. Add the new security group to the VPCE by running the following command:

    $ aws ec2 modify-vpc-endpoint --vpc-endpoint-id $VPCE_ID --add-security-group-ids $SG_ID

You now can access the API with your ROSA with HCP private cluster.