Google Kubernetes Engine (GKE) node memory swap lets GKE nodes use disk
space as virtual memory when physical memory is exhausted. Node memory swap can
help improve application resilience and prevent out-of-memory (OOM) errors for
certain workloads.

## When to use node memory swap

Use node memory swap to provide a buffer against OOM errors for memory-intensive
applications, especially during unexpected usage spikes. Node memory swap can
help improve your workload resilience, such as in the following scenarios:

- Run workloads with unpredictable memory patterns.
- Reduce the risk of applications crashing because of node memory exhaustion.
- Optimize costs by avoiding the need to overprovision memory for occasional peaks.

## How node memory swap works

When you enable node memory swap, GKE configures the node's
operating system to use disk space as virtual memory. This process provides a
buffer for applications that experience temporary memory pressure.

GKE calculates [container swap limits](https://kubernetes.io/docs/concepts/cluster-administration/swap-memory-management/) based on the container's memory
resource limits and the node's total memory.

You can configure swap on different storage types to balance performance and
cost:

- **Boot disk**: uses the node's boot disk for swap space.
- **Ephemeral Local SSD** : uses a Local SSD that is also shared with Pod ephemeral storage. If the node uses [mixed Local SSD capacity](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/node-memory-swap.md.txt#mixed-local-ssd), swap uses only the ephemeral storage portion of the Local SSDs.
- **Dedicated Local SSD**: reserves one or more Local SSDs exclusively for swap.

To protect sensitive data, GKE encrypts swap space by default using an ephemeral
key.

## Requirements and limitations

Node memory swap has the following requirements and limitations:

- GKE clusters must be version `1.34.1-gke.1341000` or later.
- Only Pods that have the `Burstable` Quality of Service (QoS) class can use node memory swap. For more information about QoS classes, see the Kubernetes documentation for [Pod quality of service classes](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/#burstable).
- To resize the memory resources of containers, you must set the [container resize policy](https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/#container-resize-policies) to `RestartContainer`.
- If you configure node memory swap to use a boot disk, the swap size cannot exceed 50% of the boot disk's total capacity.

If you configure node memory swap to use a Local SSD, you must ensure the following
requirements are met:

- The machine type must support Local SSDs. You can only use Local SSDs provisioned as [ephemeral storage](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt) or [mixed storage](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/mixed-local-ssd.md.txt). You can't use Local SSD provisioned as raw block device storage. For a list of supported swap profiles in this mode, see [Node memory swap with mixed Local SSD capacity](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/node-memory-swap.md.txt#mixed-local-ssd).
- Nodes must be provisioned with Local SSDs. The provisioning method depends on the machine series:
  - For first or second generation machine series, set the `--ephemeral-storage-local-ssd=count` flag.
  - For third or fourth generation machine series, choose a machine type that bundles Local SSDs.
- The default `e2-medium` machine type does not support Local SSDs, so you must select a different machine type.
- For instructions on how to create or update a cluster so it provisions Local SSDs, see [Provision and use Local SSD-backed ephemeral storage](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt).

## Best practices

Node memory swap is intended as a safety net for unpredictable memory spikes,
not a replacement for sufficient physical memory. For guidance on optimizing
workloads, see [Right-size your GKE workloads at scale](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/right-size-workloads-at-scale.md.txt).

You should also consider the following best practices when using node memory
swap:

- Isolate node memory swap-enabled nodes by [applying a taint to the node pool](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/isolate-workloads-dedicated-nodes.md.txt), for example, `gke-swap=enabled:NoSchedule`, and adding a corresponding toleration to the workloads intended to use swap.
- Size your node memory swap space appropriately. Insufficient node memory swap space might not prevent OOM errors, and excessive use can degrade performance.
- Monitor node memory swap use on your workloads. Frequent use of node memory swap can be an indicator of memory pressure.

## 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.

## Enable node memory swap

You can enable node memory swap on a cluster or node pool basis. To enable
node memory swap, create or update a `system-config.yaml` file that contains
the node memory swap configuration that you want. The following example
enables node memory swap with default settings:

```yaml
linuxConfig:
  swapConfig:
    enabled: true
```

There are additional settings that you can configure. This example configures
unencrypted swap to use 30% of an ephemeral Local SSD's storage:

```yaml
linuxConfig:
  swapConfig:
    enabled: true
    encryptionConfig:
      disabled: true
    ephemeralLocalSsdProfile:
      swapSizePercent: 30
```

For a list of optional fields that you can configure, see the [`LinuxNodeConfig` API documentation](https://docs.cloud.google.com/kubernetes-engine/docs/reference/rest/v1beta1/LinuxNodeConfig.md.txt#swapconfig).

### Enable node memory swap on a cluster

To enable node memory swap on a cluster, complete one of the following steps:

- To create a new cluster with node memory swap enabled, run the following
  command:

  ```bash
  gcloud container clusters create CLUSTER_NAME \
      --location=LOCATION \
      --cluster-version=1.34.1-gke.1341000 \
      --system-config-from-file=system-config.yaml
  ```

  Replace the following:
  - `CLUSTER_NAME`: the name of your new cluster.
  - `LOCATION`: the region or zone for your cluster.

  > [!NOTE]
  > **Note:** For Local SSDs on first and second generation machine types, pass the [`--ephemeral-storage-local-ssd` flag](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt).

- To update an existing cluster to enable node memory swap, run the following
  command:

  ```bash
  gcloud container clusters update CLUSTER_NAME \
      --location=LOCATION \
      --system-config-from-file=system-config.yaml
  ```

  Replace the following:
  - `CLUSTER_NAME`: the name of your new cluster.
  - `LOCATION`: the region or zone for your cluster.

### Enable node memory swap on a node pool

To enable node memory swap on a node pool, complete one of the following steps:

- To create a new node pool with node memory swap enabled, run the following
  command:

  ```bash
  gcloud container node-pools create NODEPOOL_NAME \
      --cluster=CLUSTER_NAME \
      --location=LOCATION \
      --node-version=1.34.1-gke.1293000 \
      --system-config-from-file=system-config.yaml \
      --machine-type=MACHINE_TYPE
  ```

  Replace the following:
  - `NODEPOOL_NAME`: the name of your new node pool.
  - `CLUSTER_NAME`: the name of your cluster.
  - `LOCATION`: the region or zone for your cluster.
  - `MACHINE_TYPE`: a compatible machine type. For Local SSDs, ensure that you choose a machine type that [bundles Local SSDs](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt), for example `n1-standard-1`.

  > [!NOTE]
  > **Note:** For Local SSDs on first and second generation machine types, pass the [`--ephemeral-storage-local-ssd` flag](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd.md.txt).

- To update an existing node pool to enable node memory swap, run the following
  command:

  ```bash
  gcloud container node-pools update NODEPOOL_NAME \
      --cluster=CLUSTER_NAME \
      --location=LOCATION \
      --system-config-from-file=system-config.yaml
  ```

  Replace the following:
  - `NODEPOOL_NAME`: the name of your node pool.
  - `CLUSTER_NAME`: the name of your cluster.
  - `LOCATION`: the region or zone for your cluster.

## Verify the configuration

To verify that node memory swap is enabled, complete the following steps:

1. Verify that the `system-config.yaml` is applied with the `swapConfig` settings
   by running the following command:

   ```bash
   gcloud container node-pools describe NODEPOOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --format='yaml(config.linuxNodeConfig.swapConfig)'
   ```
2. Verify the kubelet configuration exists on the node by running the following
   command:

   ```bash
   kubectl get --raw "/api/v1/nodes/NODE_NAME/proxy/configz" | jq .kubeletconfig.memorySwap
   ```

## Monitor memory swap use

You can monitor node memory with Cloud Monitoring or `kubectl`.

### Monitoring

The following system metrics are available by default for observing swap
usage:

- `kubernetes.io/node/memory/swap_used_bytes`
- `kubernetes.io/container/memory/swap_used_bytes`

GKE also provides container-level swap usage metrics through cAdvisor. To
use these metrics, [enable cAdvisor on the cluster](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/cadvisor-kubelet-metrics.md.txt):

- `prometheus.googleapis.com/container_memory_swap/gauge`

### kubectl

Monitor swap usage with `kubectl` commands by completing the following steps:

1. Check the `SwapDetected` condition on the node object by running the following command:

   ```bash
   kubectl get node NODE_NAME -o jsonpath='{.status.conditions[?(@.type=="Swap")]}' | jq .
   ```

   The output is similar to the following:

   ```json
   {
     "lastHeartbeatTime": "2025-07-11T00:14:52Z",
     "lastTransitionTime": "2025-06-25T05:20:10Z",
     "message": "Swap is active: Total=49Gi Used=0B Free=49Gi",
     "reason": "SwapDetected",
     "status": "True",
     "type": "Swap"
   }
   ```
2. Check the swap capacity by running the following command:

   ```bash
   kubectl get node NODE_NAME -o jsonpath='{.status.nodeInfo.swap}'
   ```

   The output is similar to the following:

   ```json
   {"capacity":53687087104}
   ```

## Node memory swap with mixed Local SSD capacity

> [!NOTE]
> **Note:** To use mixed Local SSD capacity for swap, your nodes must be running GKE version 1.37.0-gke.3570000 or later.

You can enable node memory swap on node pools that
[provision mixed Local SSDs](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/mixed-local-ssd.md.txt).
GKE supports the following swap profiles:

- **Boot disk (`bootDiskProfile`)**
- **Ephemeral Local SSD (`ephemeralLocalSsdProfile`)**: GKE allocates swap space from the ephemeral storage portion of the Local SSDs, not from the raw block partitions.

GKE does not support the dedicated Local SSD swap profile
(`dedicatedLocalSsdProfile`) with mixed Local SSDs.

If you use the ephemeral Local SSD profile, note the following:

- The `swapSizePercent` field is a percentage of the ephemeral capacity that you set with the `capacity` subfield, not the total physical Local SSD capacity. For example, with settings like `capacity=200GB` and `swapSizePercent: 20`, GKE allocates 40 GiB of swap.
- Swap space reduces the ephemeral storage available to your Pods. GKE calculates the [reserved ephemeral storage](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/plan-node-sizes.md.txt#local_ephemeral_storage_reservation) from the ephemeral capacity minus the swap size.
- The swap size can't exceed 80% of the ephemeral capacity minus the ephemeral storage that GKE reserves for system use. If the ephemeral capacity is too small to fit swap, the request fails.

The following example `system-config.yaml` file allocates 20% of the ephemeral
capacity to swap:

```yaml
linuxConfig:
  swapConfig:
    enabled: true
    ephemeralLocalSsdProfile:
      swapSizePercent: 20
```

To create a node pool with mixed Local SSD capacity and node memory swap, run the
following command:

```bash
gcloud container node-pools create POOL_NAME \
    --cluster=CLUSTER_NAME \
    --machine-type=MACHINE_TYPE \
    --ephemeral-storage-local-ssd count=NUMBER_OF_DISKS,capacity=CAPACITY \
    --system-config-from-file=system-config.yaml
```

Replace the following:

- `POOL_NAME`: the name of the new node pool you want to create.
- `CLUSTER_NAME`: the name of the cluster.
- `MACHINE_TYPE`: the machine type to use. You cannot use Local SSDs with the default `e2-medium` machine type, because [shared-core machine types](https://docs.cloud.google.com/compute/docs/disks/local-ssd.md.txt#limitations) don't support them.
- `NUMBER_OF_DISKS`: the number of Local SSD disks to provision on each node.
- `CAPACITY`: the total Local SSD capacity to format for ephemeral storage. This value must be greater than 0 and strictly less than the total physical Local SSD capacity (disk count × per-disk size), for example, `200GB`.

## Disable node memory swap

To disable node memory swap, update your `system-config.yaml` file by completing the following steps:

1. Update the `system-config.yaml` file to set `swapConfig.enabled` to `false`:

   ```yaml
   linuxConfig:
     swapConfig:
       enabled: false
   ```
2. Update the node pool with the new configuration:

   ```bash
   gcloud container node-pools update NODEPOOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --system-config-from-file=system-config.yaml
   ```

## What's next

- Learn more about [customizing node system configuration](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/node-system-config.md.txt).
- Learn more about [GKE storage options](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/storage-overview.md.txt).