Attach your EKS cluster

Overview

To attach a cluster means to connect it to the Google Cloud by registering it with Google Cloud Fleet management and installing the Anthos attached clusters software on it.

To attach an EKS cluster, follow the steps below.

Prerequisites

Ensure that your cluster meets the cluster requirements.

When attaching your cluster, you must specify:

The administrative region is a Google Cloud region to administer your attached cluster from. You can choose any supported region, but best practice is to choose the region geographically closest to your cluster. No user data is stored in the administrative region.

The platform version is the version of Anthos attached clusters to be installed on your cluster. You can list all supported versions by running the following command:

gcloud container attached get-server-config  \
  --location=GOOGLE_CLOUD_REGION

Replace GOOGLE_CLOUD_REGION with the name of the Google Cloud location to administer your cluster from.

Platform version numbering

These documents refer to the Anthos attached clusters version as the platform version, to distinguish it from the Kubernetes version. Anthos attached clusters uses the same version numbering convention as GKE - for example, 1.21.5-gke.1. When attaching or updating your cluster, you must choose a platform version whose minor version is the same as or one level below the Kubernetes version of your cluster. For example, you can attach a cluster running Kubernetes v1.22.* with Anthos attached clusters platform version 1.21.* or 1.22.*.

This lets you upgrade your cluster to the next minor version before upgrading Anthos attached clusters.

Attach an EKS cluster

To attach your EKS cluster to Google Cloud Fleet management:

  1. Ensure that your kubeconfig file has an entry for the cluster you'd like to attach:

    aws eks update-kubeconfig --region AWS_REGION \
      --name CLUSTER_NAME
    
  2. Retrieve the OIDC issuer URL with the following command:

    aws eks describe-cluster \
      --region AWS_REGION \
      --name CLUSTER_NAME \
      --query "cluster.identity.oidc.issuer" \
      --output text
    

    The output of this command will be the URL of your OIDC issuer. Save this value for use later.

  3. Run this command to extract your cluster's kubeconfig context and store it in the KUBECONFIG_CONTEXT environment variable:

    KUBECONFIG_CONTEXT=$(kubectl config current-context)
    
  4. Run the following command to register the cluster:

    gcloud container attached clusters register CLUSTER_NAME \
      --location=GOOGLE_CLOUD_REGION \
      --fleet-project=PROJECT_NUMBER \
      --platform-version=PLATFORM_VERSION \
      --distribution=eks \
      --issuer-url=ISSUER_URL \
      --context=KUBECONFIG_CONTEXT \
      --admin-users=ADMIN_USERS \
      --kubeconfig=KUBECONFIG_PATH \
      --description="DESCRIPTION"
    

    Replace:

  • AWS_REGION: the AWS region where your EKS cluster is located
  • CLUSTER_NAME: the name of your cluster
  • GOOGLE_CLOUD_REGION: the Google Cloud region to administer your cluster
  • PLATFORM_VERSION: the Anthos attached clusters version to use for the cluster
  • PROJECT_NUMBER: the Fleet host project where the cluster will be registered
  • ISSUER_URL: the issuer URL retrieved earlier
  • KUBECONFIG_CONTEXT: context in the kubeconfig for accessing the EKS cluster, as extracted earlier
  • DESCRIPTION: a description of the cluster
  • ADMIN_USERS: a comma-separated list of email addresses of users to be granted administrative privileges on your cluster
  • KUBECONFIG_PATH: path to your kubeconfig

Authorize Cloud Logging / Cloud Monitoring

In order for Anthos attached clusters to create and upload system logs and metrics to Google Cloud's operations suite, it must be authorized.

To authorize the Kubernetes workload identity gke-system/gke-telemetry-agent to write logs to Google Cloud Logging, and metrics to Google Cloud Monitoring, run this command:

gcloud projects add-iam-policy-binding GOOGLE_PROJECT_ID \
  --member="serviceAccount:GOOGLE_PROJECT_ID.svc.id.goog[gke-system/gke-telemetry-agent]" \
  --role=roles/gkemulticloud.telemetryWriter

Replace GOOGLE_PROJECT_ID with the cluster's Google Cloud project ID.

This IAM binding grants access for all clusters in the Google Cloud project project to upload logs and metrics. You only need to run it after creating your first cluster for the project.