1. Documentation
    2. history bug_report picture_as_pdf
×

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

Use the following steps to install and configure the Red Hat OpenShift Service on AWS (ROSA) CLI (rosa) on your installation host.

Procedure

  1. Download the latest version of the rosa CLI for your operating system from the Downloads page on OpenShift Cluster Manager.

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

  3. Add rosa to your 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

  4. Verify if the rosa CLI tool is installed correctly by querying the rosa version:

    $ rosa version
    Example output
    1.2.15
Your ROSA CLI is up to date.

  5. Optional: Enable tab completion for the rosa CLI. With tab completion enabled, you can press the Tab key twice to automatically complete subcommands and receive command suggestions:

    • To enable persistent tab completion for Bash on a Linux host:

      1. Generate a rosa tab completion configuration file for Bash and save it to your /etc/bash_completion.d/ directory:

        # rosa completion bash > /etc/bash_completion.d/rosa

      2. Open a new terminal to activate the configuration.

    • To enable persistent tab completion for Bash on a macOS host:

      1. Generate a rosa tab completion configuration file for Bash and save it to your /usr/local/etc/bash_completion.d/ directory:

        $ rosa completion bash > /usr/local/etc/bash_completion.d/rosa

      2. Open a new terminal to activate the configuration.

    • To enable persistent tab completion for Zsh:

      1. If tab completion is not enabled for your Zsh environment, enable it by running the following command:

        $ echo "autoload -U compinit; compinit" >> ~/.zshrc

      2. Generate a rosa tab completion configuration file for Zsh and save it to the first directory in your functions path:

        $ rosa completion zsh > "${fpath[1]}/_rosa"

      3. Open a new terminal to activate the configuration.

    • To enable persistent tab completion for fish:

      1. Generate a rosa tab completion configuration file for fish and save it to your ~/.config/fish/completions/ directory:

        $ rosa completion fish > ~/.config/fish/completions/rosa.fish

      2. Open a new terminal to activate the configuration.

    • To enable persistent tab completion for PowerShell:

      1. Generate a rosa tab completion configuration file for PowerShell and save it to a file named rosa.ps1:

        PS> rosa completion powershell | Out-String | Invoke-Expression

      2. Source the rosa.ps1 file from your PowerShell profile.

    For more information about configuring rosa tab completion, see the help menu by running rosa completion --help.

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.

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.

verify permissions

Verify that the AWS permissions required to create a ROSA cluster are configured correctly:

Syntax
$ rosa verify permissions [arguments]

This command verifies permissions only for clusters that do not use the AWS Security Token Service (STS).
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.
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.
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 rosa

Download the latest compatible version of the Red Hat OpenShift Service on AWS CLI (rosa).

After you download rosa, extract the contents of the archive and add it to your path. See Setting up the rosa CLI for more details.

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

--help

Shows help for this command.

--debug

Enables debug mode.

download oc

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

After you download oc, you must extract the contents of the archive and add it to your path.

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

--help

Shows help for this command.

--debug

Enables debug mode.
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 8. Optional arguments inherited from parent commands
Option Definition

--help

Shows help for this command.

--debug

Enables debug mode.
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) only if you are using non-STS.

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

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

Configure your AWS account to allow ROSA clusters:

$ rosa init

Configure a new AWS account using pre-existing OpenShift Cluster Manager 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 Red Hat OpenShift Cluster Manager 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>

Updating the ROSA CLI

Update to the latest compatible version of the Red Hat OpenShift Service on AWS CLI.

Procedure

  1. Confirm that a new version of the ROSA CLI is available:

    $ rosa version
    Example output
    1.2.12
There is a newer release version '1.2.15', please consider updating: https://mirror.openshift.com/pub/openshift-v4/clients/rosa/latest/

  2. Download the latest compatible version of the ROSA CLI:

    $ rosa download rosa

    This command downloads an archive called rosa-*.tar.gz into the current directory. The exact name of the file depends on your operating system and system architecture.

  3. Extract the contents of the archive:

    $ tar -xzf rosa-linux.tar.gz

  4. Install the new version of ROSA CLI by moving the extracted file into your 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
Verification

  • Verify that the new version of ROSA is installed.

    $ rosa version
    Example output
    1.2.15
Your ROSA CLI is up to date.