Metadata-Version: 2.4
Name: infra-mgr
Version: 0.1.5
Summary: CLI for querying, checking, and mutating an ansible YAML inventory
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# infra-mgr

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

## Install

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

## Usage

```sh
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

```sh
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:

```sh
./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:

```sh
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

```sh
$ 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
```
