Container Device Interface (CDI) for GPUs and Accelerators

GPUs, network adapters, and other accelerators need more than a container image to work inside a container: the workload also needs selected host device nodes, libraries, environment settings, and sometimes setup hooks. The Container Device Interface (CDI) gives hardware vendors and container runtimes a shared format for describing those additions. This explainer is for developers and platform operators who package device-enabled workloads or operate GPU and accelerator nodes.

What Is the Container Device Interface?

CDI is a specification for connecting vendor-managed devices to containers. A device provider writes a CDI spec describing the changes required for a device, and a CDI-aware container runtime applies those changes when a user requests that device. The CDI project maintains the format and libraries; its specification defines the device names and container edits.

A CDI device is requested using a qualified name such as vendor.example/gpu=card0: the part before = identifies a vendor and device kind, while the final part selects one device or a vendor-defined group. Names such as nvidia.com/gpu=0 are supplied by the vendor’s integration, not invented by the application author. The container runtime finds the corresponding local spec, checks the request, and adds the described edits to the container configuration.

CDI is an interface between device providers and container runtimes, not a GPU driver or a hardware abstraction that makes every accelerator interchangeable. It standardizes how a device’s container requirements can be declared and applied. Hardware discovery, names, libraries, and supported operations remain specific to the device provider.

The Problem CDI Solves

Container images make application files and user-space dependencies repeatable, but accelerators remain attached to the host. A GPU workload may need access to device files, driver libraries, environment variables, and vendor tools. Before CDI, container integrations often assembled those pieces through runtime-specific flags, hooks, or configuration. That can couple device support to one container engine and make upgrades or multi-runtime deployments harder to coordinate.

Kubernetes has a separate layer for allocating devices to Pods. Its device plugin mechanism lets a node-level plugin register hardware with the kubelet and advertise resources. That answers which workload can receive a device; a runtime still needs to make the allocated hardware usable inside the container. CDI can provide that last-mile injection when the plugin, vendor driver, and runtime support it.

How CDI Works

The typical flow has four parts:

1. The device provider discovers hardware. A driver or vendor tool detects devices and any supporting files on the host.
2. The provider creates CDI specs. It writes JSON descriptions to a directory that the runtime scans. These are usually generated or maintained by vendor software because paths and device capabilities change with drivers and hardware.
3. The workload requests a qualified device name. A runtime such as Podman receives a CDI name through its device option. The runtime resolves that name against the available specs.
4. The runtime applies the device edits. It merges the requested device’s edits into the OCI runtime configuration before starting the container.

The spec’s containerEdits can describe environment variables, device nodes, mounts, and hooks. For example, a device definition can map a host device node into the container and provide a matching environment variable. A provider can also describe edits common to all devices in a spec. Runtimes should apply device-specific edits only when that device is requested.

CDI and Kubernetes device allocation therefore solve different problems. A Kubernetes driver can decide which GPU belongs to a Pod, then use CDI to tell the runtime how to expose that GPU. CDI alone does not reserve a GPU, schedule a Pod, or enforce fair sharing.

CDI Components and Key Concepts

• CDI spec: A JSON file with a version, a kind, and one or more named devices. The kind identifies a vendor and device class, while each device name selects an entry within that class.
• Qualified device name: The value passed by a user or orchestrator, generally written as vendor.example/kind=device. The vendor defines valid names and whether names refer to individual devices or groups.
• Container edits: The requested changes to the OCI configuration. These may include device nodes, mounts, environment values, hooks, or other supported settings.
• Spec discovery: A runtime searches configured directories for CDI specs. Common locations include /etc/cdi and /var/run/cdi, but paths and behavior depend on the runtime and its configuration.
• Device provider: The driver, toolkit, or plugin that knows how to identify hardware and generate correct specs. The runtime consumes the spec; it does not replace the provider.
• Runtime support: The container engine must implement CDI and understand the spec version and fields used by the provider. Two engines can support CDI yet differ in configuration and supported details.

Real-World Uses

GPU workloads are a common use case. A vendor integration can describe which GPU device nodes and driver files a container needs, while the image contains the application and compatible user-space framework. Operators can request a device without copying a long list of host paths into every workload definition.

Kubernetes workloads can use CDI after the scheduler and a device plugin or DRA driver have selected an allocation. This separation is useful for clusters with multiple container runtimes or driver-managed accelerator types. Confirm compatibility across the Kubernetes driver, CDI spec generator, and node runtime; adopting CDI does not make those components interchangeable.

Other specialized devices can use the same general mechanism when access requires coordinated device nodes, mounts, or setup. Examples might include vendor accelerators or selected hardware interfaces. A spec should expose only the files and permissions required by the workload rather than granting broad host access.

Getting Started with CDI

CDI is not a standalone daemon that installs hardware support. Start with a supported Linux host, install the device driver and its vendor integration, and use a container runtime that supports CDI. For a local Podman environment, install Podman with the package manager for your distribution:

# Debian or Ubuntu
sudo apt-get update
sudo apt-get install podman

# Fedora
sudo dnf install podman

Ask the vendor integration which spec it generates, where it is written, and which qualified device names are valid. Do not create a real GPU spec by guessing host paths: device nodes, library paths, permissions, and supported fields depend on the driver and host. The following small JSON file illustrates the shape of a spec; the example device path is fictional and must not be used on a real host without a matching device:

{
  "cdiVersion": "0.6.0",
  "kind": "example.com/accelerator",
  "devices": [
    {
      "name": "card0",
      "containerEdits": {
        "deviceNodes": [
          {
            "path": "/dev/example-accelerator0",
            "hostPath": "/dev/example-accelerator0",
            "permissions": "rw"
          }
        ],
        "env": ["ACCELERATOR_DEVICE=card0"]
      }
    }
  ]
}

With a matching spec in a directory discovered by the runtime, request the CDI name when creating a container. Podman’s run documentation describes its --device option and CDI device support:

podman run --rm \
  --device example.com/accelerator=card0 \
  IMAGE COMMAND

Replace IMAGE and COMMAND with an image and device-aware command. For a configured NVIDIA host, for example, use the actual GPU CDI name generated on that host and an image containing nvidia-smi; a generic example.com spec does not grant access to an NVIDIA GPU.

Verify the host has CDI specs and the runtime can start the selected device:

ls -la /etc/cdi /var/run/cdi
podman info --debug
podman run --rm --device example.com/accelerator=card0 IMAGE COMMAND

If a device is not found, check that the provider generated a valid spec in a runtime search directory, that the requested name exactly matches its kind and device name, and that the runtime supports CDI. If container creation fails after resolution, inspect runtime logs and the provider’s driver compatibility notes. When Kubernetes is involved, also inspect the Pod and device allocation events; a valid CDI spec cannot resolve an unallocated or unavailable device.

Common Misconceptions

“CDI makes GPU workloads portable across every machine.” It makes device configuration easier to express consistently, but specs refer to host-specific paths and vendor-specific device names. The target machine still needs a compatible device, driver, generated spec, and runtime.

“CDI replaces Kubernetes device plugins or DRA.” It does not allocate capacity or influence scheduling. Kubernetes APIs and drivers choose devices for Pods; CDI can describe how the selected device is injected into the container.

“A CDI spec is harmless metadata.” Device nodes, mounts, permissions, and hooks affect the container’s access to the host. Treat vendor-generated specs as privileged configuration: trust the source, review changes, and grant only required access.

Related Articles

• Kubernetes Dynamic Resource Allocation for GPUs explains claim-based accelerator selection and Pod scheduling.
• Kubernetes Architecture Explained covers the control plane and node components involved in scheduling workloads.
• Docker Containers for Beginners explains images, runtimes, and the container lifecycle.
• GPU Acceleration for Video Processing introduces GPU drivers and software stacks used by accelerator workloads.

Changelog

• Initial publication; checked against the CDI specification and container runtime documentation.
• Last updated: 2026-10-06