infra-mgr (0.1.6)
Installation
pip install --index-url infra-mgrAbout 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-- typedHost/Group/Service, the internal representation everything else operates on.inventory.py-- read path: parsesansible-inventory --list --exportJSON.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 icinga2vars.*from a host's actual group membership and diffs against the real.conffile.commands/*.py-- one function per verb, no CLI concerns inside them.run.pydeliberately does NOT know what any given playbook does -- same "decide whether/what to run, hand off to ansible-playbook for how" split assync.py.output.py-- the one shareddump()used by every command's formatter exceptssh.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 realinfra-mgrCLI against a real ansible tree (site.yml+roles/) inside a throwaway container, nothing mocked. Needs Docker and--ansible-root/-rpointed at a real checkout -- seetests/e2e/README.mdandinfra-test --helpfor 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