This document shows you how to place workloads on a specific Compute Engine
machine series for optimal workload performance in your Google Kubernetes Engine (GKE)
Autopilot clusters.

Ensure that you're familiar with the following:

- [Compute Engine machine series and use cases](https://docs.cloud.google.com/compute/docs/machine-resource.md.txt#machine_type_comparison)
- Kernel-level requirements for your applications

## How machine series selection works

You can add a `cloud.google.com/machine-family` node selector to your Pod specification
for Autopilot to allocate specific Compute Engine hardware for
that Pod. For example, you can choose the C3 machine series for Pods that need more
CPU power, or the N1 machine series for Pods that need more memory.
To optimally run your workload, Autopilot
provisions one of the predefined machine types
from the machine series you selected.

In addition to optimal Pod performance, choosing a specific machine series offers
the following benefits:

- **Efficient node utilization**: By default, Autopilot optimizes node
  resource usage by scheduling onto each node as many Pods as possible that
  request the same machine
  series. This approach optimizes resource usage on the node, which
  improves the price-to-performance ratio. If your workload needs access to all of
  the resources on the node, you optionally can configure your workload to request
  one Pod for each node.

- **Burstable workloads:** You can configure Pods to *burst* into unused resource
  capacity on the node by setting your resource limits higher than your requests.
  For details, see [Configure Pod bursting in GKE](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/pod-bursting-gke.md.txt#burstable-capacity).

### Plan a dedicated node for each Pod

If you have CPU-intensive workloads that need reliable access to all of the node resources,
you can optionally configure your Pod to get Autopilot to place a Pod that requests
a machine series on its own node.

Dedicated nodes per Pod are recommended when you run large-scale, CPU-intensive
workloads, like AI/ML training workloads or high performance computing (HPC) batch workloads.

### Choose between multiple-Pod and single-Pod scheduling

Use the following guidance to choose a Pod scheduling behavior based on your requirements:

- If you have Pods that can share compute resources with other Pods or you want to optimize costs while running Pods on specialized hardware, use the [default scheduling behavior of multiple Pods per node](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#select-machine-series).
- If you have Pods that need reliable access to full node resources or you want to minimize the chance of disruptions caused by sharing compute resources, [Request a dedicated node for each Pod](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#one-pod-per-node).

## Pricing

You're billed for the underlying VM and any attached hardware by Compute Engine,
plus a premium for Autopilot node management and scalability. For details,
see [GKE pricing](https://cloud.google.com/kubernetes-engine/pricing#autopilot_mode).

## 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](https://console.cloud.google.com/apis/enableflow?apiid=container.googleapis.com)
- To use the Google Cloud CLI for this task, [install](https://docs.cloud.google.com/sdk/docs/install) and then [initialize](https://docs.cloud.google.com/sdk/docs/initialize.md.txt) 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]
  > **Note:** For existing gcloud CLI installations, make sure to set the `compute/region` [property](https://docs.cloud.google.com/sdk/docs/properties.md.txt#setting_properties). 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.

<!-- -->

- Ensure that you have an existing Autopilot cluster running version 1.30.1-gke.1396000 or later. To create a cluster, see [Create an Autopilot cluster](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/creating-an-autopilot-cluster.md.txt#set-version).

## Select a machine series

This section shows you how to select a specific Compute Engine machine
series in a Pod.

1. Save the following manifest as `machine-series-pod.yaml`:

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: machine-series-pod
   spec:
     nodeSelector:
       cloud.google.com/machine-family: MACHINE_SERIES
     containers:
     - name: my-container
       image: "k8s.gcr.io/pause"
       resources:
         requests:
           cpu: 5
           memory: "25Gi"
         limits:
           cpu: 20
           memory: 100Gi
   ```

   Replace `MACHINE_SERIES` with the Compute Engine machine
   series for your Pod, like `c3`. For supported values, see [Supported machine series](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#supported-machine-series)
   in this page.
2. Deploy the Pod:

   ```bash
   kubectl apply -f machine-series-pod.yaml
   ```

This manifest lets Autopilot optimize node resource usage by efficiently
scheduling other Pods that select the same machine series onto the same node if
there's available capacity.

### Use Local SSDs

Pods that select a machine series can use Local SSDs for ephemeral storage if you
specify a machine series that offers Local SSD. Autopilot considers ephemeral
storage requests when choosing a Compute Engine machine type for the Pod.

To learn more, see
[Use Local SSD-backed ephemeral storage with Autopilot clusters](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt#local-ssd-autopilot).

### Request a dedicated node for a Pod

If your Pod has specific performance requirements like needing reliable access to all
of the resources of your node, you can request a dedicated node for each Pod by specifying the
`cloud.google.com/compute-class: Performance` node selector along with your machine
series node selector. This indicates to Autopilot to place your Pod on a
new node that uses the specified machine series and is dedicated for that Pod.
This node selector also prevents Autopilot from scheduling other Pods on that node.

1. Save the following manifest as `dedicated-node-pod.yaml`:

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: dedicated-node-pod
   spec:
     nodeSelector:
       cloud.google.com/machine-family: MACHINE_SERIES
       cloud.google.com/compute-class: Performance
     containers:
     - name: my-container
       image: "k8s.gcr.io/pause"
       resources:
         requests:
           cpu: 12
           memory: "50Gi"
           ephemeral: "200Gi"
   ```

   Replace `MACHINE_SERIES` with a [supported machine series](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#supported-machine-series) that also supports one
   Pod per node scheduling. If the specified machine series doesn't support one
   Pod per node scheduling, the deployment fails with an error.
2. Deploy the Pod:

   ```bash
   kubectl apply -f dedicated-node-pod.yaml
   ```

When you deploy this manifest, Autopilot does the following:

- Ensures that the deployed Pod requests at least the [minimum resources for the performance-optimized node](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/autopilot-resource-requests.md.txt#compute-class-min-max).
- Calculates the total resource requests of the deployed Pod and any DaemonSets in the cluster.
- Provisions a node that's backed by the selected machine series.
- Modifies the Pod manifest with a combination of node selectors and tolerations to ensure that the Pod runs on its own node.

## Supported machine series

The `machine-family` selector supports the following machine series:

| Machine series | Node selector value | Supports multiple Pods per node | Supports single Pod per node |
|---|---|---|---|
| [C4N machine series](https://docs.cloud.google.com/compute/docs/network-optimized-machines.md.txt#c4n_series) (see [Version requirements](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#version-supported-machines)) | `c4n` | Yes | Yes |
| [C4D machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#c4d_series) (see [Version requirements](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#version-supported-machines)) | `c4d` | Yes | Yes |
| [C4A machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#c4a_series) (see [requirements and limitations](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/arm-on-gke.md.txt#arm-requirements-limitations)) | `c4a` | Yes | Yes |
| [C4 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#c4_series) *Default for the Performance class* | `c4` | Yes | Yes |
| [C3 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#c3_series) (see [Limitations](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#limitations)) | `c3` | Yes | Yes |
| [C3D machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#c3d_series) | `c3d` | Yes | Yes |
| [C2 machine series](https://docs.cloud.google.com/compute/docs/compute-optimized-machines.md.txt#c2_series) | `c2` | Yes | Yes |
| [C2D machine series](https://docs.cloud.google.com/compute/docs/compute-optimized-machines.md.txt#c2d_series) | `c2d` | Yes | Yes |
| [H4D machine series](https://docs.cloud.google.com/compute/docs/compute-optimized-machines.md.txt#h4d_series) | `h4d` | Yes | Yes |
| [H3 machine series](https://docs.cloud.google.com/compute/docs/compute-optimized-machines.md.txt#h3_series) | `h3` | Yes | Yes |
| [T2D machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#t2d_machines) | `t2d` | Yes | Yes |
| [T2A machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#t2a_machines) | `t2a` | Yes | Yes |
| [E2 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#e2_machine_types) | `e2` | Yes | No |
| [N4 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#n4_series) | `n4` | Yes | Yes |
| [N4D machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#n4d_series) (see [Version requirements](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#version-supported-machines)) | `n4d` | Yes | Yes |
| [N2 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#n2_series) | `n2` | Yes | No |
| [N2D machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#n2d_machines) | `n2d` | Yes | No |
| [N1 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#n1_machines) | `n1` | Yes | No |
| [Z3 machine series](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#z3_series) | `z3` | Yes | Yes |
| [Z4D machine series](https://docs.cloud.google.com/compute/docs/storage-optimized-machines.md.txt#z4d_series) (see [Version requirements](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/performance-pods.md.txt#version-supported-machines)) | `z4d` | Yes | Yes |

If you don't specify a machine series when you select the Performance class,
GKE uses the C4 machine series if C4 machine types are
[available in a region](https://docs.cloud.google.com/compute/docs/regions-zones.md.txt#available).

To compare these machine series and their use cases, see
[Machine series comparison](https://docs.cloud.google.com/compute/docs/machine-resource.md.txt#machine_type_comparison)
in the Compute Engine documentation.

### Limitations

- The predefined Performance ComputeClass doesn't support bare metal machine types, such as `c3-standard-192-metal`, `c4a-standard-72-metal`, and `c4d-standard-384-metal`. To use these machine types with Autopilot or node pool auto-creation, specify the exact machine type in a [custom
  ComputeClass](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/about-custom-compute-classes#machinetype-rule).

### Version requirements

See the following version requirements for specific machine series:

- **C4N** :
  - Without Local SSD: GKE version 1.36.0-gke.3009002 and later
  - With Local SSD: GKE version 1.37.2-gke.1434000 and later
- **C4D**: GKE version 1.32.9-gke.1711000 and later
- **N4D** :
  - GKE version 1.33.13-gke.1079000 and later
  - GKE version 1.34.1-gke.2037000 and later
- **C3 and C4A bare metal types** : GKE version 1.35.3-gke.1389000 and later (using a [custom
  ComputeClass](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/about-custom-compute-classes#machinetype-rule)).
- **C4D bare metal types** : GKE version 1.37.0-gke.4713000 and later (using a [custom
  ComputeClass](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/about-custom-compute-classes#machinetype-rule)).
- **Z4D**: GKE version 1.36.3-gke.1244000 and later.

## Compatibility with other GKE features

Pods that select a machine series can use the GKE capabilities and features supported by that machine series, such as:

- [Spot Pods](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/autopilot-spot-pods.md.txt)
- [Extended run time Pods](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/extended-duration-pods.md.txt) (only with dedicated nodes per Pod)
- [Workload separation](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/workload-separation.md.txt)
- [Capacity reservations](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/consuming-reservations.md.txt)
- [Committed-use discounts](https://docs.cloud.google.com/kubernetes-engine/cud.md.txt)

Spot Pods and extended run time Pods are mutually exclusive.
GKE doesn't enforce higher minimum resource requests for dedicated
Pods per node, even though they use workload separation.

## How GKE selects a machine type

To select a machine type in the specified machine series, GKE
calculates the total CPU, total memory, and total ephemeral storage requests of
the Pods and any DaemonSets that will run on the new node.
GKE rounds these values up to the nearest available
Compute Engine machine type that supports all of these totals.

- Example 1: Consider a Deployment with four replicas that selects the C3D machine series.
  You don't request dedicated nodes per Pod. The resource requests of each replica are as follows:

  - 500m vCPU (0.5 vCPU)
  - 1 GiB of memory

  Autopilot places all four Pods on a node that's backed by the
  `c3d-standard-4` machine type, which has 4 vCPUs and 16 GB of memory.
- Example 2: Consider a Pod that selects the `C3D` machine series and Local SSDs
  for ephemeral storage. You request a dedicated node for the Pod. The total resource
  requests including DaemonSets are as follows:

  - 12 vCPU
  - 50 GiB of memory
  - 200 GiB of ephemeral storage

  Autopilot places the Pod on a node that uses the `c3d-standard-16-lssd`
  machine type, which has 16 vCPUs, 64 GiB of memory, and 365 GiB of Local SSD capacity.

## What's next

- For guidance about the compute options that Autopilot offers for various use cases, see [Compute classes in Autopilot](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/autopilot-compute-classes).
- [Deploy GPU-based workloads in Autopilot](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/autopilot-gpus.md.txt).