Overview

Kubernetes Dynamic Resource Allocation (DRA) driver for CPU resources.

dra-driver-cpu is a Kubernetes Dynamic Resource Allocation (DRA) driver that assigns exclusive CPUs to workloads through ResourceClaims. This driver provides an alternative to the CPUManager functionality implemented in the kubelet, offering additional benefits such as advanced topology selection through the rich DRA API and alignment with other DRA-managed resources (like GPUs and high-speed NICs).

Getting Started

The recommended way to install the driver is via the provided Helm chart:

helm install dra-driver-cpu oci://registry.k8s.io/dra-driver-cpu/charts/dra-driver-cpu -n kube-system

The Quickstart walks through installing the driver and running a pod on exclusive CPUs, with a verification step after each stage. See the Helm chart README for the full list of configuration options, and Installation for compatibility, upgrade, and uninstall details.

Key Features

  • Topology-Aware CPU Discovery: Discovers the node’s full CPU topology by reading sysfs, including sockets, NUMA nodes, cores, SMT siblings, Last-Level Cache (LLC), core types (Performance/Efficiency), and optionally PCIe root locality.
  • Exclusive CPU Allocation: Pods requesting CPUs via a ResourceClaim are pinned to exclusive, guaranteed CPUs enforced through CDI and NRI.
  • Shared Pool Management: All other containers are dynamically confined to a shared pool made up of CPUs not exclusively assigned to any guaranteed container.
  • Grouped Device Exposure: grouped mode exposes NUMA node, socket, or machine aggregates as consumable capacity. The driver also implements an individual mode which is now deprecated; see Migrating from individual mode.
  • CPU Manager Feature Parity: Aims to match key kubelet CPUManager static policy options (e.g. PreferAlignByUnCoreCache, StrictCPUReservation) - see Feature Support for the full comparison.
  • Stateful Restarts: Synchronizes with existing pods on restart by inspecting CDI-injected environment variables, rebuilding its allocation state without disrupting running workloads.

Use Cases

Topology-aware CPU allocation per workload

Each workload requests its own exclusive CPUs through a ResourceClaim. A CEL selector constrains where the CPUs come from — for example, a specific NUMA node or socket — and the selection can be made per workload.

Example: a claim to request CPUs on socket 0.

The Pod YAML (left) and the ResourceClaim YAML (right). The Pod mirrors the claim's 8 CPUs in its cpu requests and limits and references cpus-on-socket0 by resourceClaimName; that ResourceClaim requests 8 CPUs, with a dotted box around the selector that restricts them to socket 0.

Allocation:

A machine with two sockets, each split into two NUMA nodes of two L3 cache groups; each group has eight cores sharing one L3 cache. The claim, limited to socket 0, gets all 8 CPUs of L3 group 2 on NUMA node 1.

The CEL selector only picks socket 0; the driver keeps the allocation as tight as possible, within a single NUMA node and packed into as few L3 caches as the free CPUs allow. To also pin to a specific NUMA node, a second selector on resource.kubernetes.io/numaNode can be used alongside the socket one.

To keep scheduler accounting correct, either:

  • enable the driver’s publishNodeAllocatableResourceMapping option (Kubernetes 1.37+ with the DRANodeAllocatableResources feature gate), or
  • mirror the claim’s CPU count in the container’s cpu requests and limits, as shown above.

See Workload Configuration Requirements for details.

CPU alignment with other DRA-managed resources

CPUs are allocated through the same DRA machinery as GPUs (e.g. the NVIDIA GPU DRA driver) and NICs (e.g. DraNet), so one claim can keep them on the same NUMA node or PCIe root. This helps avoid the extra latency and bandwidth contention of cross-socket traffic:

Example: one claim for CPUs, a GPU and a NIC that must share a PCIe root.

The Pod YAML (left) and the ResourceClaim YAML (right). The Pod mirrors the claim's 8 CPUs in its cpu requests and limits and references gpu-cpu-nic-claim by resourceClaimName; that ResourceClaim requests 8 CPUs, a GPU and a NIC, with a dotted box around the constraint that aligns them on one PCIe root.

Allocation:

A two-socket machine: each socket has memory, CPUs and two PCIe roots, each with one GPU and one NIC. The claim gets GPU 2 and NIC 2 behind the same PCIe root on socket 1, plus CPUs local to that root.

How It Works

The driver runs as a single executable, deployed as a DaemonSet on every node.

Inside the dra-driver-cpu DaemonSet, a DRA plugin and an NRI plugin sit on a shared core (orchestration, topology discovery, CPU allocation state). The DRA plugin publishes ResourceSlices to the API server; the scheduler allocates claims; the kubelet asks the DRA plugin to prepare the claim, which updates the CDI file; the kubelet creates the container through the container runtime; the runtime calls the NRI plugin and sets the container's cpuset.

See How it Works for the detailed architecture.

Troubleshooting

If you run into problems, run the dracpu gatherinfo diagnostic tool and attach its output when filing an issue — it collects the CPU topology and driver configuration needed to diagnose most problems quickly.

Documentation

User Documentation

Developer Documentation

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page. Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

You can reach the maintainers of this project at:

Last modified September 28, 2026: docs: publish the documentation as a website (991c540)