Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Tutorial: Detailed UI guide

edit

This tutorial outlines the detailed steps to deploy a Red Hat OpenShift Service on AWS (ROSA) cluster using the Red Hat OpenShift Cluster Manager user interface (UI).

edit

Deployment workflow

The overall deployment workflow follows these steps:

  1. Create the account wide roles and policies.

  2. Associate your AWS account with your Red Hat account.

    1. Create and link the Red Hat OpenShift Cluster Manager role.

    2. Create and link the user role.

  3. Create the cluster.

Step 1 only needs to be performed the first time you are deploying into an AWS account. Step 2 only needs to be performed the first time you are using the UI. For successive clusters of the same y-stream version, you only need to create the cluster.

Creating account wide roles

If you already have account roles from an earlier deployment, skip this step. The UI will detect your existing roles after you select an associated AWS account.

If this is the first time you are deploying ROSA in this account and you have not yet created the account roles, create the account-wide roles and policies, including the Operator policies.

  • In your terminal, run the following command to create the account-wide roles:

    $ rosa create account-roles --mode auto --yes
    Example output
    I: Creating roles using 'arn:aws:iam::000000000000:user/rosa-user'
I: Created role 'ManagedOpenShift-ControlPlane-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-ControlPlane-Role'
I: Created role 'ManagedOpenShift-Worker-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Worker-Role'
I: Created role 'ManagedOpenShift-Support-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Support-Role'
I: Created role 'ManagedOpenShift-Installer-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-Installer-Role'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-machine-api-aws-cloud-credentials'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-cloud-credential-operator-cloud-crede'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-image-registry-installer-cloud-creden'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-ingress-operator-cloud-credentials'
I: Created policy with ARN 'arn:aws:iam::000000000000:policy/ManagedOpenShift-openshift-cluster-csi-drivers-ebs-cloud-credent'
I: To create a cluster with these roles, run the following command:
rosa create cluster --sts

Associating your AWS account with your Red Hat account

This step tells the OpenShift Cluster Manager what AWS account you want to use when deploying ROSA.

If you have already associated your AWS accounts, skip this step.

  1. Open the Red Hat Hybrid Cloud Console by visiting the OpenShift Cluster Manager and logging in to your Red Hat account.

  2. Click Create Cluster.

  3. Scroll down to the Red Hat OpenShift Service on AWS (ROSA) row and click Create Cluster.

    cloud experts getting started rosa deployment detailed ui create

  4. A dropdown menu appears. Click With web interface.

    cloud experts getting started rosa deployment detailed ui web interface

  5. Under "Select an AWS control plane type," choose Classic. Then click Next.

    cloud experts getting started rosa deployment detailed ui classic

  6. Click the dropbox under Associated AWS infrastructure account. If you have not yet associated any AWS accounts, the dropbox may be empty.

  7. Click How to associate a new AWS account.

    cloud experts getting started rosa deployment detailed ui associate

  8. A sidebar appears with instructions for associating a new AWS account.

    cloud experts getting started rosa deployment detailed ui associate2

Creating and associating an OpenShift Cluster Manager role

  1. Run the following command to see if an OpenShift Cluster Manager role exists:

    $ rosa list ocm-role

  2. The UI displays the commands to create an OpenShift Cluster Manager role with two different levels of permissions:

    • Basic OpenShift Cluster Manager role: Allows the OpenShift Cluster Manager to have read-only access to the account to check if the roles and policies that are required by ROSA are present before creating a cluster. You will need to manually create the required roles, policies, and OIDC provider using the CLI.

    • Admin OpenShift Cluster Manager role: Grants the OpenShift Cluster Manager additional permissions to create the required roles, policies, and OIDC provider for ROSA. Using this makes the deployment of a ROSA cluster quicker since the OpenShift Cluster Manager will be able to create the required resources for you.

      To read more about these roles, see the OpenShift Cluster Manager roles and permissions section of the documentation.

      For the purposes of this tutorial, use the Admin OpenShift Cluster Manager role for the simplest and quickest approach.

  3. Copy the command to create the Admin OpenShift Cluster Manager role from the sidebar or switch to your terminal and enter the following command:

    $ rosa create ocm-role --mode auto --admin --yes

    This command creates the OpenShift Cluster Manager role and associates it with your Red Hat account.

    Example output
    I: Creating ocm role
I: Creating role using 'arn:aws:iam::000000000000:user/rosa-user'
I: Created role 'ManagedOpenShift-OCM-Role-12561000' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-OCM-Role-12561000'
I: Linking OCM role
I: Successfully linked role-arn 'arn:aws:iam::000000000000:role/ManagedOpenShift-OCM-Role-12561000' with organization account '1MpZfntsZeUdjWHg7XRgP000000'

  4. Click Step 2: User role.

Other OpenShift Cluster Manager role creation options

  • Manual mode: If you prefer to run the AWS CLI commands yourself, you can define the mode as manual rather than auto. The CLI will output the AWS commands and the relevant JSON files are created in the current directory.

    Use the following command to create the OpenShift Cluster Manager role in manual mode:

    $ rosa create ocm-role --mode manual --admin --yes

  • Basic OpenShift Cluster Manager role: If you prefer that the OpenShift Cluster Manager has read only access to the account, create a basic OpenShift Cluster Manager role. You will then need to manually create the required roles, policies, and OIDC provider using the CLI.

    Use the following command to create a Basic OpenShift Cluster Manager role:

    $ rosa create ocm-role --mode auto --yes

Creating an OpenShift Cluster Manager user role

As defined in the user role documentation, the user role needs to be created so that ROSA can verify your AWS identity. This role has no permissions, and it is only used to create a trust relationship between the installation program account and your OpenShift Cluster Manager role resources.

  1. Check if a user role already exists by running the following command:

    $ rosa list user-role

  2. Run the following command to create the user role and to link it to your Red Hat account:

    $ rosa create user-role --mode auto --yes
    Example output
    I: Creating User role
I: Creating ocm user role using 'arn:aws:iam::000000000000:user/rosa-user'
I: Created role 'ManagedOpenShift-User-rosa-user-Role' with ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-User-rosa-user-Role'
I: Linking User role
I: Successfully linked role ARN 'arn:aws:iam::000000000000:role/ManagedOpenShift-User-rosa-user-Role' with account '1rbOQez0z5j1YolInhcXY000000'

    As before, you can define --mode manual if you’d prefer to run the AWS CLI commands yourself. The CLI outputs the AWS commands and the relevant JSON files are created in the current directory. Make sure to link the role.

  3. Click Step 3: Account roles.

Creating account roles

  1. Create your account roles by running the following command:

    $ rosa create account-roles --mode auto

  2. Click OK to close the sidebar.

Confirming successful account association

  1. You should now see your AWS account in the Associated AWS infrastructure account dropdown menu. If you see your account, account association was successful.

  2. Select the account.

  3. You will see the account role ARNs populated below.

    cloud experts getting started rosa deployment detailed ui account roles

  4. Click Next.

Creating the cluster

  1. For the purposes of this tutorial make the following selections:

    Cluster settings

    • Cluster name: <pick a name\>

    • Version: <select latest version\>

    • Region: <select region\>

    • Availability: Single zone

    • Enable user workload monitoring: leave checked

    • Enable additional etcd encryption: leave unchecked

    • Encrypt persistent volumes with customer keys: leave unchecked

  2. Click Next.

  3. Leave the default settings on for the machine pool:

    Default machine pool settings

    • Compute node instance type: m5.xlarge - 4 vCPU 16 GiB RAM

    • Enable autoscaling: unchecked

    • Compute node count: 2

    • Leave node labels blank

  4. Click Next.

Networking

  1. Leave all the default values for configuration.

  2. Click Next.

  3. Leave all the default values for CIDR ranges.

  4. Click Next.

Cluster roles and policies

For this tutorial, leave Auto selected. It will make the cluster deployment process simpler and quicker.

If you selected a Basic OpenShift Cluster Manager role earlier, you can only use manual mode. You must manually create the operator roles and OIDC provider. See the "Basic OpenShift Cluster Manager role" section below after you have completed the "Cluster updates" section and started cluster creation.

Cluster updates

  • Leave all the options at default in this section.

Reviewing and creating your cluster

  1. Review the content for the cluster configuration.

  2. Click Create cluster.

Monitoring the installation progress

  • Stay on the current page to monitor the installation progress. It should take about 40 minutes.

    cloud experts getting started rosa deployment detailed ui cluster create

Basic OpenShift Cluster Manager Role

If you created an Admin OpenShift Cluster Manager role as directed above ignore this entire section. The OpenShift Cluster Manager will create the resources for you.

If you created a Basic OpenShift Cluster Manager role earlier, you will need to manually create two more elements before cluster installation can continue:

  • Operator roles

  • OIDC provider

Creating Operator roles

  1. A pop up window will show you the commands to run.

    cloud experts getting started rosa deployment detailed ui create cmds

  2. Run the commands from the window in your terminal to launch interactive mode. Or, for simplicity, run the following command to create the Operator roles:

    $ rosa create operator-roles --mode auto --cluster <cluster-name> --yes
    Example output
    I: Creating roles using 'arn:aws:iam::000000000000:user/rosauser'
I: Created role 'rosacluster-b736-openshift-ingress-operator-cloud-credentials' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-ingress-operator-cloud-credentials'
I: Created role 'rosacluster-b736-openshift-cluster-csi-drivers-ebs-cloud-credent' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-cluster-csi-drivers-ebs-cloud-credent'
I: Created role 'rosacluster-b736-openshift-cloud-network-config-controller-cloud' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-cloud-network-config-controller-cloud'
I: Created role 'rosacluster-b736-openshift-machine-api-aws-cloud-credentials' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-machine-api-aws-cloud-credentials'
I: Created role 'rosacluster-b736-openshift-cloud-credential-operator-cloud-crede' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-cloud-credential-operator-cloud-crede'
I: Created role 'rosacluster-b736-openshift-image-registry-installer-cloud-creden' with ARN 'arn:aws:iam::000000000000:role/rosacluster-b736-openshift-image-registry-installer-cloud-creden'

Creating the OIDC provider

  • In your terminal, run the following command to create the OIDC provider:

    $ rosa create oidc-provider --mode auto --cluster <cluster-name> --yes
    Example output
    I: Creating OIDC provider using 'arn:aws:iam::000000000000:user/rosauser'
I: Created OIDC provider with ARN 'arn:aws:iam::000000000000:oidc-provider/rh-oidc.s3.us-east-1.amazonaws.com/1tt4kvrr2kha2rgs8gjfvf0000000000'