[PR #23] [MERGED] Feature roadmap: history CLI, notifiers, targeting, custom-flow snapshots, canary rollout, --scan, run lock #23

New issue

Closed

opened 2026-06-11 14:02:04 +08:00 by ivenator1 · 0 comments

ivenator1 commented

2026-06-11 14:02:04 +08:00

Owner

📋 Pull Request Information

Original PR: https://github.com/ivenator1/proxmox-management/pull/23
Author: @ivenator1
Created: 6/11/2026
Status: ✅ Merged
Merged: 6/11/2026
Merged by: @ivenator1

Base: main ← Head: claude/feature-enhancement-planning-i63dw2

📝 Commits (10+)

9aa962a Add feature enhancement roadmap (2 small / 2 medium / 2 large)
0150b47 Add --history / --history-show CLI to view persisted runs (S1)
916ff0f Add generic webhook and Telegram notifier types (S2)
71ea158 Add --limit and --phases run targeting (M1)
2927765 Add PVE snapshot/rollback to the custom_update flow (M2, config v2)
3b8cb3d Add canary / staged rollout to remote, lxc, and vm phases (L1)
816039d Add fleet-update --scan: read-only pending-updates snapshot (L2 part 1)
72c2d16 Mark roadmap implementation status (S1-L1 done, L2 scan done)
a9913a2 Add fleet-wide run lock and pending-snapshot readers (L2 part 2 groundwork)
6e5f239 fix: defer lock dir mkdir to acquire time; bypass lock in cli/wrapper tests

📊 Changes

34 files changed (+3846 additions, -110 deletions)

View changed files

📝 .github/workflows/ci.yml (+1 -0)
📝 CLAUDE.md (+55 -10)
📝 config_templates/custom_system.yml.example (+13 -0)
➕ docs/FEATURE_ROADMAP.md (+183 -0)
📝 fleet-update.py (+75 -3)
📝 proxmox_fleet/cli.py (+130 -3)
📝 proxmox_fleet/driver.py (+352 -71)
📝 proxmox_fleet/flows/custom.py (+81 -7)
📝 proxmox_fleet/history.py (+58 -1)
📝 proxmox_fleet/inventory.py (+15 -0)
➕ proxmox_fleet/lock.py (+121 -0)
📝 proxmox_fleet/models/config.py (+19 -0)
📝 proxmox_fleet/models/settings.py (+21 -0)
📝 proxmox_fleet/notifiers.py (+35 -1)
➕ proxmox_fleet/scan.py (+372 -0)
📝 proxmox_fleet/status.py (+18 -0)
➕ roles/custom_update/molecule/custom_update_rollback/converge.yml (+18 -0)
➕ roles/custom_update/molecule/custom_update_rollback/molecule.yml (+36 -0)
➕ roles/custom_update/molecule/custom_update_rollback/prepare.yml (+110 -0)
➕ roles/custom_update/molecule/custom_update_rollback/verify.yml (+54 -0)

...and 14 more files

📄 Description

Implements the feature roadmap (docs/FEATURE_ROADMAP.md) — five complete features plus the groundwork for the web dashboard. Every commit shipped with unit tests, mypy/ruff/yamllint clean; the full suite grew from 640 to 770+ passing tests.

Small

S1 — --history / --history-show: view persisted runs from the CLI. New history_summary()/read_run() readers in history.py; table of past runs or replay of a stored briefing. Works without ansible-runner installed.
S2 — webhook + Telegram notifiers: two new notifiers: types — generic JSON webhook ({title, body, failed, timestamp} + custom headers) and Telegram sendMessage (plain text by default). No new dependencies.

Medium

M1 — --limit / --phases targeting: restrict a run to named hosts and/or LXC/VM ids, or to specific phases (remote,custom,lxc,vm,node,manager); pre-flight and notify always run. LXC limit mixes node names (whole node) and bare ids; the manager self-update is addressable via the manager token; unknown phase names fail loud.
M2 — custom-flow PVE snapshots (config v2): pve_vmid/pve_node/pve_type config keys give custom_update hosts the same BEFORE_UPDATE_AUTO snapshot → rollback-on-failure → delete-in-finally safety net as the lxc/vm flows (statuses FAILED + ROLLED BACK / FAILED (NO SNAPSHOT)); rollback_command remains the legacy fallback. New custom_update_rollback molecule scenario (verified locally, added to the CI matrix).

Large

L1 — canary / staged rollout: hosts flagged canary=true (inventory/host_vars) or listed in canary_hosts update first in the remote/lxc/vm phases; the rest run only if no canary failed and the post-soak Uptime Kuma checks pass (canary_soak_minutes), otherwise they're recorded as SKIPPED (canary failed). The LXC phase now discovers all nodes up-front so the canary wave spans nodes; with no canaries behavior is byte-identical to before.
L2 part 1 — fleet-update --scan: strictly read-only pending-updates snapshot — per-host pending OS packages (apt -s dist-upgrade / dnf check-update / apk version -l '<') plus per-LXC community-script app current → latest, written as pending-*.json next to the run history. Stopped CTs/templates are never started.
L2 part 2 groundwork — fleet-wide run lock + pending readers: flock-based proxmox_fleet/lock.py honored by both entry points for runs and scans (overlapping invocations exit 1 loudly; read-only commands unaffected), plus pending_summary()/read_pending() readers and dashboard_* settings. The FastAPI fleet-dashboard app itself (0.0.0.0:8421, token-protected trigger, SSE console, Pico.css UI) follows on this foundation — design recorded in the roadmap.

CLAUDE.md, vars.yml.example, and config_templates/custom_system.yml.example document every new flag, setting, and config key.

https://claude.ai/code/session_01HASE4GGnyrVztYbWQaajdn

Generated by Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/ivenator1/proxmox-management/pull/23 **Author:** [@ivenator1](https://github.com/ivenator1) **Created:** 6/11/2026 **Status:** ✅ Merged **Merged:** 6/11/2026 **Merged by:** [@ivenator1](https://github.com/ivenator1) **Base:** `main` ← **Head:** `claude/feature-enhancement-planning-i63dw2` --- ### 📝 Commits (10+) - [`9aa962a`](https://github.com/ivenator1/proxmox-management/commit/9aa962a75939d137a3168c80378d443c05bcb995) Add feature enhancement roadmap (2 small / 2 medium / 2 large) - [`0150b47`](https://github.com/ivenator1/proxmox-management/commit/0150b470d3db4dfd896169a86bccc0a1ecd7adac) Add --history / --history-show CLI to view persisted runs (S1) - [`916ff0f`](https://github.com/ivenator1/proxmox-management/commit/916ff0f18b90b1445d68da2c8a80300a5e0e871c) Add generic webhook and Telegram notifier types (S2) - [`71ea158`](https://github.com/ivenator1/proxmox-management/commit/71ea15808ee76ce830067c11b32d9ba0d10408bd) Add --limit and --phases run targeting (M1) - [`2927765`](https://github.com/ivenator1/proxmox-management/commit/2927765bfa3c66838dbabbafacc063e2aed8d220) Add PVE snapshot/rollback to the custom_update flow (M2, config v2) - [`3b8cb3d`](https://github.com/ivenator1/proxmox-management/commit/3b8cb3de211aad8cf326bd52e39e92d53f399133) Add canary / staged rollout to remote, lxc, and vm phases (L1) - [`816039d`](https://github.com/ivenator1/proxmox-management/commit/816039db2e89a7d8248f89dfd08972b7634847ad) Add fleet-update --scan: read-only pending-updates snapshot (L2 part 1) - [`72c2d16`](https://github.com/ivenator1/proxmox-management/commit/72c2d16e03cd73f61d02dddd2402523cbb0cd473) Mark roadmap implementation status (S1-L1 done, L2 scan done) - [`a9913a2`](https://github.com/ivenator1/proxmox-management/commit/a9913a2e02368248e08dc78f74cb5510b37788b3) Add fleet-wide run lock and pending-snapshot readers (L2 part 2 groundwork) - [`6e5f239`](https://github.com/ivenator1/proxmox-management/commit/6e5f239d529452acccf408d0bb2d24ede2cbf0a7) fix: defer lock dir mkdir to acquire time; bypass lock in cli/wrapper tests ### 📊 Changes **34 files changed** (+3846 additions, -110 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+1 -0) 📝 `CLAUDE.md` (+55 -10) 📝 `config_templates/custom_system.yml.example` (+13 -0) ➕ `docs/FEATURE_ROADMAP.md` (+183 -0) 📝 `fleet-update.py` (+75 -3) 📝 `proxmox_fleet/cli.py` (+130 -3) 📝 `proxmox_fleet/driver.py` (+352 -71) 📝 `proxmox_fleet/flows/custom.py` (+81 -7) 📝 `proxmox_fleet/history.py` (+58 -1) 📝 `proxmox_fleet/inventory.py` (+15 -0) ➕ `proxmox_fleet/lock.py` (+121 -0) 📝 `proxmox_fleet/models/config.py` (+19 -0) 📝 `proxmox_fleet/models/settings.py` (+21 -0) 📝 `proxmox_fleet/notifiers.py` (+35 -1) ➕ `proxmox_fleet/scan.py` (+372 -0) 📝 `proxmox_fleet/status.py` (+18 -0) ➕ `roles/custom_update/molecule/custom_update_rollback/converge.yml` (+18 -0) ➕ `roles/custom_update/molecule/custom_update_rollback/molecule.yml` (+36 -0) ➕ `roles/custom_update/molecule/custom_update_rollback/prepare.yml` (+110 -0) ➕ `roles/custom_update/molecule/custom_update_rollback/verify.yml` (+54 -0) _...and 14 more files_ </details> ### 📄 Description Implements the feature roadmap (`docs/FEATURE_ROADMAP.md`) — five complete features plus the groundwork for the web dashboard. Every commit shipped with unit tests, mypy/ruff/yamllint clean; the full suite grew from 640 to 770+ passing tests. ## Small - **S1 — `--history` / `--history-show`**: view persisted runs from the CLI. New `history_summary()`/`read_run()` readers in `history.py`; table of past runs or replay of a stored briefing. Works without ansible-runner installed. - **S2 — webhook + Telegram notifiers**: two new `notifiers:` types — generic JSON webhook (`{title, body, failed, timestamp}` + custom headers) and Telegram `sendMessage` (plain text by default). No new dependencies. ## Medium - **M1 — `--limit` / `--phases` targeting**: restrict a run to named hosts and/or LXC/VM ids, or to specific phases (`remote,custom,lxc,vm,node,manager`); pre-flight and notify always run. LXC limit mixes node names (whole node) and bare ids; the manager self-update is addressable via the `manager` token; unknown phase names fail loud. - **M2 — custom-flow PVE snapshots (config v2)**: `pve_vmid`/`pve_node`/`pve_type` config keys give `custom_update` hosts the same `BEFORE_UPDATE_AUTO` snapshot → rollback-on-failure → delete-in-finally safety net as the lxc/vm flows (statuses `FAILED + ROLLED BACK` / `FAILED (NO SNAPSHOT)`); `rollback_command` remains the legacy fallback. New `custom_update_rollback` molecule scenario (verified locally, added to the CI matrix). ## Large - **L1 — canary / staged rollout**: hosts flagged `canary=true` (inventory/host_vars) or listed in `canary_hosts` update first in the remote/lxc/vm phases; the rest run only if no canary failed and the post-soak Uptime Kuma checks pass (`canary_soak_minutes`), otherwise they're recorded as `SKIPPED (canary failed)`. The LXC phase now discovers all nodes up-front so the canary wave spans nodes; with no canaries behavior is byte-identical to before. - **L2 part 1 — `fleet-update --scan`**: strictly read-only pending-updates snapshot — per-host pending OS packages (apt `-s dist-upgrade` / dnf `check-update` / apk `version -l '<'`) plus per-LXC community-script app `current → latest`, written as `pending-*.json` next to the run history. Stopped CTs/templates are never started. - **L2 part 2 groundwork — fleet-wide run lock + pending readers**: flock-based `proxmox_fleet/lock.py` honored by both entry points for runs and scans (overlapping invocations exit 1 loudly; read-only commands unaffected), plus `pending_summary()`/`read_pending()` readers and `dashboard_*` settings. The FastAPI `fleet-dashboard` app itself (0.0.0.0:8421, token-protected trigger, SSE console, Pico.css UI) follows on this foundation — design recorded in the roadmap. CLAUDE.md, `vars.yml.example`, and `config_templates/custom_system.yml.example` document every new flag, setting, and config key. https://claude.ai/code/session_01HASE4GGnyrVztYbWQaajdn --- _Generated by [Claude Code](https://claude.ai/code/session_01HASE4GGnyrVztYbWQaajdn)_ --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

ivenator1 added the

pull-request

label

2026-06-11 14:02:04 +08:00

ivenator1 changed title from ~~[PR #23] Feature roadmap: history CLI, notifiers, targeting, custom-flow snapshots, canary rollout, --scan, run lock~~ to [PR #23] [MERGED] Feature roadmap: history CLI, notifiers, targeting, custom-flow snapshots, canary rollout, --scan, run lock

2026-06-11 15:01:46 +08:00

ivenator1 closed this issue

2026-06-11 15:01:46 +08:00

ivenator1 referenced this issue

2026-06-12 17:02:12 +08:00

[PR #26] FastAPI-Users session authentication for dashboard #26