/gke-compute-classes

name: gke-compute-classes
description: >-
  Configures, optimizes, and troubleshoots GKE ComputeClasses. Use when configuring Spot VMs with on-demand fallback, targeting specific accelerators (GPUs/TPUs) or machine families, restricting ComputeClass access, or debugging pending pods related to node pool auto-creation. Do not use for cluster-level Node Auto Provisioning configuration or general GKE cluster creation.
metadata:
  category: Containers

<!-- disableFinding(LINE_OVER_80) -->

GKE ComputeClasses

Guidance on configuring, optimizing, and troubleshooting GKE ComputeClasses.

When to Use

• **Cost optimization:** Spot VMs with on-demand fallback.
• **GPU/TPU workloads:** Target specific accelerators (e.g., L4, H100, v5p).
• **Performance tuning:** Select specific machine families (c3, c4, n4).
• **Zone targeting:** Colocate workloads with zonal resources.

--------------------------------------------------------------------------------

Engagement Rules: Generalized First, Refine Later

ComputeClasses depend on zone availability, CUDs, and workload constraints. **Do not block the user's initial request.** If asked for YAML/recommendations:

1. **Provide Generalized Answer Immediately:** Fulfill request using best practices and placeholders (`<YOUR-ZONE-HERE>`).

• **CRITICAL CUD RULE:** You MUST state that the provided machine families

(e.g., N4, C4) are generic best-practice examples. You MUST explicitly state that the final choice of machine family should be aligned with the user's existing Committed Use Discounts (CUDs) or Reservations.

• **YAML REQUIREMENT:** Any generated YAML template MUST include a comment

near the `machineFamily` field: `# IMPORTANT: Align machineFamily with your existing CUDs/Reservations`.

• **MUST label initial YAML as `EXAMPLE TEMPLATE - DO NOT DEPLOY`.**
• **STRICT SCHEMA RULE:** NEVER hallucinate fields. Do NOT use

`spec.description`, `gvnic`, `transparentHugepageEnabled`, or `shutdownGracePeriodSeconds`. Use `bootDiskSize` (NOT `bootDiskSizeGb`).

• **YAML FORMATTING RULE:** NEVER quote integer or boolean values (e.g.,

use `bootDiskSize: 50`, not `bootDiskSize: "50"`). `imageType` MUST be lowercase.

• **CRITICAL AI/ML RULE:** DO NOT recommend Spot instances as the primary

priority for AI/ML Inference, *even if the workload is stateless*. Accelerator node startup latency is severe. The correct priority is: `Reservations -> On-Demand -> DWS FlexStart -> Spot`.

• **CRITICAL PROVISIONING RULE:** Do NOT confuse node pool auto-creation

with cluster-level Node Auto Provisioning. Starting with GKE `1.33.3-gke.1136000`, `nodePoolAutoCreation.enabled: true` in the ComputeClass achieves automatic node pools scoped directly to the ComputeClass. **It does NOT require turning on Node Auto Provisioning at the cluster level.**

• **CRITICAL TAINT RULE:** The ONLY redundant taint is re-adding

`cloud.google.com/compute-class` on **auto-created** pools — node pool auto-creation already applies AND auto-tolerates that key, so duplicating it breaks scheduling → REMOVE it (don't add a toleration). This is NOT "never add taints": an intentional **dedication/isolation** taint (e.g. `dedicated=ml:NoSchedule`) in `nodePoolConfig.taints` is valid — it keeps other workloads off, and the intended workloads need a matching toleration (normal K8s contract). Judge intent before deleting; only the compute-class key is redundant. **Manual pools STILL require `cloud.google.com/compute-class=<NAME>` as label AND taint to bind to the ComputeClass — never remove that.** **Schema limit:** a `nodePoolConfig.taints` key may NOT contain the reserved `kubernetes.io` substring (GKE Warden rejects it) — so the Cluster-Autoscaler-ignored prefixes (`startup-taint.`/`status-taint.cluster-autoscaler.kubernetes.io/`) cannot be set via a ComputeClass; those are node-pool-level taints.

• **CRITICAL GPU-TAINT RULE:** GKE auto-taints GPU nodes

`nvidia.com/gpu:NoSchedule` — this is separate from the `cloud.google.com/compute-class` auto-toleration and is NOT covered by it. A GPU Pod stuck `Pending` / `noScaleUp` is almost always missing the toleration. Add to the PodSpec: `tolerations: [{key: nvidia.com/gpu, operator: Exists}]`.

• **CRITICAL SPOT-TAINT RULE:** GKE auto-taints Spot nodes with

`cloud.google.com/gke-spot=true:NoSchedule`. Pods targeting a Spot priority tier *must* tolerate this taint, or they will stay `Pending` / `noScaleUp` with a scheduling block. Tell the user to add the matching toleration to their PodSpec: `tolerations: [{key: cloud.google.com/gke-spot, operator: Equal, value: "true", effect: NoSchedule}]`.

• **CRITICAL PRIORITYSCORE RULE:** A shared `priorityScore` makes one

tie-break tier (lowest unit cost wins), but applies to a MAXIMUM of 3 rules. NEVER emit more than 3 priorities at the same score; if the user asks for more (e.g. 5 families "all cheapest-available"), cap at 3 and say why.

• **CRITICAL STATEFUL RULE:** For PV workloads, do NOT mix Gen 2 (PD) and

Gen 4 (Hyperdisk) in `priorities[]` (attach failures). **Exception (GKE 1.35.3-gke.1290000+):** back data PVs with the built-in **`dynamic-rwo`** StorageClass (`type: dynamic` + `use-allowed-disk-topology: "true"`) — makes the autoscaler disk-topology-aware (scales only compatible nodes, skips incompatible-gen priorities), so mixing is safe. Default for stateful PV workloads; asset `dynamic-rwo-storageclass.yaml`.

• **CRITICAL POD-PRIVILEGE RULE:** For

`privileged`/`hostNetwork`/`hostPID`