openshift-docs/modules/rosa-installing.adoc

// Module included in the following assemblies:
//
// * rosa-getting-started/rosa-installing-rosa.adoc


:_content-type: PROCEDURE
[id="rosa-installing-and-configuring-the-rosa-cli_{context}"]
= Installing and configuring the ROSA CLI

Install and configure the ROSA CLI (`rosa`). You can also install the OpenShift CLI (`oc`) and verify if the required AWS resource quotas are available by using the ROSA CLI.

.Prerequisites

* Review and complete the AWS prerequisites and ROSA policies.
* Create a link:https://cloud.redhat.com[Red Hat account], if you do not already have one. Then, check your email for a verification link. You will need these credentials to install ROSA.
* Configure your AWS account and enable the ROSA service in your AWS account.

.Procedure

. Install `rosa`, the {product-title} command-line interface (CLI).
.. Download the link:https://access.redhat.com/products/red-hat-openshift-service-aws/[latest release] of the `rosa` CLI for your operating system.
.. Optional: Rename the executable file you downloaded to `rosa`. This documentation uses `rosa` to refer to the executable file.
.. Optional: Add `rosa` to your path.
+
.Example
[source,terminal]
----
$ mv rosa /usr/local/bin/rosa
----
.. Enter the following command to verify your installation:
+
[source,terminal]
----
$ rosa
----
+
.Example output
[source,terminal]
----
Command line tool for ROSA.

Usage:
  rosa [command]

Available Commands:
  completion  Generates bash completion scripts
  create      Create a resource from stdin
  delete      Delete a specific resource
  describe    Show details of a specific resource
  edit        Edit a specific resource
  help        Help about any command
  init        Applies templates to support Managed OpenShift on AWS clusters
  list        List all resources of a specific type
  login       Log in to your Red Hat account
  logout      Log out
  logs        Show logs of a specific resource
  verify      Verify resources are configured correctly for cluster install
  version     Prints the version of the tool

Flags:
      --debug     Enable debug mode.
  -h, --help      help for rosa
  -v, --v Level   log level for V logs

Use "rosa [command] --help" for more information about a command.
----
+
.. Optional: Generate the command completion scripts for the `rosa` CLI. The following example generates the Bash completion scripts for a Linux machine:
+
[source,terminal]
----
$ rosa completion bash | sudo tee /etc/bash_completion.d/rosa
----
.. Optional: Enable `rosa` command completion from your existing terminal. The following example enables Bash completion for `rosa` in an existing terminal on a Linux machine:
+
[source,terminal]
----
$ source /etc/bash_completion.d/rosa
----

. Log in to your Red Hat account with `rosa`.
+
.. Enter the following command.
+
[source,terminal]
----
$ rosa login
----
+
.. Replace `<my_offline_access_token>` with your token.
+
.Example output
[source,terminal]
----
To login to your Red Hat account, get an offline access token at https://console.redhat.com/openshift/token/rosa
? Copy the token and paste it here: <my-offline-access-token>
----
+
.Example output continued
[source,terminal]
----
I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com'
----

. Enter the following command to verify that your AWS account has the necessary permissions.
+
[source,terminal]
----
$ rosa verify permissions
----
+
.Example output
[source,terminal]
----
I: Validating SCP policies...
I: AWS SCP policies ok
----
+
[NOTE]
====
This command verifies permissions only for ROSA clusters that do not use the AWS Security Token Service (STS).
====

. Verify that your AWS account has the necessary quota to deploy an {product-title} cluster.
+
[source,terminal]
----
$ rosa verify quota --region=us-west-2
----
+
.Example output
[source,terminal]
----
I: Validating AWS quota...
I: AWS quota ok
----
+
[NOTE]
====
Sometimes your AWS quota varies by region. If you receive any errors, try a different region.
====
+
If you need to increase your quota, go to your link:https://aws.amazon.com/console/[AWS console], and request a quota increase for the service that failed.
+
After both the permissions and quota checks pass, proceed to the next step.
+
. Prepare your AWS account for cluster deployment:
+
.. Run the following command to verify your Red Hat and AWS credentials are setup correctly.  Check that your AWS Account ID, Default Region and ARN match what you expect. You can safely ignore the rows beginning with `OCM` for now.
+
[source,terminal]
----
$ rosa whoami
----
+
.Example output
[source,terminal]
----
AWS Account ID:               000000000000
AWS Default Region:           us-east-2
AWS ARN:                      arn:aws:iam::000000000000:user/hello
OCM API:                      https://api.openshift.com
OCM Account ID:               1DzGIdIhqEWyt8UUXQhSoWaaaaa
OCM Account Name:             Your Name
OCM Account Username:         you@domain.com
OCM Account Email:            you@domain.com
OCM Organization ID:          1HopHfA2hcmhup5gCr2uH5aaaaa
OCM Organization Name:        Red Hat
OCM Organization External ID: 0000000
----
+
.. Initialize your AWS account. This step runs a CloudFormation template that prepares your AWS account for cluster deployment and management. This step typically takes 1-2 minutes to complete.
+
[source,terminal]
----
$ rosa init
----
+
.Example output
[source,terminal]
----
I: Logged in as 'rh-rosa-user' on 'https://api.openshift.com'
I: Validating AWS credentials...
I: AWS credentials are valid!
I: Validating SCP policies...
I: AWS SCP policies ok
I: Validating AWS quota...
I: AWS quota ok
I: Ensuring cluster administrator user 'osdCcsAdmin'...
I: Admin user 'osdCcsAdmin' created successfully!
I: Verifying whether OpenShift command-line tool is available...
E: OpenShift command-line tool is not installed.
Run 'rosa download oc' to download the latest version, then add it to your PATH.
----

. Install the OpenShift CLI (`oc`) from the `rosa` CLI.
.. Enter this command to download the latest version of the `oc` CLI:
+
[source,terminal]
----
$ rosa download oc
----

.. After downloading the `oc` CLI, unzip it and add it to your path.
.. Enter this command to verify that the `oc` CLI is installed correctly:
+
[source,terminal]
----
$ rosa verify oc
----

After installing ROSA, you are ready to create a cluster.