This page describes the steps that you need to complete before installing
GKE on AWS.

## Environment

To install GKE on AWS, you need an environment where you can install
and run a variety of tools. The following steps assume you are using a bash
shell on Linux or macOS. If you do not have access to a bash shell environment,
you can use [Cloud Shell](https://docs.cloud.google.com/shell).

## AWS requirements

To complete this topic, you need an AWS account with command-line access
and two AWS Key Management Service (KMS) keys in the same region as your
user clusters.

For more information on other required AWS resources, see
[Requirements](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/requirements.md.txt).

### Configuring AWS

#### Before you begin

Before you complete this section:

- Download and install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html). Confirm the installation by running `aws --version`. If the executable is not found, add the `aws` tool to your `PATH`.
- Configure your AWS IAM credentials and AWS region with [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).

### Admin user permissions

GKE on AWS requires that the creator of a management service has
certain permissions. Before you can create a management service or user clusters,
[create](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)
or gain access to AWS IAM Credentials that meet the
[Requirements](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/reference/requirements.md.txt#aws_iam_permission_requirements).

### Creating a KMS key

GKE on AWS requires two AWS KMS keys. The KMS keys encrypt:

- Data during the installation process with [envelope encryption](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#enveloping).
- Application-layer secrets in your user clusters.

Follow the steps below to create two AWS
[KMS](https://aws.amazon.com/kms/) keys.

> [!IMPORTANT]
> **Important:** Your AWS KMS keys must be in the same AWS region as your user cluster.

### Command Line

1. Create a KMS key in your AWS account.

   ```bash
   aws kms create-key
   ```

   The output includes the key's metadata.
2. In the output from the previous command, copy the key's Amazon Resource
   name (ARN) from the `Arn` field. For example, a key in the `us-west-2`
   region has the ARN
   `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`.

3. Create an alias for the key with `aws kms create-alias`. An
   alias lets you manage your AWS KMS keys by name.

   ```bash
   aws kms create-alias \
       --alias-name=alias/key-name \
       --target-key-id=key-arn
   ```
4. Repeat the preceding steps for another key.

### Console

1. Log into the [AWS console](http://console.aws.amazon.com).
2. Navigate to **KMS** and select **Customer managed keys** from the side bar.
3. Click **Create Key**.
4. Leave the default options selected.
5. Once created, select the key from the list.
6. Copy the key's ARN.
7. Repeat the preceding steps for another key.

## Google Cloud requirements

Security constraints defined by your organization might prevent you from completing the
following steps. For troubleshooting information, see
[Develop applications in a constrained Google Cloud environment](https://docs.cloud.google.com/resource-manager/docs/organization-policy/develop-apps-constrained-environment).

#### Before you begin

- Ensure your have Project Owner permissions on a Google account to enable APIs
  on the Google Cloud project where you connect your GKE on AWS
  environment. You use Owner permissions only to create the
  GKE on AWS service accounts in the following section.

- Install the [Google Cloud CLI](https://docs.cloud.google.com/sdk/install).

- The [Anthos API](https://console.cloud.google.com/apis/library/anthos.googleapis.com)
  must be enabled for your Google Cloud project. Enabling this API entitles you
  to use other Google Kubernetes Engine features with your Google Cloud project.

#### Create your GKE on AWS service accounts

In this section, you create three IAM service accounts and keys
for GKE on AWS. These service accounts are described in the
following list:

| Name | Roles | Description |
|---|---|---|
| `management-sa` | gkehub.admin | Permissions to manage GKE Fleet memberships |
| `hub-sa` | gkehub.connect | Permission to set up Connect between your user clusters and GKE Fleet. |
| `node-sa` | storage.objectViewer | Permission to access Container Registry. |

### Command Line

1. Authenticate with the Google Cloud CLI.

   ```bash
   gcloud auth login &&\
   gcloud auth application-default login
   ```

   You are prompted twice to visit `cloud.google.com` and authenticate
   with your Google account.
2. Set your Google Cloud project as an environment variable and set your default
   <var translate="no">project-id</var> with the gcloud CLI.

   ```bash
   export PROJECT_ID=project-id

   gcloud config set project $PROJECT_ID
   ```

   Replace the value of <var translate="no">project-id</var> with your Google Cloud project.
3. Enable Google Cloud APIs.

   ```bash
   gcloud services enable anthos.googleapis.com
   gcloud services enable cloudresourcemanager.googleapis.com
   gcloud services enable gkehub.googleapis.com
   gcloud services enable gkeconnect.googleapis.com
   gcloud services enable logging.googleapis.com
   gcloud services enable monitoring.googleapis.com
   gcloud services enable serviceusage.googleapis.com
   gcloud services enable stackdriver.googleapis.com
   gcloud services enable storage-api.googleapis.com
   gcloud services enable storage-component.googleapis.com
   ```
4. Create the service accounts with `gcloud` by running the following
   commands.

   ```bash
   gcloud iam service-accounts create management-sa
   gcloud iam service-accounts create hub-sa
   gcloud iam service-accounts create node-sa
   ```
5. Download the keys for each service account with `gcloud` by running the
   following commands.

   ```bash
   gcloud iam service-accounts keys create management-key.json \
        --iam-account management-sa@$PROJECT_ID.iam.gserviceaccount.com
   gcloud iam service-accounts keys create hub-key.json \
        --iam-account hub-sa@$PROJECT_ID.iam.gserviceaccount.com
   gcloud iam service-accounts keys create node-key.json \
        --iam-account node-sa@$PROJECT_ID.iam.gserviceaccount.com
   ```

   > [!IMPORTANT]
   > **Important:** Keys allow a user or application to authenticate as the service account. Protect your service account keys after downloading them.

6. Grant roles to the management service account.

   ```bash
   gcloud projects add-iam-policy-binding \
       $PROJECT_ID \
       --member serviceAccount:management-sa@$PROJECT_ID.iam.gserviceaccount.com \
       --role roles/gkehub.admin
   ```
7. Grant roles to the hub service account.

   ```bash
   gcloud projects add-iam-policy-binding \
       $PROJECT_ID \
       --member serviceAccount:hub-sa@$PROJECT_ID.iam.gserviceaccount.com \
       --role roles/gkehub.connect
   ```
8. Grant roles to the node service account.

   ```bash
   gcloud projects add-iam-policy-binding \
         $PROJECT_ID \
         --member serviceAccount:node-sa@$PROJECT_ID.iam.gserviceaccount.com \
         --role roles/storage.objectViewer
   ```

### Console

1. Open the [Google Cloud console API Library page](https://console.cloud.google.com/apis/library).
2. Select your preferred project from the dropdown at the top of the screen.
3. Find and enable the following APIs.

   - Anthos
   - Cloud Resource Manager
   - Cloud Storage
   - Cloud Logging
   - Google Cloud Storage JSON API
   - GKE Hub
   - GKE Connect API
   - Service Usage
   - Stackdriver
   - Stackdriver Monitoring
4. Open the [**Service Accounts**](https://console.cloud.google.com/iam-admin/serviceaccounts)
   page.


5. Next, create a service account and assign roles for the `management-sa`
   service account.

   1. Click **Create service account**.
   2. **Name** the account management-sa and click **Create** . The **Grant this service account access to project** screen appears.
   3. Add the GKE HUB Admin roles.
   4. Click **Continue** . The **Grant users access to this service account** screen appears.
   5. Click **Done** . The **Service accounts for project** screen appears.
   6. Find the row containing the **Email** of your service account, `management-sa@project_id.iam.gserviceaccount.com`.
   7. Click the action menu for the service account and select **Manage keys**.
   8. Click the **Add key** drop-down menu.
   9. Click **Create new key**.
   10. Select **JSON** as your key type and click **Create**. Your browser downloads the service account key.
   11. Rename the file `management-key.json`.
6. Next, create a service account and assign roles for the `hub-sa`
   service account.

   1. Click **Create service account**.
   2. **Name** the account hub-sa and click **Create** . The **Grant this service account access to project** screen appears.
   3. Add the GKE Hub Connection Agent role.
   4. Click **Continue** . The **Grant users access to this service account** screen appears.
   5. Click **Done** . The **Service accounts for project** screen appears.
   6. Find the row containing the **Email** of your service account, `hub-sa@project_id.iam.gserviceaccount.com`.
   7. Click the action menu for the service account and select **Manage keys**.
   8. Click the **Add key** drop-down menu.
   9. Click **Create new key**.
   10. Select **JSON** as your key type and click **Create**. Your browser downloads the service account key.
   11. Rename the file `hub-key.json`.
7. Next, create a service account and assign roles for the `node-sa`
   service account.

   1. Click **Create service account**.
   2. **Name** the account node-sa and click **Create** . The **Grant this service account access to project** screen appears.
   3. Add the Storage Object Viewer role.
   4. Click **Done** . The **Service accounts for project** screen appears.
   5. Find the row containing the **Email** of your service account, `node-sa@project_id.iam.gserviceaccount.com`.
   6. Click the action menu for the service account and select **Manage keys**.
   7. Click the **Add key** drop-down menu.
   8. Click **Create new key**.
   9. Select **JSON** as your key type and click **Create**. Your browser downloads the service account key.
   10. Rename the file `node-key.json`.

## anthos-gke command-line tool

`anthos-gke` is a command-line tool for GKE on AWS. You use
`anthos-gke` to create configuration and
[Install a management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt). The latest version of
`anthos-gke` is aws-1.14.1-gke.0.

The `anthos-gke` command-line tool only supports Linux and macOS.

1. Download the binary from Cloud Storage.

   ### Linux

   ```bash
   gcloud storage cp gs://gke-multi-cloud-release/aws/aws-1.14.1-gke.0/bin/linux/amd64/anthos-gke .
   ```

   ### macOS

   ```bash
   gcloud storage cp gs://gke-multi-cloud-release/aws/aws-1.14.1-gke.0/bin/darwin/amd64/anthos-gke .
   ```
2. Update the permissions of `anthos-gke` and copy it to `/usr/local/bin`.

   ```bash
   chmod 755 anthos-gke
   sudo mv anthos-gke /usr/local/bin
   ```
3. Confirm that the version is `aws-1.14.1-gke.0`

   ```bash
   anthos-gke version
   ```

### Permissions for anthos-gke command-line tool

To use the `anthos-gke` command-line tool the user executing the command must
have the ServiceUsageViewer and StorageAdmin roles. To add the roles to your
IAM principal, run these commands:

```bash
gcloud projects add-iam-policy-binding PROJECT_NAME \
    --member user:USER_NAME \
    --role roles/serviceusage.serviceUsageViewer
gcloud projects add-iam-policy-binding PROJECT_NAME \
    --member user:USER_NAME \
    --role roles/storage.admin
```

Replace the following:

- `PROJECT_NAME`: your Google Cloud project
- `USER_NAME`: the user name that executes the `anthos-gke` command-line tool. If you are using a service account, use `serviceAccount:SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com`

## Terraform

The `anthos-gke` tool generates
[Terraform](https://www.terraform.io/) configuration files and calls
the `terraform` command line tool.

GKE on AWS requires a version of Terraform higher than
v0.14.3. You can check your version of Terraform with the
following command:

```bash
terraform version
```

If you do not have v0.14.3 or higher,
[Download and install](https://learn.hashicorp.com/terraform/getting-started/install.html)
Terraform before creating a management service.

### Upgrading Terraform

To upgrade Terraform after installing GKE on AWS, you must upgrade
your Terraform binary through *each* minor version in order.

For example, if you want to upgrade Terraform from v0.12.x to v0.14.x, you must
install v0.13.x temporarily. After installing a v0.13.x, run `anthos-gke aws
management init` and `anthos-gke aws management apply`. GKE on AWS
updates your configuration. You can then upgrade to v0.14.x.

## Kubernetes

GKE on AWS requires `kubectl` version 1.17 or
higher. You can check your version of `kubectl` by running:

```bash
kubectl version --client -o yaml | grep gitVersion
```

If you do not have 1.17 or higher,
[install a newer version of `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/).

## What's next

- [Install a management service](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/installing-management.md.txt) in a dedicated VPC with a bastion host.
- [Integrating existing infrastructure](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/aws/previous-generation/how-to/integrating-existing-infrastructure.md.txt) in an existing VPC.