From d11f97f100d5d1853cd2ef174c62ab91f1ce6678 Mon Sep 17 00:00:00 2001
From: Evan Wies <evan@neomantra.net>
Date: Thu, 25 Jan 2024 17:40:40 -0500
Subject: [PATCH] Update the sfptpd doces

---
 CHANGELOG.md                                  |  4 +--
 examples/terraform/sfptpd/README.md           | 32 ++++++++++++++++++-
 .../terraform/sfptpd/files/sfptpd.nomad.tpl   |  9 +++---
 examples/terraform/sfptpd/main.tf             | 24 +++++++++-----
 4 files changed, 53 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17146d0..2bb9b93 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,10 +1,10 @@
 Changelog
 =========
 
-## v0.4.0 (2024-01-25)
+## v0.4.1 (2024-01-25)
 
  * Added `ptp` and `pps` device types. I'm more of a bottom, but I do like disciplining clocks.
- * Added `sfptpd` example at `examples/terraform/sfptpd`](./examples/terraform/sfptpd/main.tf)
+ * Added `sfptpd` example at [`examples/terraform/sfptpd`](./examples/terraform/sfptpd/main.tf)
 
 ## v0.3.0 (2024-01-24)
 
diff --git a/examples/terraform/sfptpd/README.md b/examples/terraform/sfptpd/README.md
index 4eba760..b9b70e6 100644
--- a/examples/terraform/sfptpd/README.md
+++ b/examples/terraform/sfptpd/README.md
@@ -1,6 +1,35 @@
 # `sfptpd` Nomad System Job Example
 
-Stands up sfptpd as a Nomad System Job using Terraform.  It requires `nomad-onload` plugin installed to discover the `ptp` devices.
+Stands up `sfptpd` as a Nomad System Job using  [Terraform](https://www.terraform.io).  It requires `nomad-onload` plugin installed to discover the `ptp` devices.
+
+For timekeeping to be avilable, the job must have several capabilities added.   The Nomad Job template requests it with [`cap_add` Docker driver config](https://developer.hashicorp.com/nomad/docs/drivers/docker#cap_add), but the Nomad Client must also be configured to allow it with [`allow_caps`](https://developer.hashicorp.com/nomad/docs/drivers/docker#allow_caps) and possibly `privileged` as well.
+
+Here's a matrix of settings for the `local`` values:
+
+| `is_privileged` | `device_type` | Result |
+|-----------------|---------------|------- |
+| `true`  | any | PTP/PPS devices available due to `privileged = true` and Docker settings |
+| `false`| `"pps"` or `"ptp"` | PPS or PTP devices will be availble |
+| `false`| `""` | Will run but **will not sync** because no timekeeping devices |
+
+```
+plugin "docker" {
+  config {
+    ....
+    allow_privileged = true
+    allow_caps = [
+      # default: https://developer.hashicorp.com/nomad/docs/drivers/docker#allow_caps
+      "audit_write", "chown", "dac_override", "fowner", "fsetid", "kill", "mknod",
+      "net_bind_service", "setfcap", "setgid", "setpcap", "setuid", "sys_chroot",
+      # timekeeping
+      "net_admin", "net_raw", "sys_time"
+    ]
+  }
+```
+
+----
+
+To stand it up with Terraform:
 
 ```
 cd examples/terraform/sfptpd
@@ -9,3 +38,4 @@ terraform apply
 ```
 
 This is my first stab at this, so don't take it as anything more than demonstrative.  But I do get clock sync.
+
diff --git a/examples/terraform/sfptpd/files/sfptpd.nomad.tpl b/examples/terraform/sfptpd/files/sfptpd.nomad.tpl
index 8f1c580..affb12a 100644
--- a/examples/terraform/sfptpd/files/sfptpd.nomad.tpl
+++ b/examples/terraform/sfptpd/files/sfptpd.nomad.tpl
@@ -38,7 +38,7 @@ job "sfptpd" {
 
         # Sorry, the nomad-onload plugin can't do *everything* for you!
         network_mode = "host"
-        privileged = true
+        privileged = "${IS_PRIVILEGED}"
         cap_add = [
           "net_bind_service",
           "net_admin",
@@ -47,10 +47,9 @@ job "sfptpd" {
         ]
       }
       resources {
-        device "ptp" {}
-        %{~ if lower("${ONLOAD_ENABLED}") == "true" ~}
-        device "onload" {}
-        %{~ endif ~} 
+        %{ if "${DEVICE_TYPE}" != "" }
+        device "${DEVICE_TYPE}" {}
+        %{ endif } 
       }
 
       template {
diff --git a/examples/terraform/sfptpd/main.tf b/examples/terraform/sfptpd/main.tf
index 9eef97e..8ed5a30 100644
--- a/examples/terraform/sfptpd/main.tf
+++ b/examples/terraform/sfptpd/main.tf
@@ -12,12 +12,19 @@
 
 # Yes, it should be variables, but this is a demo.
 locals {
-    # target this to your own infrastructure
-    nomad_address    = "http://localhost:4646"
-    nomad_datacenter = "*"
-    nomad_node       = "node1"
-    nic_interface    = "eth0"
-    sfptpd_image     = "onload/sfptpd:3.7.1.1007"
+  # target this to your own infrastructure
+  nomad_address    = "http://localhost:4646"
+  nomad_datacenter = "*"
+  nomad_node       = "node1"
+  nic_interface    = "eth0"
+  sfptpd_image     = "onload/sfptpd:3.7.1.1007"
+
+  # use either privileged mode to get all devices and caps
+  # is_privileged = "true"
+  # device_type   = ""
+  # or picka "pps" or "ptp" device
+  is_privileged = "false"
+  device_type   = "ptp"
 }
 
 terraform {
@@ -31,7 +38,7 @@ terraform {
 }
 
 provider "nomad" {
-    address = local.nomad_address
+  address = local.nomad_address
 }
 
 resource "nomad_variable" "sfptpd" {
@@ -48,6 +55,7 @@ resource "nomad_job" "sfptpd" {
     NOMAD_NODE_CONSTRAINT = local.nomad_node,
     NIC_INTERFACE         = local.nic_interface,
     SFPTPD_IMAGE          = local.sfptpd_image
-    ONLOAD_ENABLED        = "false"
+    IS_PRIVILEGED         = local.is_privileged
+    DEVICE_TYPE           = local.device_type
   })
 }