This page shows you how to migrate your Google Kubernetes Engine (GKE) Standard cluster and node pools to node images that use the containerd container runtime.
Overview
Kubernetes nodes use the container runtime to launch, manage, and stop containers running in Pods. The containerd runtime is an industry-standard container runtime that's supported by GKE.
The containerd runtime provides the layering abstraction that allows for the implementation of a rich set of features like gVisor and Image streaming to extend GKE functionality. The containerd runtime is considered more resource efficient and secure than the Docker runtime.
To migrate your container runtime:
- Identify nodes that use the Docker runtime
- Verify the impact of migration
- Change the node image
Before you begin
Before you start, make sure you have performed the following tasks:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Google Cloud CLI.
- Set up default Google Cloud CLI settings for your project by using one of the following methods:
- Use
gcloud init
, if you want to be walked through setting project defaults. - Use
gcloud config
, to individually set your project ID, zone, and region. -
Run
gcloud init
and follow the directions:gcloud init
If you are using SSH on a remote server, use the
--console-only
flag to prevent the command from launching a browser:gcloud init --console-only
- Follow the instructions to authorize the gcloud CLI to use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone.
- Choose a default Compute Engine region.
- Set your default project ID:
gcloud config set project PROJECT_ID
- Set your default Compute Engine region (for example,
us-central1
):gcloud config set compute/region COMPUTE_REGION
- Set your default Compute Engine zone (for example,
us-central1-c
):gcloud config set compute/zone COMPUTE_ZONE
- Update
gcloud
to the latest version:gcloud components update
gcloud init
gcloud config
By setting default locations, you can avoid errors in gcloud CLI like the
following: One of [--zone, --region] must be supplied: Please specify location
.
Identify nodes that use the Docker runtime
You can check which nodes use Docker-based node images using the following methods:
- Use a script to iterate over all nodes in all GKE clusters across your Google Cloud project.
- Use the Google Cloud CLI,
kubectl
, or the Google Cloud console to identify node images.
We recommend that you use a script to quickly identify all the nodes that you need to migrate.
Use a script to identify Docker nodes
The following script iterates over every node in every cluster in your available projects and provides you with actionable recommendations, such as:
- Whether node auto-provisioning is configured for Docker images
- Suggested containerd node image equivalents for migration
- Suggested node image versions for migration
- Suggested commands to run to migrate the identified nodes and settings
The script ignores GKE Autopilot clusters, which use the Container-Optimized OS with containerd node image by default.
Run the following script:
Identify node images using Google Cloud
You can check the node images for existing nodes using the Google Cloud CLI,
kubectl
, or the Google Cloud console.
gcloud
Run the following command:
gcloud container node-pools list \
--cluster=CLUSTER_NAME \
--format="table(name,version,config.imageType)"
Replace CLUSTER_NAME
with the name of your cluster.
The output is similar to the following:
NAME NODE_VERSION IMAGE_TYPE
default-pool 1.19.6-gke.600 UBUNTU
Console
Go to the Google Kubernetes Engine page in Google Cloud console.
In the cluster list, click the name of the cluster you want to verify.
Select the Nodes tab.
In the Node pools section, check the value in the Image type column.
kubectl
Run the following command:
kubectl get nodes -o wide
The output is similar to the following:
# For Docker runtime
NAME STATUS VERSION OS-IMAGE CONTAINER-RUNTIME
gke-node-1 Ready v1.16.15-gke.6000 Container-Optimized OS from Google docker://19.3.1
gke-node-2 Ready v1.16.15-gke.6000 Container-Optimized OS from Google docker://19.3.1
gke-node-3 Ready v1.16.15-gke.6000 Container-Optimized OS from Google docker://19.3.1
The value in the CONTAINER-RUNTIME
column shows the runtime and version.
Verify the impact of migrating
Before you migrate your production clusters and node pools to node images that use containerd, we strongly recommend that you test the impact of the migration in a staging environment to minimize the risk of issues.
Change the node image to a containerd image
If you used the script to identify your Docker nodes, you can use the suggested commands returned by the script to change your node auto-provisioning settings and your node images to the containerd equivalents.
You can also migrate nodes from a Docker image type to a containerd image type by updating the node pool and setting a different image using the gcloud CLI or the Google Cloud console.
gcloud
Run the following command:
gcloud container clusters upgrade CLUSTER_NAME \
--image-type=NODE_IMAGE \
--node-pool=POOL_NAME
Replace the following:
NODE_IMAGE
: the node image that you want the nodes to use.POOL_NAME
: the name of the node pool to migrate.
The output is similar to the following:
NAME NODE_VERSION IMAGE_TYPE
default-pool 1.19.6-gke.600 UBUNTU_CONTAINERD
Console
Go to the Google Kubernetes Engine page in Google Cloud console.
In the cluster list, click the name of the cluster you want to verify.
Click the Nodes tab.
In the Node pools section, click the name of the node pool that you want to modify.
On the Node pool details page, click
Edit.In the Nodes section, under Image type, click Change.
Select one of the containerd image types.
Click Change.
Change the default node image for node auto-provisioning
If you use node auto-provisioning in your cluster, change the default image type to a containerd node image. Changing the default image type only applies to new auto-provisioned node pools. You must manually change the node image for existing auto-provisioned node pools.
You can change the default node auto-provisioning image type using the gcloud CLI or a configuration file.
gcloud
Run the following command:
gcloud container clusters update CLUSTER_NAME \
--enable-autoprovisioning \
--autoprovisioning-image-type=IMAGE_TYPE
Replace the following:
CLUSTER_NAME
: the name of the cluster to update.IMAGE_TYPE
: the node image type, which can be one of the following:cos_containerd
ubuntu_containerd
File
You can use a YAML configuration file to change the default node image type for node auto-provisioning. When you use a file, you must also specify maximum values for CPU and memory resources.
Save the following YAML file:
resourceLimits: - resourceType: 'cpu' minimum: 4 maximum: 10 - resourceType: 'memory' maximum: 64 autoprovisioningNodePoolDefaults: imageType: 'IMAGE_TYPE'
Replace
IMAGE_TYPE
with the containerd image type.Apply the configuration:
gcloud container clusters update CLUSTER_NAME \ --enable-autoprovisioning \ --autoprovisioning-config-file=FILE_NAME
Replace
FILE_NAME
with the path to the configuration file.
Troubleshooting
For troubleshooting and for known issues with workarounds, refer to Troubleshooting the container runtime.