Docs gap: Kubernetes device-plugin GPU passthrough breaks OpenCL (tone-mapping) while VAAPI works, due to /dev/dri/by-path/* ownership

Start in the hardware-acceleration documentation and review the guidance for Kubernetes device-plugin setups. Document the /dev/dri/by-path/* ownership check for cases where VAAPI/QSV work but OpenCL-dependent features fail with ffmpeg exit 237, and explain that ATTACHED_DEVICES_PERMS=/dev/dri covers the paths. Done means the troubleshooting guidance includes this cause and fix.

Is there an existing issue for this?

• I have searched the existing issues

Description

Running this image under Kubernetes with a device plugin (e.g. Intel's intel-device-plugins-for-kubernetes), instead of a plain Docker --device /dev/dri bind mount, breaks OpenCL while VAAPI/QSV keep working.

Cause:

• The device plugin exposes /dev/dri/renderD128 and /dev/dri/card0, chowned root:root.
• /dev/dri/by-path/pci-<addr>-render and -card are also present (same major:minor), but the device plugin doesn't manage them — they keep the host's own group (render/video, arbitrary GID).
• Intel's OpenCL/NEO runtime opens the by-path render node, not renderD128. VAAPI/QSV work; OpenCL (Dolby Vision tone-mapping) fails, ffmpeg exit 237 (AVERROR(ENODEV)).

Fix: ATTACHED_DEVICES_PERMS=/dev/dri — same mechanism as #284 / #305. find /dev/dri -print recurses into by-path/ and covers the mismatched GID.

Evidence

Device ownership mismatch inside the container:

$ ls -la /dev/dri/ /dev/dri/by-path/
crw-rw---- 1 root root 226,   0 card0
crw-rw---- 1 root root 226, 128 renderD128
crw-rw---- 1 root video  226,   0 by-path/pci-0000:00:02.0-card
crw-rw---- 1 root 992    226, 128 by-path/pci-0000:00:02.0-render

strace on clinfo as the non-root PUID user, filtered to the relevant call:

openat(AT_FDCWD, "/dev/dri/by-path/pci-0000:00:02.0-render", O_RDWR|O_CLOEXEC) = -1 EACCES (Permission denied)

Resulting ffmpeg failure:

[AVHWDeviceContext] Failed to get number of OpenCL platforms: -1001.
Device creation failed: -19.
Failed to set value 'opencl=ocl@va' for option 'init_hw_device': No such device

ATTACHED_DEVICES_PERMS=/dev/dri picking it up correctly on container start:

**** permissions for /dev/dri/renderD128 are good ****
**** permissions for /dev/dri/card0 are good ****
**** creating group groupXXXX with id 992 ****
**** adding /dev/dri/by-path/pci-0000:00:02.0-render to group groupXXXX with id 992 ****
**** adding /dev/dri/by-path/pci-0000:00:02.0-card to group video with id 44 ****

Suggestion

Add a line to the hardware-acceleration docs: under Kubernetes/device-plugin setups, if VAAPI/QSV work but OpenCL-dependent features fail with ffmpeg exit 237, check /dev/dri/by-path/* group ownership. ATTACHED_DEVICES_PERMS=/dev/dri covers it.