openshift-docs/modules/rosa-getting-started-install-configure-cli-tools.adoc

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

:_content-type: PROCEDURE
[id="rosa-getting-started-install-configure-cli-tools_{context}"]
= Installing and configuring the required CLI tools

ifeval::["{context}" == "rosa-getting-started"]
:getting-started:
endif::[]
ifeval::["{context}" == "rosa-quickstart"]
:quickstart:
endif::[]

Use the following steps to install and configure 
ifdef::quickstart[]
the AWS and {product-title} (ROSA) CLI tools 
endif::[]
ifdef::getting-started[]
AWS, {product-title} (ROSA), and OpenShift CLI tools 
endif::[]
on your workstation.

ifdef::getting-started[]
.Prerequisites

* You have an AWS account.
* You created a Red Hat account.
+
[NOTE]
====
You can create a Red Hat account by navigating to link:https://console.redhat.com[console.redhat.com] and selecting *Register for a Red Hat account*.
====
endif::[]

.Procedure

. Install and configure the latest AWS CLI (`aws`).
.. Follow the link:https://aws.amazon.com/cli/[AWS Command Line Interface] documentation to install and configure the AWS CLI for your operating system.
+
Specify your `aws_access_key_id`, `aws_secret_access_key`, and `region` in the `.aws/credentials` file. See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html[AWS Configuration basics] in the AWS documentation.
+
[NOTE]
====
You can alternatively use the `AWS_DEFAULT_REGION` environment variable to set the default AWS region.
====
.. Query the AWS API to verify if the AWS CLI is installed and configured correctly:
+
[source,terminal]
----
$ aws sts get-caller-identity
----
+
.Example output
[source,terminal]
----
<aws_account_id>    arn:aws:iam::<aws_account_id>:user/<username>  <aws_user_id>
----

. Install and configure the latest ROSA CLI (`rosa`).
.. Download the latest version of the `rosa` CLI for your operating system from the link:https://console.redhat.com/openshift/downloads[*Downloads*] page on the {cluster-manager-first} {hybrid-console-second}.
.. Extract the `rosa` binary file from the downloaded archive. The following example extracts the binary from a Linux tar archive:
+
[source,terminal]
----
$ tar xvf rosa-linux.tar.gz
----
.. Add `rosa` to your path. In the following example, the `/usr/local/bin` directory is included in the path of the user:
+
[source,terminal]
----
$ sudo mv rosa /usr/local/bin/rosa
----
.. Verify if the `rosa` CLI tool is installed correctly by querying the `rosa` version:
+
[source,terminal]
----
$ rosa version
----
+
.Example output
[source,terminal]
----
1.2.8
----
ifdef::getting-started[]
+
.. Optional: Enable tab completion for the `rosa` CLI. With tab completion enabled, you can press the `Tab` key twice to automatically complete subcommands and receive command suggestions.
+
`rosa` tab completion is available for different shell types. The following example enables persistent tab completion for Bash on a Linux host. The command generates a `rosa` tab completion configuration file for Bash and saves it to the `/etc/bash_completion.d/` directory:
+
[source,terminal]
----
# rosa completion bash > /etc/bash_completion.d/rosa
----
+
You must open a new terminal to activate the configuration.
+
[NOTE]
====
For steps to configure `rosa` tab completion for different shell types, see the help menu by running `rosa completion --help`.
====
endif::[]
.. Log in to your Red Hat account by using the `rosa` CLI:
+
[source,terminal]
----
$ rosa login
----
+
.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:
----
+
Go to the URL listed in the command output to obtain an offline access token. Specify the token at the CLI prompt to log in.
+
[NOTE]
====
You can subsequently specify the offline access token by using the `--token="<offline_access_token>"` argument when you run the `rosa login` command.
====
.. Verify if you are logged in successfully and check your credentials:
+
[source,terminal]
----
$ rosa whoami
----
+
.Example output
[source,terminal]
----
AWS Account ID:               <aws_account_number>
AWS Default Region:           us-east-1
AWS ARN:                      arn:aws:iam::<aws_account_number>:user/<aws_user_name>
OCM API:                      https://api.openshift.com
OCM Account ID:               <red_hat_account_id>
OCM Account Name:             Your Name
OCM Account Username:         you@domain.com
OCM Account Email:            you@domain.com
OCM Organization ID:          <org_id>
OCM Organization Name:        Your organization
OCM Organization External ID: <external_org_id>
----
+
Check that the information in the output is correct before proceeding.

ifdef::getting-started[]
. Install and configure the latest OpenShift CLI (`oc`).
.. Use the `rosa` CLI to download the latest version of the `oc` CLI:
+
[source,terminal]
----
$ rosa download openshift-client
----
.. Extract the `oc` binary file from the downloaded archive. The following example extracts the files from a Linux tar archive:
+
[source,terminal]
----
$ tar xvf openshift-client-linux.tar.gz
----
.. Add the `oc` binary to your path. In the following example, the `/usr/local/bin` directory is included in the path of the user:
+
[source,terminal]
----
$ sudo mv oc /usr/local/bin/oc
----
.. Verify if the `oc` CLI is installed correctly:
+
[source,terminal]
----
$ rosa verify openshift-client
----
+
.Example output
[source,terminal]
----
I: Verifying whether OpenShift command-line tool is available...
I: Current OpenShift Client Version: 4.9.12
----
endif::[]


ifeval::["{context}" == "rosa-getting-started"]
:getting-started:
endif::[]
ifeval::["{context}" == "rosa-quickstart"]
:quickstart:
endif::[]