1. Documentation
    2. Page history / Open an issue
×

Getting started with the rosa CLI

Setup and basic usage of the rosa CLI.

About the rosa CLI

Use the rosa command-line utility for Red Hat OpenShift Service on AWS (ROSA) to create, update, manage, and delete Red Hat OpenShift Service on AWS clusters and resources.

Setting up the rosa CLI

To set up the rosa CLI, download the latest release, then configure and initialize rosa:

Procedure

  1. Download the latest release of the rosa CLI for your operating system from the Red Hat OpenShift Service on AWS product page.

  2. It is recommended that after you download the release, you rename the executable file that you downloaded to rosa, and then add rosa to your path.

  3. Optional: After downloading rosa, enable Bash completion for rosa. Bash completion helps to automatically complete commands and suggest options when you press Tab. The command generates a Bash completion file for rosa and sources it to your current shell session.

    To configure your Bash shell to load rosa completions for each session, add the following command to your Bashrc file (~/.Bashrc or ~/.profile).

    $ . <(rosa completion)

Configuring the rosa CLI

Use the following commands to configure the rosa CLI.

login

Log in to your Red Hat account, saving the credentials to the rosa configuration file. You must provide a token when logging in. You can copy your token from the Red Hat OpenShift Service on AWS token page.

The rosa CLI looks for a token in the following priority order:

  1. Command-line arguments

  2. The ROSA_TOKEN environment variable

  3. The rosa configuration file

  4. Interactively from a command-line prompt

Syntax
$ rosa login [arguments]
Table 1. Arguments
Option Definition

--client-id

The OpenID client identifier (string). Default: cloud-services

--client-secret

The OpenID client secret (string).

--insecure

Enables insecure communication with the server. This disables verification of TLS certificates and host names.

--scope

The OpenID scope (string). If this option is used, it replaces the default scopes. This can be repeated multiple times to specify multiple scopes. Default: openid

--token

Accesses or refreshes the token (string).

--token-url

The OpenID token URL (string). Default: https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
Table 2. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.

logout

Log out of rosa. Logging out also removes the rosa configuration file.

Syntax
$ rosa logout [arguments]
Table 3. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.

verify permissions

Verify that the AWS permissions required to create a rosa cluster are configured correctly.

Syntax
$ rosa verify permissions [arguments]
Table 4. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--region

The AWS region (string) in which to run the command. This value overrides the AWS_REGION environment variable.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.
Examples

Verify that the AWS permissions are configured correctly:

$ rosa verify permissions

Verify that the AWS permissions are configured correctly in a specific region:

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

verify quota

Verifies that AWS quotas are configured correctly for your default region.

Syntax
$ rosa verify quota [arguments]
Table 5. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--region

The AWS region (string) in which to run the command. This value overrides the AWS_REGION environment variable.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.
Examples

Verify that the AWS quotas are configured correctly for the default region:

$ rosa verify quota

Verify that the AWS quotas are configured correctly in a specific region:

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

download oc

Download the latest compatible version of the OpenShift Container Platform CLI (oc).

After downloading oc, you must unzip the archive and add it to your path.

Syntax
$ rosa download oc [arguments]
Table 6. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.
Example

Download oc client tools:

$ rosa download oc

verify oc

Verifies that the OpenShift Container Platform CLI (oc) is installed correctly.

Syntax
$ rosa verify oc [arguments]
Table 7. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--region

The AWS region (string) in which to run the command. This value overrides the AWS_REGION environment variable.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.
Example

Verify oc client tools:

$ rosa verify oc

Initializing Red Hat OpenShift Service on AWS

Use the init command to initialize Red Hat OpenShift Service on AWS (ROSA).

init

Perform a series of checks to verify that you are ready to deploy an Red Hat OpenShift Service on AWS cluster.

The list of checks includes the following:

  • Checks to see that you have logged in (see login)

  • Checks that your AWS credentials are valid

  • Checks that your AWS permissions are valid (see verify permissions)

  • Checks that your AWS quota levels are high enough (see verify quota)

  • Runs a cluster simulation to ensure cluster creation will perform as expected

  • Checks that the osdCcsAdmin user has been created in your AWS account

  • Checks that the OpenShift Container Platform command-line tool is available on your system

Syntax
$ rosa init [arguments]
Table 8. Arguments
Option Definition

--region

The AWS region (string) in which to verify quota and permissions. This value overrides the AWS_REGION environment variable only when running the init command, but it does not change your AWS CLI configuration.

--delete-stack

Deletes the stack template that is applied to your AWS account during the init command.

--client-id

The OpenID client identifier (string). Default: cloud-services

--client-secret

The OpenID client secret (string).

--insecure

Enables insecure communication with the server. This disables verification of TLS certificates and host names.

--scope

The OpenID scope (string). If this option is used, it completely replaces the default scopes. This can be repeated multiple times to specify multiple scopes. Default: openid

--token

Accesses or refreshes the token (string).

--token-url

The OpenID token URL (string). Default: https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
Table 9. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Specifies an AWS profile (string) from your credentials file.

--v <level>

The log level for V logs.
Examples

Configure your AWS account to allow ROSA clusters:

$ rosa init

Configure a new AWS account using pre-existing OpenShift Cluster Manager (OCM) credentials:

$ rosa init --token=$OFFLINE_ACCESS_TOKEN

Using a Bash script

This is an example workflow of how to use a Bash script with the rosa CLI.

Prerequisites

Make sure that AWS credentials are available as one of the following options:

  • AWS profile

  • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)

Procedure

  1. Initialize rosa using an OpenShift Cluster Manager (OCM) offline token from Red Hat:

    $ rosa init --token=<token>

  2. Create the Red Hat OpenShift Service on AWS (ROSA) cluster:

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

  3. Add an identity provider (IDP):

    $ rosa create idp --cluster=<cluster_name> --type=<identity_provider> [arguments]

  4. Add a dedicated-admin user:

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