Chapter 1. Getting started with the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa Setup and basic usage of the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa . 1.1. About the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa 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. 1.2. 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 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: USD 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: USD sudo mv rosa /usr/local/bin/rosa Verify if the ROSA CLI is installed correctly by querying the rosa version: USD 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: USD 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: USD 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: USD rosa completion zsh > "USD{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: USD 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. Note For more information about configuring rosa tab completion, see the help menu by running the rosa completion --help command. 1.3. Configuring the ROSA CLI Use the following commands to configure the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa . 1.3.1. 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 ( 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 USD rosa login [arguments] Table 1.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 1.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. 1.3.2. logout Log out of rosa . Logging out also removes the rosa configuration file. Syntax USD rosa logout [arguments] Table 1.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. 1.3.3. verify permissions Verify that the AWS permissions required to create a ROSA cluster are configured correctly: Syntax USD rosa verify permissions [arguments] Note This command verifies permissions only for clusters that do not use the AWS Security Token Service (STS). Table 1.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: USD rosa verify permissions Verify that the AWS permissions are configured correctly in a specific region: USD rosa verify permissions --region=us-west-2 1.3.4. verify quota Verifies that AWS quotas are configured correctly for your default region. Syntax USD rosa verify quota [arguments] Table 1.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: USD rosa verify quota Verify that the AWS quotas are configured correctly in a specific region: USD rosa verify quota --region=us-west-2 1.3.5. 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. See Setting up the ROSA CLI for more details. Syntax USD rosa download rosa [arguments] Table 1.6. Optional arguments inherited from parent commands Option Definition --help Shows help for this command. --debug Enables debug mode. 1.3.6. 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 USD rosa download oc [arguments] Table 1.7. Optional arguments inherited from parent commands Option Definition --help Shows help for this command. --debug Enables debug mode. Example Download oc client tools: USD rosa download oc 1.3.7. verify oc Verifies that the OpenShift Container Platform CLI ( oc ) is installed correctly. Syntax USD rosa verify oc [arguments] Table 1.8. Optional arguments inherited from parent commands Option Definition --help Shows help for this command. --debug Enables debug mode. Example Verify oc client tools: USD rosa verify oc 1.4. 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. 1.4.1. 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 USD rosa init [arguments] Table 1.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 1.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: USD rosa init Configure a new AWS account using pre-existing OpenShift Cluster Manager credentials: USD rosa init --token=USDOFFLINE_ACCESS_TOKEN 1.5. 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 : USD rosa init --token=<token> Create the Red Hat OpenShift Service on AWS (ROSA) cluster: USD rosa create cluster --cluster-name=<cluster_name> Add an identity provider (IDP): USD rosa create idp --cluster=<cluster_name> --type=<identity_provider> [arguments] Add a dedicated-admin user: USD rosa grant user dedicated-admin --user=<idp_user_name> --cluster=<cluster_name> 1.6. Updating the ROSA CLI Update to the latest compatible version of the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa . Procedure Confirm that a new version of the ROSA CLI ( rosa ) is available: USD 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: USD 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: USD 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: USD sudo mv rosa /usr/local/bin/rosa Verification Verify that the new version of ROSA is installed. USD rosa version Example output 1.2.15 Your ROSA CLI is up to date.

Commands:
tar xvf rosa-linux.tar.gz
sudo mv rosa /usr/local/bin/rosa
rosa version
1.2.15 Your ROSA CLI is up to date.
rosa completion bash > /etc/bash_completion.d/rosa
rosa completion bash > /usr/local/etc/bash_completion.d/rosa
echo "autoload -U compinit; compinit" >> ~/.zshrc
rosa completion zsh > "USD{fpath[1]}/_rosa"
rosa completion fish > ~/.config/fish/completions/rosa.fish
PS> rosa completion powershell | Out-String | Invoke-Expression
rosa login [arguments]
rosa logout [arguments]
rosa verify permissions [arguments]
rosa verify permissions
rosa verify permissions --region=us-west-2
rosa verify quota [arguments]
rosa verify quota
rosa verify quota --region=us-west-2
rosa download rosa [arguments]
rosa download oc [arguments]
rosa download oc
rosa verify oc [arguments]
rosa verify oc
rosa init [arguments]
rosa init
rosa init --token=USDOFFLINE_ACCESS_TOKEN
rosa init --token=<token>
rosa create cluster --cluster-name=<cluster_name>
rosa create idp --cluster=<cluster_name> --type=<identity_provider> [arguments]
rosa grant user dedicated-admin --user=<idp_user_name> --cluster=<cluster_name>
rosa version
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/
rosa download rosa
tar -xzf rosa-linux.tar.gz
sudo mv rosa /usr/local/bin/rosa
rosa version
1.2.15 Your ROSA CLI is up to date.