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/rosa-quickstart-guide-ui.adoc
// * rosa_hcp/rosa-hcp-quickstart-guide.adoc
// * rosa_planning/rosa-sts-setting-up-environment.adoc

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

Several command-line interface (CLI) tools are required to deploy and work with your cluster.

.Prerequisites

* You have an AWS account.
* You have a Red{nbsp}Hat account.

.Procedure

. Log in to your Red{nbsp}Hat and AWS accounts to access the download page for each required tool.
.. Log in to your Red{nbsp}Hat account at link:https://console.redhat.com[console.redhat.com].
.. Log in to your AWS account at link:https://aws.amazon.com[aws.amazon.com].
. Install and configure the latest AWS CLI (`aws`).
.. Install the AWS CLI by following the link:https://aws.amazon.com/cli/[AWS Command Line Interface] documentation appropriate for your workstation.
.. Configure the AWS CLI by specifying your `aws_access_key_id`, `aws_secret_access_key`, and `region` in the `.aws/credentials` file. For more information, see link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html[AWS Configuration basics] in the AWS documentation.
+
[NOTE]
====
You can optionally 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  --output text
----
+
.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`).
.. Navigate to link:https://console.redhat.com/openshift/downloads[*Downloads*].
.. Find *Red Hat OpenShift Service on AWS command line interface (`rosa)* in the list of tools and click *Download*.
+
The `rosa-linux.tar.gz` file is downloaded to your default download location.
.. 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
----
.. Move the `rosa` binary file to a directory in your execution 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 that the ROSA CLI is installed correctly by querying the `rosa` version:
+
[source,terminal]
----
$ rosa version
----
+
.Example output
[source,terminal]
----
1.2.47
Your ROSA CLI is up to date.
----
// OSDOCS-11789: PM recommended removing this step since it isn't required.
// 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 the ROSA CLI using an offline access token.
.. Run the login command:
+
[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:
----
.. Navigate to the URL listed in the command output to view your offline access token.
.. Enter the offline access token at the command-line prompt to log in.
+
[source,terminal]
----
? Copy the token and paste it here: *******************
[full token length omitted]
----
+
[NOTE]
====
In the future you can specify the offline access token by using the `--token="<offline_access_token>"` argument when you run the `rosa login` command.
====
.. Verify that you are logged in and confirm that your credentials are correct before proceeding:
+
[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>
----
. Install and configure the latest OpenShift CLI (`oc`).
.. Use the ROSA CLI to download the `oc` CLI.
+
The following command downloads the latest version of the CLI to the current working directory:
+
[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
----
.. Move the `oc` binary to a directory in your execution 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 that 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.17.3
----