// Module included in the following assemblies:
//
// microshift_configuring/microshift-gdp.adoc

:_mod-docs-content-type: PROCEDURE
[id="microshift-configuring-generic-device-plugin_{context}"]
= Configuring the Generic Device Plugin

The Generic Device Plugin (GDP) is disabled by default in {microshift-short}. To use the GDP, you must enable it and specify which host devices your Kubernetes applications can access. To enable the GDP, you must modify the {microshift-short} `config.yaml` file or create a configuration snippet file. For example, `/etc/microshift/config.d/10-gdp.yaml`.

.Prerequisites

* You installed {microshift-short}.
* You created a custom `config.yaml` file in the `/etc/microshift` directory.
* You installed the {oc-first}.
* You have `sudo` privileges on the {microshift-short} host.
* You have identified the specific host devices that you want to expose to your {microshift-short} node. For example, `/dev/video0`, `/dev/ttyUSB*`, or USB Vendor/Product IDs.

.Procedure

. From your CLI using `sudo` privileges, open `/etc/microshift/config.yaml` in a text editor.
+
. Locate the `genericDevicePlugin` section. If it is not present, add it.
+
. 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
[source,yaml]
----
apiServer:
# ...
genericDevicePlugin:
  devices:
  - groups:
    - paths:
      - path: /dev/ttyUSB* <1>
      - path: /dev/ttyACM* <2>
    name: serial
  - groups:
    - paths:
      - path: /dev/fuse <3>
    name: fuse <4>
  - groups:
    - usbs: <5>
      - product: "0x7523" <6>
        serial: ""
        vendor: "0x1a86" <7>
    name: converter
  domain: device.microshift.io <8>
  status: Enabled
----
<1> Exposes all the USB serial devices that are matched by this glob.
<2> Exposes all the ACM serial devices that are matched by this glob.
<3> For example, the file path for a fuse device.
<4> For example, the name of the device.
<5> Exposes a specific USB device by Vendor ID and Product ID.
<6> For example, the Product ID for a CH340 serial converter
<7> For example, the Vendor ID for a CH340 serial converter.
<8> 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`.
====
+
. Save the `config.yaml` file.

. Restart the {microshift-short} service to apply the changes:
+
[source,terminal]
----
$ sudo systemctl restart microshift
----
+
Allow some time for {microshift-short} to restart and for the GDP to register its devices with the Kubelet.

.Verification

* You can check the available devices in your node by running the following command:
+
[source,terminal,subs="+quotes"]
----
$ oc describe node _<microshift_node_name>_ | grep "device.microshift.io" <1>
----
<1> Replace _<microshift_node_name>_ with your node name.
+
* Depending on your configuration, expect output that indicates that the devices are now discoverable and schedulable within your {microshift-short} node.
+
.Example output
[source,terminal]
----
Capacity:
 cpu:                                2
 device.microshift.io/audio:         0
 device.microshift.io/capture:       0
 device.microshift.io/custom-device: 1
 device.microshift.io/dummy-video:   0
 device.microshift.io/fuse:          0
 device.microshift.io/serial:        5
 device.microshift.io/video:         0
Allocatable:
 cpu:                                2
 device.microshift.io/audio:         0
 device.microshift.io/capture:       0
 device.microshift.io/custom-device: 1
 device.microshift.io/dummy-video:   0
 device.microshift.io/fuse:          0
 device.microshift.io/serial:        5
 device.microshift.io/video:         0
Allocated resources:
 (Total limits may be over 100 percent, i.e., overcommitted.)
 Resource                           Requests     Limits
 --------                           --------     ------
 cpu                                450m (22%)   500m (25%)
 memory                             1550Mi (42%) 500Mi (13%)
 ephemeral-storage                  0 (0%)       0 (0%)
 hugepages-1Gi                      0 (0%)       0 (0%)
 hugepages-2Mi                      0 (0%)       0 (0%)
 device.microshift.io/audio         0            0
 device.microshift.io/capture       0            0
 device.microshift.io/custom-device 1            1
 device.microshift.io/dummy-video   1            1
 device.microshift.io/fuse          0            0
 device.microshift.io/serial        0            0
 device.microshift.io/video         0            0
----