Creating a zonal cluster

This page shows you how to create a Standard zonal cluster, with the default features enabled, in Google Kubernetes Engine (GKE). Zonal clusters have a single control plane instance in a single zone. Depending on your availability requirements, you can choose to distribute your nodes for your zonal cluster in a single zone or in multiple zones.

Best practice: Use regional clusters to run your production workloads as they offer higher availability than zonal clusters. In a regional cluster, the control plane is replicated across multiple zones in a region.

This page is for Operators, Cloud architects, and Developers, who need to create and configure clusters, and who deploy workloads on GKE. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE user roles and tasks.

Before reading this page, ensure that you're familiar with cluster configuration choices.

Before you begin

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

  • Enable the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • 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 the gcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.

Set up IAM service accounts for GKE

GKE uses IAM service accounts that are attached to your nodes to run system tasks like logging and monitoring. At a minimum, these node service accounts must have the Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) role on your project. By default, GKE uses the Compute Engine default service account, which is automatically created in your project, as the node service account.

To grant the roles/container.defaultNodeServiceAccount role to the Compute Engine default service account, complete the following steps:

Console

  1. Go to the Welcome page:

    Go to Welcome

  2. In the Project number field, click Copy to clipboard.
  3. Go to the IAM page:

    Go to IAM

  4. Click Grant access.
  5. In the New principals field, specify the following value:
    PROJECT_NUMBER-compute@developer.gserviceaccount.com
    Replace PROJECT_NUMBER with the project number that you copied.
  6. In the Select a role menu, select the Kubernetes Engine Default Node Service Account role.
  7. Click Save.

gcloud

  1. Find your Google Cloud project number:
    gcloud projects describe PROJECT_ID \
        --format="value(projectNumber)"

    Replace PROJECT_ID with your project ID.

    The output is similar to the following:

    12345678901
    
  2. Grant the roles/container.defaultNodeServiceAccount role to the Compute Engine default service account:
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
        --role="roles/container.defaultNodeServiceAccount"

    Replace PROJECT_NUMBER with the project number from the previous step.

Create a zonal cluster

The minimum information that you need to specify when creating a new zonal cluster is a name, project (usually the current project), and zone (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 section 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.

You can create a zonal cluster by using the gcloud CLI, the Google Cloud console, or Terraform.

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

gcloud

To create a zonal cluster with the gcloud CLI, use one of the following commands.

Replace the following:

  • CLUSTER_NAME: the name of your new cluster.
  • CHANNEL: the type of release channel, which can be one of rapid, regular, stable, or None (deprecated). By default, the cluster is enrolled in the regular release channel.
  • CONTROL_PLANE_LOCATION: the Compute Engine zone of the control plane of your cluster.
  • VERSION: the version you want to specify for your cluster.
  • COMPUTE_ZONE,COMPUTE_ZONE1,[...]: the zones in which nodes are created. You can specify as many zones as needed for your cluster. All zones must be in the same region as the cluster's control plane, specified by the --location flag. For zonal clusters, --node-locations must contain the cluster's primary zone.

We strongly recommend that you specify a minimally-privileged IAM service account that your nodes can use instead of the Compute Engine default service account. To learn how to create a minimally-privileged service account, see Use a least privilege service account.

To specify a custom service account in the gcloud CLI, add the following flag to your command:

--service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace SERVICE_ACCOUNT_NAME with the name of your minimally-privileged service account.

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 \
    --release-channel CHANNEL \
    --location CONTROL_PLANE_LOCATION \
    --node-locations COMPUTE_ZONE,COMPUTE_ZONE1

Using a specific version:

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

gcloud container clusters create CLUSTER_NAME \
    --cluster-version VERSION \
    --location CONTROL_PLANE_LOCATION \
    --node-locations COMPUTE_ZONE,COMPUTE_ZONE1

Example

The following command creates a multi-zonal cluster named example-cluster, where the cluster control plane is located in the us-east4-a zone, and there are three node locations. The cluster is enrolled in the regular release channel.

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-east4-a, us-east4-b, and us-east4-c. In GKE version 1.37.1-gke.1153000 and later, you can set the --num-nodes flag to a value of 0 to create a cluster that has zero nodes.

gcloud container clusters create example-cluster \
    --location us-east4-a \
    --node-locations us-east4-a,us-east4-b,us-east4-c

Console

To create a zonal cluster with the Google Cloud console, perform the following tasks:

  1. In the Google Cloud console, go to the Create a Kubernetes cluster page.

    Go to Create a Kubernetes cluster

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

    1. Enter the Name for your cluster.
    2. For the Location type, select Zonal, and then select the zone for your cluster.
    3. If you are creating a multi-zonal cluster, select the Specify default node locations checkbox, and then choose additional zones in which you'd like the node pools to run.

    4. Choose a release channel. You can, optionally, select No channel, but this configuration option is deprecated and will be removed. For more information, see Clusters not enrolled in a release channel.

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

  3. Optional: Configure other settings for your new cluster.

  4. Optional: If you want to register your new cluster to a fleet, go to the Advanced settings section, and follow the Google Cloud console instructions for Create and register a new cluster to complete your cluster registration.

  5. To create and configure your own node pools, follow these steps:

    1. Click Add node pool.
    2. In the Changes needed dialog, click Make changes.

    In the navigation menu, a node pool that's named default-pool appears.

  6. Optional: To create a cluster that has no node pools, follow these steps:

    1. In the navigation menu, click default-pool.
    2. Click Remove node pool.
    3. Configure any remaining settings for the cluster, and then click Create.
  7. Optional: To add node pools to the cluster, click Add node pool. In the navigation menu, a new node pool appears.

  8. Configure basic settings for a node pool:

    1. In the navigation menu, in the Node pools section, click the name of the node pool. The User-managed node pool details page opens.
    2. In the Name field, enter a name for the node pool.
    3. In the Size section, in the Number of nodes field, specify the number of nodes to create. You must have available resource quota for the nodes and their resources (such as firewall routes). In GKE version 1.37.1-gke.1153000 and later, you can create an empty node pool by specifying a value of 0.
  9. Configure settings for the VM instances that run the nodes:

    1. In the navigation menu, in the expanded section for your selected node pool, click Nodes.
    2. In the Image type drop-down list, select the node image.
    3. 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, see the machine type price sheet.
    4. In the Boot disk type drop-down list, select the disk type.
    5. In the Boot disk size field, specify a size, in GB, for the boot disk.
  10. Configure security settings for the node pool:

    1. In the navigation menu, in the expanded section for your selected node pool, click Security.
    2. Optionally, specify a custom IAM service account for your nodes:
      1. In the Advanced settings page, expand the Security section.
      2. In the Service account menu, select your preferred service account.

      We strongly recommend that you specify a minimally-privileged IAM service account that your nodes can use instead of the Compute Engine default service account. To learn how to create a minimally-privileged service account, see Use a least privilege service account.

  11. Click Create.

Terraform

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

resource "google_container_cluster" "default" {
  name               = "gke-standard-zonal-single-zone"
  location           = "us-central1-a"
  initial_node_count = 1
}

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

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

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 zonal cluster that has zero nodes

In GKE version 1.37.1-gke.1153000 and later, you can create a zonal cluster that has zero nodes in one of the following ways:

  • Skip creating the default node pool: GKE doesn't add any node pools to the cluster. If you plan to run workloads by using Autopilot ComputeClasses, node pool auto-creation, or custom node pools that you create later, then use this option.
  • Create an empty node pool: GKE creates a node pool that has zero nodes. If you want to customize node pool settings during cluster creation without creating the actual nodes, then use this option.

When you create a cluster that has zero nodes, system Pods remain in an unschedulable state until at least one node exists in the cluster. To create a zonal cluster that has zero nodes, select one of the following options:

gcloud

  • To skip creating the default node pool, use only the --num-nodes=0 flag in the gcloud container clusters create command:

    gcloud container clusters create CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION \
        --num-nodes=0
    

    Replace the following:

    • CLUSTER_NAME: the name of your new zonal cluster.
    • CONTROL_PLANE_LOCATION: the Compute Engine zone of the cluster's control plane, such as us-central1-a.

    If you specify any other node pool configuration flags, such as the --machine-type, --disk-type, or --disk-size flags, the command fails because there's no node pool for GKE to configure.

  • To create a cluster that has an empty node pool, use the --num-nodes=0 flag and the --node-pool-name flag in the gcloud container clusters create command:

    gcloud container clusters create CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION \
        --num-nodes=0 \
        --node-pool-name=NODEPOOL_NAME
    

    Replace NODEPOOL_NAME with a name for the empty node pool. You can specify other node configuration flags to customize the nodes in the empty node pool.

Console

  1. In the Google Cloud console, go to the Create a Kubernetes cluster page.

    Go to Create a Kubernetes cluster

  2. Specify a name for the cluster.

  3. In the Location type section, select Zonal.

  4. In the Zone drop-down list, select a zone for the cluster's control plane.

  5. Skip creating the default node pool or create an empty node pool:

    • To skip creating the default node pool, in the Default mode section, verify that the Autopilot option is selected. Alternatively, trigger the creation of the default node pool and then remove it:

      1. Click Add node pool.
      2. In the Changes needed dialog, click Make changes. A node pool that's named default-pool appears.
      3. In the navigation menu, click default-pool.
      4. Click Remove node pool.

      These steps create a cluster that has no node pools and uses Autopilot mode to run workloads that don't select a ComputeClass. You can also prevent the use of Autopilot mode by selecting the User-managed node pool option in the Default mode section.

    • To create an empty node pool, follow these steps:

      1. Click Add node pool.
      2. In the Changes needed dialog, click Make changes. A node pool that's named default-pool appears.
      3. In the navigation menu, click default-pool.
      4. In the Number of nodes field, specify a value of 0.
  6. Configure any remaining settings for your cluster, and then click Create.

Terraform

  • To skip creating the default node pool, in your google_container_cluster resource, set the initial_node_count field to a value of 0.
  • To create an empty initial node pool, do the following:

    1. In the google_container_cluster resource, set the initial_node_count field to a value of 0.
    2. Add a google_container_node_pool resource and set the node_count field to a value of 0.

After you create a cluster that has zero nodes, you can provision nodes in the following ways:

Cluster templates

GKE previously supported templates for clusters. Those templates were removed from the Google Cloud console, but are still accessible from the following links:

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how GKE performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try GKE free