Chapter 1. Creating a Red Hat OpenShift Service on AWS classic architecture cluster with STS using the default options
Create a Red Hat OpenShift Service on AWS classic architecture 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 command-line interface (CLI) (rosa).
If you are looking for a quick start guide for Red Hat OpenShift Service on AWS classic architecture, see Red Hat OpenShift Service on AWS classic architecture quick start guide in the Additional resources section.
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 by 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 Red Hat OpenShift Service on AWS classic architecture cluster by using manual mode or with customizations, see Creating a cluster by using customizations in the Additional resources section.
ROSA CLI 1.2.7 introduces changes to the OIDC provider endpoint URL format for new clusters. Red Hat OpenShift Service on AWS classic architecture 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.
1.1. Prerequisites Copy linkLink copied to clipboard!
- Ensure that you have completed the AWS prerequisites.
1.2. Default cluster specifications Copy linkLink copied to clipboard!
You can quickly create a Red Hat OpenShift Service on AWS classic architecture cluster by using the default installation options.
| Component | Default specifications |
|---|---|
| Accounts and roles |
|
| Cluster settings |
|
| Encryption |
|
| Control plane node configuration |
|
| Infrastructure node configuration |
|
| Compute node machine pool |
|
| Networking configuration |
|
| Classless Inter-Domain Routing (CIDR) ranges |
|
| Cluster roles and policies |
|
| Storage |
|
| Cluster update strategy |
|
1.3. AWS account association Copy linkLink copied to clipboard!
Before you can use Red Hat OpenShift Cluster Manager on the Red Hat Hybrid Cloud Console to create Red Hat OpenShift Service on AWS classic architecture 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.
1.4. Amazon virtual private cloud (VPC) requirements for non-PrivateLink Red Hat OpenShift Service on AWS classic architecture clusters Copy linkLink copied to clipboard!
To create an Amazon VPC, you must have the following:
- An internet gateway,
- An 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.
1.4.1. Troubleshoot VPC configuration for ROSA clusters Copy linkLink copied to clipboard!
If your cluster fails to install, check common VPC configuration issues.
Consider the following troubleshooting items:
- 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 serversfield of your DHCP option set is notAmazonProvideDNS), make sure it is able to properly resolve the private hosted zones configured in Route53.
For more information about troubleshooting Red Hat OpenShift Service on AWS classic architecture cluster installations, see Troubleshooting Red Hat OpenShift Service on AWS classic architecture installations.
1.4.1.1. Getting support Copy linkLink copied to clipboard!
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.
1.5. Create a cluster quickly using OpenShift Cluster Manager Copy linkLink copied to clipboard!
When using Red Hat OpenShift Cluster Manager to create a Red Hat OpenShift Service on AWS classic architecture 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 Red Hat OpenShift Service on AWS classic architecture clusters, you must associate your AWS account with your Red Hat organization and create the required account-wide STS roles and policies.
1.5.1. Associate your AWS account with your Red Hat organization Copy linkLink copied to clipboard!
Before you create Red Hat OpenShift Service on AWS classic architecture clusters that use the AWS Security Token Service (STS), create an OpenShift Cluster Manager IAM role and a user IAM role, and link them to your Red Hat organization.
Procedure
Create an OpenShift Cluster Manager role and link it to your Red Hat organization:
NoteTo 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 Red Hat OpenShift Service on AWS classic architecture cluster. For more information about the basic and administrative privileges for the OpenShift Cluster Manager role, see Understanding AWS account association.
NoteIf you choose the Basic OCM role command in the Accounts and roles step of creating a Red Hat OpenShift Service on AWS classic architecture cluster in the OpenShift Cluster Manager Hybrid Cloud Console, you must deploy a Red Hat OpenShift Service on AWS classic architecture 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-roleSelect 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-roleSelect the default values at the prompts to quickly create and link the role.
NoteThe Red Hat user account must exist in the Red Hat organization that is linked to your OpenShift Cluster Manager role.
Verification
Verify that the OpenShift Cluster Manager role and user role were created:
$ rosa list ocm-role $ rosa list user-role
1.5.2. Create the account-wide STS roles and policies Copy linkLink copied to clipboard!
Before using the Red Hat Hybrid Cloud Console to create Red Hat OpenShift Service on AWS classic architecture 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 Red Hat OpenShift Service on AWS classic architecture with STS.
- You have available AWS service quotas.
- You have enabled the Red Hat OpenShift Service on AWS classic architecture service in the AWS Console.
-
You have installed and configured the latest
rosaCLI on your installation host. Runrosa versionto see your currently installed version of therosaCLI. 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
rosaCLI.
Procedure
Check your AWS account for existing roles and policies:
$ rosa list account-rolesIf they do not exist in your AWS account, create the required account-wide AWS IAM STS roles and policies:
$ rosa create account-rolesSelect the default values at the prompts to quickly create the roles and policies.
Verification
Verify that the account roles were created:
$ rosa list account-roles
1.5.3. Create an ocm-role IAM role Copy linkLink copied to clipboard!
Create the ocm-role Identity and Access Management (IAM) roles by using the ROSA command-line interface (CLI) (rosa) to grant OpenShift Cluster Manager the permissions needed to install and manage your Red Hat OpenShift Service on AWS classic architecture clusters.
If you want to create and manage clusters by using only the rosa CLI and the OpenShift CLI (oc), you can use the --no-console profile for the ocm-role IAM resource. For more information about the ocm-role IAM resource permissions profile, see the Additional resources.
You must create the ocm-role IAM role before you can create your Red Hat OpenShift Service on AWS classic architecture cluster.
Prerequisites
- You have an AWS account.
- You have Red Hat Organization Administrator privileges in the OpenShift Cluster Manager organization.
- You have the permissions required to install AWS account-wide roles.
-
You have installed and configured the latest
rosaCLI,rosa, on your installation host.
Procedure
Run one of the following commands to create the required
ocm-roleIAM resource:ImportantThe process to change your
ocm-roleIAM resource profile requires you to unlink and delete the currentocm-roleIAM resource and create a new one with the required profile.To create an
ocm-roleIAM role with standard privileges, run the following command:$ rosa create ocm-roleTo create an
ocm-roleIAM role with admin privileges, run the following command:ImportantThe admin profile supports "auto" mode configuration for Red Hat OpenShift Service on AWS classic architecture clusters which provisions OIDC Configuration and Operator roles automatically. To achieve this automatic flow, the profile has a wider set of permissions than the standard profile.
$ rosa create ocm-role --adminThis command allows you to create the role by specifying specific attributes. The following example output shows the "auto mode" selected, which lets the
rosaCLI create your Operator roles and policies. See "Methods of account-wide role creation" for more information. The following example shows what your creation flow might look like.I: Creating ocm role ? Role prefix: ManagedOpenShift ? Enable admin capabilities for the OCM role (optional): No ? Permissions boundary ARN (optional): ? Role Path (optional): ? Role creation mode: auto I: Creating role using 'arn:aws:iam::<ARN>:user/<UserName>' ? Create the 'ManagedOpenShift-OCM-Role-182' role? Yes I: Created role 'ManagedOpenShift-OCM-Role-182' with ARN 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' I: Linking OCM role ? OCM Role ARN: arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182 ? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' role with organization '<AWS ARN>'? Yes I: Successfully linked role-arn 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' with organization account '<AWS ARN>'where:
Role prefix-
A prefix value for all of the created AWS resources. In this example,
ManagedOpenShiftprepends all of the AWS resources. Enable admin capabilities for the OCM role (optional)Choose if you want this role to have the additional admin permissions.
NoteYou do not see this prompt if you used the
--adminoption.Permissions boundary ARN (optional)- The Amazon Resource Name (ARN) of the policy to set permission boundaries.
Role Path (optional)- Specify an IAM path for the user name.
Role creation mode-
Choose the method to create your AWS roles. By using
auto, therosaCLI generates and links the roles and policies. In theautomode, you receive some different prompts to create the AWS roles. Create the 'ManagedOpenShift-OCM-Role-182' role?-
The
automethod asks if you want to create a specificocm-roleby using your prefix. OCM Role ARN- Confirm that you want to associate your IAM role with your OpenShift Cluster Manager.
Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' role with organization '<AWS ARN>'?- Links the created role with your AWS organization.
To create an
ocm-roleIAM role with the minimum required privileges, run the following command:NoteWhile the
no-consoleprofile offers the minimum permissions policy that can still create Red Hat OpenShift Service on AWS classic architecture clusters, the permissions are insufficient if you want to use OpenShift Cluster Manager for cluster creation.$ rosa create ocm-role --no-console
1.5.4. Create an OpenID Connect configuration Copy linkLink copied to clipboard!
Create an OpenID Connect (OIDC) configuration before creating your Red Hat OpenShift Service on AWS classic architecture cluster to authenticate Operator access to required AWS resources by using the AWS Security Token Service (STS). Each production cluster requires its own OIDC configuration.
Prerequisites
- You have completed the AWS prerequisites for Red Hat OpenShift Service on AWS classic architecture.
-
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 --yesExample output
? Would you like to create a Managed (Red{nbsp}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 onawsCLI 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_IDExample output
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-configExample output
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
1.5.5. Create a cluster with the default options using OpenShift Cluster Manager Copy linkLink copied to clipboard!
When using Red Hat OpenShift Cluster Manager on the Red Hat Hybrid Cloud Console to create a Red Hat OpenShift Service on AWS classic architecture 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 Red Hat OpenShift Service on AWS classic architecture with STS.
- You have available AWS service quotas.
- You have enabled the Red Hat OpenShift Service on AWS classic architecture service in the AWS Console.
-
You have installed and configured the latest
rosaCLI,rosa, on your installation host. Runrosa versionto see your currently installed version of therosaCLI. 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 Red Hat OpenShift Service on AWS classic architecture (ROSA) row.
Verify that your AWS account ID is listed in the Associated AWS accounts drop-down menu and that the installation program, support, worker, and control plane account role Amazon Resource Names (ARNs) are listed on the Accounts and roles page.
NoteIf 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.
NoteCluster 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 Red Hat OpenShift Service on AWS classic architecture 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.
NoteIf 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.
1.6. Create a cluster quickly using the CLI Copy linkLink copied to clipboard!
When using the ROSA command-line interface (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 Red Hat OpenShift Service on AWS classic architecture with STS.
- You have available AWS service quotas.
- You have enabled the Red Hat OpenShift Service on AWS classic architecture service in the AWS Console.
-
You have installed and configured the latest
rosaCLI on your installation host. Runrosa versionto see your currently installed version of therosaCLI. 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
rosaCLI. - 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 autoNoteWhen using
automode, you can optionally specify the-yargument 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-
Replace
<cluster_name>with the name of your cluster. -
When you specify
--mode auto, therosa create clustercommand creates the cluster-specific Operator IAM roles and the OIDC provider automatically. The Operators use the OIDC provider to authenticate.
NoteIf 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-prefixflag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.-
Replace
Check the status of your cluster:
$ rosa describe cluster --cluster <cluster_name|cluster_id>The following
Statefield 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 readyNoteIf the installation fails or the
Statefield does not change toreadyafter 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> --watchSpecify the
--watchflag to watch for new log messages as the installation progresses. This argument is optional.