Feature Requests
New / Open / Unreviewed

Adopt patchmon.core 2.0 as the official Ansible collection

Please adopt patchmon.core 2.0.0 as the official Ansible collection, replacing patchmon.dynamic_inventory 1.0.0.

The break is the dynamic inventory: install patchmon.core and set plugin: patchmon.core.inventory. Modules, roles, a lookup, and inventory filters are documented for advanced Ansible users. I run 2.0.0 in my homelab from the release tarball. It has tests, ansible-lint, and argument specs. Built in Cursor with Grok.

Proposal: mrjoshuap.github.io/PatchMon-ansible/docsite/proposal.html 

Fork: https://github.com/mrjoshuap/PatchMon-ansible

Covers

Dynamic inventory

feedback.patchmon.net/b/feature-requests/p…bkqs5fzst21twgbqvnze2 

Agent rollout 

feedback.patchmon.net/b/feature-requests/p…e5xncfzst242c0107agdf 

Patch management

feedback.patchmon.net/b/feature-requests/p…5ctqsenfvfjamcjdyxmqf

Compliance stays separate

feedback.patchmon.net/b/feature-requests/p…w69zbe04r3hm0efeedbxj

6 Comments

Write a comment...

Posting anonymously

JP
Josh Preston
Josh Preston·24 days ago

I'm almost done peeling my homelab development artifacts out of the repository and have been working on a reproducible development environment. To that end, there is now a dev container for the collection.

To try it, use Cursor or VS Code with Docker running. The image is based on ghcr.io/ansible/community-ansible-dev-tools, which already has Ansible, ansible-lint, and pytest. The local Dockerfile adds the requests library, sudo, and tree, and creates the dev user.

Clone the repository and open that folder, or use File → Open Workspace from File and open patchmon-ansible.code-workspace. From the Command Palette, run Dev Containers: Reopen in Container. On first start, .devcontainer/post-create.sh symlinks this checkout to .collections/ansible_collections/patchmon/core, so Ansible loads the working tree and there is no Galaxy install step.

The container does not keep credentials in later terminals. Copy .env.template to .env at the repo root (that file is gitignored), fill in the values, and source .env in each new terminal inside the container:

```bash

cp .env.template .env

# edit .env, then:

source .env

```

Set PATCHMON_SERVER_URL to the instance root, for example https://patchmon.example.com. Leave PATCHMON_API_URL and PATCHMON_ENROLLMENT_URL unset. The template and the plugin derive /api/v1/api/hosts and /api/v1/auto-enrollment from that root. PATCHMON_VERIFY_SSL is optional; true is the default, and false is for a lab only.

For inventory and the read-only plays, create an Integration API token under Settings → Integrations → API with host:get, and put the token key and secret in PATCHMON_API_KEY and PATCHMON_API_SECRET. PATCHMON_ENROLLMENT_KEY and PATCHMON_ENROLLMENT_SECRET are a separate Auto-Enrollment token (Settings → Integrations → Auto-Enrollment). They are only for plays that create a host or install the agent.

ansible.cfg in this checkout enables patchmon.core.inventory and sets the default inventory to examples/patchmon_inventory_stats.yml, so the next command is:

```bash

ansible-inventory --graph

```

The graph lists your hosts under PatchMon groups such as patchmon_automated, patchmon_no_reboot, and patchmon_manual when those groups exist in PatchMon, and under stats groups such as patchmon_security_required and patchmon_needs_reboot.

Read-only plays use that same inventory and only talk to the API from the container. For example:

```bash

ansible-playbook examples/playbooks/pending_updates.yml --limit patchmon_security_required

```

That prints pending packages. It does not change packages on the hosts. examples/playbooks/host_info.yml and examples/playbooks/report_health.yml are the same kind of check. host_info_by_id.yml and lookup_system.yml need -e patchmon_id=<uuid> and do not use the dynamic inventory.

The other plays change hosts, and they do not all use this inventory:

- apply_security_updates.yml and apply_all_updates.yml upgrade packages. maintain.yml runs report health, security updates, and reboot together.

- reboot_needed.yml reboots patchmon_automated hosts one at a time when patchmon_needs_reboot is true.

- enroll.yml installs the agent. Point it at an inventory of machines you can SSH to, and export the Auto-Enrollment key and secret. The host stays in that token's default group.

- retire.yml removes the agent and deletes the host record. It requires --limit, SSH to the host, and an Integration token with host:delete.

Git and SSH from the container are optional and only needed for commit signing or pushing. devcontainer.json already bind-mounts /run/host-services/ssh-auth.sock. To sign with a forwarded agent, also mount these host files:

- ~/.gitconfig at /tmp/host.gitconfig

- ~/.ssh/config, ~/.ssh/id_rsa.pub, and ~/.ssh/known_hosts under /tmp/host-ssh/ (all three together)

- ~/.config/git/allowed_signers at /tmp/host-ssh/allowed_signers when you verify signatures

Leave the private key in the agent. On startup, post-start.sh copies those files in, points IdentityAgent at the forwarded socket, and wraps ssh-keygen so Git signing uses that socket. I use 1Password's SSH and Git signing connector this way. Without the extra mounts, startup skips SSH config and signing, and the container still opens.

JP
Josh Preston
Josh Preston·25 days ago(edited)

Since v2.0.2 I shipped v2.0.3. The patching roles now fail in the open when they cannot update a host, and the failure text is a feedback post you can paste.

http://github.com/mrjoshuap/PatchMon-ansible/releases/tag/v2.0.3

apply_security_updates used to skip an eligible host whose package manager was not apt, dnf, or dnf5. It now fails that host. Apt with the listed-security opt-in left off is still a no-op. apply_all_updates already failed that case. Both failures name the package manager and OS, and include a subject and description for https://feedback.patchmon.net/ asking for that package manager in the roles.

The same pattern shows up in two other stops:

  • report_health still fails when the newest package report is not success. If the error says the package manager is unsupported, the message is a feedback draft for the agent. Any other report failure is unchanged.
  • agent install watches the enrollment script for an unsupported platform and fails with a feedback draft instead of only the script error. The script body is not copied into the message.
  • host enroll treats a 409 machine_id_match that includes host_id as already present. The same 409 without host_id fails with a feedback draft asking for host_id on that response. That request is also written up in PATCHMON-FEEDBACK.md.

JP
Josh Preston
Josh Preston·25 days ago

Since v2.0.0 I have been running patchmon.core in my homelab and cutting the follow-up releases from that. v2.0.2 is out: github.com/mrjoshuap/PatchMon-ansible/releases/tag/v2.0.2

v2.0.1 stopped calling session routes through the Integration API. Friendly name, notes, auto-update, host-down alerts, group membership, fetch-report, force-agent-update, and regenerate-credentials are UI or session actions, so the collection no longer pretends to set them. Inventory hostgroup is a group id or the exact PatchMon name. The docsite and role argument specs landed in that release.

v2.0.2 adds the three roles that turn PatchMon groups and stats into a patch job:

  • apply_security_updates upgrades dnf and dnf5 with the security-only flag when patchmon_update_state is security_required (or the security count is above zero). Apt has no matching flag, so those hosts stay unchanged unless you opt in. The opt-in reads host:get packages and upgrades only names PatchMon marks as security updates. Hosts in Manual are skipped. It then runs a local agent report.
  • apply_all_updates is the separate "everything pending" job: apt safe upgrade, dnf and dnf5 latest, same Manual skip, then an agent report. It is not part of the weekly maintain run.
  • reboot_needed reboots when the inventory hostvar patchmon_needs_reboot is true, one host at a time, and reports only if the reboot changed the host. Manual and No Reboot are skipped.

A maintain play refreshes inventory, fails any host whose newest package report is missing or not success, applies security updates, then reboots Automated. Enroll still installs the agent and leaves the host in the enrollment token's default group. Retire removes the agent and deletes the host record. Policy groups stay in PatchMon.

That is enough to schedule "security this week, reboot Automated one at a time, full upgrades only when I ask," with PatchMon as the source of who is eligible. Compliance summaries and group changes from a play wait on Integration API routes that do not exist yet.

JP
Josh Preston
Josh Preston·26 days ago

I'm also willing to assist maintaining of the collection or what-else is needed.

In my environment, I'm using Ansible Automation Platform (free with Red Hat Developer Account for up to 16 nodes) and have a number of different job templates and workflows setup. So far, it's working great. I effectively created some groups in patchmon that mean different patch styles that i target with the ansible inventory. before I started, I used the role to configure and auto-register the agent. Was very much fun.

JP
Josh Preston
Josh Preston·1 month ago

Compliance scope limitation link:

JP
Josh Preston
Josh Preston·1 month ago

Correct links: