24.3d Why CDI replaces the hook-based approach for modern Kubernetes deployments¶

📘 Context Introduction¶

In the early days of GPU-accelerated containers, engineers relied on hooks to inject NVIDIA drivers, libraries, and devices into containers. While hooks worked, they were brittle, runtime-specific, and difficult to manage at scale — especially in Kubernetes. The Container Device Interface (CDI) emerged as a cleaner, more standardized replacement. This section explains why CDI has become the modern standard and why hooks are being phased out.

⚙️ What Were Hooks?¶

Hooks were scripts or binaries that ran at specific points during a container's lifecycle (e.g., before the container starts). The NVIDIA Container Toolkit used hooks to:

• Mount GPU devices (/dev/nvidia0, /dev/nvidiactl, etc.)
• Inject CUDA libraries into the container filesystem
• Set environment variables like NVIDIA_VISIBLE_DEVICES

Key limitation: Hooks were tied to specific container runtimes (like Docker or containerd) and required custom configuration files.

🛠️ What Is CDI?¶

CDI is a vendor-neutral, runtime-agnostic specification for exposing devices (GPUs, FPGAs, etc.) to containers. Instead of hooks, CDI uses:

• CDI specification files (YAML) that describe device capabilities
• CDI registry that stores these specs
• Runtime support built into containerd, CRI-O, and other runtimes

With CDI, the NVIDIA Container Toolkit generates a CDI spec file that Kubernetes and container runtimes can read directly — no hooks needed.

📊 Visual Representation: Modern CDI vs. Legacy Environment Variable Hooks¶

This diagram contrasts legacy environment variable runtime hooks (which intercept runc commands) with CDI explicit spec mappings.

🕵️ Why CDI Replaces Hooks¶

1. 🎯 Standardization Across Runtimes¶

2. 🔄 Simplified Lifecycle Management¶

• Hooks required engineers to manually manage hook injection order and ensure scripts existed on every node.
• CDI lets the container runtime handle device injection automatically — just reference the CDI device name (e.g., nvidia.com/gpu=all).

3. 🧩 Better Kubernetes Integration¶

Modern Kubernetes uses CDI annotations to request GPUs:

• With hooks, engineers had to rely on the NVIDIA device plugin to inject environment variables and mount devices.
• With CDI, the device plugin simply writes a CDI spec, and the runtime handles the rest — no hook scripts needed.

4. 🚀 Performance and Reliability¶

• Hooks run as external processes — they can fail silently or introduce latency.
• CDI is built into the runtime — device injection happens at the container creation stage with better error handling and atomicity.

5. 📦 Vendor Neutrality¶

• Hooks were NVIDIA-specific — other hardware vendors had to create their own hook mechanisms.
• CDI is an open standard (CNCF sandbox project) — any hardware vendor can write a CDI spec, and it works immediately with any CDI-compatible runtime.

🔍 Real-World Impact for Engineers¶

When you deploy a GPU workload in Kubernetes today:

With hooks (legacy): - You needed to ensure the NVIDIA Container Toolkit's hook files were present on every node. - The device plugin had to set environment variables like NVIDIA_VISIBLE_DEVICES. - Runtime configuration files had to reference these hooks.

With CDI (modern): - The NVIDIA Container Toolkit generates a CDI spec file (typically at /etc/cdi/nvidia.yaml). - You simply add a CDI annotation to your pod spec: nvidia.com/gpu=all. - The runtime reads the CDI spec and mounts devices/libraries automatically.

✅ Summary¶

CDI replaces hooks because it offers:

• Standardization — works across all CDI-compatible runtimes
• Simplicity — no custom hook scripts or configuration files
• Kubernetes-native — uses annotations instead of environment variables
• Vendor-neutral — any hardware vendor can adopt it
• Reliability — built into the runtime, not bolted on as an external process

For engineers building modern AI infrastructure, CDI is the default and recommended approach. Hooks remain available for backward compatibility, but all new deployments should use CDI.

Key takeaway: If you're setting up GPU-accelerated containers in Kubernetes, use CDI. It's simpler, more portable, and aligns with the future of container device management.