Chapter 1. Red Hat OpenShift Service on AWS 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 (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. If they do not exist in your AWS account, create the required account-wide AWS IAM STS roles and policies:

   $ rosa create account-roles --hosted-cp

   Copy to Clipboard Toggle word wrap

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

Procedure

1. Create an AWS VPC using the default CloudFormations template by running the following command:

   $ rosa create network

   Copy to Clipboard Toggle word wrap

2. Optional: Customize your VPC by specifying additional parameters.

   You can use the --param flag to specify changes to the default VPC template. The following example command specifies custom values for region, Name, AvailabilityZoneCount and VpcCidr.

   $ rosa create network --param Region=us-east-2 --param Name=quickstart-stack --param AvailabilityZoneCount=3 --param VpcCidr=10.0.0.0/16

   Copy to Clipboard Toggle word wrap

   The command takes about 5 minutes to run and provides regular status updates from AWS as resources are created. If there is an issue with CloudFormation, a rollback is attempted. For all other errors that are encountered, please follow the error message instructions or contact AWS support.

Procedure

1. Open a shell prompt and clone the Terraform VPC repository by running the following command:

   $ git clone https://github.com/openshift-cs/terraform-vpc-example

   Copy to Clipboard Toggle word wrap

2. Navigate to the created directory by running the following command:

   $ cd terraform-vpc-example

   Copy to Clipboard Toggle word wrap

3. Initiate the Terraform file by running the following command:

   $ terraform init

   Copy to Clipboard Toggle word wrap

   A message confirming the initialization appears when this process completes.

4. To build your VPC Terraform plan based on the existing Terraform template, run the plan command. You must include your AWS region. You can choose to specify a cluster name. A rosa.tfplan file is added to the hypershift-tf directory after the terraform plan completes. For more detailed options, see the Terraform VPC repository’s README file.

   $ terraform plan -out rosa.tfplan -var region=<region>

   Copy to Clipboard Toggle word wrap

5. Apply this plan file to build your VPC by running the following command:

   $ terraform apply rosa.tfplan

   Copy to Clipboard Toggle word wrap

   1. Optional: You can capture the values of the Terraform-provisioned private, public, and machinepool subnet IDs as environment variables to use when creating your Red Hat OpenShift Service on AWS cluster by running the following commands:

      $ export SUBNET_IDS=$(terraform output -raw cluster-subnets-string)

      Copy to Clipboard Toggle word wrap

   2. Verify that the variables were correctly set with the following command:

      $ echo $SUBNET_IDS

      Copy to Clipboard Toggle word wrap

      Example output

      $ subnet-0a6a57e0f784171aa,subnet-078e84e5b10ecf5b0

      Copy to Clipboard Toggle word wrap

Procedure

1. To create your OIDC configuration alongside the AWS resources, run the following command:

   $ rosa create oidc-config --mode=auto --yes

   Copy to Clipboard Toggle word wrap

   This command returns the following information.

   Example output

   ? Would you like to create a Managed (Red Hat hosted) OIDC Configuration Yes
   I: Setting up managed OIDC configuration
   I: To create Operator Roles for this OIDC Configuration, run the following command and remember to replace <user-defined> with a prefix of your choice:
   	rosa create operator-roles --prefix <user-defined> --oidc-config-id 13cdr6b
   If you are going to create a Hosted Control Plane cluster please include '--hosted-cp'
   I: Creating OIDC provider using 'arn:aws:iam::4540112244:user/userName'
   ? Create the OIDC provider? Yes
   I: Created OIDC provider with ARN 'arn:aws:iam::4540112244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/13cdr6b'

   Copy to Clipboard Toggle word wrap

   When creating your cluster, you must supply the OIDC config ID. The CLI output provides this value for --mode auto, otherwise you must determine these values based on aws CLI output for --mode manual.

2. Optional: you can save the OIDC configuration ID as a variable to use later. Run the following command to save the variable:

   $ export OIDC_ID=<oidc_config_id>

   1

   Copy to Clipboard Toggle word wrap

   1

   In the example output above, the OIDC configuration ID is 13cdr6b.

   • View the value of the variable by running the following command:

     $ echo $OIDC_ID

     Copy to Clipboard Toggle word wrap

     Example output

     13cdr6b

     Copy to Clipboard Toggle word wrap

Procedure

1. To create your Operator roles, run the following command:

   $ rosa create operator-roles --hosted-cp --prefix=$OPERATOR_ROLES_PREFIX --oidc-config-id=$OIDC_ID --installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/${ACCOUNT_ROLES_PREFIX}-HCP-ROSA-Installer-Role

   Copy to Clipboard Toggle word wrap

   The following breakdown provides options for the Operator role creation.

   $ rosa create operator-roles --hosted-cp
   	--prefix=$OPERATOR_ROLES_PREFIX 

   1

   
   	--oidc-config-id=$OIDC_ID 

   2

   
   	--installer-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/$ACCOUNT_ROLES_PREFIX-HCP-ROSA-Installer-Role 

   3

   Copy to Clipboard Toggle word wrap

   1

   You must supply a prefix when creating these Operator roles. Failing to do so produces an error. See the Additional resources of this section for information on the Operator prefix.

   2

   This value is the OIDC configuration ID that you created for your Red Hat OpenShift Service on AWS cluster.

   3

   This value is the installer role ARN that you created when you created the Red Hat OpenShift Service on AWS account roles.

   You must include the --hosted-cp parameter to create the correct roles for Red Hat OpenShift Service on AWS clusters. This command returns the following information.

   Example output

   ? Role creation mode: auto
   ? Operator roles prefix: <pre-filled_prefix> 

   1

   
   ? OIDC Configuration ID: 23soa2bgvpek9kmes9s7os0a39i13qm4 | https://dvbwgdztaeq9o.cloudfront.net/23soa2bgvpek9kmes9s7os0a39i13qm4 

   2

   
   ? Create hosted control plane operator roles: Yes
   W: More than one Installer role found
   ? Installer role ARN: arn:aws:iam::4540112244:role/<prefix>-HCP-ROSA-Installer-Role
   ? Permissions boundary ARN (optional):
   I: Reusable OIDC Configuration detected. Validating trusted relationships to operator roles:
   I: Creating roles using 'arn:aws:iam::4540112244:user/<userName>'
   I: Created role '<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials'
   I: Created role '<prefix>-openshift-cloud-network-config-controller-cloud-credenti' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-cloud-network-config-controller-cloud-credenti'
   I: Created role '<prefix>-kube-system-kube-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kube-controller-manager'
   I: Created role '<prefix>-kube-system-capa-controller-manager' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-capa-controller-manager'
   I: Created role '<prefix>-kube-system-control-plane-operator' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-control-plane-operator'
   I: Created role '<prefix>-kube-system-kms-provider' with ARN 'arn:aws:iam::4540112244:role/<prefix>-kube-system-kms-provider'
   I: Created role '<prefix>-openshift-image-registry-installer-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-image-registry-installer-cloud-credentials'
   I: Created role '<prefix>-openshift-ingress-operator-cloud-credentials' with ARN 'arn:aws:iam::4540112244:role/<prefix>-openshift-ingress-operator-cloud-credentials'
   I: To create a cluster with these roles, run the following command:
   	rosa create cluster --sts --oidc-config-id 23soa2bgvpek9kmes9s7os0a39i13qm4 --operator-roles-prefix <prefix> --hosted-cp

   Copy to Clipboard Toggle word wrap

   1

   This field is prepopulated with the prefix that you set in the initial creation command.

   2

   This field requires you to select an OIDC configuration that you created for your Red Hat OpenShift Service on AWS cluster.

   The Operator roles are now created and ready to use for creating your Red Hat OpenShift Service on AWS cluster.

Procedure

1. Use one of the following commands to create your Red Hat OpenShift Service on AWS cluster:

   Note

   When creating a Red Hat OpenShift Service on AWS cluster, the default machine Classless Inter-Domain Routing (CIDR) is 10.0.0.0/16. If this does not correspond to the CIDR range for your VPC subnets, add --machine-cidr <address_block> to the following commands. To learn more about the default CIDR ranges for Red Hat OpenShift Service on AWS, see CIDR range definitions.

   • If you did not set environmental variables, run the following command:

     $ rosa create cluster --cluster-name=<cluster_name> \ 

     1

     
         --mode=auto --hosted-cp [--private] \ 

     2

     
         --operator-roles-prefix <operator-role-prefix> \ 

     3

     
         --external-id <external-id> \ 

     4

     
         --oidc-config-id <id-of-oidc-configuration> \
         --subnet-ids=<public-subnet-id>,<private-subnet-id>

     Copy to Clipboard Toggle word wrap

     1

     Specify the name of your cluster. If your cluster name is longer than 15 characters, it will contain an autogenerated domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. To customize the subdomain, use the --domain-prefix flag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.

     2

     Optional: The --private argument is used to create private Red Hat OpenShift Service on AWS clusters. If you use this argument, ensure that you only use your private subnet ID for --subnet-ids.

     3

     By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace <cluster_name>-<hash> in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see About custom Operator IAM role prefixes.

     Note

     If you specified custom ARN paths when you created the associated account-wide roles, the custom path is automatically detected. The custom path is applied to the cluster-specific Operator roles when you create them in a later step.

     4

     Optional: A unique identifier that might be required when you assume a role in another account.

   • If you set the environmental variables, create a cluster with a single, initial machine pool, using either a publicly or privately available API, and a publicly or privately available Ingress by running the following command:

     $ rosa create cluster --private --cluster-name=<cluster_name> \
         --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

     Copy to Clipboard Toggle word wrap

   • If you set the environmental variables, create a cluster with a single, initial machine pool, a publicly available API, and a publicly available Ingress by running the following command:

     $ rosa create cluster --cluster-name=<cluster_name> --mode=auto \
         --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
         --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS

     Copy to Clipboard Toggle word wrap

2. Check the status of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name>

   Copy to Clipboard Toggle word wrap

   The following State field changes are listed in the output as the cluster installation progresses:

   • pending (Preparing account)
   • installing (DNS setup in progress)
   • installing

   • ready

     Note

     If the installation fails or the State field does not change to ready after more than 10 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.

3. Track the progress of the cluster creation by watching the Red Hat OpenShift Service on AWS installation program logs. To check the logs, run the following command:

   $ rosa logs install --cluster=<cluster_name> --watch \ 

   1

   Copy to Clipboard Toggle word wrap

   1

   Optional: To watch for new log messages as the installation progresses, use the --watch argument.

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 cluster to your GitHub organization. Follow the steps in Inviting users to join your organization in the GitHub documentation.

Procedure

1. Obtain the console URL for your cluster:

   $ rosa describe cluster -c <cluster_name> | grep Console 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <cluster_name> with the name of your cluster.

   Example output

   Console URL:                https://console-openshift-console.apps.example-cluster.wxyz.p1.openshiftapps.com

   Copy to Clipboard Toggle word wrap

2. Go to the console URL in the output of the preceding step and log in.

   • If you created a cluster-admin user, log in by using the provided credentials.
   • If you configured an identity provider for your cluster, select the identity provider name in the Log in with…​ dialog and complete any authorization requests that are presented by your provider.

Procedure

1. Go to the Cluster List page in OpenShift Cluster Manager.
2. Click the options icon (⋮) next to the cluster you want to view.
3. Click Open console.
4. Your cluster console opens in a new browser window. Log in to your Red Hat account with your configured identity provider credentials.
5. In the Administrator perspective, select Home Projects Create Project.
6. Enter a name for your project and optionally add a Display Name and Description.
7. Click Create to create the project.
8. Switch to the Developer perspective and select +Add. Verify that the selected Project is the one that you just created.
9. In the Developer Catalog dialog, select All services.
10. In the Developer Catalog page, select Languages JavaScript from the menu.

11. Click Node.js, and then click Create to open the Create Source-to-Image application page.

    Note

    You might need to click Clear All Filters to display the Node.js option.

12. In the Git section, click Try sample.
13. Add a unique name in the Name field. The value will be used to name the associated resources.
14. Confirm that Deployment and Create a route are selected.
15. Click Create to deploy the application. It will take a few minutes for the pods to deploy.
16. Optional: Check the status of the pods in the Topology pane by selecting your Node.js app and reviewing its sidebar. You must wait for the nodejs build to complete and for the nodejs pod to be in a Running state before continuing.

17. When the deployment is complete, click the route URL for the application, which has a format similar to the following:

    https://nodejs-<project>.<cluster_name>.<hash>.<region>.openshiftapps.com/

    Copy to Clipboard Toggle word wrap

    A new tab in your browser opens with a message similar to the following:

    Welcome to your Node.js application on OpenShift

    Copy to Clipboard Toggle word wrap

18. Optional: Delete the application and clean up the resources that you created:

    1. In the Administrator perspective, navigate to Home Projects.
    2. Click the action menu for your project and select Delete Project.

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.

Procedure

1. Delete a cluster and watch the logs, replacing <cluster_name> with the name or ID of your cluster:

   $ rosa delete cluster --cluster=<cluster_name> --watch

   Copy to Clipboard Toggle word wrap
   Important

   You must wait for the cluster deletion to complete before you remove the IAM roles, policies, and OIDC provider. The account-wide roles are required to delete the resources created by the installer. The cluster-specific Operator roles are required to clean-up the resources created by the OpenShift Operators. The Operators use the OIDC provider to authenticate with AWS APIs.

2. After the cluster is deleted, delete the OIDC provider that the cluster Operators use to authenticate:

   $ rosa delete oidc-provider -c <cluster_id> --mode auto 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <cluster_id> with the ID of the cluster.

   Note

   You can use the -y option to automatically answer yes to the prompts.

3. Delete the cluster-specific Operator IAM roles:

   $ rosa delete operator-roles -c <cluster_id> --mode auto 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <cluster_id> with the ID of the cluster.

4. Delete the account-wide roles:

   Important

   Account-wide IAM roles and policies might be used by other Red Hat OpenShift Service on AWS clusters in the same AWS account. You must only remove the resources if they are not required by other clusters.

   $ rosa delete account-roles --prefix <prefix> --mode auto 

   1

   Copy to Clipboard Toggle word wrap

   1

   You must include the --<prefix> argument. Replace <prefix> with the prefix of the account-wide roles to delete. If you did not specify a custom prefix when you created the account-wide roles, specify the default prefix, depending on how they were created, HCP-ROSA or ManagedOpenShift.

5. Delete the account-wide and Operator IAM policies that you created for Red Hat OpenShift Service on AWS deployments:

   1. Log in to the AWS IAM Console.
   2. Navigate to Access management Policies and select the checkbox for one of the account-wide policies.
   3. With the policy selected, click on Actions Delete to open the delete policy dialog.
   4. Enter the policy name to confirm the deletion and select Delete to delete the policy.
   5. Repeat this step to delete each of the account-wide and Operator policies for the cluster.