Set up Anthos on Google Cloud

This page shows you how to set up Anthos on Google Cloud with GKE clusters.

Before you start

Decide how you would like to pay for Anthos on Google Cloud:

• You can choose to enable the Anthos API to have access to all Anthos platform features for a single per-vCPU charge. This option also lets you add clusters outside Google Cloud to your fleet to create a hybrid or multi-cloud deployment.

• You can choose to not enable the entire Anthos platform. This option lets you create fleets of GKE clusters and pay only for the Anthos features you use with them, in addition to your GKE charges.

You can see a complete list of supported Anthos features for each option in Deployment options, and learn more about Anthos pricing in our Pricing guide.

If you decide to enable the entire Anthos platform, do the following before starting to register clusters:

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

4. Enable the Anthos API.

   Enable the API

5. Install and initialize the Google Cloud CLI.

6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

7. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

8. Enable the Anthos API.

   Enable the API

9. Install and initialize the Google Cloud CLI.

You might need to enable additional APIs for your Google Cloud project to enable some Anthos features. For details, see the relevant installation guide.

Cluster requirements

Follow the instructions in the GKE documentation to create clusters for use with Anthos.

Anthos on Google Cloud supports the use of both release channels and static versions. However, we recommend the use of release channels whenever possible, as they provide additional benefits such as automated updates to GKE clusters.

If you want to use Anthos Service Mesh, be aware that this feature has specific cluster requirements for installation. For details, see the following:

• In-cluster Anthos Service Mesh requirements
• Managed Anthos Service Mesh requirements

Register clusters to your fleet

You must register all clusters that you want to use with Anthos to your project's fleet. A fleet provides a way to logically group and normalize Kubernetes clusters, making administration of infrastructure easier. Fleet clusters can be browsed and managed together in the console, and many Anthos and Google Cloud components use fleet concepts such as identity sameness and namespace sameness to simplify working with multiple clusters. You can find out much more about fleets and the functionality that they enable in our Fleet management guide.

Read the prerequisites before registering your cluster to ensure that you have the relevant permissions and enabled APIs to register a cluster. You can find out more about the different registration options for GKE clusters in Registering a cluster.

Note: If you have enabled the entire Anthos platform by enabling the Anthos API, any clusters that are registered to the fleet will incur Anthos charges. If you have not enabled the Anthos API, no additional charges are incurred for registering GKE clusters and you can choose to pay separately for fleet-enabled features. See Deployment options for more details.

Console

The simplest and quickest way to register a GKE cluster is to register it from the Anthos clusters page in the console. This option is available only if you have enabled the Anthos API.

To register a cluster:

1. (Optional) If you want your registered cluster to use fleet Workload Identity (recommended), ensure that GKE Workload Identity is enabled on the cluster. Clusters with GKE Workload Identity automatically have fleet Workload Identity enabled when you register them from the console.

2. In the console, go to the Anthos Clusters page. This page shows all your registered clusters.

   Go to the Anthos Clusters page

3. Click Register existing cluster.

4. Click Register next to the unregistered cluster that you want to add to your fleet.

Terraform

You can register GKE clusters with Terraform using the google-beta provider. You can find a complete reference for the gke_hub_membership resource used to configure registration in the terraform registry.

Register a GKE cluster

To register the cluster, use the following blocks in your configuration.

1. Specify the google-beta provider as a required provider, as in the following snippet. The version should be above 3.62.0.

   terraform {
     required_providers {
       google-beta = {
         source = "hashicorp/google-beta"
         version = "3.67.0"
       }
     }
   }
   

   This provider is required if you want to use gke_hub_membership.

2. Set the following default values for the provider:

   provider "google-beta" {
     credentials = file("SERVICE_ACCOUNT_KEY_PATH")
     project = "PROJECT_ID"
   }
   

   Replace the following:

   • SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace. This service account key enables Terraform to access your Google Cloud account.
   • PROJECT_ID: the default project that you choose to provision your Terraform resources.

3. Create a GKE cluster (optional)

   If you want to register an existing cluster, skip this step.

   resource "google_container_cluster" "TF_CLUSTER_RESOURCE_NAME" {
     provider = google-beta
     name               = "CLUSTER_NAME"
     location           = "ZONE"
     initial_node_count = 1
   }
   

   Replace the following:

   • TF_CLUSTER_RESOURCE_NAME: the name that you choose to uniquely identify the Terraform google_container_cluster resource created by this block.
   • CLUSTER_NAME: the name that you choose to uniquely represent the cluster you created.
   • ZONE: the default zone that you choose to provision your GKE cluster resource. For example: us-central1-a.

4. Register a membership for the GKE cluster.

   resource "google_gke_hub_membership" "TF_MEMBERSHIP_RESOURCE_NAME" {
     provider = google-beta
     project = "FLEET_PROJECT_ID"
     membership_id = "MEMBERSHIP_NAME"
     endpoint {
       gke_cluster {
        resource_link = "//container.googleapis.com/CLUSTER_RESOURCE_NAME"
       }
     }
   }
   

   Replace the following:

   • TF_MEMBERSHIP_RESOURCE_NAME: the name that you choose to uniquely identify the Terraform google_gke_hub_membership resource created by this block.
   • FLEET_PROJECT_ID: If this is not set, the cluster's membership will be created in the default project you specified earlier (PROJECT_ID). Set this field if you want to register the GKE cluster to a fleet in a different project.
   • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster in the fleet.
   • CLUSTER_RESOURCE_NAME: the Google Cloud resource name for the GKE cluster. For example: projects/my-project/zones/us-west1-a/clusters/my-cluster. If the cluster is provisioned with Terraform, this is ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

Enable fleet Workload Identity on a registered GKE cluster

Enabling fleet Workload Identity uses the same configuration as registering a cluster, with the following additional steps.

1. Enable GKE Workload Identity by adding the following in the relevant google_container_cluster resource block. You need to do this for both new and existing clusters.

   workload_identity_config {
     identity_namespace = "PROJECT_ID.svc.id.goog"
   }
   

   Replace the following:

   • PROJECT_ID: the default project that you choose to provision your Terraform resources.

2. Enable Fleet Workload Identity by adding the following in the relevant google_gke_hub_membership resource block.

   authority {
     issuer = "https://container.googleapis.com/v1/CLUSTER_RESOURCE_NAME"
   }
   

   Replace the following:

   • CLUSTER_RESOURCE_NAME: the Google Cloud resource for the GKE cluster. For example: projects/my-project/zones/us-west1-a/clusters/my-cluster. If the cluster is provisioned with Terraform, this is ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

Config Connector

If you have the Config Connector add-on installed, you can use Config Connector to register GKE clusters. Ensure that you have a version of Config Connector above 1.47.0.

You can find a complete reference for the GKEHubMembership resource in the Config Connector Reference.

Register a GKE cluster

To register the cluster, first specify where you want to create your resources, following the instructions in the Config Connector guide. Then create a YAML file to register and (optionally) create a cluster, as follows:

Create and register a GKE cluster

1. Create a GKE cluster, as in the following simple example:

   apiVersion: container.cnrm.cloud.google.com/v1beta1
   kind: ContainerCluster
   metadata:
     name: CLUSTER_NAME
   spec:
     location: LOCATION
     initialNodeCount: 1
   

   Replace the following:

   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created with Config Connector.
   • LOCATION: the zone or region that you chose to provision your GKE cluster resource. For example: us-central1-a.

   For a complete list of options when creating a GKE cluster with Config Connector, see the Config Connector documentation.

2. Register a membership for the GKE cluster.

   apiVersion: gkehub.cnrm.cloud.google.com/v1beta1
   kind: GKEHubMembership
   metadata:
     name: MEMBERSHIP_NAME
   spec:
     location: global
     endpoint:
       gkeCluster:
         resourceRef:
           name: CLUSTER_NAME
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name that you chose to uniquely represent the cluster being registered to the fleet.
   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created with Config Connector.

Register the cluster in a different project

Add the following to the metadata field of the GKEHubMembership resource to register a cluster to a fleet in another project.

   metadata:
     annotations:
       cnrm.cloud.google.com/project-id: FLEET_PROJECT_ID

Replace the following:

• FLEET_PROJECT_ID: the fleet host project you chose to register the GKE cluster.

Register an existing cluster

Use the following configuration if you want to register any existing cluster, regardless of how it was created. In this case you need to specify the full resource name of the cluster so that Config Connector can find it. Replace the resourceRef field of the GKEHubMembership resource with:

   resourceRef:
     external: //container.googleapis.com/CLUSTER_RESOURCE_NAME

Replace the following:

• CLUSTER_RESOURCE_NAME: the Google Cloud resource name for the GKE cluster. For example: projects/my-project/zones/us-west1-a/clusters/my-cluster.

If the cluster was created with Config Connector you don't need to specify the fully qualified cluster name.

Enable fleet Workload Identity on a registered GKE cluster

Enabling fleet Workload Identity uses the same configuration as registering a cluster, with the following additional steps.

1. Enable GKE Workload Identity by adding the following in the spec field of ContainerCluster resource. You need to do this for both new and existing clusters.

   spec:
     workloadIdentityConfig:
       identityNamespace: PROJECT_ID.svc.id.goog
   

   Replace the following:

   • PROJECT_ID: the default project you chose through namespace annotation to create your GKE cluster resource.

2. Enable fleet Workload Identity by adding the following in the spec field of GKEHubMembership resource block.

   spec:
     authority:
       issuer: https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME
   }
   

   Replace the following:

   • PROJECT_ID: the default project you chose through namespace annotation to create your GKE cluster resource.
   • LOCATION: the zone or region that you chose to provision your GKE cluster resource. For example: us-central1-a.
   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created.

gcloud

Registering a cluster with the Google Cloud CLI requires the Google Cloud CLI version 281.0.0 or higher

Registering the cluster from the command line installs the Connect Agent on the cluster, which can either use fleet Workload Identity or a Google Cloud service account for authentication.

Registering a GKE cluster using Workload Identity (recommended)

1. Ensure that the cluster has GKE Workload Identity enabled, following the instructions in our prerequisites.

2. Run either of the following commands to register the cluster:

   gcloud container fleet memberships register MEMBERSHIP_NAME \
    --gke-uri=GKE_URI \
    --enable-workload-identity
   

   or

   gcloud container fleet memberships register MEMBERSHIP_NAME \
    --gke-cluster=GKE_CLUSTER \
    --enable-workload-identity
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered to the fleet.
   • GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
   • GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Registering a GKE cluster using a Service Account

1. Ensure that you have created a service account for use by the Connect Agent, as described in our prerequisites.

2. Run either of the following commands:

   gcloud container fleet memberships register MEMBERSHIP_NAME \
    --gke-uri=GKE_URI \
    --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH
   

   or

   gcloud container fleet memberships register MEMBERSHIP_NAME \
    --gke-cluster=GKE_CLUSTER \
    --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered to the fleet.
   • SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace.
   • GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
   • GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Using the Google Cloud CLI provides you with some more advanced cluster registration options that are not available in the console, including downloading and applying the Connect Agent manifest yourself. To find out more about these options, see advanced registration options in the Connect documentation.

Enable Anthos features

After you set up your fleet, use the following guides to enable additional Anthos features for your applications. For complete documentation sets for all Anthos components, including tutorials, reference material, and more, see Anthos components.

If you have enabled the Anthos API, you can enable some features at fleet level for clusters in your fleet by using the Anthos Features page, although features require further configuration to actually use them: for example, specifying and authenticating to your chosen config source repo with Config Sync for Anthos Config Management. Other features must be set up on clusters following their installation guides. You can learn more in Manage fleet-level features.

• Anthos Service Mesh:
  • Install Anthos Service Mesh with the in-cluster control plane
  • Configure managed Anthos Service Mesh
  • Set up a multi-cluster mesh
• Anthos Config Management:
  • Enable Anthos Config Management
  • Set up Config Sync
  • Install Config Connector
  • Install Hierarchy Controller (preview)
  • Install Policy Controller
• Multi Cluster Ingress:
  • Set up Multi Cluster Ingress
• Install Cloud Run for Anthos

What's next?

• If you also need to set up Anthos clusters on-premises as part of a hybrid deployment, see the on-premises setup guide.
• If you also need to set up Anthos clusters on another public cloud (such as AWS) as part of a multi-cloud deployment, see the public clouds setup guide.
• Quickstart: Attach third-party Kubernetes clusters to Google Cloud, see Setting up attached clusters.