openshift-docs/modules/rosa-sts-setting-up-environment.adoc

// Module included in the following assemblies:
//
// * rosa_planning/rosa-sts-setting-up-environment.adoc
:_mod-docs-content-type: PROCEDURE
[id="rosa-sts-setting-up-environment_{context}"]
= Setting up the environment for STS

[role="_abstract"]
Before you create a {product-title} cluster that uses the AWS Security Token Service (STS), complete the following steps to set up your environment.

.Prerequisites

* Review and complete the deployment prerequisites and policies.
* Create a link:https://cloud.redhat.com[Red{nbsp}Hat account], if you do not already have one. Then, check your email for a verification link. You will need these credentials to install {product-title}.

.Procedure

. Log in to the Amazon Web Services (AWS) account that you want to use.
+
It is recommended to use a dedicated AWS account to run production clusters. If you are using AWS Organizations, you can use an AWS account within your organization or link:https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_create.html#orgs_manage_accounts_create-new[create a new one].
+
If you are using AWS Organizations and you need to have a service control policy (SCP) applied to the AWS account you plan to use, these policies must not be more restrictive than the roles and policies required by the cluster.
+
. Enable {product-title} in the AWS Management Console.
.. Sign in to your link:https://console.aws.amazon.com/rosa/home[AWS account].
.. To enable {product-title}, go to the link:https://console.aws.amazon.com/rosa/[ROSA service] and select *Enable OpenShift*.

. Install and configure the AWS CLI.
.. Follow the AWS command-line interface documentation to link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html[install] and link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html[configure] the AWS CLI for your operating system.
+
Specify the correct `aws_access_key_id` and `aws_secret_access_key` 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.

.. Set a default AWS region.
+
[NOTE]
====
You can use the environment variable to set the default AWS region.
====
+
{product-title} evaluates regions in the following priority order:
+
... The region specified when running the `rosa` command with the `--region` flag.
... The region set in the `AWS_DEFAULT_REGION` environment variable. See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html[Environment variables to configure the AWS CLI] in the AWS documentation.
... The default region set in your AWS configuration file. See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config[Quick configuration with aws configure] in the AWS documentation.
.. Optional: Configure your AWS CLI settings and credentials by using an AWS named profile. `rosa` evaluates AWS named profiles in the following priority order:
... The profile specified when running the `rosa` command with the `--profile` flag.
... The profile set in the `AWS_PROFILE` environment variable. See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html[Named profiles] in the AWS documentation.
.. Verify the AWS CLI is installed and configured correctly by running the following command to query the AWS API:
+
[source,terminal]
----
$ aws sts get-caller-identity
----
+
. Install the latest version of the ROSA CLI (`rosa`).
.. Download the latest release of the link:https://console.redhat.com/openshift/downloads[ROSA CLI] for your operating system.
.. Optional: Rename the file you downloaded to `rosa` and make the file executable. This documentation uses `rosa` to refer to the executable file.
+
[source,terminal]
----
$ chmod +x rosa
----
.. Optional: Add `rosa` to your path.
+
[source,terminal]
----
$ mv rosa /usr/local/bin/rosa
----
.. Enter the following command to verify your installation:
+
[source,terminal]
----
$ rosa
----
+
For example:
+
[source,terminal]
----
Command-line tool for {product-title}. For further documentation visit https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws

Usage:
  rosa [command]

Available Commands:
  completion  Generates completion scripts
  create      Create a resource from stdin
  delete      Delete a specific resource
  describe    Show details of a specific resource
  download    Download necessary tools for using your cluster
  edit        Edit a specific resource
  grant       Grant role to a specific resource
  help        Help about any command
  init        Applies templates to support Red Hat OpenShift Service on AWS
  install     Installs a resource into a cluster
  link        Link a ocm/user role from stdin
  list        List all resources of a specific type
  login       Log in to your Red Hat account
  logout      Log out
  logs        Show installation or uninstallation logs for a cluster
  revoke      Revoke role from a specific resource
  uninstall   Uninstalls a resource from a cluster
  unlink      UnLink a ocm/user role from stdin
  upgrade     Upgrade a resource
  verify      Verify resources are configured correctly for cluster install
  version     Prints the version of the tool
  whoami      Displays user account information

Flags:
      --color string   Surround certain characters with escape sequences to display them in color on the terminal. Allowed options are [auto never always] (default "auto")
      --debug          Enable debug mode.
  -h, --help           help for rosa

Use "rosa [command] --help" for more information about a command.
----
+
.. 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
----
.. Source the scripts to enable `rosa` command completion from your existing terminal. The following example sources the Bash completion scripts for `rosa` on a Linux machine:
+
[source,terminal]
----
$ source /etc/bash_completion.d/rosa
----

. Log in to your Red{nbsp}Hat account with the ROSA CLI.
+
.. Enter the following command.
+
[source,terminal]
----
$ rosa login
----
+
.. Replace `<my_offline_access_token>` with your token.
+
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: <my-offline-access-token>
----
+
The following shows the next step of the example:
+
[source,terminal]
----
I: Logged in as '<rh-rosa-user>' on 'https://api.openshift.com'
----

. Verify that your AWS account has the necessary quota to deploy a {product-title} cluster.
+
[source,terminal]
----
$ rosa verify quota [--region=<aws_region>]
----
+
For example:
+
[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 the link:https://aws.amazon.com/console/[AWS Management Console] and request a quota increase for the service that failed.
+
After the quota check succeeds, proceed to the next step.
+
. Prepare your AWS account for cluster deployment:
+
.. Run the following command to verify your Red{nbsp}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 {cluster-manager} for now.
+
[source,terminal]
----
$ rosa whoami
----
+
For example:
+
[source,terminal]
----
AWS Account ID:               000000000000
AWS Default Region:           us-east-1
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
----

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

.. 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 openshift-client
----

. After completing these steps, you are ready to set up IAM and OIDC access-based roles.