Create fleets to simplify multi-cluster management

This page provides an overview of how fleet creation works, with details for different cluster types. For more information about how to manually register clusters to your fleet and the prerequisites for manual registration, see our detailed fleet creation guides.

You can create a fleet in one of the following ways:

• By registering a cluster: When you register a cluster of any type in a project that doesn't already have a fleet, a new fleet is created and the project becomes a fleet host project. At most, a project can have a single fleet. Depending on the cluster type and where it lives, registration can happen automatically at cluster creation time with registration details specified in the cluster configuration, or you might need to manually add the cluster to your fleet.
• By creating a named fleet: You can create an empty fleet before you register clusters to it.
• By upgrading to Google Kubernetes Engine (GKE) Enterprise edition: When you enable GKE Enterprise from the Google Cloud console, you can choose to create a fleet for your project, and select Google Cloud clusters in your project to register to that fleet.

Each fleet has a name that is displayed in the Google Cloud console. By default, this is the project ID of the fleet host project with fleet appended. If you want a more descriptive name for your fleet, you can specify it when creating a fleet.

About fleet membership

Once you register a cluster to a fleet, it becomes a fleet member. Because fleets can include clusters from multiple projects and environments, you must ensure that each cluster you add to your fleet has a unique name. This is sometimes referred to in commands and documentation as the cluster's fleet membership name. Typically, a cluster's fleet membership name is its regular cluster name, but you may need to create a new name at registration time (for example by appending or prepending a qualifier to the original cluster name) if another cluster with that name already exists in the fleet. If you attempt to register a cluster with an existing name to your fleet, registration will fail.

Fleet membership location

Each fleet cluster's membership is managed by the Fleet service. The location of this service can be global or regional, depending on how the cluster is registered to the fleet.

• GKE clusters on Google Cloud registered by using the Google Cloud CLI have their membership managed by a Fleet service instance that runs in the same region as the cluster itself. This provides optimal latency for building your own high availability services, including using regional instances of some services such as the Connect gateway. Regional membership management also supports situations where, for example, you have data that cannot leave a specific region for regulatory reasons. You cannot choose to have a cluster managed from a different region.

• GKE clusters on Google Cloud registered by using Config Connector can be managed by either a global or regional Fleet service.

• All other fleet members are managed using a global Fleet service.

You cannot change a cluster's membership location while it is still a fleet member. If you have a GKE cluster with global fleet membership and want to change it to be managed from its region, you must unregister the cluster and then register it again to the same fleet using gcloud or Config Connector.

To check a cluster's membership location (for example, to use as a command parameter or if you are considering switching a cluster to regional membership), do one of the following:

• List all your fleet members. Each cluster's membership location is shown in the LOCATION column of the output.

   gcloud container fleet memberships list \
     --project=PROJECT_ID
  

• Run the following command to describe your cluster's membership, including its membership location. Replace MEMBERSHIP_NAME with your cluster's membership name.

   gcloud container fleet memberships describe MEMBERSHIP_NAME \
     --project=PROJECT_ID
  

Team scopes

A fleet member cluster can be associated with one or more team scopes within its fleet. Team scopes are an enterprise fleet-level construct for associating subsets of fleet clusters with specific application teams, and can be used to enable a range of team-based features, including access control, team-scoped observability, and sequencing cluster upgrade rollouts.

GKE clusters on Google Cloud

GKE clusters on Google Cloud must be explicitly registered to add them to a fleet. To register existing clusters, you can choose between quick registration from the Clusters page in the Google Cloud console, registration from the command line with the gcloud CLI, or declarative registration using Terraform or Config Connector. You can also register new clusters during cluster creation using the Google Cloud console, gcloud CLI, or Terraform. If you have enabled GKE Enterprise, this lets you create clusters with some fleet-level settings and features already configured for you. Find out more about these options in Register a cluster on Google Cloud to your fleet.

Clusters on Google Cloud can be registered to a fleet in their current project or (with some extra permissions) to a fleet in a different project.

Clusters outside Google Cloud

If you have enabled GKE Enterprise, you can add clusters outside Google Cloud to your fleet and view and manage your clusters across different environments together. GKE clusters outside Google Cloud are mostly registered to your fleet automatically at cluster creation time, as described in the rest of this section. If you want to add third-party Kubernetes clusters to your fleet, you must register them manually.

Registering clusters outside Google Cloud installs the Connect Agent on the cluster to handle communication between the cluster and your Google Cloud project. You can read more about how the Connect Agent works in the Connect Agent overview.

Google Distributed Cloud (on-premises)

On-premises GKE clusters on VMware and on bare metal are automatically registered to your chosen fleet at cluster creation time, with your fleet host project and other registration details specified in the relevant cluster configuration file. If you are using Google Distributed Cloud on VMware, note that from version 1.13 onwards, both admin clusters and user clusters must be registered. For versions prior to 1.13, you can optionally add registration details to admin cluster configurations if you want to manage them as part of your fleet. You can register unregistered admin clusters by updating their cluster configuration file and using gkectl to update the cluster. On-premises GKE clusters cannot be unregistered or (with the exception of unregistered admin clusters) manually registered.

GKE on other public clouds

GKE clusters on AWS and Azure created using the GKE Multi-Cloud API are automatically registered to your chosen fleet at cluster creation time, with your fleet host project specified when you run the relevant gcloud cluster create command. Because clusters created using GKE Multi-Cloud already have a project associated with them (the project where the API is enabled), you need to do some additional setup at cluster creation if you want to register them to a fleet in a different project. Clusters created with the GKE Multi-Cloud API cannot be unregistered or manually registered.

Third-party Kubernetes clusters (attached clusters)

If you have existing third-party Kubernetes clusters (such as EKS, AKS, or on-premises distributions) that you want to manage as fleet members, you can register these to your project fleet along with any GKE clusters. You can attach any conformant Kubernetes cluster that includes x86 nodes to your fleet using the GKE Multi-Cloud API. These include Amazon EKS, Azure AKS, and other CNCF-conformant clusters that meet our requirements. Any third-party clusters you register will incur a per-vCPU charge as part of your GKE Enterprise pricing.

To register an attached cluster, see the following guides:

• Attach your EKS cluster.
• Attach your AKS cluster.
• For all other cluster types, follow the instructions to attach CNCF-conformant clusters, paying attention to the cluster prerequisites.

Move a cluster to a different fleet

Moving registered clusters between fleets (unregistering then reregistering) is not currently recommended, as it can result in unexpected or unwanted behavior: for example, your workloads' fleet Workload Identity will change, potentially resulting in blocked requests and outages. The recommended approach is to create a new cluster in the fleet in which you want your workloads to reside, then move your workloads from your old cluster to the new cluster.

(Optional) Create an empty fleet

By default, a new fleet is created in your fleet host project the first time you register a cluster in that project, or if you enable GKE Enterprise from the Google Cloud console. If you want to create a new named fleet before you register any clusters (for example, to set up scopes for team access), run the following command:

gcloud container fleet create --display-name=NAME [--project=FLEET_HOST_PROJECT_ID]

If you don't specify a display-name, the new fleet has a default display name based on its fleet host project name.

View your fleets

If your organization has multiple fleets, you can view and navigate between them in the Google Cloud console. To view fleets across projects within your organization you need the roles/gkehub.viewer role at the minimum. To learn more, see the Kubernetes Engine roles and how to grant them.

What's next?

• Before you begin for all cluster types.

• Register a GKE cluster on Google Cloud:

  • Prerequisites for clusters on Google Cloud
  • Register a cluster on Google Cloud to your fleet