dra-driver-cpu

Kubernetes Dynamic Resource Allocation (DRA) driver for CPU resources. This repository implements a DRA driver that enables Kubernetes clusters to manage and assign exclusive CPUs to workloads using the DRA framework. 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).

IMPORTANT: The kubelet's CPUManager implements assignment of exclusive CPUs to workloads. The CPUManager and this DRA driver are mutually incompatible and only one can be enabled at a time on any given node. See Configuration for how to disable the CPUManager.

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.
• Two Device Exposure Modes: individual mode exposes each CPU as a selectable device for fine-grained placement; grouped mode exposes larger aggregates (NUMA node/socket) as consumable capacity for better scalability on large systems.
• 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.

How It Works

The driver runs as a single executable, deployed as a DaemonSet, that implements two core interfaces working together on each node:

• The DRA driver control loop discovers CPU topology, publishes ResourceSlice objects to the API server, and handles ResourceClaim allocation requests, writing the result as a CDI spec.
• An NRI plugin reads the CDI-injected cpuset for guaranteed containers and pins them via the cgroup cpuset controller, while dynamically managing the shared pool for everything else.

See How it Works for the detailed architecture, and Example ResourceSlices for sample driver output.

Getting Started

Your cluster's container runtime must support NRI and CDI - see Prerequisites.

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

See the Helm chart README for the full list of configuration options, and Getting Started for cluster setup, migrating from the deprecated manifest-based installation, and example workloads.

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

• Prerequisites - container runtime (NRI/CDI) requirements.
• Getting Started - installation, migration from install.yaml, and example usage.
• Configuration - kubelet prerequisites, command-line flags, and the Helm driverConfig file schema.
• How it Works - driver architecture, CDI, and NRI integration.
• Feature Support - supported/unsupported features and CPU Manager Options mapping.
• Matching CPU Manager Options - kubelet cpumanager policy options and their driver equivalents.
• Workload Configuration Requirements - how to set pod/container CPU requests alongside DRA claims.
• Custom Opaque CPUSet Allocation Overrides - explicit core assignment for --group-by=machine mode.
• Metrics - Prometheus metrics exposed by the driver.
• Example ResourceSlices - sample ResourceSlice output in each mode.
• Troubleshooting & Diagnostics - the dracpu-gatherinfo diagnostic tool.

Developer Documentation

• Testing - running unit/E2E tests and testing local changes in a Kind cluster.
• Linting - running and auto-fixing lint issues.
• Logging Guidelines
• Deep dive: PCI/PCIe root buses on Linux
• Deep dive: Linux topology reporting

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:

• Slack - preferred channels: #sig-node #wg-device-management
• Mailing List