From 97064229b2a698ffe3246172b434641d5d9a61b3 Mon Sep 17 00:00:00 2001 From: Miguel Jacq Date: Sat, 10 Jan 2026 11:35:10 +1100 Subject: [PATCH] Doc updates for 0.4.0 --- src/content/_index.html | 20 +++++++++++++++----- src/content/docs.html | 28 +++++++++++++++++++++++++++- src/content/examples.html | 28 +++++++++++++++++++++------- 3 files changed, 63 insertions(+), 13 deletions(-) diff --git a/src/content/_index.html b/src/content/_index.html index 3fb5346..e19afab 100644 --- a/src/content/_index.html +++ b/src/content/_index.html @@ -211,8 +211,10 @@ ansible-playbook ./ansible/playbooks/"$(hostname -f)".yml
- 
# Compare two harvests and get a human-friendly report
-enroll diff --old /path/to/harvestA --new /path/to/harvestB --format markdown
+          
# Compare two harvests and get a human-friendly report (ignoring noise)
+enroll diff --old /path/to/harvestA --new /path/to/harvestB --format markdown \
+  --exclude-path /var/anacron \
+  --ignore-package-versions
 
 # Send a webhook when differences are detected
 enroll diff \
@@ -221,7 +223,15 @@ enroll diff \
   --webhook https://example.net/webhook \
   --webhook-format json \
   --webhook-header 'X-Enroll-Secret: ...' \
-  --exit-code

+  --ignore-package-versions \
+  --exit-code
+
+# Ignore a path and changes to package versions, and optionally
+# enforce the old state locally (requires ansible-playbook)
+enroll diff --old /path/to/harvestA --new /path/to/harvestB \
+  --exclude-path /var/anacron \
+  --ignore-package-versions \
+  --enforce
E-mail notifications are also supported. Run it on a systemd timer to alert to drift!
@@ -285,8 +295,8 @@ enroll explain /path/to/harvest.sops \
Diff
-
Drift report + webhook/email notifications.
-
+
Drift report + webhook/email notifications, or optionally enforce the previous state!
+
diff --git a/src/content/docs.html b/src/content/docs.html index af9b7a8..39ba28e 100644 --- a/src/content/docs.html +++ b/src/content/docs.html @@ -167,6 +167,11 @@ description: "How Enroll works: harvest, manifest, modes, and configuration." 
$ enroll manifest --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$(hostname -f)"
 $ ansible-playbook /tmp/enroll-ansible/playbooks/"$(hostname -f)".yml
+ +
+
Tip: role tags
+
Generated playbooks tag each role as role_<name> (e.g. role_users, role_services, role_other). You can target a subset with ansible-playbook ... --tags role_users.
+
@@ -241,7 +246,13 @@ exclude_path = /usr/local/bin/docker-*, /usr/local/bin/some-tool [manifest] no_jinjaturtle = true -sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D +sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D + +[diff] +# ignore noisy drift +exclude_path = /var/anacron +ignore_package_versions = true +# enforce = true # requires ansible-playbook on PATH
@@ -263,6 +274,21 @@ sops = 00AE817C24A10C2540461A9C1D7CDE0234DB458D

A great way to use enroll diff is to run it periodically (e.g via cron or a systemd timer). Below is an example.

+
+
Noise suppression
+
Use --exclude-path to ignore file/dir drift under specific paths (e.g. /var/anacron). Use --ignore-package-versions to ignore routine package upgrades/downgrades while still reporting added/removed packages.
+
+ +
+ 
$ enroll diff --old /path/to/harvestA --new /path/to/harvestB   --exclude-path /var/anacron   --ignore-package-versions
+
+ +
+
Optional: enforce the old harvest state (--enforce)
+
If drift exists and ansible-playbook is on PATH, Enroll can generate a manifest from the old harvest and apply it locally to restore expected state. It avoids package downgrades, and will often run Ansible with --tags role_... so only the roles implicated by the drift are applied. This is very much like a return to Puppet's agent mode!
+
+ +

Store the below file at /usr/local/bin/enroll-harvest-diff.sh and make it executable.

diff --git a/src/content/examples.html b/src/content/examples.html index 2cb1105..911423c 100644 --- a/src/content/examples.html +++ b/src/content/examples.html @@ -68,15 +68,13 @@ description: "Copy/paste recipes for Enroll: one host, fleets, drift detection,
Drift detection with enroll diff
- 
$ enroll diff \
-  --old /path/to/harvestA \
-  --new /path/to/harvestB \
-  --format markdown
+            
$ enroll diff --old /path/to/harvestA   --new /path/to/harvestB   --format markdown   --exclude-path /var/anacron   --ignore-package-versions
 $ enroll diff --old /path/to/golden --new /path/to/current \
-  --webhook https://example.net/webhook \
+  --webhook https://example.net/webhook  \
   --webhook-format json \
-  --webhook-header 'X-Enroll-Secret: ...' \
-  --exit-code

+  --webhook-header 'X-Enroll-Secret: ...'  \
+   --ignore-package-versions --exit-code
+

Use it in cron or CI to alert on change.

@@ -98,6 +96,22 @@ description: "Copy/paste recipes for Enroll: one host, fleets, drift detection,

Great for answering "why did it include/exclude that file?" before you generate a manifest.

+ +
+
+
Enforce the previous state with enroll diff --enforce
+
+ + 
$ enroll diff \
+  --old /path/to/harvestA \
+  --new /path/to/harvestB \
+  --enforce \
+  --format json
+
+
+

Enforcing the old harvest will restore its files/perms, missing packages, changed services or users, if ansible-playbook is on the PATH.

+
+