Troubleshooting IAM roles - Troubleshooting | Support | Red Hat OpenShift Service on AWS

Resolving issues with ocm-roles and user-role IAM resources

Resolving issues with ocm-roles and user-role IAM resources

You may receive an error when trying to create a cluster using the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

example output

e: Failed to create cluster: The sts_user_role is not linked to account '1oNl'. Please create a user role and link it to the account.

This error means that the user-role IAM role is not linked to your AWS account. The most likely cause of this error is that another user in your Red Hat organization created the ocm-role IAM role. Your user-role IAM role needs to be created.

After any user sets up an ocm-role IAM resource linked to a Red Hat account, any subsequent users wishing to create a cluster in that Red Hat organization must have a user-role IAM role to provision a cluster.

Procedure

Assess the status of your ocm-role and user-role IAM roles with the following commands:

$ rosa list ocm-role

example output

I: Fetching ocm roles
ROLe NAMe                           ROLe ARN                                          LINKeD  ADMIN
ManagedOpenShift-OCM-Role-1158  arn:aws:iam::2066:role/ManagedOpenShift-OCM-Role-1158   No      No

$ rosa list user-role

example output

I: Fetching user roles
ROLe NAMe                                   ROLe ARN                                        LINKeD
ManagedOpenShift-User.osdocs-Role  arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role  Yes

With the results of these commands, you can create and link the missing IAM resources.

edit

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.

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

edit

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.

edit

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

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

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

edit

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.