Menu Close
ROSA CLI
Learning how to use the command-line tools for Red Hat OpenShift Service on AWS
Abstract
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
-
Download the latest release of the
rosa
CLI for your operating system from the Download page of Red Hat OpenShift Service on AWS. -
It is recommended that after you download the release, you rename the executable file that you downloaded to
rosa
, and then addrosa
to your path. Optional: After downloading
rosa
, enable Bash completion forrosa
. Bash completion helps to automatically complete commands and suggest options when you pressTab
. The command generates a Bash completion file forrosa
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 yourBashrc
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:
- Command-line arguments
-
The
ROSA_TOKEN
environment variable -
The
rosa
configuration file - Interactively from a command-line prompt
Syntax
$ rosa login [arguments]
Table 1.1. Arguments
Option | Definition |
---|---|
--client-id |
The OpenID client identifier (string). Default: |
--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: |
--token | Accesses or refreshes the token (string). |
--token-url |
The OpenID token URL (string). Default: |
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. |
--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
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. |
1.3.3. 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 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 |
--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
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 |
--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
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
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
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
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
Option | Definition |
---|---|
--region |
The AWS region (string) in which to verify quota and permissions. This value overrides the |
--delete-stack |
Deletes the stack template that is applied to your AWS account during the |
--client-id |
The OpenID client identifier (string). Default: |
--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: |
--token | Accesses or refreshes the token (string). |
--token-url |
The OpenID token URL (string). Default: |
Table 1.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 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
Initialize
rosa
using an Red Hat OpenShift Cluster Manager offline token from Red Hat:$ rosa init --token=<token>
Create the Red Hat OpenShift Service on AWS (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>
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--cluster |
Required: The name or ID (string) of the cluster. When used with the |
--channel-group |
The channel group (string) is the name of the group where this image belongs, for example |
--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: |
--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 |
--host-prefix |
The subnet prefix length (integer) to assign to each individual node. For example, if host prefix is set to |
--machine-cidr |
Block of IP addresses (ipNet) used by OpenShift Container Platform while installing the cluster. Example: |
--max-replicas |
Specifies the maximum number of compute nodes when enabling autoscaling. Default: |
--min-replicas |
Specifies the minimum number of compute nodes when enabling autoscaling. Default: |
--multi-az | Deploys to multiple data centers. |
--pod-cidr |
Block of IP addresses (ipNet) from which pod IP addresses are allocated. Example: |
--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 |
--region |
The AWS region (string) where your worker pool will be located. This argument overrides the |
--service-cidr |
Block of IP addresses (ipNet) for services. Example: |
--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:
When using |
--version |
The version (string) of OpenShift Container Platform that will be used to install the cluster. Example: |
Table 2.4. Optional arguments inherited from parent commands
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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: |
--name | The name (string) for the identity provider. |
--type |
The type (string) of identity provider. Options: |
Table 2.6. GitHub arguments
Option | Definition |
---|---|
--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 |
Table 2.7. GitLab arguments
Option | Definition |
---|---|
--host-url |
The host URL (string) of a GitLab provider. Default: |
Table 2.8. Google arguments
Option | Definition |
---|---|
--hosted-domain | Restricts users to a Google Apps domain (string). |
Table 2.9. LDAP arguments
Option | Definition |
---|---|
--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: |
--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: |
--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: |
Table 2.10. OpenID arguments
Option | Definition |
---|---|
--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 |
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
--instance-type |
The instance type (string) that should be used. Default: |
--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 |
Table 2.15. Optional arguments inherited from parent commands
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
--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 |
Table 2.21. Optional arguments inherited from parent commands
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
Example
Add the codeready-workspaces
add-on installation to a cluster named mycluster
.
$ rosa install addon --cluster=mycluster codeready-workspaces
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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 |
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
Option | Definition |
---|---|
--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
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. |
2.7.2. list clusters
List all of your clusters.
Syntax
$ rosa list clusters [arguments]
Table 2.38. Arguments
Option | Definition |
---|---|
--count |
The number (integer) of clusters to display. Default: |
Table 2.39. 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. |
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
Option | Definition |
---|---|
--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
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
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
Option | Definition |
---|---|
--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
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
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
Option | Definition |
---|---|
--help | Shows help for this command. |
--debug | Enables debug mode. |
--output |
The output format. Allowed formats are |
--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
Option | Definition |
---|---|
--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
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
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
Option | Definition |
---|---|
--multi-az | Lists regions that provide support for multiple availability zones. |
Table 2.48. 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
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
Option | Definition |
---|---|
--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
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
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
Option | Definition |
---|---|
--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
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
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
Option | Definition |
---|---|
--channel-group |
Lists only versions from the specified channel group (string). Default: |
Table 2.54. 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
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
Option | Definition |
---|---|
--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
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
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
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
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
Option | Definition |
---|---|
--cluster | Required: The name or ID (string) of the cluster. |
Table 2.59. 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
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
Option | Definition |
---|---|
--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: |
--schedule-time |
The next time the upgrade will run on the specified date. Format: |
--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: |
Table 2.61. Optional arguments inherited from parent commands
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--help | Shows help for this command. |
--debug | Enables debug mode. |
--v level | Log level for V logs. |
--yes |
Automatically answers |
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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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
Option | Definition |
---|---|
--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: |
--watch | Watches for changes after getting the logs. |
Table 4.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. |
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
Option | Definition |
---|---|
--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: |
--watch | Watches for changes after getting the logs. |
Table 4.4. 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
Show the last 100 uninstall logs for a cluster named mycluster
:
$ rosa logs uninstall --cluster=mycluster --tail=100