Chapter 3. ROSA IAM role resources

Red Hat OpenShift Service on AWS (ROSA) web UI requires that you have specific 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 the ocm-role AWS IAM role. This role has a trust policy with the AWS installer that links your Red Hat account to your AWS account. In addition, you also need a user-role AWS IAM role for each web UI user, which serves to identify these users. This user-role AWS IAM role has no permissions.

The AWS IAM roles required to use OpenShift Cluster Manager are:

  • ocm-role
  • user-role

Whether you manage your clusters using the ROSA CLI (rosa) or OpenShift Cluster Manager web UI, you must create the account-wide roles, known as account-roles in the ROSA CLI, by using the ROSA CLI. These account roles are necessary for your first cluster, and these roles can be used across multiple clusters. These required account roles are:

  • Worker-Role
  • Support-Role
  • Installer-Role
  • ControlPlane-Role
Note

Role creation does not request your AWS access or secret keys. AWS Security Token Service (STS) is used as the basis of this workflow. AWS STS uses temporary, limited-privilege credentials to provide authentication.

For more information about creating these roles, see Account-wide IAM role and policy reference.

Cluster-specific Operator roles, known as operator-roles in the ROSA CLI, obtain the temporary permissions required to carry out cluster operations, such as managing back-end storage, ingress, and registry. These roles are required by the cluster that you create. These required Operator roles are:

  • <cluster_name>-<hash>-openshift-cluster-csi-drivers-ebs-cloud-credentials
  • <cluster_name>-<hash>-openshift-cloud-network-config-controller-credentials
  • <cluster_name>-<hash>-openshift-machine-api-aws-cloud-credentials
  • <cluster_name>-<hash>-openshift-cloud-credential-operator-cloud-credentials
  • <cluster_name>-<hash>-openshift-image-registry-installer-cloud-credentials
  • <cluster_name>-<hash>-openshift-ingress-operator-cloud-credentials

For more information on creating these roles, see Cluster-specific Operator IAM role reference.

3.1. About the ocm-role IAM resource

You must create the ocm-role IAM resource to enable a Red Hat organization of users to create Red Hat OpenShift Service on AWS (ROSA) clusters. Within the context of linking to AWS, a Red Hat organization is a single user within OpenShift Cluster Manager.

Some considerations for your ocm-role IAM resource are:

  • Only one ocm-role IAM role can be linked per Red Hat organization; however, you can have any number of ocm-role IAM roles per AWS account. The web UI requires that only one of these roles can be linked at a time.
  • 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.

    Note

    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.

  • See "Understanding the OpenShift Cluster Manager role" in the Additional resources of this section for a list of the AWS permissions policies for the basic and admin ocm-role IAM resources.

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

Note

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

Additional resources

3.1.1. Creating an ocm-role IAM role

You create your ocm-role 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 Red Hat OpenShift Service on AWS (ROSA) CLI, rosa, 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 (rosa) create your Operator roles and policies. See "Methods of account-wide role creation" 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 Path (optional): 4
? Role creation mode: auto 5
I: Creating role using 'arn:aws:iam::<ARN>:user/<UserName>'
? Create the 'ManagedOpenShift-OCM-Role-182' role? Yes 6
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 7
? Link the 'arn:aws:iam::<ARN>:role/ManagedOpenShift-OCM-Role-182' role with organization '<AWS ARN>'? Yes 8
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.
Note

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
Specify an IAM path for the user name.
5
Choose the method to create your AWS roles. Using auto, the ROSA CLI generates and links the roles and policies. In the auto mode, you receive some different prompts to create the AWS roles.
6
The auto method asks if you want to create a specific ocm-role using your prefix.
7
Confirm that you want to associate your IAM role with your OpenShift Cluster Manager.
8
Links the created role with your AWS organization.

3.2. About the user-role IAM role

You need to create a user-role IAM role per web UI user to enable those 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.
  • Your AWS account can have multiple user-role IAM roles, but you must link each IAM role to each user in your Red Hat organization. No user can have more than one linked user-role IAM role.
Note

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

3.2.1. Creating a user-role IAM role

You can create your user-role IAM roles by using the command-line interface (CLI).

Prerequisites

  • You have an AWS account.
  • You have installed and configured the latest Red Hat OpenShift Service on AWS (ROSA) CLI, rosa, on your installation host.

Procedure

  • To create a user-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 (rosa) 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 Path (optional): 3
? Role creation mode: auto 4
I: Creating ocm user role using 'arn:aws:iam::2066:user'
? Create the 'ManagedOpenShift-User.osdocs-Role' role? Yes 5
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 6
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
Specify an IAM path for the user name.
4
Choose the method to create your AWS roles. Using auto, the ROSA CLI 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 user-role using your prefix.
6
Links the created role with your AWS organization.
Important

If you unlink or delete your user-role IAM role prior to deleting your cluster, an error prevents you from deleting your cluster. You must create or relink this role to proceed with the deletion process. See Repairing a cluster that cannot be deleted for more information.

3.3. AWS account association

Red Hat OpenShift Service on AWS (ROSA) cluster-provisioning tasks require linking ocm-role and user-role IAM roles 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.

3.3.1. Linking your AWS account

You can link your AWS account to existing IAM roles by using the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

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. See the "Additional resources" of this section for more information.
  • 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, but have not yet linked them to your AWS account. You can check whether your IAM roles are already linked by running the following commands: 

    $ rosa list ocm-role
    $ rosa list user-role

    If Yes is displayed in the Linked column for both roles, you have already linked the roles to an AWS account.

Procedure

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

    Note

    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>'

3.3.2. 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
Note

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

3.4. Additional resources