Getting started with the ROSA CLI - ROSA CLI | CLI tools

About the ROSA CLI
Setting up the ROSA CLI
Configuring the ROSA CLI
Initializing ROSA
- init
Using a Bash script
Updating the ROSA CLI

About the ROSA CLI

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

edit

Setting up the ROSA CLI

Use the following steps to install and configure the ROSA CLI (rosa) on your installation host.

Procedure

Install and configure the latest AWS CLI (aws).
1. Follow the AWS Command Line Interface documentation to install and configure the AWS CLI for your operating system.
  
  Specify your aws_access_key_id, aws_secret_access_key, and region in the .aws/credentials file. See AWS Configuration basics in the AWS documentation.
  
  You can optionally use the AWS_DEFAULT_REGION environment variable to set the default AWS region.
2. Query the AWS API to verify if the AWS CLI is installed and configured correctly:
  $ aws sts get-caller-identity --output text
  Example output
  <aws_account_id> arn:aws:iam::<aws_account_id>:user/<username> <aws_user_id>
Download the latest version of the ROSA CLI (rosa) for your operating system from the Downloads page on OpenShift Cluster Manager.
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
```
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
```
Verify if the ROSA CLI is installed correctly by querying the rosa version:
```
$ rosa version
```
Example output
```
1.2.15
Your ROSA CLI is up to date.
```
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:
  
  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
  
  Open a new terminal to activate the configuration.
- To enable persistent tab completion for Bash on a macOS host:
  
  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
  
  Open a new terminal to activate the configuration.
- To enable persistent tab completion for Zsh:
  
  If tab completion is not enabled for your Zsh environment, enable it by running the following command:
  
  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
  
  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"
  
  Open a new terminal to activate the configuration.
- To enable persistent tab completion for fish:
  
  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
  
  Open a new terminal to activate the configuration.
- To enable persistent tab completion for PowerShell:
  
  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
  
  Source the rosa.ps1 file from your PowerShell profile.
For more information about configuring rosa tab completion, see the help menu by running the rosa completion --help command.

Configuring the ROSA CLI

Use the following commands to configure the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

edit

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 ROSA token page.

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

Command-line arguments
The ROSA_TOKEN environment variable
The rosa configuration file
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 rosa CLI.

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

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

Additional resources

Initializing ROSA

Use the init command to initialize Red Hat OpenShift Service on AWS (ROSA) only if you are using non-STS.

edit

init

Perform a series of checks to verify that you are ready to deploy a ROSA 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

edit

Using a Bash script

This is an example workflow of how to use a Bash script with the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

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

Initialize rosa using an Red Hat OpenShift Cluster Manager offline token from Red Hat:
```
$ rosa init --token=<token>
```

Create the ROSA cluster:

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

Add an identity provider (IDP):

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

Add a dedicated-admin user:

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

edit

Updating the ROSA CLI

Update to the latest compatible version of the ROSA CLI (rosa).

Procedure

Confirm that a new version of the ROSA CLI (rosa) 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/

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.
Extract the contents of the archive:
```
$ tar -xzf rosa-linux.tar.gz
```
Install the new version of the 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.
```