×

It is recommended that you access your Red Hat OpenShift Service on AWS (ROSA) cluster using an identity provider (IDP) account. However, the cluster administrator who created the cluster can access it using the quick access procedure.

This document describes how to access a cluster and set up an IDP using the ROSA CLI (rosa). Alternatively, you can create an IDP account using OpenShift Cluster Manager console.

Accessing your cluster quickly

You can use this quick access procedure to log in to your cluster.

As a best practice, access your cluster with an IDP account instead.

Procedure
  1. Enter the following command:

    $ rosa create admin --cluster=<cluster_name>
    Example output
    W: It is recommended to add an identity provider to login to this cluster. See 'rosa create idp --help' for more information.
    I: Admin account has been added to cluster 'cluster_name'. It may take up to a minute for the account to become active.
    I: To login, run the following command:
    oc login https://api.cluster-name.t6k4.i1.oragnization.org:6443 \ (1)
    --username cluster-admin \
    --password FWGYL-2mkJI-3ZTTZ-rINns
    1 For a Red Hat OpenShift Service on AWS (ROSA) with hosted control planes (HCP) cluster, the port number should be 443.
  2. Enter the oc login command, username, and password from the output of the previous command:

    Example output
    $ oc login https://api.cluster_name.t6k4.i1.oragnization.org:6443 \ (1)
    >  --username cluster-admin \
    >  --password FWGYL-2mkJI-3ZTTZ-rINns
    Login successful.                                                                                                                                                                                                                                                       You have access to 77 projects, the list has been suppressed. You can list all projects with ' projects'
    1 For a ROSA with HCP cluster, the port number should be 443.
  3. Using the default project, enter this oc command to verify that the cluster administrator access is created:

    $ oc whoami
    Example output
    cluster-admin

Accessing your cluster with an IDP account

To log in to your cluster, you can configure an identity provider (IDP). This procedure uses GitHub as an example IDP. To view other supported IDPs, run the rosa create idp --help command.

Alternatively, as the user who created the cluster, you can use the quick access procedure.

Procedure

To access your cluster using an IDP account:

  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=<cluster_name> --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 organization)

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

      The fields in the Register a new OAuth application GitHub form are automatically filled with the required values through the URL that is defined by the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

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

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

      $ rosa list idps --cluster=<cluster_name>
      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 --cluster=<cluster_name>
      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 (1)
      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
      1 For a Red Hat OpenShift Service on AWS (ROSA) with hosted control planes (HCP) cluster, the port number should be 443.
    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 (1)
      1 For a ROSA with HCP cluster, use the port number 443.
      Example output
      Logged into "https://api.rh-rosa-cluster1.j9n4.s1.devshift.org:6443" as "rh-rosa-test-user" using the token provided. (1)
      
      You have access to 67 projects, the list has been suppressed. You can list all projects with 'oc projects'
      
      Using project "default".
      1 For a ROSA with HCP cluster, the port number should be 443.
    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

Granting cluster-admin access

As the user who created the cluster, add the cluster-admin user role to your account to have the maximum administrator privileges. These privileges are not automatically assigned to your user account when you create the cluster.

Additionally, only the user who created the cluster can grant cluster access to other cluster-admin or dedicated-admin users. Users with dedicated-admin access have fewer privileges. As a best practice, limit the number of cluster-admin users to as few as possible.

Prerequisites
  • You have added an identity provider (IDP) to your cluster.

  • You have the IDP user name for the user you are creating.

  • You are logged in to the cluster.

Procedure
  1. Give your user cluster-admin privileges:

    $ rosa grant user cluster-admin --user=<idp_user_name> --cluster=<cluster_name>
  2. 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
  3. 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
Additional resources

Granting dedicated-admin access

Only the user who created the cluster can grant cluster access to other cluster-admin or dedicated-admin users. Users with dedicated-admin access have fewer privileges. As a best practice, grant dedicated-admin access to most of your administrators.

Prerequisites
  • You have added an identity provider (IDP) to your cluster.

  • You have the IDP user name for the user you are creating.

  • You are logged in to the cluster.

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

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

Additional resources