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.

Cluster templates

When you create a new cluster using GCP Console, you see all of the available cluster templates. By default, the Standard template is selected. To learn more about a specific template, including the presets it includes, click its entry. The presets are shown in the information panel on the right-hand side of the page.

The following templates are available:

  • Standard cluster: Equivalent to the previous defaults for a new 3-node zonal cluster.
  • Your first cluster: A small cluster that runs less powerful nodes and disables some advanced features such as autoscaling.
  • CPU intensive applications: A cluster whose nodes provide more powerful multi-core CPUs than a standard cluster.
  • Memory intensive applications: A cluster whose nodes provide moderately powerful multi-core CPUs and a large amount of memory.
  • GPU Accelerated Computing: A cluster with a default node pool configured with less powerful nodes, as well as an additional GPU-enabled node pool. Autoscaling is disabled by default.
  • Highly Available: The cluster is configured as a regional cluster, with cluster masters available in each zone of a given region. Autoscaling and a a maintenance window are enabled.

After you choose your template, you can customize the cluster.

In addition to the available templates, you can clone an existing cluster.

Customizing a template's presets

To customize the cluster, first click the template that most closely matches your use case. Before creating the cluster, you can change any editable field.

  • To configure advanced cluster-wide options, click Advanced options near the bottom of the form.
  • To configure the CPUs or memory for the nodes in a given node pool, click Customize for that node pool.
  • To configure advanced options for a given node pool, click Advanced edit.

Cloning an existing cluster

To use an existing cluster's configuration as the basis for your new cluster, click Clone an existing cluster rather than a cluster template. Select the cluster to clone from the drop-down menu.

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.

  3. Choose the Standard cluster template or choose an appropriate template for your workload.
  4. Customize the template if necessary. 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.
  5. 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 <var>[COMPUTE_ZONE]</var> is the zone for the cluster control plane
  • --node-locations <var>[COMPUTE_ZONE]</var>,<var>[COMPUTE_ZONE]</var>,...] 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. Choose the Standard cluster template or choose an appropriate template for your workload.
  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 [COMPUTE_ZONE],[COMPUTE_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. Choose the Highly Available cluster template.
  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. Choose the Standard cluster template or choose an appropriate template for your workload.
  4. From the Cluster Version drop-down menu, select the desired GKE version to run in the cluster.
  5. Configure your cluster as desired.
  6. To create an alpha cluster, first disable settings that are not compatible with alpha clusters.
  7. Select Advanced options.
  8. Disable Enable auto-repair.
  9. Click Save to go back to the main cluster creation screen.
  10. Click Advanced options. Near the bottom of the page, select Enable Kubernetes alpha features in this cluster.
  11. Read and acknowledge the warning by selecting I understand the consequences.
  12. 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

Clusters with Binary Authorization

Binary Authorization is a service on GCP that provides software supply-chain security for applications that run in the Cloud. Binary Authorization works with images that you deploy to GKE from Container Registry or another container image registry. With Binary Authorization, you can ensure that internal processes that safeguard the quality and integrity of your software have successfully completed before an application is deployed to your production environment.

For instructions about creating a cluster with Binary Authorization enabled, visit Creating a Cluster in the Binary Authorization documentation.

What's next

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

Send feedback about...

Kubernetes Engine