Creating a regional cluster

Standard

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

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.

You can read more about the types of clusters you can create.

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.

Before you begin

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

Ensure that you have enabled the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

Ensure that you have installed the Cloud SDK.

Set up default gcloud settings using one of the following methods:

Using gcloud init, if you want to be walked through setting defaults.
Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

Run gcloud init and follow the directions:
```
gcloud init
```
If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:
```
gcloud init --console-only
```
Follow the instructions to authorize gcloud to use your Google Cloud account.
Create a new configuration or select an existing one.
Choose a Google Cloud project.
Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Using gcloud config

Set your default project ID:
```
gcloud config set project PROJECT_ID
```
If you are working with zonal clusters, set your default compute zone:
```
gcloud config set compute/zone COMPUTE_ZONE
```
If you are working with Autopilot or regional clusters, set your default compute region:
```
gcloud config set compute/region COMPUTE_REGION
```
Update gcloud to the latest version:
```
gcloud components update
```

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Ensure you have the correct permission to create clusters. At minimum, you should be a Kubernetes Engine Cluster Admin.

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 tool or the Google Cloud Console 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 tool, use one of the following commands and replace the following variables:

CLUSTER_NAME: the name of your new regional cluster.
COMPUTE_REGION: the desired region for your cluster, such as us-central1.
COMPUTE_ZONE: the desired 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 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.

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

Using the static default version:

To create a new cluster using the static default cluster version, 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

Go to the Google Kubernetes Engine page in the Cloud Console.

Go to Google Kubernetes Engine
Click Create.
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 desired 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 Control plane version. Defaults to the recommended option of Release channel. If you must specify a static version, ensure auto-upgrade is enabled for your node pools.
From the navigation pane, under Node Pools, click default-pool.
In the Node pool details section, complete the following:
1. Enter a Name for the default Node pool.
2. For static version nodes, 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).
From the navigation pane, under Node Pools, click Nodes.
From the Image type drop-down list, select the desired node image.
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.
From the Boot disk type drop-down list, select the desired disk type.
Enter the Boot disk size.
Click Create.
In the Standard section, click Configure.

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 tool or the Google Cloud Console 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 tool, use one of the following commands and replace the following variables:

CLUSTER_NAME: the name of your new regional cluster.
COMPUTE_REGION: the desired 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.

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

Using the static default version:

To create a new cluster using the static default cluster version, 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

Go to the Google Kubernetes Engine page in the Cloud Console.

Go to Google Kubernetes Engine
Click Create.
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 desired 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 Control plane version. Defaults to the recommended option of Release channel. If you must specify a static version, ensure auto-upgrade is enabled for your node pools.
From the navigation pane, under Node Pools, click default-pool.
In the Node pool details section, complete the following:
1. Enter a Name for the default Node pool.
2. For static version nodes, 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).
From the navigation pane, under Node Pools, click Nodes.
From the Image type drop-down list, select the desired node image.
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.
From the Boot disk type drop-down list, select the desired disk type.
Enter the Boot disk size.
Click Create.
In the Standard section, click Configure.

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.