Prerequisites

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.

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.

Configuring AWS

Before you begin

Before you complete this section:

• Download and install the AWS CLI. 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.

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 or gain access to AWS IAM Credentials that meet the 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.
• Application-layer secrets in your user clusters.

Follow the steps below to create two AWS KMS keys.

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.

   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.

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

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.

• The GKE Enterprise API must be enabled for your Google Cloud project. Enabling this API entitles you to use other GKE Enterprise 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 Hub memberships
hub-sa	gkehub.connect	Permission to set up Connect between your user clusters and Hub.
node-sa	storage.objectViewer	Permission to access Container Registry.

Command Line

1. Authenticate with the Google Cloud CLI.

   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 project-id with the gcloud CLI.

   export PROJECT_ID=project-id
   
   gcloud config set project $PROJECT_ID
   

   Replace the value of project-id with your Google Cloud project.

3. Enable Google Cloud APIs.

   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.

   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.

   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: 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.

   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.

   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.

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

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

   macOS

   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.

   chmod 755 anthos-gke
   sudo mv anthos-gke /usr/local/bin
   

3. Confirm that the version is aws-1.14.1-gke.0

   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:

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

terraform version

If you do not have v0.14.3 or higher, Download and install 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:

kubectl version --client -o yaml | grep gitVersion

If you do not have 1.17 or higher, install a newer version of kubectl.

What's next

• Install a management service in a dedicated VPC with a bastion host.
• Integrating existing infrastructure in an existing VPC.