Control scheduling with taints and tolerations

This page provides an overview oftaints and tolerations on Google Distributed Cloud. When you schedule workloads to bedeployed on your cluster, node taints help you control which nodes they areallowed to run on.

Overview

When you submit a workload to run in a cluster, thescheduler determines where to place the Pods associated with the workload. The scheduleris free to place a Pod on any node that satisfies the Pod's CPU, memory, andcustom resource requirements.

If your cluster runs a variety of workloads, you might want to exercise somecontrol over which workloads can run on a particular pool of nodes.

Anode taint lets you mark a node so that the scheduler avoids or preventsusing it for certain Pods. A complementary feature,tolerations, lets youdesignate Pods that can be used on "tainted" nodes.

Taints and tolerations work together to ensure that Pods are not scheduled ontoinappropriate nodes.

Taints arekey-value pairs associated with aneffect. The following tablelists the available effects:

EffectDescription
NoSchedulePods that do not tolerate this taint are not scheduled on the node; existing Pods are not evicted from the node.
PreferNoScheduleKubernetes avoids scheduling Pods that do not tolerate this taint onto the node.
NoExecuteThe Pod is evicted from the node if it is already running on the node, and is not scheduled onto the node if it is not yet running on the node.

Advantages of setting node taints in Google Distributed Cloud

Although you can set node taints using thekubectl taint command, usinggkectl or the Google Cloud console to set a node taint has thefollowing advantages overkubectl:

  • Taints are preserved when a node is restarted or replaced.
  • Taints are created automatically when a node is added to a node pool.
  • When usinggkectl to add taints, the taints are created automatically duringcluster autoscaling. (Autoscaling for nodepools created in theGoogle Cloud console isn't available currently.)

Set node taints

You can set node taints in a node pool either when you create a user cluster orafter the cluster is created. This section shows adding taints to clusters thathave already been created, but the process is similar when creating newclusters.

You can eitheradd a new node pooland set a taint, or you canupdate an existing node pooland set a taint. Before you add another node pool,verify that enough IP addresses are availableon the cluster.

If you created the cluster in the Google Cloud console, you can use theGoogle Cloud console to add or update a node pool.

Set taints in a new node pool

Console

  1. In the console, go to theGoogle Kubernetes Engine clusters overviewpage.

    Go to GKE clusters

  2. Select the Google Cloud project that the user cluster is in.

  3. In the cluster list, click the name of the cluster, and then clickView details in theDetails panel.

  4. ClickAdd node pool.

  5. Configure the node pool:

    1. Enter theNode pool name.
    2. Enter the number ofvCPUs for each node in the pool (minimum4 per user cluster worker).
    3. Enter thememory size in mebibytes (MiB) for each node in the pool(minimum 8192 MiB per user cluster worker node and must be a multiple of4).
    4. In theReplicas field, enter the number of nodes in the pool(minimum of 3).

    5. Select theOS image type:Ubuntu ContainerdorCOS.

      Note: TheUbuntu OS Image type for node pools is unsupported inGoogle Distributed Cloud version 1.13. You must update your node poolsto use eitherUbuntu Containerd orCOS for the OS Image type.

    6. Enter theBoot disk size in gibibytes (GiB) (default is 40 GiB).

  6. In theNode pool metadata (optional) section, click+ Add Taint.Enter theKey,Value, andEffect for the taint. Repeat asneeded.

  7. Optionally, click+ Add Kubernetes Labels. Enter theKey andValue for the label. Repeat as needed.

  8. ClickCreate.

  9. The Google Cloud console displaysCluster status: changes inprogress. ClickShow Details to view theResource statuscondition andStatus messages.

Command line

  1. In youruser cluster configuration file,fill in thenodePoolssection.

    You must specify the following fields:

    • nodePools.[i].name
    • nodePools[i].cpus
    • nodePools.[i].memoryMB
    • nodePools.[i].replicas

    The following fields are optional. If you don't includenodePools[i].bootDiskSizeGBornodePools[i].osImageType,the default values are used.

  2. Fill in thenodePools[i].taintssection. For example:

    nodePools:- name: "my-node-pool"  taints:  - key: "staging"    value: "true"    effect: "NoSchedule"

  3. Optionally, fill in the following sections:

    • nodePools[i].labels
    • nodePools[i].bootDiskSizeGB
    • nodePools[i].osImageType
    • nodePools[i].vsphere.datastore
    • nodePools[i].vsphere.tags
    Note: TheUbuntu OS Image type for node pools is unsupported inGoogle Distributed Cloud version 1.13. You must update your node pools touse eitherUbuntu Containerd orCOS for the OS Image type.

  4. Run the following command:

    gkectl update cluster --kubeconfigADMIN_CLUSTER_KUBECONFIG --configUSER_CLUSTER_CONFIG

    Replace the following:

Set taints in an existing node pool

Console

  1. In the console, go to theGoogle Kubernetes Engine clusters overviewpage.

    Go to GKE clusters

  2. Select the Google Cloud project that the user cluster is in.

  3. In the cluster list, click the name of the cluster, and then clickView details in theDetails panel.

  4. Click theNodes tab.

  5. Click the name of the node pool that you want to modify.

  6. ClickEdit next to theNode pool metadata (optional) section, and click+ Add Taint.Enter theKey,Value, andEffect for the taint. Repeat asneeded.

  7. ClickDone.

  8. Click to go back to theprevious page.

  9. The Google Cloud console displaysCluster status: changes inprogress. ClickShow Details to view theResource statuscondition andStatus messages.

Command line

  1. In youruser cluster configuration file,go to thenodePoolssection of the node pool that you want to update.

  2. Fill in thenodePools[i].taintsFor example:

    nodePools:- name: "my-node-pool"  taints:  - key: "staging"    value: "true"    effect: "NoSchedule"

  3. Run the following command:

    gkectl update cluster --kubeconfigADMIN_CLUSTER_KUBECONFIG --configUSER_CLUSTER_CONFIG

    Replace the following:

    • [ADMIN_CLUSTER_KUBECONFIG] with the path of thekubeconfig file for your admin cluster.

    • [USER_CLUSTER_CONFIG] with the path of your user clusterconfiguration file.

Configure Pods to tolerate a taint

You can configure Pods to tolerate a taint by including thetolerations fieldin the Pods' specification. In the following example, the Pod can be scheduledon a node that has thededicated=experimental:NoSchedule taint:

tolerations:-key:dedicatedoperator:Equalvalue:experimentaleffect:NoSchedule

For additional examples, seeTaints and Tolerations.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.