A new version of GKE on AWS was released on November 2. See the release notes for more information.

Prerequisites

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

Environment

The following instructions assume you are using a bash shell on Linux or macOS. If you do not have access to a regular 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 GKE on AWS cluster.

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 Key Management Service (KMS) keys. The KMS keys encrypt:

  • Data during the installation process with envelope encryption.
  • Application-layer secrets in your GKE on AWS clusters.

Follow the steps below to create two AWS KMS keys.

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

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

  • Install the Cloud SDK.

  • The Anthos API must be enabled for your Google Cloud project. Enabling this API entitles you to use other Anthos features with the 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,
serviceusage.serviceUsageViewer
Permissions to manage Hub memberships and verify Google Cloud APIs are enabled.
hub-sa gkehub.connect Permission to set up Connect between your GKE on AWS cluster and Hub.
node-sa storage.objectViewer Permission to access Container Registry.

Command Line

  1. Authenticate with the gcloud command-line tool.

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

    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
    
  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
    gcloud projects add-iam-policy-binding \
        $PROJECT_ID \
        --member serviceAccount:management-sa@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/serviceusage.serviceUsageViewer
    
  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 and Service Usage Viewer 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. Click the Email of your service account, management-sa@project_id.iam.gserviceaccount.com.
    7. Click ADD KEY -> Create New Key. The Create private key for management-sa dialog appears.
    8. Select JSON as your key type and click Create. Your browser downloads the service account key.
    9. 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. Click the Email of your service account, hub-sa@project_id.iam.gserviceaccount.com.
    7. Click ADD KEY -> Create New Key. The Create private key for hub-sa dialog appears.
    8. Select JSON as your key type and click Create. Your browser downloads the service account key.
    9. 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. Click the Email of your service account, node-sa@project_id.iam.gserviceaccount.com.
    6. Click ADD KEY -> Create New Key. The Create private key for node-sa dialog appears.
    7. Select JSON as your key type and click Create. Your browser downloads the service account key.
    8. 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 that installs a management service. The latest version of anthos-gke is aws-1.5.1-gke.1.

  1. Download the binary from Cloud Storage.

    Linux

    gsutil cp gs://gke-multi-cloud-release/aws/aws-1.5.1-gke.1/bin/linux/amd64/anthos-gke .
    

    macOS

    gsutil cp gs://gke-multi-cloud-release/aws/aws-1.5.1-gke.1/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.5.1-gke.1

    anthos-gke version
    

Terraform

The anthos-gke tool generates Terraform configuration files. The configuration is declarative, can be version controlled, and is auditable.

GKE on AWS requires Terraform v0.12.28 or higher. You can check your version of Terraform with the following command:

terraform version

If you do not have v0.12.28 or higher, Download and install Terraform before creating a management service.

Kubernetes

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

kubectl version --client -o yaml | grep gitVersion

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

What's next