[OSDOCS-17084] Resolves third set of ADV errors for 17084

microshift_configuring/microshift-disable-lvms-csi-provider-csi-snapshot.adoc

@@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can configure {microshift-short} to disable the built-in logical volume manager storage (LVMS) Container Storage Interface (CSI) provider or the CSI snapshot capabilities to reduce the use of runtime resources such as RAM, CPU, and storage.
 
 include::modules/microshift-disabling-lvms-csi-snapshot.adoc[leveloffset=+1]

microshift_configuring/microshift-gdp.adoc

@@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 The Generic Device Plugin (GDP) for {microshift-short} enables your containerized applications to securely access physical host devices, such as serial ports, video cameras, or sound cards directly from within Kubernetes pods. By using GDP, you can extend capabilities of {microshift-short} to support applications that require direct hardware interaction, such as Internet of Things (IoT) applications.
 
 include::modules/microshift-con-understanding-generic-device-plugin.adoc[leveloffset=+1]

modules/microshift-con-limitations-of-generic-device-plugin.adoc

@@ -6,7 +6,8 @@
 [id="microshift-limitations-of-generic-device-plugin_{context}"]
 = Limitations and considerations for the Generic Device Plugin
 
-Although the Generic Device Plugin (GDP) provides powerful capabilities for accessing host devices in {microshift-short}, it is important to understand its limitations and current status.
+[role="_abstract"]
+The Generic Device Plugin in {product-title} has limitations and considerations for exposing host devices. You can use this information to choose suitable devices, configure stable identifiers, and plan for performance.
 
 [id="microshift-devices-not-suited-generic-device-plugin_{context}"]
 == Devices not suited for the Generic Device Plugin

modules/microshift-con-understanding-generic-device-plugin.adoc

@@ -6,9 +6,10 @@
 [id="microshift-understanding-generic-device-plugin-con_{context}"]
 = Understanding the Generic Device Plugin
 
-The Generic Device Plugin (GDP) is a Kubernetes device plugin that enables applications running in pods to access host devices such as serial ports, cameras, and sound cards securely. This capability is especially important for edge and IoT environments where direct hardware interaction is a common requirement. The GDP integrates with the kubelet to advertise available devices to the node and facilitate their allocation to pods without requiring elevated privileges within the container itself.
+[role="_abstract"]
+The Generic Device Plugin in {product-title} is a Kubernetes device plugin that enables pods to access host devices such as serial ports, cameras, and sound cards securely. You can use it for edge and IoT workloads that require direct hardware access without elevated container privileges.
 
-The GDP is designed to handle devices that are initialized and managed by the operating system and do not require any special initialization procedures or drivers for a pod to use them.
+The GDP integrates with the kubelet to advertise available devices to the node and facilitate their allocation to pods without requiring elevated privileges within the container itself. It is designed to handle devices that are initialized and managed by the operating system and do not require any special initialization procedures or drivers for a pod to use them.
 
 Here are examples of generic devices that are suitable for the GDP:
 

modules/microshift-proc-configuring-generic-device-plugin.adoc

@@ -6,7 +6,8 @@
 [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`.
+[role="_abstract"]
+The Generic Device Plugin (GDP) is disabled by default in {microshift-short}. To expose host devices such as serial ports and cameras to pods in {product-title}, you can enable the Generic Device Plugin and define devices in the `config.yaml` file or create a configuration snippet file such as `/etc/microshift/config.d/10-gdp.yaml`.
 
 .Prerequisites
 
@@ -33,30 +34,40 @@ genericDevicePlugin:
   devices:
   - groups:
     - paths:
-      - path: /dev/ttyUSB* <1>
-      - path: /dev/ttyACM* <2>
+      - path: /dev/ttyUSB*
+      - path: /dev/ttyACM*
     name: serial
   - groups:
     - paths:
-      - path: /dev/fuse <3>
-    name: fuse <4>
+      - path: /dev/fuse
+    name: fuse
   - groups:
-    - usbs: <5>
-      - product: "0x7523" <6>
+    - usbs:
+      - product: "0x7523"
         serial: ""
-        vendor: "0x1a86" <7>
+        vendor: "0x1a86"
     name: converter
-  domain: device.microshift.io <8>
+  domain: device.microshift.io
   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.
++
+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]
 ====
@@ -84,9 +95,8 @@ Allow some time for {microshift-short} to restart and for the GDP to register it
 +
 [source,terminal,subs="+quotes"]
 ----
-$ oc describe node _<microshift_node_name>_ | grep "device.microshift.io" <1>
+$ oc describe node _<microshift_node_name>_ | grep "device.microshift.io"
 ----
-<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.
 +

modules/microshift-proc-deploying-applications-with-generic-devices.adoc

@@ -6,6 +6,7 @@
 [id="microshift-deploying-applications-with-generic-devices_{context}"]
 = Deploying applications that use generic devices
 
+[role="_abstract"]
 After the Generic Device Plugin (GDP) is configured and enabled in {microshift-short}, you can deploy Kubernetes workloads, such as pods, deployments, or `StatefulSets`, that request access to the host devices that you have exposed. Devices are made available inside the container without requiring the pod to run with elevated privileges.
 
 .Prerequisites
@@ -27,39 +28,40 @@ metadata:
 spec:
   containers:
   - name: container
-    image: <your_application_image> <1>
-    command: ["/path/to/your/app"] <2>
-    args: ["--device_path=/dev/video0"] <3>
+    image: <your_application_image>
+    command: ["/path/to/your/app"]
+    args: ["--device_path=/dev/video0"]
     resources:
-      limits: <4>
-        device.microshift.io/video: 1 <5>
-    securityContext: <6>
+      limits:
+        device.microshift.io/video: 1
+    securityContext:
       allowPrivilegeEscalation: false
       capabilities:
         drop: ["ALL"]
       runAsNonRoot: true
       seccompProfile:
         type: "RuntimeDefault"
 ----
-<1> Replace with your container image.
-<2> Replace with the command for your application.
-<3> For example, how your application might use the device.
-<4> 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.
-<5> A request for one instance of the `video` device.
-<6> 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.
++
+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.
+--
 +
 . Deploy the Kubernetes workload by applying the manifest to the {microshift-short} node by running the following command:
 +
 [source,terminal,subs="+quotes"]
 ----
-$ oc apply -f _<your-workload-manifest.yaml>_ <1>
+$ oc apply -f _<your_workload_manifest.yaml>_
 ----
-<1> Replace _<your_workload_manifest>_ with the name of your workload manifest.
-
-.Results
-
++
 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.
 
 .Verification
@@ -68,7 +70,5 @@ For example, if you requested `device.microshift.io/serial`, which maps to `/dev
 +
 [source,terminal,subs="+quotes"]
 ----
-$ oc exec -it _<pod_name>_ -- ls -l /dev/video0 <1>
-----
-<1> Replace _<pod_name>_ with the name of the pod.
-+
+$ oc exec -it _<pod_name>_ -- ls -l /dev/video0
+----

modules/microshift-ref-generic-device-plugin-configuration-parameters.adoc

@@ -6,7 +6,8 @@
 [id="microshift-generic-device-plugin-configuration-parameters_{context}"]
 = Generic Device Plugin configuration reference
 
-This section provides a detailed reference for the configuration parameters available for the Generic Device Plugin within the {microshift-short} `config.yaml` file.
+[role="_abstract"]
+The Generic Device Plugin configuration reference lists and describes the parameters in the `genericDevicePlugin` section of the` config.yaml` file in {product-title}. You can use this reference when you enable the GDP and define which host devices to expose.
 
 .GDP configuration fields definitions table
 [cols="1,2"]

modules/microshift-ref-generic-device-plugin-troubleshooting.adoc

@@ -6,4 +6,9 @@
 [id="microshift-generic-device-plugin-troubleshooting_{context}"]
 = Troubleshooting configuration issues
 
-If you encounter errors such as "invalid configuration: failed to parse device" or "cannot define both path and usbs at the same time", it means you have incorrectly mixed `paths` and `usbs` fields within the same `groups` entry for a device. Each `group` must exclusively use either `paths` or `usbs` to define its devices.
+[role="_abstract"]
+The following entries explain common Generic Device Plugin configuration issues and how to resolve them. 
+
+`Invalid configuration: failed to parse device`:: Occurs when you have incorrectly mixed `paths` and `usbs` fields within the same `groups` entry for a device. Each `group` must exclusively use either `paths` or `usbs` to define its devices.
+
+`Cannot define both path and usbs at the same time`:: Occurs when you have incorrectly mixed `paths` and `usbs` fields within the same `groups` entry for a device. Each `group` must exclusively use either `paths` or `usbs` to define its devices.