From 7ee04de44167d722a65c4a2ddceb44c0a626d6db Mon Sep 17 00:00:00 2001
From: Daniel Bennett <dbennett@hashicorp.com>
Date: Thu, 3 Oct 2024 13:06:50 -0400
Subject: [PATCH 1/2] update example device readme

---
 plugins/device/cmd/example/README.md | 109 +++++++++++++++++++++++++--
 1 file changed, 103 insertions(+), 6 deletions(-)

diff --git a/plugins/device/cmd/example/README.md b/plugins/device/cmd/example/README.md
index 036aa515b3f5..42e2f2e7098c 100644
--- a/plugins/device/cmd/example/README.md
+++ b/plugins/device/cmd/example/README.md
@@ -5,15 +5,31 @@ reference.
 
 The example device plugin models files within a specified directory as devices. The plugin will periodically scan the directory for changes and will expose them via the streaming Fingerprint RPC. Device health is set to unhealthy if the file has a specific filemode permission as described by the config `unhealthy_perm`. Further statistics are also collected on the detected devices.
 
+# Installation
+
+```shell
+nomad_plugin_dir='/opt/nomad/plugins' # for example
+go build -o $nomad_plugin_dir/nomad-device-example ./cmd
+```
+
 # Config
 
-The configuration should be passed via an HCL file that begins with a top level `config` block:
+Example client agent config with our
+[plugin](https://developer.hashicorp.com/nomad/docs/configuration/plugin) block:
 
-```
-config {
-  dir = "/my/path/to/scan"
-  list_period = "1s"
-  unhealthy_perm = "-rw-rw-rw-"
+```hcl
+client {
+  enabled = true
+}
+
+plugin_dir = "/opt/nomad/plugins"
+
+plugin "nomad-device-example" {
+  config {
+    dir            = "/tmp/nomad-device"
+    list_period    = "1s"
+    unhealthy_perm = "-rwxrwxrwx"
+  }
 }
 ```
 
@@ -22,3 +38,84 @@ The valid configuration options are:
 * `dir` (`string`: `"."`): The directory to scan for files that will represent fake devices.
 * `list_period` (`string`: `"5s"`): The interval to scan the directory for changes.
 * `unhealthy_perm` (`string`: `"-rwxrwxrwx"`): The file mode permission that if set on a detected file will casue the device to be considered unhealthy.
+
+# Usage
+
+Create two instances of the device, one unhealthy:
+
+```shell
+mkdir -p /tmp/nomad-device
+cd /tmp/nomad-device
+touch device01 && chmod 0777 device01
+touch device02
+```
+
+It should be fingerprinted by the client agent after the ~`list_period`,
+which you can check with:
+
+```shell
+nomad node status -json -self | jq '.NodeResources.Devices'
+```
+
+```json
+[
+  {
+    "Attributes": null,
+    "Instances": [
+      {
+        "HealthDescription": "Device has bad permissions \"-rwxrwxrwx\"",
+        "Healthy": false,
+        "ID": "device01",
+        "Locality": null
+      },
+      {
+        "HealthDescription": "",
+        "Healthy": true,
+        "ID": "device02",
+        "Locality": null
+      }
+    ],
+    "Name": "mock",
+    "Type": "file",
+    "Vendor": "nomad"
+  }
+]
+
+```
+
+The value to put in job specification
+[device](https://developer.hashicorp.com/nomad/docs/job-specification/device)
+block, or a quota specification,
+is `"{Vendor}/{Type}/{Name}"` i.e. `"nomad/file/mock"`:
+
+`job.nomad.hcl`:
+
+```hcl
+job "job" {
+  group "grp" {
+    task "tsk" {
+      driver = "..."
+      config {}
+      resources {
+        device "nomad/file/mock" {
+          count = 1
+        }
+      }
+    }
+  }
+}
+```
+
+`dev.quota.hcl`:
+
+```hcl
+name = "dev"
+limit {
+  region = "global"
+  region_limit {
+    device "nomad/file/mock" {
+      count = 2 # to allow for deployments/reschedules
+    }
+  }
+}
+```

From 2256c25d8cfeb6f2525a38d13563cbc9fa89d664 Mon Sep 17 00:00:00 2001
From: Daniel Bennett <dbennett@hashicorp.com>
Date: Thu, 3 Oct 2024 13:24:36 -0500
Subject: [PATCH 2/2] untilde

Co-authored-by: Tim Gross <tgross@hashicorp.com>
---
 plugins/device/cmd/example/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/device/cmd/example/README.md b/plugins/device/cmd/example/README.md
index 42e2f2e7098c..3e5d6d1a6cf8 100644
--- a/plugins/device/cmd/example/README.md
+++ b/plugins/device/cmd/example/README.md
@@ -50,7 +50,7 @@ touch device01 && chmod 0777 device01
 touch device02
 ```
 
-It should be fingerprinted by the client agent after the ~`list_period`,
+It should be fingerprinted by the client agent after the `list_period`,
 which you can check with:
 
 ```shell