Creating a ROSA cluster with STS using the default options

Note

If you are looking for a quickstart guide for ROSA, see OpenShift Container Platform quickstart guide.

Create a OpenShift Container Platform (ROSA) cluster quickly by using the default options and automatic AWS Identity and Access Management (IAM) resource creation. You can deploy your cluster by using Red Hat OpenShift Cluster Manager or the ROSA CLI (rosa).

The procedures in this document use the auto modes in the ROSA CLI (rosa) and OpenShift Cluster Manager to immediately create the required IAM resources using the current AWS account. The required resources include the account-wide IAM roles and policies, cluster-specific Operator roles and policies, and OpenID Connect (OIDC) identity provider.

Alternatively, you can use manual mode, which outputs the aws commands needed to create the IAM resources instead of deploying them automatically. For steps to deploy a ROSA cluster by using manual mode or with customizations, see Creating a cluster using customizations.

Next steps

Ensure that you have completed the AWS prerequisites.

Note

ROSA CLI 1.2.7 introduces changes to the OIDC provider endpoint URL format for new clusters. OpenShift Container Platform cluster OIDC provider URLs are no longer regional. The AWS CloudFront implementation provides improved access speed and resiliency and reduces latency.

Because this change is only available to new clusters created by using ROSA CLI 1.2.7 or later, existing OIDC-provider configurations do not have any supported migration paths.

Overview of the default cluster specifications

You can quickly create a OpenShift Container Platform cluster by using the default installation options.

The following summary describes the default cluster specifications.

Table 1. Default OpenShift Container Platform cluster specifications
Component	Default specifications
Accounts and roles	Default IAM role prefix: `HCP-ROSA`
Cluster settings	Default cluster version: Latest Default AWS region for installations using the ROSA CLI (`rosa`): Defined by your `aws` CLI configuration Default EC2 IMDS endpoints (both v1 and v2) are enabled Availability: Single zone for the data plane Monitoring for user-defined projects: Enabled No cluster admin role created
Compute node machine pool	Compute node instance type: m5.xlarge (4 vCPU 16, GiB RAM) Compute node count: 2 Autoscaling: Not enabled No additional node labels
Networking configuration	Cluster privacy: Public No cluster-wide proxy is configured
Classless Inter-Domain Routing (CIDR) ranges	Machine CIDR: 10.0.0.0/16 Service CIDR: 172.30.0.0/16 Pod CIDR: 10.128.0.0/14 Host prefix: /23 Note The static IP address `172.20.0.1` is reserved for the internal Kubernetes API address. The machine, pod, and service CIDRs ranges must not conflict with this IP address.
Cluster roles and policies	Mode used to create the Operator roles and the OpenID Connect (OIDC) provider: `auto` Note For installations that use OpenShift Cluster Manager on the Hybrid Cloud Console, the `auto` mode requires an admin-privileged OpenShift Cluster Manager role (ocm-role). Default Operator role prefix: `<cluster_name>-<4_digit_random_string>`
Storage	Node volumes: Type: AWS EBS GP3 Default size: 300GiB (adjustable at creation time) Workload persistent volumes: Default StorageClass: gp3-csi Provisioner: ebs.csi.aws.com Dynamic persistent volume provisioning
Cluster update strategy	Individual updates 1 hour grace period for node draining

Understanding AWS account association

Before you can use Red Hat OpenShift Cluster Manager on the Red Hat Hybrid Cloud Console to create OpenShift Container Platform (ROSA) clusters that use the AWS Security Token Service (STS), you must associate your AWS account with your Red Hat organization. You can associate your account by creating and linking the following IAM roles.

OpenShift Cluster Manager role: Create an OpenShift Cluster Manager IAM role and link it to your Red Hat organization.

You can apply basic or administrative permissions to the OpenShift Cluster Manager role. The basic permissions enable cluster maintenance using OpenShift Cluster Manager. The administrative permissions enable automatic deployment of the cluster-specific Operator roles and the OpenID Connect (OIDC) provider using OpenShift Cluster Manager.

You can use the administrative permissions with the OpenShift Cluster Manager role to deploy a cluster quickly.
User role: Create a user IAM role and link it to your Red Hat user account. The Red Hat user account must exist in the Red Hat organization that is linked to your OpenShift Cluster Manager role.

The user role is used by Red Hat to verify your AWS identity when you use the OpenShift Cluster Manager Hybrid Cloud Console to install a cluster and the required STS resources.

Additional resources

For detailed steps to create and link the OpenShift Cluster Manager and user IAM roles, see Associating your AWS account with your Red Hat organization.

Amazon VPC Requirements for non-PrivateLink ROSA clusters

To create an Amazon VPC, You must have the following:

An internet gateway,
A NAT gateway,
Private and public subnets that have internet connectivity provided to install required components.

You must have at least one single private and public subnet for Single-AZ clusters, and you need at least three private and public subnets for Multi-AZ clusters.

Troubleshooting

If your cluster fails to install, check these common troubleshooting issues:

Make sure your DHCP option set includes a domain name, and ensure that the domain name does not include any spaces or capital letters.
If your VPC uses a custom DNS resolver (the domain name servers field of your DHCP option set is not AmazonProvideDNS), make sure it is able to properly resolve the private hosted zones configured in Route53.

For more information about troubleshooting ROSA cluster installations, see Troubleshooting OpenShift Container Platform installations.

Get support

If you need additional support, visit the Red Hat Customer Portal to review knowledge base articles, submit a support case, and review additional product documentation and resources.

Additional resources

For more information about the default components required for an AWS cluster, see Default VPCs in the AWS documentation.
For instructions on creating a VPC in the AWS console, see Create a VPC in the AWS documentation.

Creating a cluster quickly using OpenShift Cluster Manager

When using Red Hat OpenShift Cluster Manager to create a OpenShift Container Platform (ROSA) cluster that uses the AWS Security Token Service (STS), you can select the default options to create the cluster quickly.

Before you can use OpenShift Cluster Manager to deploy ROSA with STS clusters, you must associate your AWS account with your Red Hat organization and create the required account-wide STS roles and policies.

Associating your AWS account with your Red Hat organization

Before using Red Hat OpenShift Cluster Manager on the Red Hat Hybrid Cloud Console to create clusters that use the AWS Security Token Service (STS), create an OpenShift Cluster Manager IAM role and link it to your Red Hat organization. Then, create a user IAM role and link it to your Red Hat user account in the same Red Hat organization.

Prerequisites

You have completed the AWS prerequisites for ROSA with STS.
You have available AWS service quotas.
You have enabled the ROSA service in the AWS Console.
You have installed and configured the latest ROSA CLI (rosa) on your installation host.

Note

To successfully install ROSA clusters, use the latest version of the ROSA CLI.
You have logged in to your Red Hat account by using the ROSA CLI.
You have organization administrator privileges in your Red Hat organization.

Procedure

Create an OpenShift Cluster Manager role and link it to your Red Hat organization:

Note

To enable automatic deployment of the cluster-specific Operator roles and the OpenID Connect (OIDC) provider using the OpenShift Cluster Manager Hybrid Cloud Console, you must apply the administrative privileges to the role by choosing the Admin OCM role command in the Accounts and roles step of creating a ROSA cluster. For more information about the basic and administrative privileges for the OpenShift Cluster Manager role, see Understanding AWS account association.

Note

If you choose the Basic OCM role command in the Accounts and roles step of creating a ROSA cluster in the OpenShift Cluster Manager Hybrid Cloud Console, you must deploy a ROSA cluster using manual mode. You will be prompted to configure the cluster-specific Operator roles and the OpenID Connect (OIDC) provider in a later step.
```
$ rosa create ocm-role
```
Select the default values at the prompts to quickly create and link the role.
Create a user role and link it to your Red Hat user account:
```
$ rosa create user-role
```
Select the default values at the prompts to quickly create and link the role.

Note

The Red Hat user account must exist in the Red Hat organization that is linked to your OpenShift Cluster Manager role.

Creating the account-wide STS roles and policies

Before using the Red Hat Hybrid Cloud Console to create OpenShift Container Platform clusters that use the AWS Security Token Service (STS), create the required account-wide STS roles and policies, including the Operator policies.

Prerequisites

You have completed the AWS prerequisites for ROSA with STS.
You have available AWS service quotas.
You have enabled the ROSA service in the AWS Console.
You have installed and configured the latest ROSA CLI on your installation host. Run rosa version to see your currently installed version of the ROSA CLI. If a newer version is available, the CLI provides a link to download this upgrade.
You have logged in to your Red Hat account by using the ROSA CLI.

Procedure

Check your AWS account for existing roles and policies:
```
$ rosa list account-roles
```
If they do not exist in your AWS account, create the required account-wide AWS IAM STS roles and policies:

+ Select the default values at the prompts to quickly create the roles and policies.

Creating an OpenID Connect configuration

When creating a OpenShift Container Platform cluster, you can create the OpenID Connect (OIDC) configuration before creating your cluster. This configuration is registered to be used with OpenShift Cluster Manager.

Prerequisites

You have completed the AWS prerequisites for OpenShift Container Platform.
You have installed and configured the latest ROSA command-line interface (CLI) (rosa) on your installation host.

Procedure

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.

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

Verification

You can list the possible OIDC configurations available for your clusters that are associated with your user organization. Run the following command:

$ rosa list oidc-config

For example:

ID                                MANAGED  ISSUER URL                                                             SECRET ARN
2330dbs0n8m3chkkr25gkkcd8pnj3lk2  true     https://dvbwgdztaeq9o.cloudfront.net/2330dbs0n8m3chkkr25gkkcd8pnj3lk2
233hvnrjoqu14jltk6lhbhf2tj11f8un  false    https://oidc-r7u1.s3.us-east-1.amazonaws.com                           aws:secretsmanager:us-east-1:242819244:secret:rosa-private-key-oidc-r7u1-tM3MDN

Creating a cluster with the default options using OpenShift Cluster Manager

When using Red Hat OpenShift Cluster Manager on the Red Hat Hybrid Cloud Console to create a OpenShift Container Platform (ROSA) cluster that uses the AWS Security Token Service (STS), you can select the default options to create the cluster quickly. You can also use the admin OpenShift Cluster Manager IAM role to enable automatic deployment of the cluster-specific Operator roles and the OpenID Connect (OIDC) provider.

Prerequisites

You have completed the AWS prerequisites for ROSA with STS.
You have available AWS service quotas.
You have enabled the ROSA service in the AWS Console.
You have installed and configured the latest ROSA CLI (rosa) on your installation host. Run rosa version to see your currently installed version of the ROSA CLI. If a newer version is available, the CLI provides a link to download this upgrade.
You have verified that the AWS Elastic Load Balancing (ELB) service role exists in your AWS account.
You have associated your AWS account with your Red Hat organization. When you associated your account, you applied the administrative permissions to the OpenShift Cluster Manager role. For detailed steps, see Associating your AWS account with your Red Hat organization.
You have created the required account-wide STS roles and policies. For detailed steps, see Creating the account-wide STS roles and policies.

Procedure

Navigate to OpenShift Cluster Manager and select Create cluster.
On the Create an OpenShift cluster page, select Create cluster in the OpenShift Container Platform (ROSA) row.
Verify that your AWS account ID is listed in the Associated AWS accounts drop-down menu and that the installer, support, worker, and control plane account role Amazon Resource Names (ARNs) are listed on the Accounts and roles page.

Note

If your AWS account ID is not listed, check that you have successfully associated your AWS account with your Red Hat organization. If your account role ARNs are not listed, check that the required account-wide STS roles exist in your AWS account.
Click Next.
On the Cluster details page, provide a name for your cluster in the Cluster name field. Leave the default values in the remaining fields and click Next.

Note

Cluster creation generates a domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. If the cluster name is less than or equal to 15 characters, that name is used for the domain prefix. If the cluster name is longer than 15 characters, the domain prefix is randomly generated as a 15-character string. To customize the subdomain, select the Create custom domain prefix checkbox, and enter your domain prefix name in the Domain prefix field.
To deploy a cluster quickly, leave the default options in the Cluster settings, Networking, Cluster roles and policies, and Cluster updates pages and click Next on each page.
On the Review your ROSA cluster page, review the summary of your selections and click Create cluster to start the installation.
Optional: On the Overview tab, you can enable the delete protection feature by selecting Enable, which is located directly under Delete Protection: Disabled. This will prevent your cluster from being deleted. To disable delete protection, select Disable. By default, clusters are created with the delete protection feature disabled.
Verification
- You can check the progress of the installation in the Overview page for your cluster. You can view the installation logs on the same page. Your cluster is ready when the Status in the Details section of the page is listed as Ready.
  
  Note
  
  If the installation fails or the cluster State does not change to Ready after about 40 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.

Creating a cluster quickly using the CLI

When using the OpenShift Container Platform (ROSA) CLI, rosa, to create a cluster that uses the AWS Security Token Service (STS), you can select the default options to create the cluster quickly.

Prerequisites

You have completed the AWS prerequisites for ROSA with STS.
You have available AWS service quotas.
You have enabled the ROSA service in the AWS Console.
You have installed and configured the latest ROSA CLI (rosa) on your installation host. Run rosa version to see your currently installed version of the ROSA CLI. If a newer version is available, the CLI provides a link to download this upgrade.
You have logged in to your Red Hat account by using the ROSA CLI.
You have verified that the AWS Elastic Load Balancing (ELB) service role exists in your AWS account.

Procedure

Create the required account-wide roles and policies, including the Operator policies:
```
$ rosa create account-roles --mode auto
```
Note

When using auto mode, you can optionally specify the -y argument to bypass the interactive prompts and automatically confirm operations.
Create a cluster with STS using the defaults. When you use the defaults, the latest stable OpenShift version is installed:
$ rosa create cluster --cluster-name <cluster_name> \ --sts --mode auto
1. Replace <cluster_name> with the name of your cluster.
2. When you specify --mode auto, the rosa create cluster command creates the cluster-specific Operator IAM roles and the OIDC provider automatically. The Operators use the OIDC provider to authenticate.
Note

If your cluster name is longer than 15 characters, it will contain an autogenerated domain prefix as a sub-domain 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.
Check the status of your cluster:
```
$ rosa describe cluster --cluster <cluster_name|cluster_id>
```
The following State field changes are listed in the output as the cluster installation progresses:
- waiting (Waiting for OIDC configuration)
- 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 about 40 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.
Track the progress of the cluster creation by watching the OpenShift installer logs:
```
$ rosa logs install --cluster <cluster_name|cluster_id> --watch 
```
1. Specify the --watch flag to watch for new log messages as the installation progresses. This argument is optional.

Next steps

Additional resources

For steps to deploy a ROSA cluster using manual mode, see Creating a cluster using customizations.
For more information about the AWS Identity Access Management (IAM) resources required to deploy OpenShift Container Platform with STS, see About IAM resources for clusters that use STS.
For details about optionally setting an Operator role name prefix, see About custom Operator IAM role prefixes.
For information about the prerequisites to installing ROSA with STS, see AWS prerequisites for ROSA with STS.
For details about using the auto and manual modes to create the required STS resources, see Understanding the auto and manual deployment modes.
For more information about using OpenID Connect (OIDC) identity providers in AWS IAM, see Creating OpenID Connect (OIDC) identity providers in the AWS documentation.
For more information about troubleshooting ROSA cluster installations, see Troubleshooting installations.
For steps to contact Red Hat Support for assistance, see Getting support for Red Hat OpenShift Service on AWS.