Creating a zonal cluster

Standard

---

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 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.

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

Single-zone versus multi-zonal

A single-zone cluster has a single control plane running in one zone. This control plane manages workloads on nodes running in the same zone. If you run a workload in a single zone, this workload is unavailable in the event of a zonal outage.

A multi-zonal cluster's nodes run in multiple zones, but it has only a single replica of the control plane. If you run a workload in multiple zones and there is a zonal outage, the workload is disrupted in that zone but remains available in other zones.

If you need higher availability for the control plane, consider creating a regional cluster instead. In a regional cluster, the control plane is replicated across multiple zones in a region.

After you create a cluster, you cannot change it from zonal to regional, or regional to zonal.

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.

• Multi-zonal clusters use more resources than single-zone clusters. If you are creating a multi-zonal cluster, ensure you have adequate quotas.
• 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.

Important: New clusters have the cos-metrics-enabled flag enabled by default. This setting allows kernel crash logs to be collected using dmesg. The report does not include any user logs, and does not intentionally collect any PII. It can potentially include user logs if you write logs from a privileged container and bind mount /dev/kmsg. And certain PII, for example process name, may appear in the report if kernel includes them in the error messages, such as OOM kills.

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.

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.

Best practice: Instead of using the Compute Engine default service account, create a custom service account for your nodes to use and give it only the permissions that GKE needs to run system tasks. For more information, see Use a least privileged 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:

   [e-mail]

   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:[e-mail]" \
       --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.

Note: If you are creating a single-zone cluster, you can omit the --node-locations flag from the command.

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. 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.
• COMPUTE_ZONE: the compute zone for the cluster control plane.
• VERSION: the version you wish 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 --zone 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 \
    --zone COMPUTE_ZONE \
    --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 \
    --zone COMPUTE_ZONE \
    --node-locations COMPUTE_ZONE,COMPUTE_ZONE1

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 \
    --release-channel None \
    --zone COMPUTE_ZONE \
    --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-central-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-central1-a, us-central1-b, and us-central1-c.

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

Console

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

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 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 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. 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.

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

14. 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

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

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

  # 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.

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:

• Your first cluster

  Note: GKE provides a guided walkthrough for My first cluster.

• CPU intensive applications

• Memory intensive applications

• GPU accelerated computing

• Highly available

What's next

• Learn about cluster configuration choices you can create.
• Learn about the GKE cluster architecture.
• Learn about managing your clusters.
• Learn how to delete clusters.

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