Procedure

1. Select the AWS account you want to use.

   Unless you are just testing out Red Hat OpenShift Service on AWS, it is recommended to use a dedicated AWS account to run any production clusters. If you are using AWS Organizations, you can use an AWS account within your organization or create a new one.

   If you are using AWS organizations and you need to have a Service Control Policy (SCP) applied to the AWS account you plan to use, see the Red Hat Requirements for Customer Cloud Subscriptions for details on the minimum required SCP.

   As part of the cluster creation process, rosa will create an osdCcsAdmin IAM user. This user will leverage the IAM credentials you provide when configuring the AWS CLI.

   Note

   This user will have Programmatic access enabled and the AdministratorAccess policy attached to it.

2. Install and configure the AWS CLI.

   1. Follow the AWS Command Line Interface documentation to install and configure the AWS CLI for your operating system.

   2. Optional: Set a default AWS region. rosa evaluates regions in the following priority order:

      1. The region specified when running a rosa command with the --region flag.
      2. The region set in the AWS_DEFAULT_REGION environment variable. See Environment variables to configure the AWS CLI in the AWS documentation.
      3. The default region set in your AWS configuration file. See Quick configuration with aws configure in the AWS documentation.

   3. Optional: Configure your AWS CLI settings and credentials by using an AWS named profile. rosa evaluates AWS named profiles in the following priority order:

      1. The profile specified when running a rosa command with the --profile flag.
      2. The profile set in the AWS_PROFILE environment variable. See Named profiles in the AWS documentation.

   4. Verify the AWS CLI is installed and configured correctly by running the following command to query the AWS API:

      $ aws ec2 describe-regions

      Example output

      ---------------------------------------------------------------------------------
      |                                DescribeRegions                                |
      +-------------------------------------------------------------------------------+
      ||                                   Regions                                   ||
      |+-----------------------------------+-----------------------+-----------------+|
      ||             Endpoint              |      OptInStatus      |   RegionName    ||
      |+-----------------------------------+-----------------------+-----------------+|
      ||  ec2.eu-north-1.amazonaws.com     |  opt-in-not-required  |  eu-north-1     ||
      ||  ec2.ap-south-1.amazonaws.com     |  opt-in-not-required  |  ap-south-1     ||
      ||  ec2.eu-west-3.amazonaws.com      |  opt-in-not-required  |  eu-west-3      ||
      ||  ec2.eu-west-2.amazonaws.com      |  opt-in-not-required  |  eu-west-2      ||
      ||  ec2.eu-west-1.amazonaws.com      |  opt-in-not-required  |  eu-west-1      ||
      ||  ec2.ap-northeast-2.amazonaws.com |  opt-in-not-required  |  ap-northeast-2 ||
      ||  ec2.ap-northeast-1.amazonaws.com |  opt-in-not-required  |  ap-northeast-1 ||
      ||  ec2.sa-east-1.amazonaws.com      |  opt-in-not-required  |  sa-east-1      ||
      ||  ec2.ca-central-1.amazonaws.com   |  opt-in-not-required  |  ca-central-1   ||
      ||  ec2.ap-southeast-1.amazonaws.com |  opt-in-not-required  |  ap-southeast-1 ||
      ||  ec2.ap-southeast-2.amazonaws.com |  opt-in-not-required  |  ap-southeast-2 ||
      ||  ec2.eu-central-1.amazonaws.com   |  opt-in-not-required  |  eu-central-1   ||
      ||  ec2.us-east-1.amazonaws.com      |  opt-in-not-required  |  us-east-1      ||
      ||  ec2.us-east-2.amazonaws.com      |  opt-in-not-required  |  us-east-2      ||
      ||  ec2.us-west-1.amazonaws.com      |  opt-in-not-required  |  us-west-1      ||
      ||  ec2.us-west-2.amazonaws.com      |  opt-in-not-required  |  us-west-2      ||
      |+-----------------------------------+-----------------------+-----------------+|

3. Install rosa, the Red Hat OpenShift Service on AWS Command-line Interface (CLI).

   1. Download the latest release of rosa for your operating system.
   2. Optional: Rename the executable file you downloaded to rosa. This documentation uses rosa to refer to the executable file.
   3. Optional: Add rosa to your path.

   4. Verify your installation by running the following command:

      $ rosa

      Example output

      Command line tool for ROSA.
      
      Usage:
        rosa [command]
      
      Available Commands:
        completion  Generates bash completion scripts
        create      Create a resource from stdin
        delete      Delete a specific resource
        describe    Show details of a specific resource
        edit        Edit a specific resource
        help        Help about any command
        init        Applies templates to support Managed OpenShift on AWS clusters
        list        List all resources of a specific type
        login       Log in to your Red Hat account
        logout      Log out
        logs        Show logs of a specific resource
        verify      Verify resources are configured correctly for cluster install
        version     Prints the version of the tool
      
      Flags:
            --debug     Enable debug mode.
        -h, --help      help for rosa
        -v, --v Level   log level for V logs
      
      Use "rosa [command] --help" for more information about a command.

   5. Optional: You can run the rosa completion command to generate a bash completion file.

      $ rosa completion > /etc/bash_completion.d/rosa

      Add this file to the correct location for your operating system. For example, on a Linux machine run the following command to enable rosa bash completion:

      $ source /etc/bash_completion.d/rosa

4. Run the following command to verify that your AWS account has the necessary permissions:

   $ rosa verify permissions

   Example output

   I: Validating SCP policies...
   I: AWS SCP policies ok

5. Verify that your AWS account has the necessary quota to deploy an Red Hat OpenShift Service on AWS cluster.

   $ rosa verify quota --region=us-west-2

   Example output

   I: Validating AWS quota...
   I: AWS quota ok

   Note

   Sometimes your AWS quota varies by region. If you receive any errors, try a different region.

   If you need to increase your quota, navigate to your AWS console, and request a quota increase for the service that failed.

   After both the permissions and quota checks pass, proceed to preparing your AWS account for cluster deployment.

6. Prepare your AWS account for cluster deployment

   1. Run the following command to log in to your Red Hat account with rosa.

      $ rosa login

      Replace <my_offline_access_token> with your token.

      Example output

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

      Note

      If you do not already have a Red Hat account, follow this link to create one. Accept the required terms and conditions. Then, check your email for a verification link.

      Example output continued

      I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com'

   2. Run the following command to verify your Red Hat and AWS credentials are setup correctly. Check that your AWS Account ID, Default Region and ARN match what you expect. You can safely ignore the rows beginning with OCM for now (OCM stands for OpenShift Cluster Manager).

      $ rosa whoami

      Example output

      AWS Account ID:               000000000000
      AWS Default Region:           us-east-2
      AWS ARN:                      arn:aws:iam::000000000000:user/hello
      OCM API:                      https://api.openshift.com
      OCM Account ID:               1DzGIdIhqEWyt8UUXQhSoWaaaaa
      OCM Account Name:             Your Name
      OCM Account Username:         you@domain.com
      OCM Account Email:            you@domain.com
      OCM Organization ID:          1HopHfA2hcmhup5gCr2uH5aaaaa
      OCM Organization Name:        Red Hat
      OCM Organization External ID: 0000000

   3. Initialize your AWS account. This step runs a CloudFormation template that prepares your AWS account for cluster deployment and management. This step typically takes 1-2 minutes to complete.

      $ rosa init

      Example output

      I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com'
      I: Validating AWS credentials...
      I: AWS credentials are valid!
      I: Validating SCP policies...
      I: AWS SCP policies ok
      I: Validating AWS quota...
      I: AWS quota ok
      I: Ensuring cluster administrator user 'osdCcsAdmin'...
      I: Admin user 'osdCcsAdmin' created successfully!
      I: Verifying whether OpenShift command-line tool is available...
      E: OpenShift command-line tool is not installed.
      Run 'rosa download oc' to download the latest version, then add it to your PATH.

      Note

      If you have not already installed the OpenShift Command-line Interface (CLI), also known as oc, run rosa download oc to download the latest version, then add it to your PATH.

Procedure

1. Add an IDP.

   1. The following command creates an IDP backed by GitHub. After running the command, follow the interactive prompts from the output to access your GitHub developer settings and configure a new OAuth application.

      $ rosa create idp --cluster=rh-rosa-test-cluster --interactive

   2. Enter the following values:

      • Type of identity provider: github
      • Restrict to members of: organizations (if you do not have a GitHub Organization, you can create one now.)
      • GitHub organizations: rh-test-org (enter the name of your org)

      Example output

      I: Interactive mode enabled.
      Any optional fields can be left empty and a default will be selected.
      ? Type of identity provider: github
      ? Restrict to members of: organizations
      ? GitHub organizations: rh-test-org
      ? To use GitHub as an identity provider, you must first register the application:
        - Open the following URL:
          https://github.com/organizations/rh-rosa-test-cluster/settings/applications/new?oauth_application%5Bcallback_url%5D=https%3A%2F%2Foauth-openshift.apps.rh-rosa-test-cluster.z7v0.s1.devshift.org%2Foauth2callback%2Fgithub-1&oauth_application%5Bname%5D=rh-rosa-test-cluster-stage&oauth_application%5Burl%5D=https%3A%2F%2Fconsole-openshift-console.apps.rh-rosa-test-cluster.z7v0.s1.devshift.org
        - Click on 'Register application'
      ...

   3. Follow the URL from the output. This creates a new OAuth application in the GitHub organization you specified.
   4. Click Register applicaton to access your Client ID and Client Secret.

   5. Use the information from the GitHub application you created and continue the prompts. Enter the following values:

      • Client ID: <my_github_client_id>
      • Client Secret: [? for help] <my_github_client_secret>
      • Hostname: (optional, you can leave it blank for now)
      • Mapping method: claim

      Continued example output

      ...
      ? Client ID: <my_github_client_id>
      ? Client Secret: [? for help] <my_github_client_secret>
      ? Hostname:
      ? Mapping method: claim
      I: Configuring IDP for cluster 'rh_rosa_test_cluster'
      I: Identity Provider 'github-1' has been created. You need to ensure that there is a list of cluster administrators defined. See 'rosa create user --help' for more information. To login into the console, open https://console-openshift-console.apps.rh-test-org.z7v0.s1.devshift.org and click on github-1

      The IDP can take 1-2 minutes to be configured within your cluster.

   6. Enter the following command to verify that your IDP has been configured correctly:

      $ rosa list idps --cluster rh-rosa-test-cluster1

      Example output

      NAME        TYPE      AUTH URL
      github-1    GitHub    https://oauth-openshift.apps.rh-rosa-test-cluster1.j9n4.s1.devshift.org/oauth2callback/github-1

2. Log in to your cluster.

   1. Enter the following command to get the Console URL of your cluster:

      $ rosa describe cluster rh-rosa-test-cluster1

      Example output

      Name:        rh-rosa-test-cluster1
      ID:          1de87g7c30g75qechgh7l5b2bha6r04e
      External ID: 34322be7-b2a7-45c2-af39-2c684ce624e1
      API URL:     https://api.rh-rosa-test-cluster1.j9n4.s1.devshift.org:6443
      Console URL: https://console-openshift-console.apps.rh-rosa-test-cluster1.j9n4.s1.devshift.org
      Nodes:       Master: 3, Infra: 3, Compute: 4
      Region:      us-east-2
      State:       ready
      Created:     May 27, 2020

   2. Navigate to the Console URL, and log in using your Github credentials.
   3. In the top right of the OpenShift console, click your name and click Copy Login Command.
   4. Select the name of the IDP you added (in our case github-1), and click Display Token.

   5. Copy and paste the oc login command into your terminal.

      $ oc login --token=z3sgOGVDk0k4vbqo_wFqBQQTnT-nA-nQLb8XEmWnw4X --server=https://api.rh-rosa-test-cluster1.j9n4.s1.devshift.org:6443

      Example output

      Logged into "https://api.rh-rosa-cluster1.j9n4.s1.devshift.org:6443" as "rh-rosa-test-user" using the token provided.
      
      You have access to 67 projects, the list has been suppressed. You can list all projects with 'oc projects'
      
      Using project "default".

   6. Enter a simple oc command to verify everything is setup properly and that you are logged in.

      $ oc version

      Example output

      Client Version: 4.4.0-202005231254-4a4cd75
      Server Version: 4.3.18
      Kubernetes Version: v1.16.2

Procedure

1. Enable cluster-admin capability on the cluster:

   $ rosa edit cluster <cluster_name> --enable-cluster-admins

2. Give your user cluster-admin privileges:

   $ rosa grant user cluster-admin --user <idp_user_name> --cluster <cluster_name>

3. Verify your user is listed as a cluster administrator:

   $ rosa list users --cluster <cluster_name>

   Example output

   GROUP             NAME
   cluster-admins    rh-rosa-test-user
   dedicated-admins  rh-rosa-test-user

4. Enter the following command to verify that your user now has cluster-admin access. A cluster administrator can run this command without errors, but a dedicated administrator cannot.

   $ oc get all -n openshift-apiserver

   Example output

   NAME                  READY   STATUS    RESTARTS   AGE
   pod/apiserver-6ndg2   1/1     Running   0          17h
   pod/apiserver-lrmxs   1/1     Running   0          17h
   pod/apiserver-tsqhz   1/1     Running   0          17h
   NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
   service/api   ClusterIP   172.30.23.241   <none>        443/TCP   18h
   NAME                       DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR                     AGE
   daemonset.apps/apiserver   3         3         3       3            3           node-role.kubernetes.io/master=   18h

Procedure

1. Enter the following command to promote your user to a dedicated-admin:

   $ rosa grant user dedicated-admin --user <idp_user_name> --cluster <cluster_name>

2. Enter the following command to verify that your user now has dedicated-admin access:

   $ oc get groups dedicated-admins

   Example output

   NAME               USERS
   dedicated-admins   rh-rosa-test-user

   Note

   A Forbidden error displays if user without dedicated-admin privileges runs this command.

Procedure

1. Enter the following command to revoke access for a dedicated-admin:

   $ rosa revoke user dedicated-admin --user <idp_user_name> --cluster <cluster_name>

2. Enter the following command to verify that your user no longer has dedicated-admin access. The user will not be listed in the output.

   $ oc get groups dedicated-admins

   Note

   A Forbidden error displays if user without dedicated-admin privileges runs this command.

Procedure

1. Revoke the user cluster-admin privileges:

   $ rosa revoke user --cluster <cluster_name> --cluster-admins <idp_user_name>

2. Verify your user is no longer listed as a cluster-admin:

   $ rosa list users --cluster <cluster_name>