Understanding OCM role and User role for ROSA

What and Why

The Red Hat OpenShift Service on AWS (ROSA) web interface needs some permissions in trust with a customer's AWS account in order to provide the end-user experience at console.redhat.com / cloud.redhat.com and for the ROSA CLI.
This is achieved through the creation and association (linkage) of two AWS IAM roles
1. ocm-role
2. user-role

Contrasting to a customer that may choose to create ROSA clusters from the CLI, a number of permissions are granted intrinsically, since the user is simultaneously authenticated to both Red Hat and AWS. That very combination is not available to someone that uses our web interface for the same.
You will notice this approach is not requesting customers' AWS access keys or secret keys because instead it utilises a AWS Secure Token Service (STS) based workflow instead.

About the ocm-role

The first role necessary to enable a Red Hat organisation of users to create ROSA clusters is the 'ocm-role'.

• only one ocm-role is needed per Red Hat organisation
• if you just created a new Red Hat account that is not part of an existing org, then you are also the org-admin.
• Any user in a Red Hat org, may create and link an ocm-role
• ONLY the Red Hat org-admin may unlink an ocm-role -- this is to protect other Red Hat org members from disturbing interface capabilities for others
• Only one ocm-role can be created per AWS account per Red Hat organisation.
• A published listing of the AWS permissions policy for the basic and admin ocm-role can be found in the documentation (see Table 1)

Using the ROSA CLI, the process of creating this role also offers to link it. What we refer to as 'association' or 'link' is actually about creating a trust-policy between your ocm-role and the Red Hat cluster manager AWS role. Once created and linked, you will see a trust relationship from your ocm-role in AWS with arn:aws:iam::710019948333:role/RH-Managed-OpenShift-Installer

Note A: Once any org-admin for a Red Hat organisation has created and linked an ocm-role, all other org members that wish to use the ROSA CLI or ROSA UI for cluster provisioning must have created and linked their own user-role only once.
Note B: If another person in your Red Hat org has already created and linked an ocm-role, you will then need to ensure you have created and linked your own user-role.

How to Manage Your ocm-role

Create your ocm-role with rosa create ocm-role
(this command will also offer to link the role)
example:

$ rosa create ocm-role
I: Creating ocm role
? Role prefix: ManagedOpenShift
? Enable admin capabilities for the OCM role (optional): No
? Permissions boundary ARN (optional):
? Role creation mode: auto
I: Creating role using 'arn:aws:iam::133713371337:user/thatsme'
? Create the 'ManagedOpenShift-OCM-Role-12345678' role? Yes
I: Created role 'ManagedOpenShift-OCM-Role-12345678' with ARN 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678'
I: Linking OCM role
? OCM Role ARN: arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678
? Link the 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' role with organization '<red hat org id>'? Yes
I: Successfully linked role-arn 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' with organization account '<red hat org id>'

List and check status of your ocm-roles with rosa list ocm-role, indicating the name, role ARN, linked status and admin privilege status.
example:

$ rosa list ocm-role
ROLE NAME                           ROLE ARN                                                           LINKED  ADMIN
ManagedOpenShift-OCM-Role-12345678      arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678   Yes     No
myprefixOtherOrg-OCM-Role-12345678          arn:aws:iam::133713371337:role/myprefixOtherOrg-OCM-Role-12345678         No      Yes

Link the ocm-role with rosa link ocm-role --role-arn <ARN here>.

$ rosa link ocmrole --role-arn arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678   -y
I: Linking OCM role
I: Successfully linked role-arn 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678   ' with organization account '<red hat org id>'

Unlink the ocm-role with rosa unlink ocm-role --role-arn <ARN here>.

$ rosa unlink ocmrole --role-arn arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678
I: Unlinking OCM role
? Unlink the 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' role from organization '<red hat org id>'? Yes
I: Successfully unlinked role-arn 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' from organization account '<red hat org id>'

Delete the ocm-role with rosa delete ocm-role --role-arn <ARN here>. This command will offer to unlink the role before deletion.
example:

$ rosa delete ocm-role --role-arn arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678
I: Deleting OCM role
? OCM Role ARN: arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678
? Delete 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' ocm role? Yes
? OCM role deletion mode: auto
W: Role ARN 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' is linked to organization '<red hat org id>'
I: Unlinking OCM role
? Unlink the 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' role from organization '<red hat org id>'? Yes
I: Successfully unlinked role-arn 'arn:aws:iam::133713371337:role/ManagedOpenShift-OCM-Role-12345678' from organization account '<red hat org id>'
I: Successfully deleted the OCM role

About the user-role

The second of 2 roles necessary to enable a Red Hat organisation user to create ROSA clusters is the 'user-role'.

• only one user-role is needed per Red Hat user account, and many will exist within a Red Hat org.
• Any user in a Red Hat org, may create and link a user-role
• Many user-roles can be created per AWS account per Red Hat organisation.
• The user-role is necessary for identifying the end-user. It has no AWS account permissions

Using the ROSA CLI, the process of creating this role also offers to link it. What we refer to as 'association' or 'link' is actually about creating a trust-policy between your user-role and the Red Hat cluster manager AWS role. Once created and linked, you will see a trust relationship from your user-role in AWS with arn:aws:iam::710019948333:role/RH-Managed-OpenShift-Installer

Note A: Once any org-admin for a Red Hat organisation has created and linked an ocm-role, all other org members that wish to use the ROSA CLI or ROSA UI for cluster provisioning must have created and linked their own user-role only once.
Note B: If another person in your Red Hat org has already created and linked an ocm-role, you will then need to ensure you have created and linked your own user-role.

How to Manage Your user-role

The user-role is managed with the same commands as the ocm-role, except that you are not required to be an org-admin to unlink the user-role.
The following similar commands apply :

rosa create user-role
rosa list user-role
rosa unlink user-role --role-arn
rosa link user-role --role-arn
rosa delete user-role --role-arn

Tips

• Do not share your user-role or ocm-role with others, especially outside your organisation.
• Once both the ocm-role and user-role are linked for your org and your Red Hat user respectively, the roles no longer require management and the use of the ROSA provisioning console works with the associated AWS account where the roles reside.