Chapter 9. Using the Generic Device Plugin

Procedure

1. From your CLI using sudo privileges, open /etc/microshift/config.yaml in a text editor.
2. Locate the genericDevicePlugin section. If it is not present, add it.

3. Set the status parameter to Enabled and define the devices that should be exposed. Each device definition needs a name and one or more groups. Each group can specify devices using paths, for file-based devices, including glob patterns, or usbs, for USB devices using Vendor/Product IDs. You cannot mix paths and usbs within the same device group.

   GDP fields with default values

   apiServer:
   # ...
   genericDevicePlugin:
     devices:
     - groups:
       - paths:
         - path: /dev/ttyUSB*
         - path: /dev/ttyACM*
       name: serial
     - groups:
       - paths:
         - path: /dev/fuse
       name: fuse
     - groups:
       - usbs:
         - product: "0x7523"
           serial: ""
           vendor: "0x1a86"
       name: converter
     domain: device.microshift.io
     status: Enabled

   where:

   /dev/ttyUSB*

   Specifies the file path for all the USB serial devices that are matched by this glob.

   /dev/ttyACM*

   Specifies the file path for all the ACM serial devices that are matched by this glob.

   /dev/fuse

   Specifies the file path for a fuse device.

   fuse

   Specifies the name of the device.

   0x7523

   Specifies the Product ID for a CH340 serial converter.

   0x1a86

   Specifies the Vendor ID for a CH340 serial converter.

   device.microshift.io

   Specifies the default domain for the GDP.

   Important
   • The output of the microshift show-config parameter might include pre-configured default paths for serial devices even if you have not explicitly configured them in config.yaml. These paths represent the default discovery settings if the Generic Device Plugin is enabled without specific user configuration.
   • For consistency and precise device targeting, especially when dealing with multiple similar devices, consider using stable device paths like /dev/serial/by-id/ or specific USB Vendor, Product, or Serial IDs instead of broad glob patterns like /dev/ttyUSB*.
   • The count parameter in a device group allows a single device, or a set of devices matched by a glob, to be allocated multiple times concurrently to different pods. If omitted, count defaults to 1.
4. Save the config.yaml file.

5. Restart the MicroShift service to apply the changes:

   $ sudo systemctl restart microshift

   Allow some time for MicroShift to restart and for the GDP to register its devices with the Kubelet.

Procedure

1. Define the device request in your Pod specification:

   apiVersion: v1
   kind: Pod
   metadata:
     name: device-app
   spec:
     containers:
     - name: container
       image: <your_application_image>
       command: ["/path/to/your/app"]
       args: ["--device_path=/dev/video0"]
       resources:
         limits:
           device.microshift.io/video: 1
       securityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop: ["ALL"]
         runAsNonRoot: true
         seccompProfile:
           type: "RuntimeDefault"

   where:

   spec.containers.image

   Specifies the container image.

   spec.containers.command

   Specifies the command for your application.

   spec.containers.args

   Specifies the arguments for your application. For example, how your application might use the device.

   spec.containers.resources.limits

   Specifies the resource limit for the device. The resource name must follow the pattern device.microshift.io/<device_name>, where <device_name> matches the name that you specified in your configuration file. This example requests one instance of the video device.

   spec.containers.securityContext

   Specifies the privilege escalation. Define and configure with the least privilege value to ensure that the container has only required permissions, such as access to the device file, and to restrict other capabilities for the container.

2. Deploy the Kubernetes workload by applying the manifest to the MicroShift node by running the following command:

   $ oc apply -f <your_workload_manifest.yaml>

   After the pod is running, the specified host device is available at its original path, or mountPath if specified, inside the container. Your application can then interact with it as if it were a local device.

   For example, if you requested device.microshift.io/serial, which maps to /dev/ttyUSB*, your application might find the device at /dev/ttyUSB0 or a similar path inside the container.