bvandeusen
0596f1d9c1
Sweeps README, docs/, example configs, code docstrings, report and notification subject lines, plugin catalog URL default, and stray comments in Dockerfile/entrypoint.sh/.gitignore. Adds a legacy note to docs/core/configuration.md explaining the FABLEDSCRYER_* fallback. docker-compose DB credentials intentionally left as fabledscryer to preserve the existing pgdata volume.
144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# Ansible Integration
|
|
|
|
Roundtable 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.
|
|
|
|
```yaml
|
|
# 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.
|
|
|
|
```yaml
|
|
ansible.sources:
|
|
- name: "infra-repo"
|
|
type: git
|
|
url: "https://github.com/example/infra.git"
|
|
branch: "main"
|
|
pull_interval_seconds: 300
|
|
cache_path: "/data/playbook_cache/infra-repo"
|
|
```
|
|
|
|
Git sources register a `ScheduledTask` named `ansible_git_pull_<name>` that runs `git pull` on the configured interval.
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|---|---|
|
|
| `running` | Execution in progress |
|
|
| `success` | Playbook exited 0 |
|
|
| `failed` | Playbook exited non-zero |
|
|
| `interrupted` | App restarted while run was in progress |
|
|
|
|
On startup, the app marks any runs still in `running` state as `interrupted` (see `_mark_interrupted_runs()` in `app.py`).
|
|
|
|
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 `roundtable/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 |
|
|
|---|---|
|
|
| `roundtable/ansible/sources.py` | Source discovery, git pull logic |
|
|
| `roundtable/ansible/executor.py` | Subprocess execution and output streaming |
|
|
| `roundtable/ansible/routes.py` | HTTP routes (browse, trigger, stream, history) |
|
|
| `roundtable/models/ansible.py` | `AnsibleRun` model |
|