Specify a node image

Standard

---

This page shows you how to specify a node image for nodes in Google Kubernetes Engine (GKE) Standard mode clusters. To learn about how node images work, and the types of node images that are available, see Node images.

Nodes in GKE Autopilot clusters always use the Container-Optimized OS with containerd (cos_containerd) node image.

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.

Specifying a node image

You can select the node image you want to use when you create a new cluster, or you can change the node image for an existing cluster.

Note: Starting with GKE node version 1.19, the default node image for Linux nodes is the Container-Optimized OS with Containerd (cos_containerd) variant instead of the Container-Optimized OS with Docker (cos) variant.

Warning: In GKE version 1.24 and later, Docker-based node image types are not supported. In GKE version 1.23, you also cannot create new node pools with Docker node image types. You must migrate to a containerd node image type. To learn more about this change, see About the Docker node image deprecation.

Creating a new cluster

gcloud

To create a new cluster with a specific node image, run the following command:

gcloud container clusters create CLUSTER_NAME --image-type IMAGE_TYPE

Replace the following:

• CLUSTER_NAME: the name you choose for the cluster.
• IMAGE_TYPE: the name of your node image type.

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click Create.

3. Configure your cluster as desired.

4. From the navigation pane, under Node Pools, click Nodes.

5. In the Image type drop-down list, select the desired node image.

6. Click Create.

Terraform

To create a new cluster with a specific node image using Terraform, refer to the following example:

resource "google_container_cluster" "default" {
  name               = "gke-standard-zonal-node-image"
  initial_node_count = 2

  node_config {
    image_type = "cos_containerd"
  }

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

Upgrading an existing cluster

Warning: In GKE version 1.24 and later, Docker-based node image types are not supported. In GKE version 1.23, you also cannot create new node pools with Docker node image types. You must migrate to a containerd node image type. To learn more about this change, see About the Docker node image deprecation.

This change requires recreating the nodes, which can cause disruption to your running workloads. For details about this specific change, find the corresponding row in the manual changes that recreate the nodes using a node upgrade strategy without respecting maintenance policies table. To learn more about node updates, see Planning for node update disruptions.

Caution: GKE immediately begins recreating the nodes for this change using the node upgrade strategy, regardless of active maintenance policies. GKE depends on resource availability for the change. Disabling node auto-upgrades doesn't prevent this change. Ensure that your workloads running on the nodes are prepared for disruption before you initiate this change.

gcloud

You can upgrade an existing cluster to use a specific node image by using the gcloud container clusters upgrade command. You can upgrade all node pools in the cluster, or you can specify specific a node pool using --node-pool.

To upgrade an existing cluster to use a specific node image, run the following command:

gcloud container clusters upgrade CLUSTER_NAME --image-type IMAGE_TYPE \
    [--node-pool POOL_NAME]

Replace the following:

• CLUSTER_NAME: the name of your existing cluster.
• POOL_NAME: the name of the node pool you want to update.
• IMAGE_TYPE: the name of your node image type.

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. In the cluster list, click the name of the cluster you want to modify.

3. Click the Nodes tab.

4. Under Node Pools, click the name of the node pool you want to upgrade.

5. On the Node pool details page, click Edit.

6. Under Node version, click Change.

7. Select the desired node version and click Change to start the upgrade.

What's next

• Learn more about node images.
• Learn more about node pools.