Menu Close

Chapter 1. Creating a ROSA cluster with STS using the default options

Create a Red Hat OpenShift Service on AWS (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 auto mode to immediately create the required IAM resources using the current AWS account, including the account-wide IAM roles and policies, Operator policies, cluster-specific Operator roles, and the 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 information about the auto and manual deployment modes, see Understanding the auto and manual deployment modes. For steps to deploy a ROSA cluster using manual mode, see Creating a cluster using customizations.

1.1. Creating a cluster with the default options

Use the default options and auto mode to create a Red Hat OpenShift Service on AWS (ROSA) cluster quickly. You can deploy your cluster by using Red Hat OpenShift Cluster Manager or the ROSA CLI (rosa).

1.1.1. Creating a cluster with the default options using OpenShift Cluster Manager

When using Red Hat OpenShift Cluster Manager to create a Red Hat OpenShift Service on AWS (ROSA) 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.

    Note

    To successfully install ROSA 4.10 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 verified that the AWS Elastic Load Balancing (ELB) service role exists in your AWS account.

Procedure

  1. Navigate to OpenShift Cluster Manager and select Create cluster.
  2. On the Create an OpenShift cluster page, select Create cluster in the Red Hat OpenShift Service on AWS (ROSA) row.
  3. Review and complete the Prerequisites listed on the Accounts and roles page. Select the checkbox to acknowledge that you have read and completed all of the prerequisites.
  4. Select an AWS account from the Associated AWS account drop-down menu. If no associated AWS accounts are found, click Associate AWS account and follow these steps:

    1. On the Authenticate page, click the copy button next to the rosa login command. The provided command includes your ROSA API login token.

      Note

      You can also load your API token on the OpenShift Cluster Manager API Token page on OpenShift Cluster Manager.

    2. Run the copied command in the CLI to log in to your ROSA account:

      $ rosa login --token=<api_login_token> 1
      1
      Replace <api_login_token> with the token that is provided in the copied command.

      Example output

      I: Logged in as '<username>' on 'https://api.openshift.com'

    3. On the Authenticate page in OpenShift Cluster Manager, click Next.
    4. On the OCM role page, click the copy button next to the Admin OCM role command. The admin role enables automatic deployment of the cluster-specific Operator roles and the OpenID Connect (OIDC) provider by using OpenShift Cluster Manager.
    5. Run the copied command in the CLI and follow the prompts to create the OpenShift Cluster Manager IAM role.

      The following example creates an admin OpenShift Cluster Manager IAM role using the default options and auto mode for immediate STS resource creation. The example also links the OpenShift Cluster Manager IAM role to a Red Hat organization:

      $ rosa create ocm-role --admin

      Example output

      I: Creating ocm role
      ? Role prefix: ManagedOpenShift 1
      ? Permissions boundary ARN (optional):  2
      ? Role creation mode: auto 3
      I: Creating role using 'arn:aws:iam::<aws_account_id>:user/<aws_username>'
      ? Create the 'ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>' role? Yes
      I: Created role 'ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>' with ARN 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>'
      I: Linking OCM role
      ? OCM Role ARN: arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>
      ? Link the 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>' role with organization '<red_hat_organization_id>'? Yes 4
      I: Successfully linked role-arn 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-OCM-Role-<red_hat_organization_external_id>' with organization account '<red_hat_organization_id>'

      1
      Specifies the prefix to include in the OpenShift Cluster Manager IAM role name. The default is ManagedOpenShift.
      2
      Optional: Specifies a permissions boundary Amazon Resource Name (ARN) for the role. For more information, see Permissions boundaries for IAM entities in the AWS documentation.
      3
      Selects the role creation mode. You can use auto mode to automatically create the OpenShift Cluster Manager IAM role and link it to your Red Hat organization account.
      4
      Links the OpenShift Cluster Manager IAM role to your Red Hat organization account.
    6. Select Next on the OpenShift Cluster Manager OCM role page.
    7. On the User role page, click the copy button for the User role command and run the command in the CLI. Follow the prompts to create the user role:

      $ rosa create user-role

      Example output

      I: Creating User role
      ? Role prefix: ManagedOpenShift 1
      ? Permissions boundary ARN (optional): 2
      ? Role creation mode: auto 3
      I: Creating ocm user role using 'arn:aws:iam::<aws_account_id>:user/<aws_username>'
      ? Create the 'ManagedOpenShift-User-<ocm_username>-Role' role? Yes
      I: Created role 'ManagedOpenShift-User-<ocm_username>-Role' with ARN 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-User-<ocm_username>-Role'
      I: Linking User role
      ? User Role ARN: arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-User-<ocm_username>-Role
      ? Link the 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-User-<ocm_username>-Role' role with account '<ocm_user_account_id>'? Yes 4
      I: Successfully linked role ARN 'arn:aws:iam::<aws_account_id>:role/ManagedOpenShift-User-<ocm_username>-Role' with account '<ocm_user_account_id>'

      1
      Specifies the prefix to include in the user role name. The default is ManagedOpenShift.
      2
      Optional: Specifies a permissions boundary Amazon Resource Name (ARN) for the role. For more information, see Permissions boundaries for IAM entities in the AWS documentation.
      3
      Selects the role creation mode. You can use auto mode to automatically create the user role and link it to your OpenShift Cluster Manager user account.
      4
      Links the user role to your OpenShift Cluster Manager user account.
    8. On the OpenShift Cluster Manager User role page, select Ok.
    9. Under the Accounts and roles page, verify that your AWS account is listed as an Associated AWS account.
  5. If the required AWS IAM Account roles are not automatically detected and listed on the Accounts and roles page, create the roles and policies:

    1. Click the copy buffer next to the rosa create account-roles command. Run the command in the CLI to create the required AWS account-wide roles and policies, including the Operator policies::

      $ rosa create account-roles

      Example output

      I: Logged in as '<ocm_username>' on 'https://api.openshift.com'
      I: Validating AWS credentials...
      I: AWS credentials are valid!
      I: Validating AWS quota...
      I: AWS quota ok. If cluster installation fails, validate actual AWS resource usage against https://docs.openshift.com/rosa/rosa_getting_started/rosa-required-aws-service-quotas.html
      I: Verifying whether OpenShift command-line tool is available...
      I: Current OpenShift Client Version: 4.9.12
      I: Creating account roles
      ? Role prefix: ManagedOpenShift 1
      ? Permissions boundary ARN (optional): 2
      ? Role creation mode: auto 3
      I: Creating roles using 'arn:aws:iam::<aws_account_number>:user/<aws_username>'
      ? Create the 'ManagedOpenShift-Installer-Role' role? Yes 4
      I: Created role 'ManagedOpenShift-Installer-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Installer-Role'
      ? Create the 'ManagedOpenShift-ControlPlane-Role' role? Yes 5
      I: Created role 'ManagedOpenShift-ControlPlane-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-ControlPlane-Role'
      ? Create the 'ManagedOpenShift-Worker-Role' role? Yes 6
      I: Created role 'ManagedOpenShift-Worker-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Worker-Role'
      ? Create the 'ManagedOpenShift-Support-Role' role? Yes 7
      I: Created role 'ManagedOpenShift-Support-Role' with ARN 'arn:aws:iam::<aws_account_number>:role/ManagedOpenShift-Support-Role'
      ? Create the operator policies? Yes 8
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-cloud-credential-operator-cloud-crede'
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-image-registry-installer-cloud-creden'
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-ingress-operator-cloud-credentials'
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-cluster-csi-drivers-ebs-cloud-credent'
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-cloud-network-config-controller-cloud'
      I: Created policy with ARN 'arn:aws:iam::<aws_account_number>:policy/ManagedOpenShift-openshift-machine-api-aws-cloud-credentials'
      I: To create a cluster with these roles, run the following command:
      rosa create cluster --sts

      1
      Specifies the prefix to include in the account-wide role and policy names. The default is ManagedOpenShift.
      2
      Optional: Specifies a permissions boundary Amazon Resource Name (ARN) for the roles. For more information, see Permissions boundaries for IAM entities in the AWS documentation.
      3
      Selects the role creation mode. You can use auto mode to automatically create the account wide roles and policies.
      4 5 6 7
      Creates the account-wide installer, control plane, worker and support roles and corresponding inline IAM policies. For more information, see Account-wide IAM role and policy reference.
      8
      Creates the cluster-specific Operator IAM roles that permit the ROSA cluster Operators to carry out core OpenShift functionality. For more information, see Account-wide IAM role and policy reference.
    2. On the Accounts and roles page, click Refresh ARNs and verify that the installer, support, worker, and control plane account roles are detected.
  6. Select Next.
  7. On the Cluster details page, provide a name for your cluster and specify the cluster details:

    1. Add a Cluster name.
    2. Select a cluster version from the Version drop-down menu.
    3. Select a cloud provider region from the Region drop-down menu.
    4. Select a Single zone or Multi-zone configuration.
    5. Leave Enable user workload monitoring selected to monitor your own projects in isolation from Red Hat Site Reliability Engineer (SRE) platform metrics. This option is enabled by default.
    6. Optional: Select Enable additional etcd encryption if you require etcd key value encryption. With this option, the etcd key values are encrypted, but not the keys. This option is in addition to the control plane storage encryption that encrypts the etcd volumes in Red Hat OpenShift Service on AWS clusters by default.

      Note

      By enabling etcd encryption for the key values in etcd, you will incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Consider enabling etcd encryption only if you specifically require it for your use case.

    7. Optional: Select Encrypt persistent volumes with customer keys if you want to provide your own AWS Key Management Service (KMS) key Amazon Resource Name (ARN). The key is used for encryption of persistent volumes in your cluster.
    8. Click Next.
  8. On the Default machine pool page, select a Compute node instance type.

    Note

    After your cluster is created, you can change the number of compute nodes in your cluster, but you cannot change the compute node instance type in the default machine pool. The number and types of nodes available to you depend on whether you use single or multiple availability zones. They also depend on what is enabled and available in your AWS account and the selected region.

  9. Optional: Configure autoscaling for the default machine pool:

    1. Select Enable autoscaling to automatically scale the number of machines in your default machine pool to meet the deployment needs.
    2. Set the minimum and maximum node count limits for autoscaling. The cluster autoscaler does not reduce or increase the default machine pool node count beyond the limits that you specify.

      • If you deployed your cluster using a single availability zone, set the Minimum node count and Maximum node count. This defines the minimum and maximum compute node limits in the availability zone.
      • If you deployed your cluster using multiple availability zones, set the Minimum nodes per zone and Maximum nodes per zone. This defines the minimum and maximum compute node limits per zone.
      Note

      Alternatively, you can set your autoscaling preferences for the default machine pool after the machine pool is created.

  10. If you did not enable autoscaling, select a compute node count for your default machine pool:

    • If you deployed your cluster using a single availability zone, select a Compute node count from the drop-down menu. This defines the number of compute nodes to provision to the machine pool for the zone.
    • If you deployed your cluster using multiple availability zones, select a Compute node count (per zone) from the drop-down menu. This defines the number of compute nodes to provision to the machine pool per zone.
  11. Optional: Expand Edit node labels to add labels to your nodes. Click Add label to add more node labels and select Next.
  12. In the Cluster privacy section of the Network configuration page, select Public or Private to use either public or private API endpoints and application routes for your cluster.

    Important

    If you are using private API endpoints, you cannot access your cluster until you update the network settings in your cloud provider account.

  13. Optional: If you opted to use public API endpoints, you can select Install into an existing VPC to install your cluster into an existing VPC.

    Note

    If you opted to use private API endpoints, you must use an existing VPC and PrivateLink and the Install into an existing VPC and Use a PrivateLink options are automatically selected. With these options, the Red Hat Site Reliability Engineering (SRE) team can connect to the cluster to assist with support by using only AWS PrivateLink endpoints.

  14. Optional: If you are installing your cluster into an existing VPC, select Configure a cluster-wide proxy to enable an HTTP or HTTPS proxy to deny direct access to the internet from your cluster.
  15. Click Next.
  16. If you opted to install the cluster in an existing AWS VPC, provide your Virtual Private Cloud (VPC) subnet settings.

    Note

    You must ensure that your VPC is configured with a public and a private subnet for each availability zone that you want the cluster installed into. If you opted to use PrivateLink, only private subnets are required.

  17. In the CIDR ranges dialog, configure custom classless inter-domain routing (CIDR) ranges or use the defaults that are provided and click Next.

    Note

    If you are installing into a VPC, the Machine CIDR range must match the VPC subnets.

    Important

    CIDR configurations cannot be changed later. Confirm your selections with your network administrator before proceeding.

  18. Under the Cluster roles and policies page, select Auto mode. With this mode, you can automatically create the cluster-specific Operator IAM roles and OIDC provider.

    Note

    To enable Auto mode, the OpenShift Cluster Manager IAM role must have administrator capabilities.

    If you alternatively want to create the cluster-specific IAM roles and the OIDC provider by using Manual mode, see Creating a cluster using customizations.

  19. Optional: Specify a Custom operator roles prefix for your cluster-specific Operator roles.

    Note

    By default, the cluster-specific Operator role names are prefixed with the cluster name and 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.

  20. Select Next.
  21. On the Cluster update strategy page, configure your update preferences:

    1. Choose a cluster update method:

      • Select Individual updates if you want to schedule each update individually. This is the default option.
      • Select Recurring updates to update your cluster on your preferred day and start time, when updates are available.

        Important

        Even when you opt for recurring updates, you must update the account-wide and cluster-specific IAM resources before you upgrade your cluster between minor releases.

        Note

        You can review the end-of-life dates in the update life cycle documentation for Red Hat OpenShift Service on AWS. For more information, see Red Hat OpenShift Service on AWS update life cycle.

    2. If you opted for recurring updates, select a preferred day of the week and upgrade start time in UTC from the drop-down menus.
    3. Optional: You can set a grace period for Node draining during cluster upgrades. A 1 hour grace period is set by default.
    4. Click Next.

      Note

      In the event of critical security concerns that significantly impact the security or stability of a cluster, Red Hat Site Reliability Engineering (SRE) might schedule automatic updates to the latest z-stream version that is not impacted. The updates are applied within 48 hours after customer notifications are provided. For a description of the critical impact security rating, see Understanding Red Hat security ratings.

  22. Review the summary of your selections and click Create cluster to start the cluster installation.

Verification

  • You can monitor 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.

1.1.2. Creating a cluster with the default options using the CLI

When using the Red Hat OpenShift Service on AWS (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.

    Note

    To successfully install ROSA 4.10 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 verified that the AWS Elastic Load Balancing (ELB) service role exists in your AWS account.

Procedure

  1. 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.

  2. 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
    1
    Replace <cluster_name> with the name of your cluster.
    Note

    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.

  3. 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.

  4. Track the progress of the cluster creation by watching the OpenShift installer logs:

    $ rosa logs install --cluster <cluster_name|cluster_id> --watch 1
    1
    Specify the --watch flag to watch for new log messages as the installation progresses. This argument is optional.

1.2. Next steps

1.3. Additional resources