Creating a Cluster

This page shows you how to create a cluster in Google Kubernetes Engine. To learn about how clusters work, refer to Cluster Architecture.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have enabled the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • Ensure that you have installed the Cloud SDK.
  • 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 regional clusters, set your default compute region:
    gcloud config set compute/region [COMPUTE_REGION]
  • Update gcloud to the latest version:
    gcloud components update

Types of clusters

You can create four types of clusters in GKE:

Zonal clusters
A zonal cluster runs in one or more compute zones within a region. A multi-zone cluster runs its nodes across two or more compute zones within a single region. Zonal clusters run a single cluster master.
Regional cluster
A regional cluster runs three cluster masters across three compute zones, and runs nodes in two or more compute zones.
Private cluster
A private cluster is a zonal or regional cluster which hides its cluster master and nodes from the public Internet by default.
Alpha cluster
An alpha cluster is an experimental zonal or regional cluster that runs with alpha Kubernetes features enabled. Alpha clusters expire after 30 days and are not recommended for production use.

Working with multiple clusters

If you work with multiple clusters—created by you, created by different users within your project, or created using Google Cloud Platform Console—you need to configure the kubectl command-line tool to interact with those clusters.

To learn more, refer to Configuring Cluster Access for kubectl.

Zonal clusters

By default, a cluster is created in a single compute zone. A multi-zone cluster runs nodes in multiple zones within the same region. All nodes in a single-zone or multi-zone cluster are controlled by the same cluster master.

Multi-zone clusters can help improve the availability of your applications by running them on nodes across multiple zones. This helps protect against downtime in the unlikely event of a zone-wide outage.

How multi-zone clusters work

When you create a multi-zone cluster, either initially or by adding zones to an existing cluster, GKE makes the resource footprint the same in all zones.

For example, suppose that you request two nodes with four cores each, and you ask for your cluster to be spread across three zones. In that case, you would get a total of 24 cores, with eight cores in each zone.

Multi-zone clusters attempt to spread resources evenly across zones to ensure that Pods are scheduled evenly across zones. Doing so improves availability and failure recovery. If computing resources were spread unevenly across zones, the scheduler might not be able to schedule Pods evenly. You can guarantee even distribution of resources by specifying Pod anti-affinity.

Node pools in multi-zone clusters automatically have multi-zone availability. Those nodes also have labels applied in Kubernetes that indicate their failure domain, so that they can be taken into account by the Kubernetes scheduler.

Creating a single-zone cluster

gcloud

To create a cluster with the gcloud command-line tool, use the gcloud container clusters command:

gcloud container clusters create [CLUSTER_NAME] [--zone [COMPUTE_ZONE]]

where [CLUSTER_NAME] is the name you choose for the cluster. The optional --zone flag overrides the default compute/zone property set by gcloud config set compute/zone.

For the full list of optional flags, refer to the gcloud container clusters create documentation.

Console

To create a cluster using GCP Console, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click Create cluster. The following fields are required:

    • Name: The name you choose for the cluster. It must be unique within the project and the zone.
    • Location type: Whether all the nodes in the cluster are in the same zone, or can be in any zone in a given region.
    • Zone: Compute Engine compute zone in which to create the cluster, if the Location type is Zonal.
    • Region: Compute Engine compute zone in which to create the cluster, if the Location type is Regional.
    • Node pool:
      • Cluster size: 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).
      • Machine type: Compute Engine machine type to use for the instances. Each machine type is billed differently. The default machine type is n1-standard-1. For machine type pricing information, refer to the machine type price sheet.
  3. Click Create.

After you create a cluster in GCP Console, you need to configure kubectl to interact with the cluster. To learn more, refer to Generating a kubeconfig entry.

Creating a multi-zone cluster

gcloud

To create a multi-zone cluster, run the following command. Use --zone to specify the zone for the cluster control plane. Use --node-locations to specify all of the desired zones for nodes:

gcloud container clusters create [CLUSTER_NAME] \
--zone [COMPUTE_ZONE] \
--node-locations [COMPUTE_ZONE,COMPUTE_ZONE,...]`

where:

  • [CLUSTER_NAME] is the name you choose for the cluster
  • --zone [COMPUTE_ZONE] is the zone for the cluster control plane
  • --node-locations [COMPUTE_ZONE,COMPUTE_ZONE,...] is all of the zones in which the cluster runs, including the cluster control plane's zone.

For example:

gcloud container clusters create example-cluster \
--zone us-central1-a \
--node-locations us-central1-a,us-central1-b,us-central1-c

When the --num-nodes flag is omitted, the default number of per-zone nodes created by the cluster is three. Because three zones were specified, this command creates a nine-node cluster with three nodes each in us-central1-a, us-central1-b, and us-central1-c.

Console

To create a multi-zone cluster, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click Create cluster.

  3. From Location, ensure that Zonal is selected.
  4. From the Zone drop-down menu, select the desired zone for your cluster control plane, such as us-central1-a.
  5. Configure your cluster as desired, then click Advanced options.
  6. From the Additional zone locations section, select additional zones in which you'd like the cluster to run.
  7. Click Save to exit the Advanced options overlay.
  8. Click Create.

After you create a cluster in GCP Console, you need to configure kubectl to interact with the cluster. To learn more, refer to Generating a kubeconfig entry.

Regional clusters

Regional clusters distribute Kubernetes resources across multiple zones within a region. Regional cluster create three cluster masters across three zones and, by default, create nodes in three zones, or in as many zones as desired.

To learn about regional clusters, refer to the regional cluster Concept page.

Creating a regional cluster

You can create a regional cluster by using the GCP Console or the gcloud command-line tool.

By default, when a regional cluster is created, the cluster's node pools are replicated across three zones.

gcloud

To create a regional cluster, run the following command:

gcloud container clusters create [CLUSTER_NAME]--region [REGION] \
[--node-locations [ZONE,ZONE...]`]

where [CLUSTER_NAME] is the name you choose for the regional cluster, and [REGION] is the desired region, such as us-central1. For regions with more than three zones or in cases where fewer zones is preferred, the optional --node-locations flag overrides the default zones in which the nodes are replicated.

For example, to create a regional cluster with nine nodes in us-east1 (three zones with three nodes each, which is default):

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

To create a regional cluster with six nodes (three zones with two nodes each, specified by --num-nodes):

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

To create a regional cluster 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

To create a regional cluster, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in the GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click Create cluster.

  3. From Location, select Regional.
  4. From the Region drop-down menu, select the desired [region][r], such as us-central1.
  5. Configure your cluster as desired, then click Create.

After you create a cluster in GCP Console, you need to configure kubectl to interact with the cluster. To learn more, refer to Generating a kubeconfig entry.

Private clusters

To learn how to create a private cluster, refer to the private cluster How-to Guide.

Alpha clusters

Alpha clusters are short-lived clusters that run stable Kubernetes releases with all Kubernetes APIs and features enabled.

To learn about alpha clusters, refer to the alpha cluster Concept page.

Creating an alpha cluster

gcloud

To create an alpha cluster, run the following command:

gcloud container clusters create [CLUSTER_NAME] \
    --enable-kubernetes-alpha [--zone [COMPUTE_ZONE]]
    [--cluster-version [VERSION]]

where:

  • [CLUSTER_NAME] is the name you choose for the cluster
  • [COMPUTE_ZONE] is the Compute Engine [compute zone] in which to create the cluster. The optional --zone flag overrides the default compute/zone property set by gcloud config set compute/zone. Note: Your default compute zone must be set using gcloud config set compute/zone [COMPUTE_ZONE] or specified using --zone.
  • [VERSION] is the GKE version to run in the cluster. If unset, the cluster runs the current default version documented in Versioning and Upgrades.

You are prompted to acknowledge a warning that the alpha cluster is not upgraded and is deleted after 30 days:

This will create a cluster with all Kubernetes Alpha features enabled.
- This cluster will not be covered by the GKE SLA and should
  not be used for production workloads.
- You will not be able to upgrade the master or nodes.
- The cluster will be deleted after 30 days.

Console

To create an alpha cluster, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in GCP Console.

    Visit the Google Kubernetes Engine menu

  2. Click Create cluster.

  3. From the Cluster Version drop-down menu, select the desired GKE version to run in the cluster.
  4. Configure your cluster as desired.
  5. To create an alpha cluster, first disable settings that are not compatible with alpha clusters.
  6. Select Advanced options.
  7. Disable Enable auto-repair.
  8. Click Save to go back to the main cluster creation screen.
  9. Click Advanced options. Near the bottom of the page, select Enable Kubernetes alpha features in this cluster.
  10. Read and acknowledge the warning by selecting I understand the consequences.
  11. Click Create.

After you create a cluster in GCP Console, you need to configure kubectl to interact with the cluster. To learn more, refer to Generating a kubeconfig entry.

Alpha cluster expiration

To check when alpha clusters expire, run the following command:

gcloud container clusters list

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine