Support Container Device Interface device labels in Docker executor
Description
The Gitlab Runner Docker Executor should support Container Device Interface (CDI) labels.
Problem
Container Device Interface (CDI) is a specification, for container-runtimes, to support third-party devices. It introduces an abstract notion of a device as a resource. Such devices are uniquely specified by a fully-qualified name that is constructed from a vendor ID, a device class, and a name that is unique per vendor ID-device class pair: vendor.com/class=unique_name. Docker (v25+) and Podman (v4.1+) both support CDI device specifications. Currently, this capability is not supported by the gitlab-runner docker executor due to how it processes device options.
The docker executor provides a configuration option to support device mapping into containers. The config.toml configuration runners.docker.devices accepts an array of host devices to share with the container. In accordance with the Docker standard device mapping permissions, each device entry is parsed as "host-path[:container-path[:permissions]]". When the container-path and permissions are left off, the gitlab-runner docker executor explicitly defines the container-path and permissions fields with assumed values (e.g. container-path=host-path, permissions=rwm). This implementation effectively disallows the usage of CDI labels for both Podman and Docker as the resulting device option is not recognized as a valid CDI device.
Example
Given a config.toml that contains a CDI device label:
[runners.docker]
devices = ["nvidia.com/gpu=all"]The resulting device specification nvidia.com/gpu=all:nvidia.com/gpu=all:rwm will be passed to either Podman or Docker. This results in an invalid device specification as it is neither CDI compliant, nor a standard host device.
Use Cases
Nvidia GPU Support on Podman
The Nvidia Container Toolkit v1.12+ includes support for generating CDI specifications and this also improves the compatibility of the NVIDIA container stack with certain features such as rootless containers. This is now the recommended approach for using Nvidia devices in the Podman environment, but currently it is not supported by the gitlab-runner docker executor due to how it processes the device options. The current approach relying on the --gpus option of Docker does not work with Podman to gain access to the host GPUs. In order to maintain drop-in replacement capability for Podman (#27119 (closed)), this should be supported to more broadly support Podman and the use of GPUs.
More Generalized Device Support for Docker/Podman
Other device vendors can provide CDI support and be able to map the capability into the container.
Benefits
This positions docker executor to be capable of supporting a broader range of devices and container runtime settings for emerging usage and adoption of the CDI specification.
It extends and maintains gpu/device support for Podman to be equivalent to Docker.
Proposal
-
Enable the ability to add valid CDI device labels to the runners.docker.devices configuration so that they can be provided to the underlying container environment. -
The host path portion could be regex matched to see if it is a valid CDI label. If it is, the label should utilized directly as a DeviceRequest instead of a DeviceMapping. Reference the Docker CLI: Support CDI devices link below for more info.
Implementation details
-
placeholder