Creating a regional cluster

Standard

---

This document shows how to create a Standard regional cluster to increase availability of the cluster's control plane and workloads during cluster upgrades, automated maintenance, or a zonal disruption.

GKE Autopilot clusters are always regional.

Overview

When you create a regional cluster instead of a zonal cluster, the cluster's control plane is replicated across multiple zones in a given region. For node pools in a regional cluster, you can manually specify the zone(s) in which to run the node pools or you can use the default configuration, which replicates each node pool across three zones of the control plane's region. All zones must be within the same region as the cluster's control plane.

Regional clusters replicate resources across multiple zones and consume additional quotas.

To learn about the different cluster availability types, see About cluster configuration choices.

The instructions in the following sections show you how to:

• Create a regional cluster with a single-zone node pool.
• Create a regional cluster with a multi-zone node pool.

After you create a regional cluster, you cannot convert it to a zonal cluster.

The minimum information that you need to specify when creating a new regional cluster is a name, project (usually the current project), and region (usually the default location for command line tools), using the default settings for all other values. However, there are more possible configuration settings, only some of which are described in this guide and some of which can't be changed after cluster creation. Ensure that you understand which settings can't be changed after cluster creation, and that you choose the right setting when creating a cluster if you don't want to have to create it again.

You can see an overview of cluster configuration options in About cluster configuration choices, and a complete list of possible options in the gcloud container clusters create and Terraform google_container_cluster reference guides.

Before you begin

Before you start, make sure you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
  Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

• Ensure you have the correct permissions to create clusters. At minimum, you should be a Kubernetes Engine Cluster Admin.
• If you want to register your new cluster to a fleet, ensure that you have the required APIs and permissions.

Caution: If you have the organization policy constraint constraints/compute.vmExternalIpAccess configured to Deny All or to restrict external IPs to specific VM instances at the organization, folder, or project level where you are trying to create a public GKE cluster, then your cluster creation operations will fail. See the troubleshooting information for details.

Create a regional cluster with a single-zone node pool

The following instructions show you how to create a regional cluster with a node pool operating in a single zone within the region. The cluster's control plane is replicated across multiple zones in the specified region, but the nodes are located in the single zone, and are not replicated to other zones.

You can use the gcloud CLI, the Google Cloud console, or Terraform to create the cluster.

If you're developing GKE applications with Cloud Code for VS Code, try creating clusters with Cloud Code.

gcloud

To create a regional cluster with the gcloud CLI, use one of the following commands and replace the following variables:

• CLUSTER_NAME: the name of your new regional cluster.
• COMPUTE_REGION: the region for your cluster, such as us-central1.
• COMPUTE_ZONE: the zone for your node pool, such as us-central1-a. The zone must be in the same region as the cluster control plane.
• CHANNEL: the type of release channel, which can be one of rapid, regular, stable, or None. By default, the cluster is enrolled in the regular release channel unless at least one of the following flags is specified: --cluster-version, --release-channel, --no-enable-autoupgrade, and --no-enable-autorepair.
• VERSION: the version you want to specify for your cluster.

When you create a cluster, you can optionally use the --service-account flag to specify a different IAM service account that nodes in the cluster's first node pool use instead of the Compute Engine default service account. We recommend that you create and use a minimally-privileged service account.

Caution: You can't modify the service account on an existing node pool after creation.

Using a specific release channel:

To create a new cluster using a specific release channel, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --node-locations COMPUTE_ZONE \
    --release-channel CHANNEL

Using a specific version:

To create a new cluster using a specific cluster version, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --node-locations COMPUTE_ZONE \
    --cluster-version VERSION

Note: If you specify a cluster version, the cluster uses that specific version and is enrolled in the most mature release channel where that version is available.

Using the default version for clusters not enrolled in a release channel:

To create a new cluster using the default version for clusters not enrolled in a release channel, you don't need to specify a cluster version, but you do need to set the release channel to None:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --node-locations COMPUTE_ZONE \
    --release-channel None

Example

The following command creates a regional cluster enrolled in the regular release channel (default), with three nodes (default) in the us-west1-c zone:

gcloud container clusters create my-regional-cluster \
    --region us-west1 \
    --node-locations us-west1-c

Example

The following command creates a regional cluster enrolled in the regular release channel (default), with two nodes located in the us-west1-c zone:

gcloud container clusters create my-regional-cluster \
    --region us-west1 \
    --node-locations us-west1-c \
    --num-nodes 2

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click Create.

3. In the Cluster basics section, complete the following:

   1. Enter the Name for your cluster.
   2. For the Location type, select Regional, and then select the region for your cluster.
   3. If you want to override the default node locations (for example, to run in a single zone), select the Specify default node locations checkbox, and then choose the zone(s) in which you want the node pools to run.

   4. Choose a release channel. You can, optionally, select No channel from the drop-down list, however we recommend that you review the comparison between clusters enrolled and not enrolled in a release channel before choosing this option. GKE automatically upgrades clusters not in a release channel with versions from the Stable channel.

   5. Optional: Specify a control plane version from the Version drop-down list.

4. Optional (available with GKE Enterprise): If you want to register your new cluster to a fleet, go to the Fleet registration section, and follow the Google Cloud console instructions for Create and register a new cluster to complete your cluster registration.

5. From the navigation pane, under Node Pools, click default-pool.

6. In the Node pool details section, complete the following:

   1. Enter a Name for the default Node pool.
   2. Optional: Choose the Node version.
   3. Enter the Number of nodes to create in the cluster. You must have available resource quota for the nodes and their resources (such as firewall routes).
   4. Optional: You can choose to disable node auto-upgrades, however we recommend that you review the considerations before disabling node auto-upgrades before choosing this option.

7. From the navigation pane, under Node Pools, click Nodes.

8. From the Image type drop-down list, select the node image.

9. Choose the default Machine configuration to use for the instances. Each machine type is billed differently. The default machine type is e2-medium. For machine type pricing information, refer to the machine type price sheet.

10. From the Boot disk type drop-down list, select the disk type.

11. Enter the Boot disk size.

12. Optional: From the navigation pane, under Node Pools, click Security.

13. Optional: From the Service account drop-down list, select an Identity and Access Management (IAM) service account for your applications to use when calling Google Cloud APIs. We recommend that you use a minimally privileged service account instead of using the default service account.

    Caution: You can't modify the service account on an existing node pool after creation.

14. Click Create.

Terraform

To create a regional cluster with a single-zone node pool using Terraform, refer to the following example:

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-single-zone"
  location           = "us-west1"
  node_locations     = ["us-west1-c"]
  initial_node_count = 2

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

To learn more about using Terraform, see Terraform support for GKE.

Interact with a cluster using kubectl

After you create a cluster, you need to configure kubectl before you can interact with the cluster from the command line.

Create a regional cluster with a multi-zone node pool

The following instructions show you how to create a regional cluster with a multi-zone node pool, which is the default set up. The cluster's control plane and nodes are replicated across multiple zones in the specified region.

You can use the gcloud CLI, Google Cloud console, or Terraform to create the cluster.

If you're developing GKE applications with Visual Studio Code, try creating clusters with Cloud Code.

gcloud

To create a regional cluster with the gcloud CLI, use one of the following commands and replace the following variables:

• CLUSTER_NAME: the name of your new regional cluster.
• COMPUTE_REGION: the region for your cluster, such as us-central1.
• CHANNEL: the type of release channel, which can be one of rapid, regular, stable, or None. By default, the cluster is enrolled in the regular release channel if the following flags aren't specified: --cluster-version, --release-channel, --no-enable-autoupgrade, and --no-enable-autorepair.
• VERSION: the version you want to specify for your cluster.
• For regions with more than three zones or in cases where fewer zones is preferred, you can use the optional --node-locations flag to override the default zones in which the nodes are replicated.

When you create a cluster, you can optionally use the --service-account flag to specify a different IAM service account that nodes in the cluster's first node pool use instead of the Compute Engine default service account. We recommend that you create and use a minimally-privileged service account.

You can't modify the service account on an existing node pool after creation.

Using a specific release channel:

To create a new cluster using a specific release channel, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --release-channel CHANNEL

Using a specific version:

To create a new cluster using a specific cluster version, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --cluster-version VERSION

Note: If you specify a cluster version, the cluster uses that specific version and is not enrolled in a release channel.

Using the default version for clusters not enrolled in a release channel:

To create a new cluster using the default version for clusters not enrolled in a release channel, you don't need to specify a cluster version, but you do need to set the release channel to None:

gcloud container clusters create CLUSTER_NAME \
    --region COMPUTE_REGION \
    --release-channel None

Example

The following command creates a regional cluster enrolled in the regular release channel, with nine nodes in us-west1 (three zones with three nodes each, which is default):

gcloud container clusters create my-regional-cluster --region us-west1

Example

The following command creates a regional cluster enrolled in the regular release channel, with six nodes (three zones with two nodes each, specified by --num-nodes):

gcloud container clusters create my-regional-cluster \
    --region us-west1 \
    --num-nodes 2

Example

The following command creates a regional cluster enrolled in the regular release channel, with six nodes in two zones (two zones, specified by --node-locations, with three nodes each):

gcloud container clusters create my-regional-cluster \
    --region us-central1 \
    --node-locations us-central1-b,us-central1-c

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click Create.

3. In the Cluster basics section, complete the following:

   1. Enter the Name for your cluster.
   2. For the Location type, select Regional, and then select the region for your cluster.
   3. If you want to override the default node locations (for example, to run in a single zone), select the Specify default node locations checkbox, and then choose the zone(s) in which you want the node pools to run.

   4. Choose a release channel. You can, optionally, select No channel from the drop-down list, however we recommend that you review the comparison between clusters enrolled and not enrolled in a release channel before choosing this option. GKE automatically upgrades clusters not in a release channel with versions from the Stable channel.

   5. Optional: Specify a control plane version from the Version drop-down list.

4. Optional (available with GKE Enterprise): If you want to register your new cluster to a fleet, go to the Fleet registration section, and follow the Google Cloud console instructions for Create and register a new cluster to complete your cluster registration.

5. From the navigation pane, under Node Pools, click default-pool.

6. In the Node pool details section, complete the following:

   1. Enter a Name for the default Node pool.
   2. Optional: Choose the Node version.
   3. Enter the Number of nodes to create in the cluster. You must have available resource quota for the nodes and their resources (such as firewall routes).
   4. Optional: You can choose to disable node auto-upgrades, however we recommend that you review the considerations before disabling node auto-upgrades before choosing this option.

7. From the navigation pane, under Node Pools, click Nodes.

8. From the Image type drop-down list, select the node image.

9. Choose the default Machine configuration to use for the instances. Each machine type is billed differently. The default machine type is e2-medium. For machine type pricing information, refer to the machine type price sheet.

10. From the Boot disk type drop-down list, select the disk type.

11. Enter the Boot disk size.

12. Optional: From the navigation pane, under Node Pools, click Security.

13. Optional: From the Service account drop-down list, select an Identity and Access Management (IAM) service account for your applications to use when calling Google Cloud APIs. We recommend that you use a minimally privileged service account instead of using the default service account.

    Caution: You can't modify the service account on an existing node pool after creation.

14. Click Create.

Terraform

To create a regional cluster with a multi-zone node pool using Terraform, refer to the following example:

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-multi-zone"
  location           = "us-central1"
  node_locations     = ["us-central1-b", "us-central1-c"]
  initial_node_count = 2

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

To learn more about using Terraform, see Terraform support for GKE.

Interact with a cluster using kubectl

After you create a cluster, you need to configure kubectl before you can interact with the cluster from the command line.

What's next

• Learn more about the types of clusters you can create.
• Create a zonal cluster.