Chapter 1. Red Hat OpenShift Service on AWS classic architecture quick start guide

Procedure

1. Sign in to the AWS Management Console.
2. Navigate to the ROSA service.

3. Click Get started.

   The Verify ROSA prerequisites page opens.

4. Under ROSA enablement, ensure that a green check mark and You previously enabled ROSA are displayed.

   If not, follow these steps:

   1. Select the checkbox beside I agree to share my contact information with Red Hat.

   2. Click Enable ROSA.

      After a short wait, a green check mark and You enabled ROSA message are displayed.

5. Under Service Quotas, ensure that a green check and Your quotas meet the requirements for ROSA are displayed.

   If you see Your quotas don’t meet the minimum requirements, take note of the quota type and the minimum listed in the error message. See Amazon’s documentation on requesting a quota increase for guidance. It may take several hours for Amazon to approve your quota request.

6. Under ELB service-linked role, ensure that a green check mark and AWSServiceRoleForElasticLoadBalancing already exists are displayed.

7. Click Continue to Red Hat.

   The Get started with Red Hat OpenShift Service on AWS classic architecture (ROSA) page opens in a new tab. You have already completed Step 1 on this page, and can now continue with Step 2.

Procedure

1. Log in to your Red Hat and AWS accounts to access the download page for each required tool.

   1. Log in to your Red Hat account at console.redhat.com.
   2. Log in to your AWS account at aws.amazon.com.

2. Install and configure the latest AWS CLI (aws).

   1. Install the AWS CLI by following the AWS Command Line Interface documentation appropriate for your workstation.

   2. Configure the AWS CLI by specifying your aws_access_key_id, aws_secret_access_key, and region in the .aws/credentials file. For more information, see AWS Configuration basics in the AWS documentation.

      Note

      You can optionally use the AWS_DEFAULT_REGION environment variable to set the default AWS region.

   3. Query the AWS API to verify if the AWS CLI is installed and configured correctly:

      $ aws sts get-caller-identity  --output text

      Copy to Clipboard Toggle word wrap

      Example output

      <aws_account_id>    arn:aws:iam::<aws_account_id>:user/<username>  <aws_user_id>

      Copy to Clipboard Toggle word wrap

3. Install and configure the latest ROSA CLI.

   1. Navigate to Downloads.

   2. Find Red Hat OpenShift Service on AWS command line interface (rosa) in the list of tools and click Download.

      The rosa-linux.tar.gz file is downloaded to your default download location.

   3. Extract the rosa binary file from the downloaded archive. The following example extracts the binary from a Linux tar archive:

      $ tar xvf rosa-linux.tar.gz

      Copy to Clipboard Toggle word wrap

   4. Move the rosa binary file to a directory in your execution path. In the following example, the /usr/local/bin directory is included in the path of the user:

      $ sudo mv rosa /usr/local/bin/rosa

      Copy to Clipboard Toggle word wrap

   5. Verify that the ROSA CLI is installed correctly by querying the rosa version:

      $ rosa version

      Copy to Clipboard Toggle word wrap

      Example output

      1.2.47
      Your ROSA CLI is up to date.

      Copy to Clipboard Toggle word wrap

4. Log in to the ROSA CLI using an offline access token.

   1. Run the login command:

      $ rosa login

      Copy to Clipboard Toggle word wrap

      Example output

      To login to your Red Hat account, get an offline access token at https://console.redhat.com/openshift/token/rosa
      ? Copy the token and paste it here:

      Copy to Clipboard Toggle word wrap

   2. Navigate to the URL listed in the command output to view your offline access token.

   3. Enter the offline access token at the command-line prompt to log in.

      ? Copy the token and paste it here: *******************
      [full token length omitted]

      Copy to Clipboard Toggle word wrap
      Note

      In the future you can specify the offline access token by using the --token="<offline_access_token>" argument when you run the rosa login command.

   4. Verify that you are logged in and confirm that your credentials are correct before proceeding:

      $ rosa whoami

      Copy to Clipboard Toggle word wrap

      Example output

      AWS Account ID:               <aws_account_number>
      AWS Default Region:           us-east-1
      AWS ARN:                      arn:aws:iam::<aws_account_number>:user/<aws_user_name>
      OCM API:                      https://api.openshift.com
      OCM Account ID:               <red_hat_account_id>
      OCM Account Name:             Your Name
      OCM Account Username:         you@domain.com
      OCM Account Email:            you@domain.com
      OCM Organization ID:          <org_id>
      OCM Organization Name:        Your organization
      OCM Organization External ID: <external_org_id>

      Copy to Clipboard Toggle word wrap

5. Install and configure the latest OpenShift CLI (oc).

   1. Use the ROSA CLI to download the oc CLI.

      The following command downloads the latest version of the CLI to the current working directory:

      $ rosa download openshift-client

      Copy to Clipboard Toggle word wrap

   2. Extract the oc binary file from the downloaded archive. The following example extracts the files from a Linux tar archive:

      $ tar xvf openshift-client-linux.tar.gz

      Copy to Clipboard Toggle word wrap

   3. Move the oc binary to a directory in your execution path. In the following example, the /usr/local/bin directory is included in the path of the user:

      $ sudo mv oc /usr/local/bin/oc

      Copy to Clipboard Toggle word wrap

   4. Verify that the oc CLI is installed correctly:

      $ rosa verify openshift-client

      Copy to Clipboard Toggle word wrap

      Example output

      I: Verifying whether OpenShift command-line tool is available...
      I: Current OpenShift Client Version: 4.17.3

      Copy to Clipboard Toggle word wrap

Procedure

1. Create an OpenShift Cluster Manager role and link it to your Red Hat organization:

   Note

   To enable automatic deployment of the cluster-specific Operator roles and the OpenID Connect (OIDC) provider using the OpenShift Cluster Manager Hybrid Cloud Console, you must apply the administrative privileges to the role by choosing the Admin OCM role command in the Accounts and roles step of creating a ROSA cluster. For more information about the basic and administrative privileges for the OpenShift Cluster Manager role, see Understanding AWS account association.

   Note

   If you choose the Basic OCM role command in the Accounts and roles step of creating a ROSA cluster in the OpenShift Cluster Manager Hybrid Cloud Console, you must deploy a ROSA cluster using manual mode. You will be prompted to configure the cluster-specific Operator roles and the OpenID Connect (OIDC) provider in a later step.

   $ rosa create ocm-role

   Copy to Clipboard Toggle word wrap

   Select the default values at the prompts to quickly create and link the role.

2. Create a user role and link it to your Red Hat user account:

   $ rosa create user-role

   Copy to Clipboard Toggle word wrap

   Select the default values at the prompts to quickly create and link the role.

   Note

   The Red Hat user account must exist in the Red Hat organization that is linked to your OpenShift Cluster Manager role.

Procedure

1. If they do not exist in your AWS account, create the required account-wide AWS IAM STS roles and policies:

   $ rosa create account-roles

   Copy to Clipboard Toggle word wrap

   Select the default values at the prompts to quickly create the roles and policies.

Procedure

1. Navigate to OpenShift Cluster Manager and select Create cluster.
2. On the Create an OpenShift cluster page, select Create cluster in the Red Hat OpenShift Service on AWS classic architecture (ROSA) row.

3. Verify that your AWS account ID is listed in the Associated AWS accounts drop-down menu and that the installer, support, worker, and control plane account role Amazon Resource Names (ARNs) are listed on the Accounts and roles page.

   Note

   If your AWS account ID is not listed, check that you have successfully associated your AWS account with your Red Hat organization. If your account role ARNs are not listed, check that the required account-wide STS roles exist in your AWS account.

4. Click Next.

5. On the Cluster details page, provide a name for your cluster in the Cluster name field. Leave the default values in the remaining fields and click Next.

   Note

   Cluster creation generates a domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. If the cluster name is less than or equal to 15 characters, that name is used for the domain prefix. If the cluster name is longer than 15 characters, the domain prefix is randomly generated as a 15-character string. To customize the subdomain, select the Create custom domain prefix checkbox, and enter your domain prefix name in the Domain prefix field.

6. To deploy a cluster quickly, leave the default options in the Cluster settings, Networking, Cluster roles and policies, and Cluster updates pages and click Next on each page.
7. On the Review your ROSA cluster page, review the summary of your selections and click Create cluster to start the installation.

8. Optional: On the Overview tab, you can enable the delete protection feature by selecting Enable, which is located directly under Delete Protection: Disabled. This will prevent your cluster from being deleted. To disable delete protection, select Disable. By default, clusters are created with the delete protection feature disabled.

   Verification

   • You can check the progress of the installation in the Overview page for your cluster. You can view the installation logs on the same page. Your cluster is ready when the Status in the Details section of the page is listed as Ready.

     Note

     If the installation fails or the cluster State does not change to Ready after about 40 minutes, check the installation troubleshooting documentation for details. For more information, see Troubleshooting installations. For steps to contact Red Hat Support for assistance, see Getting support for Red Hat OpenShift Service on AWS.

Procedure

1. Go to github.com and log in to your GitHub account.
2. If you do not have an existing GitHub organization to use for identity provisioning for your ROSA cluster, create one. Follow the steps in the GitHub documentation.

3. Configure a GitHub identity provider for your cluster that is restricted to the members of your GitHub organization.

   1. Configure an identity provider using the interactive mode:

      $ rosa create idp --cluster=<cluster_name> --interactive 

      1

      Copy to Clipboard Toggle word wrap

      1

      Replace <cluster_name> with the name of your cluster.

      Example output

      I: Interactive mode enabled.
      Any optional fields can be left empty and a default will be selected.
      ? Type of identity provider: github
      ? Identity provider name: github-1
      ? Restrict to members of: organizations
      ? GitHub organizations: <github_org_name> 

      1

      
      ? To use GitHub as an identity provider, you must first register the application:
        - Open the following URL:
          https://github.com/organizations/<github_org_name>/settings/applications/new?oauth_application%5Bcallback_url%5D=https%3A%2F%2Foauth-openshift.apps.<cluster_name>/<random_string>.p1.openshiftapps.com%2Foauth2callback%2Fgithub-1&oauth_application%5Bname%5D=<cluster_name>&oauth_application%5Burl%5D=https%3A%2F%2Fconsole-openshift-console.apps.<cluster_name>/<random_string>.p1.openshiftapps.com
        - Click on 'Register application'
      ...

      Copy to Clipboard Toggle word wrap

      1

      Replace <github_org_name> with the name of your GitHub organization.

   2. Follow the URL in the output and select Register application to register a new OAuth application in your GitHub organization. By registering the application, you enable the OAuth server that is built into ROSA to authenticate members of your GitHub organization into your cluster.

      Note

      The fields in the Register a new OAuth application GitHub form are automatically filled with the required values through the URL defined by the ROSA CLI.

   3. Use the information from your GitHub OAuth application page to populate the remaining rosa create idp interactive prompts.

      Continued example output

      ...
      ? Client ID: <github_client_id> 

      1

      
      ? Client Secret: [? for help] <github_client_secret> 

      2

      
      ? GitHub Enterprise Hostname (optional):
      ? Mapping method: claim 

      3

      
      I: Configuring IDP for cluster '<cluster_name>'
      I: Identity Provider 'github-1' has been created.
         It will take up to 1 minute for this configuration to be enabled.
         To add cluster administrators, see 'rosa grant user --help'.
         To login into the console, open https://console-openshift-console.apps.<cluster_name>.<random_string>.p1.openshiftapps.com and click on github-1.

      Copy to Clipboard Toggle word wrap

      1

      Replace <github_client_id> with the client ID for your GitHub OAuth application.

      2

      Replace <github_client_secret> with a client secret for your GitHub OAuth application.

      3

      Specify claim as the mapping method.

      Note

      It might take approximately two minutes for the identity provider configuration to become active. If you have configured a cluster-admin user, you can watch the OAuth pods redeploy with the updated configuration by running oc get pods -n openshift-authentication --watch.

   4. Enter the following command to verify that the identity provider has been configured correctly:

      $ rosa list idps --cluster=<cluster_name>

      Copy to Clipboard Toggle word wrap

      Example output

      NAME        TYPE      AUTH URL
      github-1    GitHub    https://oauth-openshift.apps.<cluster_name>.<random_string>.p1.openshiftapps.com/oauth2callback/github-1

      Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to github.com and log in to your GitHub account.
2. Invite users that require access to the Red Hat OpenShift Service on AWS classic architecture cluster to your GitHub organization. Follow the steps in Inviting users to join your organization in the GitHub documentation.

Procedure

1. Navigate to github.com and log in to your GitHub account.
2. Remove the user from your GitHub organization. Follow the steps in Removing a member from your organization in the GitHub documentation.