This document shows you how to apply ComputeClasses by default toGoogle Kubernetes Engine (GKE) Pods that don't explicitly select a ComputeClass.This page has instructions for setting a ComputeClass as the default in anamespace and for an entire cluster. This document is intended for clusteradministrators who want to reduce manual overhead caused by individual workloadand node configuration.

You should already be familiar withcustom ComputeClasses.

About default ComputeClasses

You can configure GKE clusters or specific namespaces to have adefault ComputeClass. The default class that you configure applies toany Pod in that cluster or namespace that doesn't select a different ComputeClass. When you deploy a Pod that doesn't select a ComputeClass,GKE applies default ComputeClasses in the following order:

1. If the namespace has a default ComputeClass, GKE modifiesthe Pod specification to select that ComputeClass.
2. If the namespace doesn't have a default ComputeClass, the cluster-leveldefault class applies. GKE doesn't modify the Podspecification.

When you set a default ComputeClass for a cluster or a namespace, your changeapplies only to new Pods. Existing Pods aren't affected until the Pods arere-created. This behavior applies even if your ComputeClass has activemigration enabled.

If your default ComputeClass has theactiveMigration.optimizeRulePriority fieldset totrue, this setting might affect workloads in your clusters. For more information,seeActive migration in default ComputeClasses.

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
• If you want to use the Google Cloud CLI for this task,install and theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

• Have a GKE Autopilot or Standard cluster thatruns a version that supports setting a default ComputeClass at the cluster-or namespace-level. For more information, see theRequirements section.

• If you're using a Standard mode cluster, ensure that you meet oneof the following requirements:

  • Enableautoscaling on atleast one node pool in the cluster.
  • If your Standard cluster runs a version earlier than1.33.3-gke.1136000 and isn't enrolled in the Rapid releasechannel,enable cluster-level node auto-provisioning.

• If you want to set a custom ComputeClass as the default for a namespace,deploy a custom ComputeClass.

Requirements

• To set a ComputeClass as the cluster-level default, the cluster must runGKE version 1.33.1-gke.1744000 or later.
• To set a ComputeClass as the namespace-level default for only non-DaemonSetPods, the cluster must run GKE version1.33.1-gke.1788000 or later.

Required roles and permissions

To get the permissions that you need to configure cluster- or namespace-level default ComputeClasses, ask your administrator to grant you the following IAM roles on the Google Cloud project:

• Kubernetes Engine Developer (roles/container.developer)
• Update the cluster-level default ComputeClass:Kubernetes Engine Cluster Admin (roles/container.clusterAdmin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to configure cluster- or namespace-level default ComputeClasses. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Configure a default ComputeClass for a namespace

You can annotate any Kubernetes namespace in your cluster with the name of aComputeClass to use as the default. If a Pod that's deployed to that namespacedoesn't already select a ComputeClass, GKE modifies the Podspecification to select the default class in the namespace. You can set anycustom or built-in ComputeClass as the default.

• To apply a ComputeClass to all Pods in a namespace by default, add thecloud.google.com/default-compute-class label to that namespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class=COMPUTECLASS_NAME

  Replace the following:

  • NAMESPACE_NAME: the name of the namespace to update.
  • COMPUTECLASS_NAME: the name of the ComputeClass toset as the default for the namespace.

  If the command fails with the following error message, the namespace alreadyhas a default ComputeClass:

  error: 'cloud.google.com/default-compute-class' already has a value, and --overwrite is false

  To resolve this error,update the default ComputeClass for the namespace.

• To apply a ComputeClass to all non-DaemonSet Pods in a namespace by default,add thecloud.google.com/default-compute-class-non-daemonset label to thatnamespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class-non-daemonset=COMPUTECLASS_NAME

  If the command fails with the following error message, the namespace alreadyhas a default ComputeClass for non-DaemonSet Pods:

  error: 'cloud.google.com/default-compute-class-non-daemonset' already has a value, and --overwrite is false

  To resolve this error,update the default ComputeClass for the namespace.

Your changes apply to any new Pods in that namespace. Existing Pods aren't affected.

Update the existing default ComputeClass in a namespace

To overwrite the existing default ComputeClass for a namespace, run one of thefollowing commands:

• Update the default ComputeClass for all Pods in the namespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class=COMPUTECLASS_NAME\--overwrite

  Replace the following:

  • NAMESPACE_NAME: the name of the namespace to update.
  • COMPUTECLASS_NAME: the name of the ComputeClass toset as the new default for the namespace.

• Overwrite the default ComputeClass for non-DaemonSet Pods in the namespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class-non-daemonset=COMPUTECLASS_NAME\--overwrite

Configure a default ComputeClass for system namespaces

GKE uses system namespaces to run various managed workloads, suchas monitoring agents. Some of these managed workloads are DaemonSets, which mustrun on every node in the cluster to provide critical functionality. However, youcan specify a default ComputeClass for non-DaemonSet Pods in system namespaces,so that those Pods run separately from your workloads.

To set a default ComputeClass for system namespaces, follow these steps:

1. Save the following script asapply-system-cc.sh. This script lets youapply a recommended ComputeClass or your own existing ComputeClass to systemnamespaces.

   #!/bin/bash# The recommended default ComputeClass name for system pods.DEFAULT_SYSTEM_CC_NAME="system-default-computeclass"# The YAML manifest for the recommended default ComputeClass for system pods.read-r-d''DEFAULT_CC_YAML<< EOFapiVersion: cloud.google.com/v1kind: ComputeClassmetadata:  name: ${DEFAULT_SYSTEM_CC_NAME}spec:  nodePoolAutoCreation:    enabled: true  whenUnsatisfiable: ScaleUpAnyway  priorities:  - machineFamily: t2dEOF# The label key to apply to namespaces.LABEL_KEY="cloud.google.com/default-compute-class-non-daemonset"# List of GKE system namespaces.SYSTEM_NAMESPACES=("kube-system""gke-gmp-system""gmp-system""gke-managed-cim""gke-managed-volumepopulator""gke-managed-checkpointing""gkebackup""gke-managed-lustrecsi")# 1. Ask the user for their choice.echo"This script sets a default ComputeClass for GKE system namespaces."echo"--------------------------------------------------------------------"echo"The following ComputeClass is recommended for system Pods:"echo""echo"$DEFAULT_CC_YAML"echo"--------------------------------------------------------------------"read-p"Do you want to use the recommended ComputeClass? (y/N): "user_choiceCC_TO_APPLY=""# 2. Process the user's choice.if[["$user_choice"=~^[Yy]$]];then# Path 1: User chose YES.echo"Installing the recommended default ComputeClass '${DEFAULT_SYSTEM_CC_NAME}'..."if!echo"$DEFAULT_CC_YAML"|kubectlapply-f-;then# If kubectl apply fails, print an error and exit.echo"❌ Error: Failed to create the default ComputeClass. An internal error occurred."echo"Check for kubectl permissions or other cluster issues and re-run the script."exit1fi# If the command succeeded, set the name to be used for labeling.CC_TO_APPLY="$DEFAULT_SYSTEM_CC_NAME"elseread-p"Specify the name of an existing ComputeClass to set as the default for system Pods: "custom_cc_name# Validate that the user entered a name.while[[-z"$custom_cc_name"]];doecho"Error: Name cannot be empty."read-p"Specify the name of an existing ComputeClass: "custom_cc_namedone# Check if the specified ComputeClass actually exists in the cluster.echo"--> Verifying that ComputeClass '${custom_cc_name}' exists..."ifkubectlgetcomputeclass"$custom_cc_name">/dev/null2>&1;thenecho"Verified."CC_TO_APPLY="$custom_cc_name"elseecho"Error: ComputeClass '${custom_cc_name}' doesn't exist in the cluster."echo"Create the ComputeClass, and then then re-run this script."exit1fifiecho""echo"Labelling system namespaces with ComputeClass: '${CC_TO_APPLY}'"echo"--------------------------------------------------------------------"# 3. Apply the label to all system namespaces.fornsin"${SYSTEM_NAMESPACES[@]}";do# Gracefully handle namespaces that don't exist on this specific cluster.ifkubectlgetnamespace"${ns}">/dev/null2>&1;thenecho"--> Applying label to namespace:${ns}"kubectllabelnamespace"${ns}"\"${LABEL_KEY}=${CC_TO_APPLY}"--overwriteelseecho"--> Skipping namespace${ns} (does not exist)"fidoneecho""echo"✅ Script finished successfully."

   This script uses thecloud.google.com/default-compute-class-non-daemonset label, which affectsonly non-DaemonSet Pods in system namespaces.

   Warning: Don't set thecloud.google.com/default-compute-class label for asystem namespace. This label affects DaemonSets and might causedisruptions to your cluster.

2. Run the script:

   ./apply-system-cc.sh

After the script completes, all new non-DaemonSet system Pods use the specifiedComputeClass by default, unless they already have a ComputeClass. Existing Podsin those namespaces aren't affected. If GKE adds new systemnamespaces, run this script again to apply changes to those namespaces.

To unset the default ComputeClass for system namespaces, follow these steps:

1. Save the following script asunset-system-cc.sh:

   #!/bin/bash# The recommended default ComputeClass name for system pods.DEFAULT_SYSTEM_CC_NAME="system-default-computeclass"# The YAML manifest for the recommended default ComputeClass for system pods.read-r-d''DEFAULT_CC_YAML<< EOFapiVersion: cloud.google.com/v1kind: ComputeClassmetadata:  name: ${DEFAULT_SYSTEM_CC_NAME}spec:  nodePoolAutoCreation:    enabled: true  whenUnsatisfiable: ScaleUpAnyway  priorities:  - machineFamily: t2dEOF# The label key to apply to namespaces.LABEL_KEY="cloud.google.com/default-compute-class-non-daemonset"# List of GKE system namespaces.SYSTEM_NAMESPACES=("kube-system""gke-gmp-system""gmp-system""gke-managed-cim""gke-managed-volumepopulator""gke-managed-checkpointing""gkebackup""gke-managed-lustrecsi")# 1. Ask the user for their choice.echo"This script sets a default ComputeClass for GKE system namespaces."echo"--------------------------------------------------------------------"echo"The following ComputeClass is recommended for system Pods:"echo""echo"$DEFAULT_CC_YAML"echo"--------------------------------------------------------------------"read-p"Do you want to use the recommended ComputeClass? (y/N): "user_choiceCC_TO_APPLY=""# 2. Process the user's choice.if[["$user_choice"=~^[Yy]$]];then# Path 1: User chose YES.echo"Installing the recommended default ComputeClass '${DEFAULT_SYSTEM_CC_NAME}'..."if!echo"$DEFAULT_CC_YAML"|kubectlapply-f-;then# If kubectl apply fails, print an error and exit.echo"❌ Error: Failed to create the default ComputeClass. An internal error occurred."echo"Check for kubectl permissions or other cluster issues and re-run the script."exit1fi# If the command succeeded, set the name to be used for labeling.CC_TO_APPLY="$DEFAULT_SYSTEM_CC_NAME"elseread-p"Specify the name of an existing ComputeClass to set as the default for system Pods: "custom_cc_name# Validate that the user entered a name.while[[-z"$custom_cc_name"]];doecho"Error: Name cannot be empty."read-p"Specify the name of an existing ComputeClass: "custom_cc_namedone# Check if the specified ComputeClass actually exists in the cluster.echo"--> Verifying that ComputeClass '${custom_cc_name}' exists..."ifkubectlgetcomputeclass"$custom_cc_name">/dev/null2>&1;thenecho"Verified."CC_TO_APPLY="$custom_cc_name"elseecho"Error: ComputeClass '${custom_cc_name}' doesn't exist in the cluster."echo"Create the ComputeClass, and then then re-run this script."exit1fifiecho""echo"Labelling system namespaces with ComputeClass: '${CC_TO_APPLY}'"echo"--------------------------------------------------------------------"# 3. Apply the label to all system namespaces.fornsin"${SYSTEM_NAMESPACES[@]}";do# Gracefully handle namespaces that don't exist on this specific cluster.ifkubectlgetnamespace"${ns}">/dev/null2>&1;thenecho"--> Applying label to namespace:${ns}"kubectllabelnamespace"${ns}"\"${LABEL_KEY}=${CC_TO_APPLY}"--overwriteelseecho"--> Skipping namespace${ns} (does not exist)"fidoneecho""echo"✅ Script finished successfully."

2. Run the script:

   ./unset-system-cc.sh

Configure a default ComputeClass for a cluster

This section shows you how to set a ComputeClass as the default for yourcluster. For cluster-level default ComputeClasses, don't manually specify nodetaints and node labels for existing node pools in the cluster.GKE doesn't scale node pools that have node taints forComputeClasses. If you manually add a label for thedefault ComputeClass,GKE can scale that node pool. However, this manual configurationisn't required to use a default cluster-level compute class.

1. To enable setting a cluster-level default ComputeClass for a cluster,use the--enable-default-compute-class flagwhen you create or update a cluster:

   • Create a cluster:

     gcloudcontainerclusterscreateCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--enable-default-compute-class

     Replace the following:

     • CLUSTER_NAME: a name for your cluster.
     • CONTROL_PLANE_LOCATION: the location of yourcluster control plane, likeus-central1.

   • Update a cluster:

     gcloudcontainerclustersupdateCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--enable-default-compute-class

     Replace the following:

     • CLUSTER_NAME: the name of your cluster.
     • CONTROL_PLANE_LOCATION: the location of yourcluster control plane, likeus-central1.

   After you complete this step, GKE looks for a ComputeClassnameddefault in your cluster. You won't notice any changes to yourworkloads until you create thedefault ComputeClass.

2. Save the following manifest, which defines a ComputeClass nameddefault:

   apiVersion:cloud.google.com/v1kind:ComputeClassmetadata:name:defaultspec:priorities:-machineFamily:n4-machineFamily:n2whenUnsatisfiable:ScaleUpAnywaynodePoolAutoCreation:enabled:true

   This example manifest requests nodes that use N4 instances. If N4 instancesaren't available, the ComputeClass requests N2 instances instead. You canconfigure thedefault ComputeClass with any of the available fields intheComputeClass CustomResourceDefinition.

3. Apply the manifest to your cluster:

   kubectlapply-fPATH_TO_MANIFEST

   ReplacePATH_TO_MANIFEST with the path to themanifest for the ComputeClass.

After you set a cluster-level default ComputeClass, GKEscales node pools that meet both of the following requirements:

• The node configuration is the same as the configuration of thedefaultComputeClass.
• The node pool has no taints or labels for a different ComputeClass.GKE can scale node pools that have a taint and a labelfor thedefault ComputeClass.

For example, if thedefault ComputeClass specifies the N4 machine series,GKE can scale an existing node pool that uses N4 instances anddoesn't have taints or labels for a different ComputeClass.

Your changes apply to all new Pods in the cluster that don't already have aComputeClass. Existing Pods might be affected depending on the active migrationsettings of the cluster-level default ComputeClass. For more information, seeActive migration in default ComputeClasses.

Verify the default ComputeClass behavior

To check whether the default ComputeClass that you set for a namespace orfor a cluster works as expected, do the following:

1. Review the following example Deployment:

   apiVersion:apps/v1kind:Deploymentmetadata:name:helloweblabels:app:hellospec:selector:matchLabels:app:hellotier:webtemplate:metadata:labels:app:hellotier:webspec:containers:-name:hello-appimage:us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0ports:-containerPort:8080resources:requests:cpu:200m

   This Deployment doesn't explicitly request a ComputeClass.

2. Create the Deployment:

   kubectlapply--namespace=NAMESPACE_NAME\-fhttps://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/refs/heads/main/quickstarts/hello-app/manifests/helloweb-deployment.yaml

   ReplaceNAMESPACE_NAME with one of the following,depending on what you want to verify:

   • The name of a namespace that has a default ComputeClass.
   • The name of a namespace that doesn't have a default ComputeClass.

   GKE might take some time to create new nodes to run thePods.

3. Identify the nodes that run the Pods from the example Deployment:

   kubectlgetpods--namespace=NAMESPACE_NAME\--selector=app=hello-o=wide

   The output is similar to the following:

   NAME                        READY   STATUS    RESTARTS   AGE     IP          NODE                                                  NOMINATED NODE   READINESS GATEShelloweb-7795fbf856-58n5l   1/1     Running   0          9m21s   10.52.2.3   gke-cluster-1-nap-n2-highcpu-2-3muqi8-f213e529-rx7d   <none>           <none>

4. Get the node labels:

   kubectlgetnodeNODE_NAME--show-labels\|grep"cloud.google.com/compute-class"

   ReplaceNODE_NAME with the name of the node fromthe output of the previous step.

   The output is similar to the following:

   NODE_NAME   Ready    <none>   22m   v1.32.4-gke.1236007# lines are omitted from this outputcloud.google.com/compute-class=COMPUTECLASS_NAME,cloud.google.com/gke-boot-disk=pd-balanced,cloud.google.com/gke-container-runtime=containerd

   The value inCOMPUTECLASS_NAME is one of the following:

   • Cluster-level default ComputeClass:default for nodes that werecreated by GKE Autopilot or by node poolauto-creation. Nodes in existing manually created node pools might nothave thecloud.google.com/compute-class label.
   • Namespace-level default ComputeClass: the name of the ComputeClassthat youconfigured as the namespace default.

Disable the default ComputeClass

To disable the default ComputeClass in a namespace or a cluster, do one of thefollowing:

• To disable the namespace-level default ComputeClass for all Pods, remove thecloud.google.com/default-compute-class label from the namespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class-

  The- character at the end of the label key removes any labels with thatkey from theNamespace object in the Kubernetes API.

• To disable the namespace-level default ComputeClass for non-DaemonSet Pods,remove thecloud.google.com/default-compute-class-non-daemonset label fromthe namespace:

  kubectllabelnamespacesNAMESPACE_NAME\cloud.google.com/default-compute-class-non-daemonset-

• To disable the cluster-level default ComputeClass, use thegcloud container clusters update command with the--no-enable-default-compute-class flag:

  gcloudcontainerclustersupdateCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--no-enable-default-compute-class

What's next

• Learn more aboutcustom ComputeClasses in GKE.