Install clusters

Procedure

1. To create your OIDC configuration alongside the AWS resources, run the following command:

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

   This command returns the following information.

   For example:

   ? Would you like to create a Managed (Red Hat hosted) OIDC Configuration Yes
   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 13cdr6b
   If you are going to create a Hosted Control Plane cluster please include '--hosted-cp'
   I: Creating OIDC provider using 'arn:aws:iam::4540112244:user/userName'
   ? Create the OIDC provider? Yes
   I: Created OIDC provider with ARN 'arn:aws:iam::4540112244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/13cdr6b'

   When creating your cluster, you must supply the OIDC config ID. The CLI output provides this value for --mode auto, otherwise you must determine these values based on aws CLI output for --mode manual.

2. Optional: you can save the OIDC configuration ID as a variable to use later. Run the following command to save the variable:

   $ export OIDC_ID=<oidc_config_id>

   <oidc_config_id>

   In this example output, the OIDC configuration ID is 13cdr6b.

   • View the value of the variable by running the following command:

     $ echo $OIDC_ID

     For example:

     13cdr6b

Procedure

1. To create your Operator roles, run the following command:

   $ rosa create operator-roles --hosted-cp --prefix=$OPERATOR_ROLES_PREFIX --oidc-config-id=$OIDC_ID --installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/${ACCOUNT_ROLES_PREFIX}-HCP-ROSA-Installer-Role

   The following breakdown provides options for the Operator role creation.

   $ rosa create operator-roles --hosted-cp
   	--prefix=$OPERATOR_ROLES_PREFIX
   	--oidc-config-id=$OIDC_ID
   	--installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/$ACCOUNT_ROLES_PREFIX-HCP-ROSA-Installer-Role

   where:

   --prefix=

   You must supply a prefix when creating these Operator roles. Failing to do so produces an error. See the Additional resources of this section for information on the Operator prefix.

   --oidc-config-id=

   This value is the OIDC configuration ID that you created for your Red Hat OpenShift Service on AWS cluster.

   --installer-role-arn

   This value is the installer role ARN that you created when you created the Red Hat OpenShift Service on AWS account roles.

   You must include the --hosted-cp parameter to create the correct roles for Red Hat OpenShift Service on AWS clusters. This command returns the following information.

   For example:

   ? Role creation mode: auto
   ? Operator roles prefix: <pre-filled_prefix>
   ? OIDC Configuration ID: 23soa2bgvpek9kmes9s7os0a39i13qm4 | https://dvbwgdztaeq9o.cloudfront.net/23soa2bgvpek9kmes9s7os0a39i13qm4
   ? Create hosted control plane operator roles: Yes
   W: More than one Installer role found
   ? Installer role ARN: arn:aws:iam::4540112244:role/<prefix>-HCP-ROSA-Installer-Role
   ? Permissions boundary ARN (optional):
   I: Reusable OIDC Configuration detected. Validating trusted relationships to operator roles:
   I: Creating roles using 'arn:aws:iam::4540112244:user/<userName>'
   I: Created role '<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials'
   I: Created role '<prefix>-openshift-cloud-network-config-controller-cloud-credenti' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cloud-network-config-controller-cloud-credenti'
   I: Created role '<prefix>-kube-system-kube-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kube-controller-manager'
   I: Created role '<prefix>-kube-system-capa-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-capa-controller-manager'
   I: Created role '<prefix>-kube-system-control-plane-operator' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-control-plane-operator'
   I: Created role '<prefix>-kube-system-kms-provider' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kms-provider'
   I: Created role '<prefix>-openshift-image-registry-installer-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-image-registry-installer-cloud-credentials'
   I: Created role '<prefix>-openshift-ingress-operator-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-ingress-operator-cloud-credentials'
   I: To create a cluster with these roles, run the following command:
   	rosa create cluster --sts --oidc-config-id 23soa2bgvpek9kmes9s7os0a39i13qm4 --operator-roles-prefix <prefix> --hosted-cp

   where:

   Operator roles prefix

   This field is prepopulated with the prefix that you set in the initial creation command.

   OIDC Configuration ID

   This field requires you to select an OIDC configuration that you created for your Red Hat OpenShift Service on AWS cluster.

   The Operator roles are now created and ready to use for creating your Red Hat OpenShift Service on AWS cluster.

Procedure

1. Use one of the following commands to create your Red Hat OpenShift Service on AWS cluster:

   Note

   When creating a Red Hat OpenShift Service on AWS cluster, the default machine Classless Inter-Domain Routing (CIDR) is 10.0.0.0/16. If this does not correspond to the CIDR range for your VPC subnets, add --machine-cidr <address_block> to the following commands. To learn more about the default CIDR ranges for Red Hat OpenShift Service on AWS, see CIDR range definitions.

   • If you did not set environmental variables, run the following command:

     $ rosa create cluster --cluster-name=<cluster_name> \
         --mode=auto --hosted-cp [--private] \
         --operator-roles-prefix <operator-role-prefix> \
         --external-id <external-id> \
         --oidc-config-id <id-of-oidc-configuration> \
         --subnet-ids=<public-subnet-id>,<private-subnet-id>

     where:

     <cluster_name>

     Specify the name of your cluster. If your cluster name is longer than 15 characters, it will contain an autogenerated domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. To customize the subdomain, use the --domain-prefix flag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.

     --private

     Optional. The --private argument is used to create private Red Hat OpenShift Service on AWS clusters. If you use this argument, ensure that you only use your private subnet ID for --subnet-ids.

     <operator-role-prefix>

     By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace <cluster_name>-<hash> in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see About custom Operator IAM role prefixes.

     <external-id>

     Optional. A unique identifier that might be required when you assume a role in another account.

     Note

     If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.

   • If you set the environmental variables, create a cluster with a single, initial machine pool, using either a publicly or privately available API, and a publicly or privately available Ingress by running the following command:

     $ rosa create cluster --private --cluster-name=<cluster_name> \
         --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

   • If you set the environmental variables, create a cluster with a single, initial machine pool, a publicly available API, and a publicly available Ingress by running the following command:

     $ rosa create cluster --cluster-name=<cluster_name> --mode=auto \
         --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

2. Check the status of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name>

   The following State field changes are listed in the output as the cluster installation progresses:

   • pending (Preparing account)
   • installing (DNS setup in progress)
   • installing

   • ready

     Note

     If the installation fails or the State field does not change to ready after more than 10 minutes, check the installation troubleshooting documentation for details. For more information, see Troubleshooting installations. For steps to contact Red Hat Support for assistance, see Getting support for Red Hat OpenShift Service on AWS.

3. Track the progress of the cluster creation by watching the Red Hat OpenShift Service on AWS installation program logs. To check the logs, run the following command:

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

   Optional: To watch for new log messages as the installation progresses, use the --watch argument.

Procedure

1. Navigate to github.com and log in to your GitHub account.
2. Invite users that require access to the Red Hat OpenShift Service on AWS cluster to your GitHub organization. Follow the steps in Inviting users to join your organization in the GitHub documentation.

Procedure

1. Obtain the console URL for your cluster:

   $ rosa describe cluster -c <cluster_name> | grep Console

   Example output

   Console URL:                https://console-openshift-console.apps.example-cluster.wxyz.p1.openshiftapps.com

2. Go to the console URL in the output of the preceding step and log in.

   • If you created a cluster-admin user, log in by using the provided credentials.
   • If you configured an identity provider for your cluster, select the identity provider name in the Log in with…​ dialog and complete any authorization requests that are presented by your provider.

Procedure

1. Go to the Cluster List page in OpenShift Cluster Manager.
2. Click the options icon (⋮) next to the cluster you want to view.
3. Click Open console.
4. Your cluster console opens in a new browser window. Log in to your Red Hat account with your configured identity provider credentials.
5. In the Administrator perspective, select Home → Projects → Create Project.
6. Enter a name for your project and optionally add a Display Name and Description.
7. Click Create to create the project.
8. Switch to the Developer perspective and select +Add. Verify that the selected Project is the one that you just created.
9. In the Developer Catalog dialog, select All services.
10. In the Developer Catalog page, select Languages → JavaScript from the menu.

11. Click Node.js, and then click Create to open the Create Source-to-Image application page.

    Note

    You might need to click Clear All Filters to display the Node.js option.

12. In the Git section, click Try sample.
13. Add a unique name in the Name field. The value will be used to name the associated resources.
14. Confirm that Deployment and Create a route are selected.
15. Click Create to deploy the application. It will take a few minutes for the pods to deploy.
16. Optional: Check the status of the pods in the Topology pane by selecting your Node.js app and reviewing its sidebar. You must wait for the nodejs build to complete and for the nodejs pod to be in a Running state before continuing.

17. When the deployment is complete, click the route URL for the application, which has a format similar to the following:

    https://nodejs-<project>.<cluster_name>.<hash>.<region>.openshiftapps.com/

    A new tab in your browser opens with a message similar to the following:

    Welcome to your Node.js application on OpenShift

18. Optional: Delete the application and clean up the resources that you created:

    1. In the Administrator perspective, navigate to Home → Projects.
    2. Click the action menu for your project and select Delete Project.

Procedure

1. Delete a cluster and watch the logs, replacing <cluster_name> with the name or ID of your cluster:

   $ rosa delete cluster --cluster=<cluster_name> --watch

   Important

   You must wait for the cluster deletion to complete before you remove the IAM roles, policies, and OIDC provider. The account-wide roles are required to delete the resources created by the installer. The cluster-specific Operator roles are required to clean-up the resources created by the OpenShift Operators. The Operators use the OIDC provider to authenticate with AWS APIs.

2. After the cluster is deleted, delete the OIDC provider that the cluster Operators use to authenticate:

   $ rosa delete oidc-provider -c <cluster_id> --mode auto

   Note

   You can use the -y option to automatically answer yes to the prompts.

3. Delete the cluster-specific Operator IAM roles:

   $ rosa delete operator-roles -c <cluster_id> --mode auto

4. Delete the account-wide roles:

   Important

   Account-wide IAM roles and policies might be used by other Red Hat OpenShift Service on AWS clusters in the same AWS account. You must only remove the resources if they are not required by other clusters.

   $ rosa delete account-roles --prefix <prefix> --mode auto

   Replace <prefix> with the prefix of the account-wide roles to delete. If you did not specify a custom prefix when you created the account-wide roles, specify the default prefix, depending on how they were created, HCP-ROSA or ManagedOpenShift.

5. Delete the account-wide and Operator IAM policies that you created for Red Hat OpenShift Service on AWS deployments:

   1. Log in to the AWS IAM Console.
   2. Navigate to Access management → Policies and select the checkbox for one of the account-wide policies.
   3. With the policy selected, click on Actions → Delete to open the delete policy dialog.
   4. Enter the policy name to confirm the deletion and select Delete to delete the policy.
   5. Repeat this step to delete each of the account-wide and Operator policies for the cluster.

Procedure

1. Use one of the following commands to create your Red Hat OpenShift Service on AWS cluster:

   Note

   When creating a Red Hat OpenShift Service on AWS cluster, the default machine Classless Inter-Domain Routing (CIDR) is 10.0.0.0/16. If this does not correspond to the CIDR range for your VPC subnets, add --machine-cidr <address_block> to the following commands. To learn more about the default CIDR ranges for Red Hat OpenShift Service on AWS, see CIDR range definitions.

   • If you did not set environmental variables, run the following command:

     $ rosa create cluster --cluster-name=<cluster_name> \
         --mode=auto --hosted-cp [--private] \
         --operator-roles-prefix <operator-role-prefix> \
         --external-id <external-id> \
         --oidc-config-id <id-of-oidc-configuration> \
         --subnet-ids=<public-subnet-id>,<private-subnet-id>

     where:

     <cluster_name>

     Specify the name of your cluster. If your cluster name is longer than 15 characters, it will contain an autogenerated domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. To customize the subdomain, use the --domain-prefix flag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.

     --private

     Optional. The --private argument is used to create private Red Hat OpenShift Service on AWS clusters. If you use this argument, ensure that you only use your private subnet ID for --subnet-ids.

     <operator-role-prefix>

     By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace <cluster_name>-<hash> in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see About custom Operator IAM role prefixes.

     <external-id>

     Optional. A unique identifier that might be required when you assume a role in another account.

     Note

     If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.

   • If you set the environmental variables, create a cluster with a single, initial machine pool, using either a publicly or privately available API, and a publicly or privately available Ingress by running the following command:

     $ rosa create cluster --private --cluster-name=<cluster_name> \
         --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

   • If you set the environmental variables, create a cluster with a single, initial machine pool, a publicly available API, and a publicly available Ingress by running the following command:

     $ rosa create cluster --cluster-name=<cluster_name> --mode=auto \
         --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

2. Check the status of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name>

   The following State field changes are listed in the output as the cluster installation progresses:

   • pending (Preparing account)
   • installing (DNS setup in progress)
   • installing

   • ready

     Note

     If the installation fails or the State field does not change to ready after more than 10 minutes, check the installation troubleshooting documentation for details. For more information, see Troubleshooting installations. For steps to contact Red Hat Support for assistance, see Getting support for Red Hat OpenShift Service on AWS.

3. Track the progress of the cluster creation by watching the Red Hat OpenShift Service on AWS installation program logs. To check the logs, run the following command:

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

   Optional: To watch for new log messages as the installation progresses, use the --watch argument.

Procedure

1. Create or modify a VPC to your specifications in the VPC section of the AWS console. Make sure you have selected the correct region.

2. Create the Route 53 role.

   Note

   You must create the Route 53 role in the same account where you plan to create the Amazon Route 53 hosted zones (which are created in Step 3). For example, if you want to create the hosted zones in the centrally-managed VPC account, you must create the Route 53 role in the VPC Owner account. If you want to create the hosted zones in the workload account, you must create the Route 53 role in the Cluster Creator account.

   1. Create a custom trust policy file that grants permission to assume roles:

      $ cat <<EOF > /tmp/route53-role.json
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:iam::<Account-ID>:root"
                  },
                  "Action": "sts:AssumeRole"
              }
          ]
      }
      EOF

      The trust policy principals (Principal.AWS) may be scoped down to the ingress Operator role and installer account role rather than root.

   2. Create the IAM role for the AWS managed policy ROSASharedVPCRoute53Policy.

      $ aws iam create-role --role-name <role_name> \
          --assume-role-policy-document file:///tmp/route53-role.json

   3. Attach the AWS managed policy ROSASharedVPCRoute53Policy to allow for necessary shared VPC permissions.

      $ aws iam attach-role-policy --role-name <role_name> \
      --policy-arn arn:aws:iam::aws:policy/ROSASharedVPCRoute53Policy

3. Create the VPC endpoint role.

   1. Create a custom trust policy file that grants permission to assume roles:

      $ cat <<EOF > /tmp/shared-vpc-role.json
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:iam::<Account-ID>:root"
                  },
                  "Action": "sts:AssumeRole"
              }
          ]
      }
      EOF

      The trust policy principals (Principal.AWS) may be scoped down to the ingress Operator role and installer account role rather than root.

   2. Create the IAM role for the AWS managed policy ROSASharedVPCEndpointPolicy:

      $ aws iam create-role --role-name <role_name> \
          --assume-role-policy-document file:///tmp/vpce-role.json

   3. Attach the AWS managed policy ROSASharedVPCEndpointPolicy to allow for necessary shared VPC permissions.

      $ aws iam attach-role-policy --role-name <role_name> \
      --policy-arn arn:aws:iam::aws:policy/ROSASharedVPCEndpointPolicy

4. Provide the Route 53 role ARN and the VPC endpoint role ARN to the Cluster Creator to continue configuration.

Procedure

1. Reserve an openshiftapps.com DNS domain with the following command:

   $ rosa create dns-domain --hosted-cp

   The command creates a reserved openshiftapps.com DNS domain.

   I: DNS domain '14eo.p3.openshiftapps.com' has been created.
   I: To view all DNS domains, run 'rosa list dns-domains'

2. Create an OIDC configuration.

   Review this article for more information on the OIDC configuration process. The following command produces the OIDC configuration ID that you need:

   $ rosa create oidc-config

   You receive confirmation that the command created an 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 25tu67hq45rto1am3slpf5lq6jargg

3. Create the account roles by entering the following command:

   $ rosa create account-roles \
       --route53-role-arn <Created_Route_53_Role_Arn> \
       --vpc-endpoint-role-arn <Created_VPC_Endpoint_Role_Arn> \
       --prefix <user_defined_account_role_prefix> \
       --hosted-cp

   where:

   <Created_Route_53_Role_Arn>

   Provide the ARN for the Route 53 role that the VPC Owner created.

   <Created_VPC_Endpoint_Role_Arn>

   Provide the ARN for the VPC endpoint role that the VPC Owner created.

   <user_defined_account_role_prefix>

   Provide a prefix for the Operator roles.

4. Create the Operator roles by entering the following command:

   $ rosa create operator-roles --oidc-config-id <oidc-config-ID> \
       --installer-role-arn <Installer_Role> \
       --route53-role-arn <Created_Route_53_Role_Arn> \
       --vpc-endpoint-role-arn <Created_VPC_Endpoint_Role_Arn> \
       --prefix <operator-prefix> \
       --hosted-cp

   where:

   <oidc-config-ID>

   Provide the OIDC configuration ID that you created in the previous step.

   <Installer_Role>

   Provide your installer ARN that was created as part of the rosa create account-roles process.

   <Created_Route_53_Role_Arn>

   Provide the ARN for the Route 53 role that the VPC Owner created.

   <Created_VPC_Endpoint_Role_Arn>

   Provide the ARN for the VPC endpoint role that the VPC Owner created.

   <operator-prefix>

   Provide a prefix for the Operator roles.

   Note

   The Installer account role and the shared VPC roles must have a one-to-one relationship. If you want to create multiple shared VPC roles, you should create one set of account roles per shared VPC role.

5. After you create the Operator roles, share your Ingress Operator Cloud Credentials role’s ARN, your Installer role’s ARN, and your Control plane Operator Cloud Credentials role’s ARN with the VPC Owner to continue configuration.

   The shared information resembles these examples:

   • my-rosa-cluster.14eo.p1.openshiftapps.com
   • arn:aws:iam::111122223333:role/ManagedOpenShift-Installer-Role
   • arn:aws:iam::111122223333:role/my-rosa-cluster-openshift-ingress-operator-cloud-credentials
   • arn:aws:iam::111122223333:role/my-rosa-cluster-control-plane-operator

Procedure

1. In the Resource Access Manager of the AWS console, create a resource share that shares the previously created VPC’s public and private subnets with the Cluster Creator’s AWS account ID.

2. Update the Route 53 role and add the Installer and Ingress Operator Cloud Credentials roles to the principal section of the trust policy.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
   	  "Sid": "Statement1",
   	  "Effect": "Allow",
   	  "Principal": {
   	  	"AWS": [
             "arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-ingress-operator-cloud-credentials",
             "arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-hcp-Installer-Role",
             "arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-control-plane-operator"
           ]
   	  },
   	  "Action": "sts:AssumeRole"
   	}
     ]
   }

3. Update the VPC endpoint role and add the Installer and Ingress Operator Cloud Credentials roles to the principal section of the trust policy.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
   	  "Sid": "Statement1",
   	  "Effect": "Allow",
   	  "Principal": {
   	  	"AWS": [
             "arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-hcp-Installer-Role",
             "arn:aws:iam::<Cluster-Creator's-AWS-Account-ID>:role/<prefix>-control-plane-operator"
           ]
   	  },
   	  "Action": "sts:AssumeRole"
   	}
     ]
   }

4. Create a private hosted zone in the Route 53 section of the AWS console. In the hosted zone configuration, the domain name is rosa.<cluster-name>.<base-domain>. The private hosted zone must be associated with the network owner’s VPC.
5. Create a local hosted zone in the Route 53 section of the AWS console. In the hosted zone configuration, the domain name is <cluster-name>.hypershift.local. The local hosted zone must be associated with the network owner’s VPC.

6. After the hosted zones are created and associated with the network owner’s VPC, provide the following to the Cluster Creator to continue configuration:

   • Hosted zone IDs
   • AWS region
   • Subnet IDs

Procedure

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.

   Important

   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 Red Hat OpenShift Service on AWS 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>

   Note

   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

Procedure

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

   $ export CLUSTER_NAME=<cluster_name>

   Verify that the variable exists by running the following command:

   $ echo $CLUSTER_NAME

   Example output

   hcp-private

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)

   Warning

   Modifying or removing the default AWS PrivateLink endpoint security group is not supported and might result in unexpected behavior.

3. Create an additional 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 inbound (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=<cidr-to-allow>}]

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 can now access the API of your Red Hat OpenShift Service on AWS private cluster from the specified CIDR block.

Procedure

1. Set your environment variable by running the following command:

   $ export <variable_name>=<variable_value>

2. You can confirm that your variable has been set by running the following command:

   $ echo <variable_name>

   Expand

   Table 7.2. Suggested variables for disconnected Red Hat OpenShift Service on AWS clusters

   Variable name	Variable value	Notes
   AWS_ACCOUNT_ID	$(aws sts get-caller-identity --query Account --output text)	You must be logged in to your AWS account with rosa login.
   CLUSTER_NAME	The name you want for your cluster.	Your cluster name cannot exceed 26 characters.
   OIDC_ID	The 32-digit ID for your OpenID Connect (OIDC) configuration.	You generate this ID by running rosa create oidc-config.
   OPERATOR_ROLES_PREFIX	The Operator role prefix.	If you want to make your AWS account roles use the same prefix as your Operator roles, you can run ACCOUNT_ROLES_PREFIX=$OPERATOR_ROLES_PREFIX after setting your Operator role prefix variable.
   PRIVATE_SUBNET	The ID of your private subnets.	You must enclose this value in quotation marks (") and separate the subnet IDs with commas.
   REGION	Your AWS region.	-
   SUBNET_IDS	The IDs of all your subnets.	You must enclose this value in quotation marks (") and separate the subnet IDs with commas.

   Show more

Procedure

1. If they do not exist in your AWS account, create the required account-wide STS roles and attach the policies by running the following command:

   $ rosa create account-roles --hosted-cp

2. Ensure that the your worker role has the correct AWS policy by running the following command:

   $ aws iam attach-role-policy \
   --role-name ManagedOpenShift-HCP-ROSA-Worker-Role \
   --policy-arn "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"

   --role-name ManagedOpenShift-HCP-ROSA-Worker-Role::This role needs to include the prefix that was created in the previous step.

3. Optional: Set your prefix as an environmental variable by running the following command:

   $ export ACCOUNT_ROLES_PREFIX=<account_role_prefix>

   • View the value of the variable by running the following command:

     $ echo $ACCOUNT_ROLES_PREFIX

     For example:

     ManagedOpenShift

     For more information regarding AWS managed IAM policies for Red Hat OpenShift Service on AWS, see AWS managed IAM policies for ROSA.

Procedure

1. To create your OIDC configuration alongside the AWS resources, run the following command:

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

   This command returns the following information.

   For example:

   ? Would you like to create a Managed (Red Hat hosted) OIDC Configuration Yes
   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 13cdr6b
   If you are going to create a Hosted Control Plane cluster please include '--hosted-cp'
   I: Creating OIDC provider using 'arn:aws:iam::4540112244:user/userName'
   ? Create the OIDC provider? Yes
   I: Created OIDC provider with ARN 'arn:aws:iam::4540112244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/13cdr6b'

   When creating your cluster, you must supply the OIDC config ID. The CLI output provides this value for --mode auto, otherwise you must determine these values based on aws CLI output for --mode manual.

2. Optional: you can save the OIDC configuration ID as a variable to use later. Run the following command to save the variable:

   $ export OIDC_ID=<oidc_config_id>

   <oidc_config_id>

   In this example output, the OIDC configuration ID is 13cdr6b.

   • View the value of the variable by running the following command:

     $ echo $OIDC_ID

     For example:

     13cdr6b

Procedure

1. To create your Operator roles, run the following command:

   $ rosa create operator-roles --hosted-cp --prefix=$OPERATOR_ROLES_PREFIX --oidc-config-id=$OIDC_ID --installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/${ACCOUNT_ROLES_PREFIX}-HCP-ROSA-Installer-Role

   The following breakdown provides options for the Operator role creation.

   $ rosa create operator-roles --hosted-cp
   	--prefix=$OPERATOR_ROLES_PREFIX
   	--oidc-config-id=$OIDC_ID
   	--installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/$ACCOUNT_ROLES_PREFIX-HCP-ROSA-Installer-Role

   where:

   --prefix=

   You must supply a prefix when creating these Operator roles. Failing to do so produces an error. See the Additional resources of this section for information on the Operator prefix.

   --oidc-config-id=

   This value is the OIDC configuration ID that you created for your Red Hat OpenShift Service on AWS cluster.

   --installer-role-arn

   This value is the installer role ARN that you created when you created the Red Hat OpenShift Service on AWS account roles.

   You must include the --hosted-cp parameter to create the correct roles for Red Hat OpenShift Service on AWS clusters. This command returns the following information.

   For example:

   ? Role creation mode: auto
   ? Operator roles prefix: <pre-filled_prefix>
   ? OIDC Configuration ID: 23soa2bgvpek9kmes9s7os0a39i13qm4 | https://dvbwgdztaeq9o.cloudfront.net/23soa2bgvpek9kmes9s7os0a39i13qm4
   ? Create hosted control plane operator roles: Yes
   W: More than one Installer role found
   ? Installer role ARN: arn:aws:iam::4540112244:role/<prefix>-HCP-ROSA-Installer-Role
   ? Permissions boundary ARN (optional):
   I: Reusable OIDC Configuration detected. Validating trusted relationships to operator roles:
   I: Creating roles using 'arn:aws:iam::4540112244:user/<userName>'
   I: Created role '<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials'
   I: Created role '<prefix>-openshift-cloud-network-config-controller-cloud-credenti' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cloud-network-config-controller-cloud-credenti'
   I: Created role '<prefix>-kube-system-kube-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kube-controller-manager'
   I: Created role '<prefix>-kube-system-capa-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-capa-controller-manager'
   I: Created role '<prefix>-kube-system-control-plane-operator' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-control-plane-operator'
   I: Created role '<prefix>-kube-system-kms-provider' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kms-provider'
   I: Created role '<prefix>-openshift-image-registry-installer-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-image-registry-installer-cloud-credentials'
   I: Created role '<prefix>-openshift-ingress-operator-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-ingress-operator-cloud-credentials'
   I: To create a cluster with these roles, run the following command:
   	rosa create cluster --sts --oidc-config-id 23soa2bgvpek9kmes9s7os0a39i13qm4 --operator-roles-prefix <prefix> --hosted-cp

   where:

   Operator roles prefix

   This field is prepopulated with the prefix that you set in the initial creation command.

   OIDC Configuration ID

   This field requires you to select an OIDC configuration that you created for your Red Hat OpenShift Service on AWS cluster.

   The Operator roles are now created and ready to use for creating your Red Hat OpenShift Service on AWS cluster.

Procedure

1. Use one of the following commands to create your Red Hat OpenShift Service on AWS cluster:

   Note

   When creating a Red Hat OpenShift Service on AWS cluster, the default machine Classless Inter-Domain Routing (CIDR) is 10.0.0.0/16. If this does not correspond to the CIDR range for your VPC subnets, add --machine-cidr <address_block> to the following commands. To learn more about the default CIDR ranges for Red Hat OpenShift Service on AWS, see the CIDR range definitions.

   • If you did not set environment variables, run the following command:

     $ rosa create cluster --cluster-name=<cluster_name> \
          --mode=auto --hosted-cp [--private] \
          --operator-roles-prefix <operator-role-prefix> \
          --oidc-config-id <id-of-oidc-configuration> \
          --subnet-ids=<private-subnet-id> --region <region> \
          --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 \
          --pod-cidr 10.128.0.0/14 --host-prefix 23 \
          --billing-account <root-acct-id> \
          --properties zero_egress:true

     where:

     <cluster_name>

     Specify the name of your cluster. If your cluster name is longer than 15 characters, it will contain an autogenerated domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. To customize the subdomain, use the --domain-prefix flag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.

     <operator-role-prefix>

     By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace <cluster_name>-<hash> in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see About custom Operator IAM role prefixes.

     Note

     If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.

     <root-acct-id>

     If your billing account is different from your user account, add this argument and specify the AWS account that is responsible for all billing.

   • If you set the environment variables, create a cluster with egress zero that has a single, initial machine pool, using a privately available API, and a privately available Ingress by running the following command:

     $ rosa create cluster --private --cluster-name=$CLUSTER_NAME \
         --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS \
         --region $REGION --machine-cidr 10.0.0.0/16 --service-cidr 172.30.0.0/16 \
         --pod-cidr 10.128.0.0/14 --host-prefix 23 \
         --private --properties zero_egress:true

2. Check the status of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name>

   The following State field changes are listed in the output as cluster installation progresses:

   • pending (Preparing account)
   • installing (DNS setup in progress)
   • installing

   • ready

     Note

     If the installation fails or the State field does not change to ready after more than 10 minutes, check the installation troubleshooting documentation for details. For more information, see Troubleshooting installations. For steps to contact Red Hat Support for assistance, see Getting support for Red Hat OpenShift Service on AWS.

3. Track the cluster creation progress by watching the Red Hat OpenShift Service on AWS installation program logs. To check the logs, run the following command:

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

   Optional: To watch for new log messages as the installation progresses, use the --watch argument.