Menu Close

ROSA CLI

Red Hat OpenShift Service on AWS 4

Learning how to use the command-line tools for Red Hat OpenShift Service on AWS

Red Hat OpenShift Documentation Team

Abstract

This document provides information about installing, configuring, and using the command-line tools for Red Hat OpenShift Service on AWS (ROSA). It also contains a reference of CLI commands and examples.

Chapter 1. Getting started with the rosa CLI

Setup and basic usage of the rosa CLI.

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

1.2. 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 Download page of Red Hat OpenShift Service on AWS.
  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)

1.3. Configuring the rosa CLI

Use the following commands to configure the rosa CLI.

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

OptionDefinition

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

OptionDefinition

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

1.3.2. logout

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

Syntax

$ rosa logout [arguments]

Table 1.3. Optional arguments inherited from parent commands

OptionDefinition

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

1.3.3. verify permissions

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

Syntax

$ 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

OptionDefinition

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

1.3.4. verify quota

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

Syntax

$ rosa verify quota [arguments]

Table 1.5. Optional arguments inherited from parent commands

OptionDefinition

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

1.3.5. 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 1.6. Optional arguments inherited from parent commands

OptionDefinition

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

1.3.6. verify oc

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

Syntax

$ rosa verify oc [arguments]

Table 1.7. Optional arguments inherited from parent commands

OptionDefinition

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

1.4. Initializing Red Hat OpenShift Service on AWS

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

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

$ rosa init [arguments]

Table 1.8. Arguments

OptionDefinition

--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 1.9. Optional arguments inherited from parent commands

OptionDefinition

--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 credentials:

$ rosa init --token=$OFFLINE_ACCESS_TOKEN

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

Chapter 2. Managing objects with the rosa CLI

Managing objects with the rosa CLI, such as adding dedicated-admin users, managing clusters, and scheduling cluster upgrades.

2.1. Common commands and arguments

These common commands and arguments are available for the rosa CLI.

2.1.1. debug

Enables debug mode for the parent command.

Example

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

2.1.2. help

Displays general help information for the rosa CLI and a list of available commands. This option can also be used as an argument to display help information for a parent command, such as version or create.

Examples

Displays general help for the rosa CLI:

$ rosa --help

Displays general help for version:

$ rosa version --help

2.1.3. interactive

Enables interactive mode.

Example

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

2.1.4. profile

Specifies an AWS profile from your credential file.

Example

$ rosa create cluster --cluster=<cluster_name> --profile=myAWSprofile

2.1.5. v level

Specifies the log level for V logs.

Example

$ rosa create cluster --cluster=<cluster_name> --v <level>

2.1.6. version

Displays the rosa version.

Example

$ rosa version [arguments]

2.2. Parent commands

The rosa CLI uses parent commands with child commands to manage objects. The parent commands are create, edit, delete, list, and describe. Not all parent commands can be used with all child commands. For more information, see the specific reference topics that describes the child commands.

2.2.1. create

Creates an object or resource when paired with a child command.

Example

$ rosa create cluster --cluster-name=mycluster

2.2.2. edit

Edits options for an object, such as making a cluster private.

Example

$ rosa edit cluster --cluster=mycluster --private

2.2.3. delete

Deletes an object or resource when paired with a child command.

Example

$ rosa delete ingress --cluster=mycluster

2.2.4. list

Lists clusters or resources for a specific cluster.

Example

$ rosa list users --cluster=mycluster

2.2.5. describe

Shows the details for a cluster.

Example

$ rosa describe --cluster=mycluster

2.3. Create objects

This section describes the create commands for clusters and resources.

2.3.1. create admin

Create a cluster administrator with an automatically generated password that can log in to a cluster.

Syntax

$ rosa create admin --cluster=<cluster_name> | <cluster_id>

Table 2.1. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to add to the identity provider (IDP).

Table 2.2. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Example

Create a cluster administrator that can log in to a cluster named mycluster:

$ rosa create admin --cluster=mycluster

2.3.2. create cluster

Create a new cluster.

Syntax

$ rosa create cluster --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.3. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster. When used with the create cluster command, this argument is used to generate a sub-domain for your cluster on openshiftapps.com.

--channel-group

The channel group (string) is the name of the group where this image belongs, for example stable or fast. Default: stable

--compute-machine-type

The instance type (string) for the compute nodes. Determines the amount of memory and vCPU that are allocated to each compute node.

--compute-nodes

The number (integer) of worker nodes to provision per zone. Single-zone clusters require at least 2 nodes. Multi-zone clusters require at least 3 nodes. Default: 2 for single-az; 3 for multi-az

--disable-scp-checks

Indicates whether cloud permission checks are disabled when attempting to install a cluster.

--dry-run

Simulates creating the cluster.

--enable-autoscaling

Enables autoscaling of compute nodes. By default, autoscaling is set to 2 nodes. To set non-default node limits, use this argument with the --min-replicas and --max-replicas arguments.

--host-prefix

The subnet prefix length (integer) to assign to each individual node. For example, if host prefix is set to 23, then each node is assigned a /23 subnet out of the given CIDR.

--machine-cidr

Block of IP addresses (ipNet) used by OpenShift Container Platform while installing the cluster. Example: 10.0.0.0/16

--max-replicas

Specifies the maximum number of compute nodes when enabling autoscaling. Default: 2

--min-replicas

Specifies the minimum number of compute nodes when enabling autoscaling. Default: 2

--multi-az

Deploys to multiple data centers.

--pod-cidr

Block of IP addresses (ipNet) from which pod IP addresses are allocated. Example: 10.128.0.0/14

--private

Restricts primary API endpoint and application routes to direct, private connectivity.

--private-link

Specifies to use AWS PrivateLink to provide private connectivity between VPCs and services. The --subnet-ids argument is required when using --private-link.

--region

The AWS region (string) where your worker pool will be located. This argument overrides the AWS_REGION environment variable.

--service-cidr

Block of IP addresses (ipNet) for services. Example: 172.30.0.0/16

--subnet-ids

The subnet IDs (string) to use when installing the cluster. Subnet IDs must be in pairs with one private subnet ID and one public subnet ID per availability zone. Subnets are comma-delimited. Example: --subnet-ids=subnet-1,subnet-2. Leave the value empty for installer-provisioned subnet IDs.

When using --private-link, the --subnet-ids argument is required and only one private subnet is allowed per zone.

--version

The version (string) of OpenShift Container Platform that will be used to install the cluster. Example: 4.3.10

Table 2.4. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Create a cluster named mycluster:

$ rosa create cluster --cluster=mycluster

Create a cluster with a specific AWS region:

$ rosa create cluster --cluster=mycluster --region=us-east-2

Create a cluster with autoscaling enabled on the default worker machine pool:

$ rosa create cluster --cluster=mycluster -region=us-east-1 --enable-autoscaling --min-replicas=2 --max-replicas=5

2.3.3. create idp

Add an identity provider (IDP) to define how users log in to a cluster.

Syntax

$ rosa create idp --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.5. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to which the IDP will be added.

--ca

The path (string) to the PEM-encoded certificate file to use when making requests to the server.

--client-id

The client ID (string) from the registered application.

--client-secret

The client secret (string) from the registered application.

--mapping-method

Specifies how new identities (string) are mapped to users when they log in. Default: claim

--name

The name (string) for the identity provider.

--type

The type (string) of identity provider. Options: github, gitlab, google, ldap, openid

Table 2.6. GitHub arguments

OptionDefinition

--hostname

The optional domain (string) to use with a hosted instance of GitHub Enterprise.

--organizations

Specifies the organizations for login access. Only users that are members of at least one of the listed organizations (string) are allowed to log in.

--teams

Specifies the teams for login access. Only users that are members of at least one of the listed teams (string) are allowed to log in. The format is <org>/<team>.

Table 2.7. GitLab arguments

OptionDefinition

--host-url

The host URL (string) of a GitLab provider. Default: https://gitlab.com

Table 2.8. Google arguments

OptionDefinition

--hosted-domain

Restricts users to a Google Apps domain (string).

Table 2.9. LDAP arguments

OptionDefinition

--bind-dn

The domain name (string) to bind with during the search phase.

--bind-password

The password (string) to bind with during the search phase.

--email-attributes

The list (string) of attributes whose values should be used as the email address.

--id-attributes

The list (string) of attributes whose values should be used as the user ID. Default: dn

--insecure

Does not make TLS connections to the server.

--name-attributes

The list (string) of attributes whose values should be used as the display name. Default: cn

--url

An RFC 2255 URL (string) which specifies the LDAP search parameters to use.

--username-attributes

The list (string) of attributes whose values should be used as the preferred username. Default: uid

Table 2.10. OpenID arguments

OptionDefinition

--email-claims

The list (string) of claims to use as the email address.

--extra-scopes

The list (string) of scopes to request, in addition to the openid scope, during the authorization token request.

--issuer-url

The URL (string) that the OpenID provider asserts as the issuer identifier. It must use the HTTPS scheme with no URL query parameters or fragment.

--name-claims

The list (string) of claims to use as the display name.

--username-claims

The list (string) of claims to use as the preferred username when provisioning a user.

Table 2.11. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Add a GitHub identity provider to a cluster named mycluster:

$ rosa create idp --type=github --cluster=mycluster

Add an identity provider following interactive prompts:

$ rosa create idp --cluster=mycluster --interactive

2.3.4. create ingress

Add an ingress endpoint to enable API access to the cluster.

Syntax

$ rosa create ingress --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.12. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to which the ingress will be added.

--label-match

The label match (string) for ingress. The format must be a comma-delimited list of key=value pairs. If no label is specified, all routes are exposed on both routers.

--private

Restricts application route to direct, private connectivity.

Table 2.13. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Add an internal ingress to a cluster named mycluster:

$ rosa create ingress --private --cluster=mycluster

Add a public ingress to a cluster named mycluster:

$ rosa create ingress --cluster=mycluster

Add an ingress with a route selector label match:s

$ rosa create ingress --cluster=mycluster --label-match=foo=bar,bar=baz

2.3.5. create machinepool

Add a machine pool to an existing cluster.

Syntax

$ rosa create machinepool --cluster=<cluster_name> | <cluster_id> --replicas=<number> --name=<machinepool_name> [arguments]

Table 2.14. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to which the machine pool will be added.

--enable-autoscaling

Enable or disable autoscaling of compute nodes. To enable autoscaling, use this argument with the --min-replicas and --max-replicas arguments. To disable autoscaling, use --enable-autoscaling=false with the --replicas argument.

--instance-type

The instance type (string) that should be used. Default: m5.xlarge

--labels

The labels (string) for the machine pool. The format must be a comma-delimited list of key=value pairs. This list overwrites any modifications made to node labels on an ongoing basis.

--max-replicas

Specifies the maximum number of compute nodes when enabling autoscaling.

--min-replicas

Specifies the minimum number of compute nodes when enabling autoscaling.

--name

Required: The name (string) for the machine pool.

--replicas

Required when autoscaling is not configured. The number (integer) of machines for this machine pool.

--taints

Taints for the machine pool. This string value should be formatted as a comma-separated list of key=value:ScheduleType. This list will overwrite any modifications made to Node taints on an ongoing basis.

Table 2.15. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Interactively add a machine pool to a cluster named mycluster:

$ rosa create machinepool --cluster=mycluster --interactive

Add a machine pool that is named mp-1 to a cluster with autoscaling enabled:

$ rosa create machinepool --cluster=mycluster --enable-autoscaling --min-replicas=2 --max-replicas=5 --name=mp-1

Add a machine pool that is named mp-1 with 3 replicas of m5.xlarge to a cluster:

$ rosa create machinepool --cluster=mycluster --replicas=3 --instance-type=m5.xlarge --name=mp-1

Add a machine pool with labels to a cluster:

$ rosa create machinepool --cluster=mycluster --replicas=2 --instance-type=r5.2xlarge --labels=foo=bar,bar=baz --name=mp-1

2.4. Edit objects

This section describes the edit commands for clusters and resources.

2.4.1. edit cluster

Allows edits to an existing cluster.

Syntax

$ rosa edit cluster --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.16. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to edit.

--private

Restricts a primary API endpoint to direct, private connectivity.

Table 2.17. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Edit a cluster named mycluster to make it private.

$ rosa edit cluster --cluster=mycluster --private

Edit all cluster options interactively on a cluster named mycluster.

$ rosa edit cluster --cluster=mycluster --interactive

2.4.2. edit ingress

Edits the additional non-default application router for a cluster.

Syntax

$ rosa edit ingress --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.18. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to which the ingress will be added.

--label-match

The label match (string) for ingress. The format must be a comma-delimited list of key=value pairs. If no label is specified, all routes are exposed on both routers.

--private

Restricts the application route to direct, private connectivity.

Table 2.19. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Make an additional ingress with the ID a1b2 as a private connection on a cluster named mycluster.

$ rosa edit ingress --private --cluster=mycluster a1b2

Update the router selectors for the additional ingress with the ID a1b2 on a cluster named mycluster.

$ rosa edit ingress --label-match=foo=bar --cluster=mycluster a1b2

Update the default ingress using the sub-domain identifier apps on a cluster named mycluster.

$ rosa edit ingress --private=false --cluster=mycluster apps

2.4.3. edit machinepool

Allows edits to the machine pool in a cluster.

Syntax

$ rosa edit machinepool --cluster=<cluster_name> | <cluster_id> <machinepool_ID> [arguments]

Table 2.20. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to edit on which the additional machine pool will be edited.

--enable-autoscaling

Enable or disable autoscaling of compute nodes. To enable autoscaling, use this argument with the --min-replicas and --max-replicas arguments. To disable autoscaling, use --enable-autoscaling=false with the --replicas argument.

--labels

The labels (string) for the machine pool. The format must be a comma-delimited list of key=value pairs. Editing this value only affects newly created nodes of the machine pool, which are created by increasing the node number, and does not affect the existing nodes. This list overwrites any modifications made to node labels on an ongoing basis.

--max-replicas

Specifies the maximum number of compute nodes when enabling autoscaling.

--min-replicas

Specifies the minimum number of compute nodes when enabling autoscaling.

--replicas

Required when autoscaling is not configured. The number (integer) of machines for this machine pool.

--taints

Taints for the machine pool. This string value should be formatted as a comma-separated list of key=value:ScheduleType. Editing this value only affect newly created nodes of the machine pool, which are created by increasing the node number, and does not affect the existing nodes. This list overwrites any modifications made to Node taints on an ongoing basis.

Table 2.21. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Examples

Set 4 replicas on a machine pool named mp1 on a cluster named mycluster.

$ rosa edit machinepool --cluster=mycluster --replicas=4 --name=mp1

Enable autoscaling on a machine pool named mp1 on a cluster named mycluster.

$ rosa edit machinepool --cluster-name=mycluster --enable-autoscaling --min-replicas=3 --max-replicas=5 --name=mp1

Disable autoscaling on a machine pool named mp1 on a cluster named mycluster.

$ rosa edit machinepool --cluster-name=mycluster  --enable-autoscaling=false --replicas=3 --name=mp1

Modify the autoscaling range on a machine pool named mp1 on a cluster named mycluster.

$ rosa edit machinepool --max-replicas=9 --cluster=mycluster --name=mp1

2.5. Delete objects

This section describes the delete commands for clusters and resources.

2.5.1. delete admin

Deletes a cluster administrator from a specified cluster.

Syntax

$ rosa delete admin --cluster=<cluster_name> | <cluster_id>

Table 2.22. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to add to the identity provider (IDP).

Table 2.23. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

Example

Delete a cluster administrator from a cluster named mycluster.

$ rosa delete admin --cluster=mycluster

2.5.2. delete cluster

Deletes a cluster.

Syntax

$ rosa delete cluster --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.24. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to delete.

--watch

Watches the cluster uninstallation logs.

Table 2.25. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Examples

Delete a cluster named mycluster.

$ rosa delete cluster --cluster=mycluster

2.5.3. delete idp

Deletes a specific identity provider (IDP) from a cluster.

Syntax

$ rosa delete idp --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.26. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster from which the IDP will be deleted.

Table 2.27. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Example

Delete an identity provider named github from a cluster named mycluster.

$ rosa delete idp github --cluster=mycluster

2.5.4. delete ingress

Deletes a non-default application router (ingress) from a cluster.

Syntax

$ rosa delete ingress --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.28. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster from which the ingress will be deleted.

Table 2.29. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Examples

Delete an ingress with the ID a1b2 from a cluster named mycluster.

$ rosa delete ingress --cluster=mycluster a1b2

Delete a secondary ingress with the subdomain name apps2 from a cluster named mycluster.

$ rosa delete ingress --cluster=mycluster apps2

2.5.5. delete machinepool

Deletes a machine pool from a cluster.

Syntax

$ rosa delete machinepool --cluster=<cluster_name> | <cluster_id> <machine_pool_id>

Table 2.30. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the machine pool will be deleted from.

Table 2.31. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--interactive

Enables interactive mode.

--profile

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

--v <level>

The log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Example

Delete the machine pool with the ID mp-1 from a cluster named mycluster.

$ rosa delete machinepool --cluster=mycluster mp-1

2.6. Install and uninstall add-ons

This section describes how to install and uninstall Red Hat managed service add-ons to a cluster.

2.6.1. install addon

Installs a managed service add-on on a cluster.

Syntax

$ rosa install addon --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.32. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster where the add-on will be installed.

Table 2.33. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Uses a specific AWS profile (string) from your credentials file.

--v level

Log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Example

Add the codeready-workspaces add-on installation to a cluster named mycluster.

$ rosa install addon --cluster=mycluster codeready-workspaces
Note

After installing Red Hat CodeReady Workspace, it can be deployed to any namespace except openshift-workspaces. For more information, see Installing the Red Hat CodeReady Workspaces Operator.

2.6.2. uninstall addon

Uninstalls a managed service add-on from a cluster.

Syntax

$ rosa uninstall addon --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.34. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the add-on will be uninstalled from.

Table 2.35. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

Uses a specific AWS profile (string) from your credentials file.

--v level

Log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Example

Remove the codeready-workspaces add-on installation from a cluster named mycluster.

$ rosa uninstall addon --cluster=mycluster codeready-workspaces

2.7. List and describe objects

This section describes the list and describe commands for clusters and resources.

2.7.1. list addon

List the managed service add-on installations.

Syntax

$ rosa list addons --cluster=<cluster_name> | <cluster_id>

Table 2.36. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to list the add-ons for.

Table 2.37. Optional arguments inherited from parent commands

OptionDefinition

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

2.7.2. list clusters

List all of your clusters.

Syntax

$ rosa list clusters [arguments]

Table 2.38. Arguments

OptionDefinition

--count

The number (integer) of clusters to display. Default: 100

Table 2.39. Optional arguments inherited from parent commands

OptionDefinition

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

2.7.3. list idps

List all of the identity providers (IDPs) for a cluster.

Syntax

$ rosa list idps --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.40. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the IDPs will be listed for.

Table 2.41. Optional arguments inherited from parent commands

OptionDefinition

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

List all identity providers (IDPs) for a cluster named mycluster:

$ rosa list idps --cluster=mycluster

2.7.4. list ingresses

List all of the API and ingress endpoints for a cluster.

Syntax

$ rosa list ingresses --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.42. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the IDPs will be listed for.

Table 2.43. Optional arguments inherited from parent commands

OptionDefinition

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

List all API and ingress endpoints for a cluster named mycluster:

$ rosa list ingresses --cluster=mycluster

2.7.5. list instance-types

List all of the available instance types for use with Red Hat OpenShift Service on AWS. Availability is based on the account’s AWS quota.

Syntax

$ rosa list instance-types [arguments]

Table 2.44. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--output

The output format. Allowed formats are json or yaml.

--profile

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

Example

List all instance types:

$ rosa list instance-types

2.7.6. list machinepools

List the machine pools configured on a cluster.

Syntax

$ rosa list machinepools --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.45. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the machine pools will be listed for.

Table 2.46. Optional arguments inherited from parent commands

OptionDefinition

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

List all of the machine pools on a cluster named mycluster:

$ rosa list machinepools --cluster=mycluster

2.7.7. list regions

List all of the available regions for the current AWS account.

Syntax

$ rosa list regions [arguments]

Table 2.47. Arguments

OptionDefinition

--multi-az

Lists regions that provide support for multiple availability zones.

Table 2.48. Optional arguments inherited from parent commands

OptionDefinition

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

List all of the available regions:

$ rosa list regions

2.7.8. list upgrades

List all available and scheduled cluster version upgrades.

Syntax

$ rosa list upgrades --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.49. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the available upgrades will be listed for.

Table 2.50. Optional arguments inherited from parent commands

OptionDefinition

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

List all of the available upgrades for a cluster named mycluster:

$ rosa list upgrades --cluster=mycluster

2.7.9. list users

List the cluster administrator and dedicated administrator users for a specified cluster.

Syntax

$ rosa list users --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.51. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the cluster administrators will be listed for.

Table 2.52. Optional arguments inherited from parent commands

OptionDefinition

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

List all of the cluster administrators and dedicated administrators for a cluster named mycluster:

$ rosa list users --cluster=mycluster

2.7.10. list versions

List all of the OpenShift versions that are available for creating a cluster.

Syntax

$ rosa list versions [arguments]

Table 2.53. Arguments

OptionDefinition

--channel-group

Lists only versions from the specified channel group (string). Default: stable

Table 2.54. Optional arguments inherited from parent commands

OptionDefinition

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

List all of the OpenShift Container Platform versions:

$ rosa list versions

2.7.11. describe admin

Show the details of a specified cluster-admin user and a command to log in to the cluster.

Syntax

$ rosa describe admin --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.55. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to which the cluster-admin belongs.

Table 2.56. Optional arguments inherited from parent commands

OptionDefinition

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

Describe the cluster-admin user for a cluster named mycluster:

$ rosa describe admin --cluster=mycluster

2.7.12. describe addon

Show the details of a managed service add-on.

Syntax

$ rosa describe addon <addon_id> | <addon_name> [arguments]

Table 2.57. Optional arguments inherited from parent commands

OptionDefinition

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

Describe an add-on named codeready-workspaces:

$ rosa describe addon codeready-workspaces

2.7.13. describe cluster

Shows the details for a cluster.

Syntax

$ rosa describe cluster --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.58. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster.

Table 2.59. Optional arguments inherited from parent commands

OptionDefinition

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

Describe a cluster named mycluster:

$ rosa describe cluster --cluster=mycluster

2.8. Upgrade and delete upgrade for clusters

This section describes the upgrade command usage for clusters.

2.8.1. upgrade cluster

Schedule a cluster upgrade.

Syntax

$ rosa upgrade cluster --cluster=<cluster_name> | <cluster_id> [arguments]

Table 2.60. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the upgrade will be scheduled for.

--interactive

Enables interactive mode.

--version

The version (string) of OpenShift Container Platform that the cluster will be upgraded to.

--schedule-date

The next date (string) when the upgrade will run at the specified time. Format: yyyy-mm-dd

--schedule-time

The next time the upgrade will run on the specified date. Format: HH:mm

--node-drain-grace-period

Sets a grace period (string) for how long the pod disruption budget-protected workloads are respected during upgrades. After this grace period, any workloads protected by pod disruption budgets that have not been successfully drained from a node will be forcibly evicted. Default: 1 hour

Table 2.61. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

Examples

Interactively schedule an upgrade on a cluster named mycluster:

$ rosa upgrade cluster --cluster=mycluster --interactive

Schedule a cluster upgrade within the hour on a cluster named mycluster:

$ rosa upgrade cluster --cluster=mycluster --version 4.5.20

2.8.2. delete upgrade

Cancel a scheduled cluster upgrade:

Syntax

$ rosa delete upgrade --cluster=<cluster_name> | <cluster_id>

Table 2.62. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster that the upgrade will be cancelled for.

Table 2.63. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--v level

Log level for V logs.

--yes

Automatically answers yes to confirm the operation.

Chapter 3. Checking account and version information with the rosa cli

3.1. Checking account and version information with the rosa CLI

Use the following commands to check your account and version information.

3.1.1. whoami

Display information about your AWS and Red Hat accounts.

Syntax

$ rosa whoami [arguments]

Table 3.1. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

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

--v level

Log level for V logs.

Example

$ rosa whoami

3.1.2. version

Display the version of your rosa CLI.

Syntax

$ rosa version [arguments]

Table 3.2. Optional arguments inherited from parent commands

OptionDefinition

--help

Shows help for this command.

--debug

Enables debug mode.

--profile

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

--v level

Log level for V logs.

Example

$ rosa version

Chapter 4. Checking logs with the rosa CLI

4.1. Checking logs with the rosa CLI

Use the following commands to check your install and uninstall logs.

4.1.1. logs install

Show the cluster install logs.

Syntax

$ rosa logs install --cluster=<cluster_name> | <cluster_id> [arguments]

Table 4.1. Arguments

OptionDefinition

--cluster

Required: The name or ID (string) of the cluster to get logs for.

--tail

The number (integer) of lines to get from the end of the log. Default: 2000

--watch

Watches for changes after getting the logs.

Table 4.2. Optional arguments inherited from parent commands

OptionDefinition

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

Show the last 100 install log lines for a cluster named mycluster:

$ rosa logs install mycluster --tail=100

Show the install logs for a cluster named mycluster:

$ rosa logs install --cluster=mycluster

4.1.2. logs uninstall

Show the cluster uninstall logs.

Syntax

$ rosa logs uninstall --cluster=<cluster_name> | <cluster_id> [arguments]

Table 4.3. Arguments

OptionDefinition

--cluster

The name or ID (string) of the cluster to get logs for.

--tail

The number (integer) of lines to get from the end of the log. Default: 2000

--watch

Watches for changes after getting the logs.

Table 4.4. Optional arguments inherited from parent commands

OptionDefinition

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

Show the last 100 uninstall logs for a cluster named mycluster:

$ rosa logs uninstall --cluster=mycluster --tail=100

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.