Apply ComputeClasses to Pods by default

Autopilot Standard

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

You should already be familiar with custom ComputeClasses.

About default ComputeClasses

You can configure GKE clusters or specific namespaces to have a default ComputeClass. The default class that you configure applies to any 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:

If the namespace has a default ComputeClass, GKE modifies the Pod specification to select that ComputeClass.
If the namespace doesn't have a default ComputeClass, the cluster-level default class applies. GKE doesn't modify the Pod specification.

If your default ComputeClass has the activeMigration.optimizeRulePriority field set to true, this setting might affect workloads in your clusters. For more information, see Active 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 then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the gcloud 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 the compute/region property. If you use primarily zonal clusters, set the compute/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 that runs a version that supports setting a default ComputeClass at the cluster- or namespace-level. For more information, see the Requirements section.
If you're using a Standard mode cluster, ensure that you meet one of the following requirements:
- Enable autoscaling on at least one node pool in the cluster.
- If your Standard cluster runs a version earlier than 1.33.3-gke.1136000 and isn't enrolled in the Rapid release channel, 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 run GKE version 1.33.1-gke.1744000 or later.
To set a ComputeClass as the namespace-level default for only non-DaemonSet Pods, the cluster must run GKE version 1.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, see Manage 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 the Required permissions section:

Required permissions

The following permissions are required to configure cluster- or namespace-level default ComputeClasses:

container.customResourceDefinitions.create
container.customResourceDefinitions.update
container.customResourceDefinitions.get
container.customResourceDefinitions.list
container.namespaces.get
container.namespaces.list
container.pods.get
container.nodes.get
container.nodes.list
container.deployments.create
container.deployments.get
Add labels to namespaces: container.namespaces.update
Enable the cluster-level default ComputeClass: container.clusters.update

You might also be able to get these permissions with custom roles or other predefined roles.

Configure a default ComputeClass for a namespace

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

To apply a ComputeClass to all Pods in a namespace by default, add the cloud.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 to set as the default for the namespace.
If the command fails with the following error message, the namespace already has 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 the cloud.google.com/default-compute-class-non-daemonset label to that namespace:
```
kubectllabelnamespacesNAMESPACE_NAME\
cloud.google.com/default-compute-class-non-daemonset=COMPUTECLASS_NAME
```
If the command fails with the following error message, the namespace already has 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 the following 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 to set 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

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

Configure a default ComputeClass for a cluster

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

To enable setting a cluster-level default ComputeClass for a cluster, run the gcloud container clusters update command with the --enable-default-compute-class flag:
```
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 your cluster control plane, like us-central1.
You can also specify this flag when you create an Autopilot or Standard cluster.
Save the following manifest, which defines a ComputeClass named default:
```
apiVersion:cloud.google.com/v1
kind:ComputeClass
metadata:
name:default
spec:
priorities:
-machineFamily:n4
-machineFamily:n2
whenUnsatisfiable:ScaleUpAnyway
nodePoolAutoCreation:
enabled:true
```
This example manifest requests nodes that use N4 instances. If N4 instances aren't available, the ComputeClass requests N2 instances instead. You can configure the default ComputeClass with any of the available fields in the ComputeClass CustomResourceDefinition.
Apply the manifest to your cluster:
```
kubectlapply-fPATH_TO_MANIFEST
```
Replace PATH_TO_MANIFEST with the path to the manifest for the ComputeClass.

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

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

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

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

Verify the default ComputeClass behavior

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

Review the following example Deployment:

apiVersion:apps/v1
kind:Deployment
metadata:
name:helloweb
labels:
app:hello
spec:
selector:
matchLabels:
app:hello
tier:web
template:
metadata:
labels:
app:hello
tier:web
spec:
containers:
-name:hello-app
image:us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
ports:
-containerPort:8080
resources:
requests:
cpu:200m

This Deployment doesn't explicitly request a ComputeClass.

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
```
Replace NAMESPACE_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 the Pods.

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 GATES
helloweb-7795fbf856-58n5l 1/1 Running 0 9m21s 10.52.2.3 gke-cluster-1-nap-n2-highcpu-2-3muqi8-f213e529-rx7d <none> <none>

Get the node labels:
```
kubectlgetnodeNODE_NAME--show-labels\
|grep"cloud.google.com/compute-class"
```
Replace NODE_NAME with the name of the node from the 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 output
cloud.google.com/compute-class=COMPUTECLASS_NAME,cloud.google.com/gke-boot-disk=pd-balanced,cloud.google.com/gke-container-runtime=containerd
```
The value in COMPUTECLASS_NAME is one of the following:
- Cluster-level default ComputeClass: default for nodes that were created by GKE Autopilot or by node pool auto-creation. Nodes in existing manually created node pools might not have the cloud.google.com/compute-class label.
- Namespace-level default ComputeClass: the name of the ComputeClass that you configured as the namespace default.

Disable the default ComputeClass

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

To disable the namespace-level default ComputeClass for all Pods, remove the cloud.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 that key from the Namespace object in the Kubernetes API.
To disable the namespace-level default ComputeClass for non-DaemonSet Pods, remove the cloud.google.com/default-compute-class-non-daemonset label from the namespace:
```
kubectllabelnamespacesNAMESPACE_NAME\
cloud.google.com/default-compute-class-non-daemonset-
```
To disable the cluster-level default ComputeClass, use the gcloud 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 about custom ComputeClasses in GKE.