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

ifeval::["{context}" == "rosa-hcp-quickstart-guide"]
:quickstart:
endif::[]

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

[role="_abstract"]
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]
====
Optional: 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
----
+
For example:
+
[source,terminal]
----
<aws_account_id>    arn:aws:iam::<aws_account_id>:user/<username>  <aws_user_id>
----
+
. Install and configure the latest {rosa-cli}.
.. 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
----
+
For example:
+
[source,terminal,subs="attributes+"]
----
1.2.47
Your {rosa-cli} is up to date.
----

. Log in to the {rosa-cli} using an offline access token.
.. Run the login command:
+
[source,terminal]
----
$ rosa login
----
+
For example:
+
[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
----
+
For example:
+
[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
----
+
For example:
+
[source,terminal]
----
I: Verifying whether OpenShift command-line tool is available...
I: Current OpenShift Client Version: 4.17.3
----

.Verification

* Verify the installation of each CLI tool:
+
[source,terminal]
----
$ rosa version
$ aws --version
$ oc version
----

[role="_additional-resources"]
.Additional resources

* link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html[AWS Command Line Interface documentation]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]

ifeval::["{context}" == "rosa-hcp-quickstart-guide"]
:!quickstart:
endif::[]
