×

Red Hat OpenShift Service on AWS (ROSA) web UI needs you to have some permissions on your AWS account that create a trust relationship to provide the end-user experience at OpenShift Cluster Manager and for the rosa command line interface (CLI).

This trust relationship is achieved through the creation and association of two AWS IAM roles:

  1. ocm-role

  2. user-role

If you use the rosa CLI, the rosa tool creates a number of these required permissions for you. This creation is available since your user account authenticates for both Red Hat and AWS. In the OpenShift Cluster Manager web UI, you need to create these roles.

Role creation does not request your AWS access or secret keys. This is because it uses an AWS Secure Token Service (STS) as the basis of its workflow.

About the ocm-role IAM resource

You must create the ocm-role IAM resource to enable a Red Hat organization of users to create ROSA clusters.

Some considerations for your ocm-role IAM resource are:

  • You have only one ocm-role per AWS account in a Red Hat organization. You can have multiple ocm-role IAM roles in a Red Hat organization as long as these roles are for different AWS accounts.

  • Any user in a Red Hat organization may create and link an ocm-role IAM resource.

  • Only the Red Hat Organization Administrator can unlink an ocm-role IAM resource. This limitation is to protect other Red Hat organization members from disturbing the interface capabilities of other users.

    If you just created a Red Hat account that is not part of an existing organization, this account is also the Red Hat Organization Administrator.

  • Only one ocm-role IAM resource can be created per AWS account per Red Hat organization.

  • See the associated permission tables for a list of the AWS permissions policy for the basic and admin ocm-role IAM resources.

Using the rosa CLI, you can link your IAM resource when you create it.

"Linking" or "associating" your IAM resources with your AWS account means creating a trust-policy with your ocm-role IAM role and the Red Hat OpenShift Cluster Manager AWS role. After creating and linking your IAM resource, you see a trust relationship from your ocm-role IAM resource in AWS with the arn:aws:iam::7333:role/RH-Managed-OpenShift-Installer resource.

After a Red Hat Organization Administrator has created and linked an ocm-role IAM resource, all organization members may want to create and link their own user-role IAM role. This IAM resource only needs to be created and linked only once per user. If another user in your Red Hat organization has already created and linked an ocm-role IAM resource, you need to ensure you have created and linked your own user-role IAM role.

Creating an OpenShift Cluster Manager IAM role

You create your OpenShift Cluster Manager IAM roles by using the command-line interface (CLI).

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 AWS (aws) and ROSA (rosa) CLIs on your installation host.

Procedure
  • To create an ocm-role IAM role with basic privileges, run the following command:

    $ rosa create ocm-role
  • To create an ocm-role IAM role with admin privileges, run the following command:

    $ rosa create ocm-role --admin

    This command allows you create the role by specifying specific attributes. The following example output shows the "auto mode" selected, which lets the rosa CLI to create your Operator roles and policies. See "Understanding the auto and manual deployment modes" in the Additional resources for more information.

Example output
I: Creating ocm role
? Role prefix: ManagedOpenShift (1)
? Enable admin capabilities for the OCM role (optional): No (2)
? Permissions boundary ARN (optional):  (3)
? Role creation mode: auto (4)
I: Creating role using 'arn:aws:iam::<ARN>:user/<UserName>'
? Create the 'ManagedOpenShift-OCM-Role-182' role? Yes (5)
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 (6)
? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' role with organization '<AWS ARN'? Yes (7)
I: Successfully linked role-arn 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' with organization account '<AWS ARN>'
1 A prefix value for all of the created AWS resources. In this example, ManagedOpenShift prepends all of the AWS resources.
2 Choose if you want this role to have the additional admin permissions.

You do not see this prompt if you used the --admin option.

3 The Amazon Resource Name (ARN) of the policy to set permission boundaries.
4 Choose the method of how to create your AWS roles. Using auto, the rosa CLI tool generates and links the roles and policies. In the auto mode, you receive some different prompts to create the AWS roles.
5 The auto method asks if you want to create a specific ocm-role using your prefix.
6 Confirm that you want to associate your IAM role with your OpenShift Cluster Manager.
7 Links the created role with your AWS organization.

About the user-role IAM role

You need to create the user-role IAM role to enable a Red Hat organization of users to create ROSA clusters.

Some considerations for your user-role IAM role are:

  • You only need one user-role IAM role per Red Hat user account, but your Red Hat organization can have many of these IAM resources.

  • Any user in a Red Hat organization may create and link an user-role IAM role.

  • There can be numerous user-role IAM roles per AWS account per Red Hat organization.

  • Red Hat uses the user-role IAM role to identify the user. This IAM resource has no AWS account permissions.

"Linking" or "associating" your IAM resources with your AWS account means creating a trust-policy with your user-role IAM role and the Red Hat OpenShift Cluster Manager AWS role. After creating and linking this IAM resource, you see a trust relationship from your user-role IAM role in AWS with the arn:aws:iam::710019948333:role/RH-Managed-OpenShift-Installer resource.

Creating an user-role IAM role

You can create your OpenShift Cluster Manager IAM roles by using the command-line interface (CLI).

Prerequisites
  • You have an AWS account.

  • You have installed and configured the latest AWS (aws) and ROSA (rosa) CLIs on your installation host.

Procedure
  • To create an ocm-role IAM role with basic privileges, run the following command:

    $ rosa create user-role

    This command allows you create the role by specifying specific attributes. The following example output shows the "auto mode" selected, which lets the rosa CLI to create your Operator roles and policies. See "Understanding the auto and manual deployment modes" in the Additional resources for more information.

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::2066:user'
? Create the 'ManagedOpenShift-User.osdocs-Role' role? Yes (4)
I: Created role 'ManagedOpenShift-User.osdocs-Role' with ARN 'arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role'
I: Linking User role
? User Role ARN: arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role
? Link the 'arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role' role with account '1AGE'? Yes (5)
I: Successfully linked role ARN 'arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role' with account '1AGE'
1 A prefix value for all of the created AWS resources. In this example, ManagedOpenShift prepends all of the AWS resources.
2 The Amazon Resource Name (ARN) of the policy to set permission boundaries.
3 Choose the method of how to create your AWS roles. Using auto, the rosa CLI tool generates and links the role to your AWS account. In the auto mode, you receive some different prompts to create the AWS roles.
4 The auto method asks if you want to create a specific user-role using your prefix.
5 Links the created role with your AWS organization.

AWS account association

Red Hat OpenShift Service on AWS (ROSA) cluster-provisioning tasks require linking ocm-role and user-role OpenShift Cluster Manager IAM resources to your AWS account using your Amazon Resource Name (ARN).

The ocm-role ARN is stored as a label in your Red Hat organization while the user-role ARN is stored as a label inside your Red Hat user account. Red Hat uses these ARN labels to confirm that the user is a valid account holder and that the correct permissions are available to perform the necessary tasks in the AWS account.

Linking your AWS account

You link your AWS account using the rosa CLI.

Prerequisites
  • You have an AWS account.

  • You are using OpenShift Cluster Manager to create clusters.

  • You have the permissions required to install AWS account-wide roles.

  • You have installed and configured the latest AWS (aws) and ROSA (rosa) CLIs on your installation host.

  • You have created your ocm-role and user-role IAM roles.

Procedure
  1. From the CLI, link your ocm-role resource to your Red Hat organization by using your Amazon Resource Name (ARN):

    You must have Red Hat Organization Administrator privileges to run the rosa link command. After you link the ocm-role resource with your AWS account, it is visible for all users in the organization.

    $ rosa link ocm-role --role-arn <arn>
    Example output
    I: Linking OCM role
    ? Link the '<AWS ACCOUNT ID>` role with organization '<ORG ID>'? Yes
    I: Successfully linked role-arn '<AWS ACCOUNT ID>' with organization account '<ORG ID>'
  2. From the CLI, link your user-role resource to your Red Hat user account by using your Amazon Resource Name (ARN):

    $ rosa link user-role --role-arn <arn>
    Example output
    I: Linking User role
    ? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-User-Role-125' role with organization '<AWS ID>'? Yes
    I: Successfully linked role-arn 'arn:aws:iam::<ARN>:role/ManagedOpenShift-User-Role-125' with organization account '<AWS ID>'

Associating multiple AWS accounts with your Red Hat organization

You can associate multiple AWS accounts with your Red Hat organization. Associating multiple accounts lets you create Red Hat OpenShift Service on AWS (ROSA) clusters on any of the associated AWS accounts from your Red Hat organization.

With this feature, you can create clusters in different AWS regions by using multiple AWS profiles as region-bound environments.

Prerequisites
  • You have an AWS account.

  • You are using OpenShift Cluster Manager to create clusters.

  • You have the permissions required to install AWS account-wide roles.

  • You have installed and configured the latest AWS (aws) and ROSA (rosa) CLIs on your installation host.

  • You have created your ocm-role and user-role IAM roles.

Procedure

To associate an additional AWS account, first create a profile in your local AWS configuration. Then, associate the account with your Red Hat organization by creating the ocm-role, user, and account roles in the additional AWS account.

To create the roles in an additional region, specify the --profile <aws-profile> parameter when running the rosa create commands and replace <aws_profile> with the additional account profile name:

  • To specify an AWS account profile when creating an OpenShift Cluster Manager role:

    $ rosa create --profile <aws_profile> ocm-role
  • To specify an AWS account profile when creating a user role:

    $ rosa create --profile <aws_profile> user-role
  • To specify an AWS account profile when creating the account roles:

    $ rosa create --profile <aws_profile> account-roles

If you do not specify a profile, the default AWS profile is used.

Additional resources