add per-plugin example runbooks

Author: marcofortina

examples/runbooks/.gitignore

@@ -0,0 +1,3 @@
+# Local lab secrets must not be committed.
+lab-secrets.local.yaml
+*.local.yaml

examples/runbooks/README.md

@@ -0,0 +1,76 @@
+# Automax per-plugin smoke runbooks
+
+These examples live in the repository under `examples/runbooks`; no `/tmp` extraction step is required.
+
+Contents:
+
+- `runbooks/*.check.yaml`: one check-mode runbook per plugin or plugin family.
+- `RUNBOOK_INDEX.md`: plugin index and substep counts.
+- `lab-inventory.example.yaml`, `lab-vars.example.yaml`, `lab-secrets.example.yaml`: minimal lab examples.
+- `controller-fixtures/`: local controller-side fixtures for plugins that need source files or directories.
+- `scripts/`: small helpers to run one check or all checks.
+
+These runbooks are intended for `automax run --check`. They validate rendering, parameter validation, preview/manual coverage, and per-plugin coverage one plugin at a time. They are not ordered runtime smoke flows and they are not destructive workflows.
+
+## Setup
+
+From the Automax repository:
+
+```bash
+cd examples/runbooks
+
+export RB="$PWD"
+export INV="$RB/lab-inventory.example.yaml"
+export VARS="$RB/lab-vars.example.yaml"
+
+cp lab-secrets.example.yaml lab-secrets.local.yaml
+$EDITOR lab-secrets.local.yaml
+export SECRETS="$RB/lab-secrets.local.yaml"
+```
+
+`lab-secrets.example.yaml` intentionally contains empty values only. Populate `lab-secrets.local.yaml` locally and do not commit it. The local file is ignored by the `examples/runbooks/.gitignore` rules.
+
+`lab-vars.example.yaml` uses `controller-fixtures` as a relative path when commands are launched from `examples/runbooks`. The helper scripts pass an absolute path to avoid ambiguity.
+
+## Run one plugin
+
+Example for `ufw`:
+
+```bash
+python -m automax.cli.cli run \
+  --job "$RB/runbooks/64-ufw.check.yaml" \
+  --inventory "$INV" \
+  --vars "$VARS" \
+  --secrets "$SECRETS" \
+  --sudo-password-env AUTOMAX_SUDO_PASSWORD \
+  --var automax_controller_fixture_root="$RB/controller-fixtures" \
+  --check
+```
+
+Or use the helper:
+
+```bash
+"$RB/scripts/run-one-check.sh" 64-ufw
+```
+
+The helper also accepts the full relative path:
+
+```bash
+"$RB/scripts/run-one-check.sh" runbooks/64-ufw.check.yaml
+```
+
+## Run all per-plugin check runbooks
+
+```bash
+"$RB/scripts/run-all-checks.sh"
+```
+
+The helpers respect optional overrides:
+
+```bash
+INV=/path/to/inventory.yaml \
+VARS=/path/to/vars.yaml \
+SECRETS=/path/to/lab-secrets.local.yaml \
+AUTOMAX_SUDO_PASSWORD_ENV=AUTOMAX_SUDO_PASSWORD \
+"$RB/scripts/run-all-checks.sh"
+```

examples/runbooks/RUNBOOK_INDEX.md

@@ -0,0 +1,72 @@
+# Automax per-plugin smoke runbooks
+
+Per-plugin runbooks only. No combined runbook, no reused runtime smoke flow, and no separate destructive workflow.
+
+| File | Plugin/family | Substeps |
+|---|---:|---:|
+| `runbooks/01-alternatives.check.yaml` | `alternatives` | 3 |
+| `runbooks/02-apparmor.check.yaml` | `apparmor` | 8 |
+| `runbooks/03-archive.check.yaml` | `archive` | 6 |
+| `runbooks/04-assert.check.yaml` | `assert` | 5 |
+| `runbooks/05-auditd.check.yaml` | `auditd` | 8 |
+| `runbooks/06-authselect.check.yaml` | `authselect` | 1 |
+| `runbooks/07-backup.check.yaml` | `backup` | 9 |
+| `runbooks/08-blkid.check.yaml` | `blkid` | 1 |
+| `runbooks/09-block.check.yaml` | `block` | 12 |
+| `runbooks/10-capability.check.yaml` | `capability` | 1 |
+| `runbooks/11-cert.check.yaml` | `cert` | 11 |
+| `runbooks/12-chrony.check.yaml` | `chrony` | 3 |
+| `runbooks/13-cron.check.yaml` | `cron` | 5 |
+| `runbooks/14-db.check.yaml` | `db` | 5 |
+| `runbooks/15-download.check.yaml` | `download` | 1 |
+| `runbooks/16-env.check.yaml` | `env` | 1 |
+| `runbooks/17-facts.check.yaml` | `facts` | 5 |
+| `runbooks/18-findmnt.check.yaml` | `findmnt` | 1 |
+| `runbooks/19-firewalld.check.yaml` | `firewalld` | 11 |
+| `runbooks/20-fs.check.yaml` | `fs` | 27 |
+| `runbooks/21-fstab.check.yaml` | `fstab` | 4 |
+| `runbooks/22-group.check.yaml` | `group` | 5 |
+| `runbooks/23-health.check.yaml` | `health` | 4 |
+| `runbooks/24-hostname.check.yaml` | `hostname` | 1 |
+| `runbooks/25-hosts.check.yaml` | `hosts` | 1 |
+| `runbooks/26-http.check.yaml` | `http` | 3 |
+| `runbooks/27-iptables.check.yaml` | `iptables` | 9 |
+| `runbooks/28-journal.check.yaml` | `journal` | 2 |
+| `runbooks/29-kernel.check.yaml` | `kernel` | 8 |
+| `runbooks/30-limits.check.yaml` | `limits` | 1 |
+| `runbooks/31-local.check.yaml` | `local` | 1 |
+| `runbooks/32-log.check.yaml` | `log` | 2 |
+| `runbooks/33-login.check.yaml` | `login` | 1 |
+| `runbooks/34-lvm.check.yaml` | `lvm` | 12 |
+| `runbooks/35-mail.check.yaml` | `mail` | 1 |
+| `runbooks/36-mount.check.yaml` | `mount` | 6 |
+| `runbooks/37-multipath.check.yaml` | `multipath` | 3 |
+| `runbooks/38-network.check.yaml` | `network` | 10 |
+| `runbooks/39-nftables.check.yaml` | `nftables` | 6 |
+| `runbooks/40-pam.check.yaml` | `pam` | 14 |
+| `runbooks/41-password.check.yaml` | `password` | 1 |
+| `runbooks/42-pkg.check.yaml` | `pkg` | 18 |
+| `runbooks/43-pki.check.yaml` | `pki` | 3 |
+| `runbooks/44-platform.check.yaml` | `platform` | 1 |
+| `runbooks/45-plugin.check.yaml` | `plugin` | 1 |
+| `runbooks/46-process.check.yaml` | `process` | 5 |
+| `runbooks/47-remote.check.yaml` | `remote` | 1 |
+| `runbooks/48-resolver.check.yaml` | `resolver` | 2 |
+| `runbooks/49-secret.check.yaml` | `secret` | 3 |
+| `runbooks/50-selinux.check.yaml` | `selinux` | 6 |
+| `runbooks/51-ssh.check.yaml` | `ssh` | 8 |
+| `runbooks/52-sshd.check.yaml` | `sshd` | 2 |
+| `runbooks/53-sudo.check.yaml` | `sudo` | 5 |
+| `runbooks/54-sudoers.check.yaml` | `sudoers` | 1 |
+| `runbooks/55-swap.check.yaml` | `swap` | 3 |
+| `runbooks/56-sysctl.check.yaml` | `sysctl` | 7 |
+| `runbooks/57-system.check.yaml` | `system` | 1 |
+| `runbooks/58-systemctl.check.yaml` | `systemctl` | 12 |
+| `runbooks/59-systemd.check.yaml` | `systemd` | 4 |
+| `runbooks/60-timedatectl.check.yaml` | `timedatectl` | 3 |
+| `runbooks/61-tool.check.yaml` | `tool` | 2 |
+| `runbooks/62-transfer.check.yaml` | `transfer` | 4 |
+| `runbooks/63-udev.check.yaml` | `udev` | 7 |
+| `runbooks/64-ufw.check.yaml` | `ufw` | 6 |
+| `runbooks/65-user.check.yaml` | `user` | 11 |
+| `runbooks/66-wait.check.yaml` | `wait` | 5 |

examples/runbooks/controller-fixtures/source-dir/source.txt

@@ -0,0 +1 @@
+upload fixture

examples/runbooks/controller-fixtures/source.txt

@@ -0,0 +1 @@
+upload fixture

examples/runbooks/lab-inventory.example.yaml

@@ -0,0 +1,28 @@
+# Example only. You can keep using your existing /mnt/data/automax-full-plugin-lab/lab-full-plugin-inventory.yaml.
+servers:
+  lab01:
+    host: 192.168.1.100
+    groups: [ssh, lab]
+    # Optional, but recommended for plugin-smoke-04-storage-destructive.yaml
+    # when each VM has a different /dev/disk/by-id path.
+    # vars:
+    #   automax_lab_disk: /dev/disk/by-id/REPLACE_ME_LAB01_EMPTY_DISK
+    ssh:
+      user: "{{ secrets.ssh_user }}"
+      password: "{{ secrets.ssh_password }}"
+      missing_host_key_policy: reject
+      look_for_keys: false
+      allow_agent: false
+  lab02:
+    host: 192.168.1.101
+    groups: [ssh, lab]
+    # Optional, but recommended for plugin-smoke-04-storage-destructive.yaml
+    # when each VM has a different /dev/disk/by-id path.
+    # vars:
+    #   automax_lab_disk: /dev/disk/by-id/REPLACE_ME_LAB02_EMPTY_DISK
+    ssh:
+      user: "{{ secrets.ssh_user }}"
+      password: "{{ secrets.ssh_password }}"
+      missing_host_key_policy: reject
+      look_for_keys: false
+      allow_agent: false

examples/runbooks/lab-secrets.example.yaml

@@ -0,0 +1,9 @@
+# Example only. Copy this file to lab-secrets.local.yaml, fill it locally,
+# and keep populated secret files out of Git.
+ssh_user:
+ssh_password:
+smtp_password:
+postgres_password:
+mysql_password:
+oracle_password:
+automax_smoke_user_password:

examples/runbooks/lab-vars.example.yaml

@@ -0,0 +1,10 @@
+# Relative to examples/runbooks when commands are launched from this directory.
+# The helper scripts override this with an absolute path.
+automax_controller_fixture_root: controller-fixtures
+automax_lab_root: /tmp/automax-smoke
+automax_lab_acl_user: ubuntu
+# Optional placeholder used by storage-related check previews only.
+# Per-plugin files in runbooks/ are intended for --check mode.
+automax_lab_disk: /dev/disk/by-id/REPLACE_ME_EMPTY_5GB_DISK
+automax_lab_confirm_destroy: "no"
+deploy_public_key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDemo automax@example

examples/runbooks/runbooks/01-alternatives.check.yaml

@@ -0,0 +1,29 @@
+# Check-only plugin catalog. Run with automax run --check, not as a normal runtime job.
+apiVersion: automax.io/v1
+kind: Job
+metadata:
+  name: plugin-smoke-check-alternatives
+tasks:
+- id: alternatives
+  description: Check-mode catalog for alternatives plugins.
+  targets: all
+  tags:
+  - all-functions
+  - check
+  - alternatives
+  steps:
+  - id: catalog
+    substeps:
+    - id: alternatives_get
+      use: alternatives.get
+      with:
+        name: nginx
+    - id: alternatives_list
+      use: alternatives.list
+      with:
+        sudo: true
+    - id: alternatives_set
+      use: alternatives.set
+      with:
+        name: nginx
+        path: /tmp/automax-demo

examples/runbooks/runbooks/02-apparmor.check.yaml

@@ -0,0 +1,53 @@
+# Check-only plugin catalog. Run with automax run --check, not as a normal runtime job.
+apiVersion: automax.io/v1
+kind: Job
+metadata:
+  name: plugin-smoke-check-apparmor
+tasks:
+- id: apparmor
+  description: Check-mode catalog for apparmor plugins.
+  targets: all
+  tags:
+  - all-functions
+  - check
+  - apparmor
+  steps:
+  - id: catalog
+    substeps:
+    - id: apparmor_complain
+      use: apparmor.complain
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+    - id: apparmor_disable
+      use: apparmor.disable
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+        confirm: true
+    - id: apparmor_enforce
+      use: apparmor.enforce
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+    - id: apparmor_parser_validate
+      use: apparmor.parser_validate
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+    - id: apparmor_profile
+      use: apparmor.profile
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+        state: enforce
+        sudo: true
+    - id: apparmor_profile_assert
+      use: apparmor.profile_assert
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+        state: present
+    - id: apparmor_reload
+      use: apparmor.reload
+      with:
+        profile: /etc/apparmor.d/usr.sbin.nginx
+        sudo: true
+    - id: apparmor_status
+      use: apparmor.status
+      with:
+        sudo: true