infra-mgr (0.1.6)

Published 2026-09-27 19:32:12 +00:00 by alban

Installation

pip install --index-url  infra-mgr

About this package

CLI for querying, checking, and mutating an ansible YAML inventory

infra-mgr

CLI for querying, checking, and mutating an ansible YAML inventory, and for checking icinga2 host-registration conformity against it.

Install

pip install --user -e .
# or, with a real venv:
python3 -m venv .venv && .venv/bin/pip install -e . pytest pyyaml

Usage

infra-mgr ls hosts | ls groups | ls services
infra-mgr cat host <name> | cat group <name> | cat service <name>
infra-mgr ssh [--group <name>] [--lan] [--pager N]
infra-mgr add host <hostname> [--ipv4 ...] [--groups g1,g2]
infra-mgr add group <hostname> <group>
infra-mgr rm host <hostname> [--apply]            # remove host + all its group memberships
infra-mgr rm group <hostname> <group> [--apply]   # remove one membership only
infra-mgr check <hostname>                  # icinga2 registration conformity
infra-mgr sync <hostname> [--apply]         # check + fix (dry-run by default)
infra-mgr run <hostname> [playbook] [--apply]     # run any playbook (dry-run by default)
infra-mgr lint <playbook> [<playbook> ...]  # cross-check services.py against roles actually used

Run any subcommand with no arguments (or --help) to see worked examples, not just a bare usage line.

run is the general-purpose sibling to sync (which only ever knows how to fix icinga2 registration specifically): it builds ansible-playbook -i <inventory> -l <host> <playbook> and, same dry-run-by-default/ --apply pattern as sync, only prints the command unless you pass --apply. If playbook is omitted, it looks for site.yml next to the inventory file's own directory (e.g. <org>/site.yml when run with the default <org>/inventory/hosts.yml layout) -- anything without such a sibling (e.g. a flat /etc/ansible/hosts) has no derivable default and run says so rather than guess. Needs a real --inventory-yaml path -- --inventory-json is fixture/offline-only and isn't a valid ansible-playbook -i argument, so run refuses it outright.

lint is a pure static check, no ansible/live target/inventory needed: it parses the roles: lists out of the given playbook file(s) and cross-checks them against services.py's SERVICES table two ways -- every service's declared role should be used by some play (else the table is stale), and every composite role used in a play should have a service entry (else a new composite was added without registering it). Pass one org's playbooks together (e.g. infra-mgr lint site.yml backup.yml) -- run per-org, not mixed across orgs, since a service genuinely unused by one org is expected, not a bug, and running org-by-org keeps the tool from reporting expected absences as findings. Exits non-zero (with the specific role/service names) if anything's out of sync.

check/sync's --icinga-conf-dir defaults to the standard Debian icinga2 path (/etc/icinga2/conf.d/hosts.d) -- override it for tests or an unusual setup.

rm is the mirror of add, same dry-run-by-default/--apply pattern as sync/run: rm host removes the host from the inventory AND every group it currently belongs to (an add host call can add to several groups at once; the reverse removes all of them too, so no group-membership entry is left pointing at a host that no longer exists). rm group only removes one membership, leaving the host and its other groups untouched. Neither writes anything without --apply -- the dry-run output shows exactly what would be removed.

All output (except ssh, which must stay plain space-separated for tools like cssh to consume) is real YAML via yaml.safe_dump.

By default, reads/writes inventory/hosts.yml relative to your current working directory (override with --inventory-yaml). A missing or invalid inventory path (including a real file that just isn't a valid inventory source) raises a clear error rather than silently returning empty output. Pass --inventory-json <export.json> to point at a pre-captured ansible-inventory --list --export dump instead (used by the test suite's fixture, also handy for offline inspection).

check/sync may need elevated privileges on a real target: they read /etc/icinga2/conf.d/hosts.d/<host>.conf directly, which an unprivileged user typically can't. Run these two with sudo infra-mgr ... if you hit a permissions error; ls/cat/ssh/add/rm don't need it.

Design

  • models.py -- typed Host/Group/Service, the internal representation everything else operates on.
  • inventory.py -- read path: parses ansible-inventory --list --export JSON.
  • store.py -- write path: reads/mutates/writes the structured YAML inventory source directly. Every mutation persists immediately.
  • services.py -- static service -> group metadata (which role, which icinga check).
  • conformity/icinga2.py -- derives expected icinga2 vars.* from a host's actual group membership and diffs against the real .conf file.
  • commands/*.py -- one function per verb, no CLI concerns inside them. run.py deliberately does NOT know what any given playbook does -- same "decide whether/what to run, hand off to ansible-playbook for how" split as sync.py.
  • output.py -- the one shared dump() used by every command's formatter except ssh.
  • cli.py -- argparse wiring only.

Tests

python3 -m pytest

All tests run against tests/fixtures/inventory_export.json, a fixture with fabricated hostnames/secrets -- no live inventory, ansible install, or SSH access needed to run the suite.

Three tiers, one runner: infra-test

The command above (python3 -m pytest) is the fast unit tier only -- it mocks the Runner callable for sync/run (see test_sync.py) and never actually invokes real ansible-playbook. That gap is exactly what the e2e tier below exists to close: a command can build a plausible-looking ansible-playbook invocation that's subtly wrong (missing -i, a --tags that doesn't exist) and the unit suite alone would never catch it, since it never runs the real subprocess.

./infra-test runs all three tiers and reports one YAML document, readable by a human or an LLM agent equally:

./infra-test                              # everything: unit, molecule, e2e
./infra-test -u                           # just the fast unit suite (no Docker needed)
./infra-test role nrpe_check              # molecule, scoped to one role
./infra-test command sync                 # unit, scoped to sync-ish tests (pytest -k, approximate)
./infra-test -e -r /path/to/ansible/checkout --groups web,mysql
./infra-test -a --out results.yml         # everything, written to a file instead of stdout
  • unit -- this directory's own suite (above), always runnable.
  • molecule -- <role>/molecule/default/ for every role with a real scenario. Needs Docker.
  • e2e -- tests/e2e/, drives the real infra-mgr CLI against a real ansible tree (site.yml + roles/) inside a throwaway container, nothing mocked. Needs Docker and --ansible-root/-r pointed at a real checkout -- see tests/e2e/README.md and infra-test --help for the one-time setup.

Output shape (per tier): a header with an HTTP-flavored return_code (200 all passed, 400 the tier ran and something failed, 500 the tier could not run at all -- e.g. Docker missing) plus counts/timing, and a body listing {check_name, message} for whatever failed (empty when return_code is 200). The process exits 0 only if every tier that ran was 200, 1 otherwise -- never fails fast in multi-tier runs, so one invocation surfaces the whole backlog to fix, not one failure at a time across repeated pushes.

Molecule and e2e both need Docker -- infra-test reports a clean 500 rather than failing opaquely when Docker isn't available.

Deploying against a real inventory

This CLI has no org-specific logic -- point --inventory-yaml at whatever real inventory you're managing:

infra-mgr --inventory-yaml /path/to/inventory/hosts.yml ls hosts

add/rm --apply/sync --apply mutate whatever file --inventory-yaml points at -- double-check you're pointed at the file you actually mean to change before running with --apply.

Example session

$ infra-mgr --inventory-yaml inventory/hosts.yml cat host host1.example.org
host: host1.example.org
vars:
  vpn_address: 10.254.0.254
  vpn_interface: tinc0
  vpn_software: tinc
  web_software: apache2
groups:
- mysql
- vpn
- web

$ sudo infra-mgr --inventory-yaml inventory/hosts.yml check host1.example.org
host: host1.example.org
ok: false
missing_in_icinga2_config:
- mysql
- vpn

$ infra-mgr --inventory-yaml inventory/hosts.yml sync host1.example.org
# dry-run: prints the ansible-playbook command that would fix it

$ infra-mgr --inventory-yaml inventory/hosts.yml sync host1.example.org --apply
# applies it for real

Requirements

Requires Python: >=3.10
Details
PyPI
2026-09-27 19:32:12 +00:00
6
71 KiB
Assets (2)
Versions (6) View all
0.4.0 2026-10-13
0.3.1 2026-10-07
0.3.0 2026-10-06
0.2.0 2026-10-06
0.1.6 2026-09-27