FabledSteward/docs/core/ansible.md

Ansible Integration

Steward can browse, trigger, and stream output from Ansible playbooks directly from the web UI. Runs execute as asyncio tasks inside the same process — no Celery, no external workers.

---

Playbook Sources

Sources are configured at /settings/ under Ansible. Two source types are supported:

Local Filesystem

Points to a directory on the host that already contains playbooks.

# In app_settings (configured via UI)
ansible.sources:
  - name: "homelab"
    type: local
    path: "/opt/playbooks"

Git Repository

The app clones or pulls the repo into a local cache directory on a configurable schedule. All execution uses the local cache.

ansible.sources:
  - name: "infra-repo"
    type: git
    url: "https://github.com/example/infra.git"
    branch: "main"
    pull_interval_seconds: 300

Each git source is checked out under /data/ansible/sources/<name> (override with STEWARD_ANSIBLE_SOURCE_DIR), on the persistent volume, so a redeploy keeps it. One scheduled task, ansible_git_pulls, ticks every 30 s and pulls each source once its pull_interval_seconds has passed; a source added in Settings is pulled within a tick, with no restart. A clone or pull that runs past 120 s is cut (its process group terminated), a clone that fails is removed so the next attempt starts clean, and git never prompts for credentials.

---

Inventory Discovery

The app discovers inventory files within the root of the playbook source directory (non-recursive). It looks for files named:

• hosts
• inventory
• inventory.yml
• inventory.ini

A manual relative path can also be entered in the UI (e.g. inventories/production/hosts) for inventories in subdirectories.

---

Triggering a Run

From the UI at /ansible/, you can:

1. Browse available playbooks across all sources
2. View playbook contents before running
3. Select an inventory file
4. Trigger a run (requires operator or viewer role — execution is restricted to operator/admin)

The run flow:

1. UI submits POST /ansible/runs with playbook_path, source_name, and inventory_path
2. An AnsibleRun row is created with status = running
3. Playbook execution starts as asyncio.create_task()
4. The response returns the run_id and an HTMX partial that wires the SSE subscription
5. The browser connects to GET /ansible/runs/<run_id>/stream to receive live output

---

SSE Streaming

Run output is streamed to the browser via Server-Sent Events (SSE) at:

GET /ansible/runs/<run_id>/stream

Each output line is sent as:

event: output
data: <line of stdout/stderr>

Run completion:

event: done
data: success|failed|interrupted

Output is flushed to the ansible_runs.output DB column every 50 lines or every 5 seconds (whichever comes first) and always on completion. This means partial output survives a process crash.

If a client connects after the run has already completed, the endpoint immediately sends event: done with the final status and closes the stream. To view stored output, use the run history view at GET /ansible/runs/<run_id>.

---

Run Lifecycle

Status	Description
queued	Waiting for a host another run holds, or for a run slot
running	Execution in progress
success	Playbook exited 0
failed	Playbook exited non-zero
interrupted	App restarted while run was in progress
cancelled	Stopped by an operator, or by Steward shutting down mid-run

On startup, the app marks any runs still running or queued as interrupted (see _mark_interrupted_runs() in app.py).

Overlapping runs

• One run per host. Before it takes a run slot, a run claims every host it touches. Hosts come from the inventory Steward writes, keyed by address. A run on a source's own inventory file claims that file, because Steward doesn't read its hosts. While another run holds one of its hosts, the run shows queued and says which run it waits for. After an hour of waiting it fails and says so.
• One run at a time per schedule. A schedule that falls due while its previous run is still queued or running skips that firing. The Schedules page shows "Skipped: the previous run was still going" beside that run. The next firing comes an interval later.
• One action run at a time per alert rule. When a rule fires again while the action run from an earlier firing is still going, no new run starts. The firing's event says it was skipped and names the run.

Output stored in the DB is capped at 1 MB. If truncated, [output truncated] is appended to the DB column, but the live SSE stream continues unaffected.

---

Data Model

ansible_runs table (defined in steward/models/ansible.py):

Column	Type	Description
id	UUID	Primary key
playbook_path	str	Relative path to playbook
inventory_path	str	Inventory path used
source_name	str	Name of the playbook source
triggered_by	FK → users
status	enum	running, success, failed, interrupted
started_at	timestamp UTC
finished_at	timestamp UTC	Null if still running
output	text	Captured stdout/stderr (capped at 1 MB)

Runs older than data.retention_days (default 90) are pruned by the data_cleanup scheduled task.

---

Source Files

File	Purpose
steward/ansible/sources.py	Source discovery, git pull logic
steward/ansible/executor.py	Subprocess execution and output streaming
steward/ansible/routes.py	HTTP routes (browse, trigger, stream, history)
steward/models/ansible.py	AnsibleRun model