A new version of Anthos clusters on AWS (GKE on AWS) was released on October 29. See the release notes for more information.

Prerequisites

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

Environment

To install Anthos clusters 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

Anthos clusters 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

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

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

Some of the steps in this document might not work correctly if your organization applies constraints to your Google Cloud environment. In that case, you might not be able to complete tasks like creating public IP addresses or service account keys. If you make a request that returns an error about constraints, see how to 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 Anthos clusters on AWS environment. You use Owner permissions only to create the Anthos clusters on AWS service accounts in the following section.

  • 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 your Cloud project.

Create your Anthos clusters on AWS service accounts

In this section, you create three IAM service accounts and keys for Anthos clusters 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 user clusters 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. 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 Anthos clusters on AWS. You use anthos-gke to create configuration that installs a management service. The latest version of anthos-gke is aws-1.9.1-gke.0.

  1. Download the binary from Cloud Storage.

    Linux

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

    macOS

    gsutil cp gs://gke-multi-cloud-release/aws/aws-1.9.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.9.1-gke.0

    anthos-gke version
    

Terraform

The anthos-gke tool generates Terraform configuration files and calls the terraform command line tool.

Anthos clusters 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 Anthos clusters 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. Anthos clusters on AWS updates your configuration. You can then upgrade to v0.14.x.

Kubernetes

Anthos clusters 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