Overview

Date: 2026-05-11

Time: 15:32

Overview

AutomationContext is the primary user-facing class in FTL2's automation framework. It provides the async with automation() as ftl: pattern that enables intuitive module execution via ftl.module_name() syntax. The class manages inventory, secrets, SSH connections, policy enforcement, state persistence, audit recording/replay, and gate (pre-built module bundle) lifecycle — all configured through a single constructor and driven by the async context manager protocol.

Usage Patterns

The canonical entry point is the automation() factory (not shown but wraps AutomationContext). Typical usage:

async with automation() as ftl:
    await ftl.file(path="/tmp/test", state="touch")
    await ftl.copy(src="config.yml", dest="/etc/app/")

With inventory and secrets:

async with automation(
    inventory="hosts.yml",
    secrets=["AWS_KEY"],
    vault_secrets={"DB_PW": "myapp#db_password"},
    fail_fast=True,
    policy="rules.yaml",
) as ftl:
    await ftl.file(path="/tmp/test", state="touch")
    if ftl.failed:
        for msg in ftl.error_messages:
            print(msg)

Module calls are proxied through ModuleProxy — ftl.file(...) resolves to the file module at runtime. If a host/group name shadows a module name, the module is accessible via ftl.module.<name>().

Error checking after execution:

ftl.failed          # bool — any failures?
ftl.errors          # list[ExecuteResult] — failed results
ftl.error_messages  # list[str] — error strings

API and Configuration

Constructor parameters (key ones):

| Parameter | Type | Default | Purpose |

|-----------|------|---------|---------|

| modules | list[str] \| None | None (all) | Restrict which modules are available |

| inventory | str \| Path \| Inventory \| dict \| None | None (localhost) | Inventory source — YAML file path, object, dict, or None |

| secrets | list[str] | None | Env var names to load into ftl.secrets |

| secret_bindings | dict[str, dict[str, str]] | None | Auto-inject secrets into module params by pattern |

| vault_secrets | dict[str, str] | None | Vault KV v2 refs as "path#field" format |

| check_mode | bool | False | Dry-run mode |

| fail_fast | bool | False | Raise AutomationError on first failure |

| verbose / quiet | bool | False | Output control (quiet overrides verbose) |

| on_event | EventCallback | None | Structured event callback |

| state_file | str \| Path \| None | ".ftl2-state.json" | State persistence for crash recovery |

| record / replay | str \| Path \| None | None | Audit trail recording / replay from prior recording |

| policy | str \| Path \| None | None | YAML policy file or directory |

| environment | str | "" | Environment label for policy matching |

| policy_audit | str \| Path \| None | None | JSON-lines policy audit file |

| gate_modules | list[str] \| "auto" \| None | None | Pre-bake modules into gate bundles |

| gate_dependencies | list[str] | None | Extra deps for gate builds |

| record_deps | bool | False | Record module deps to .ftl2-deps.txt |

| ignoremissinginventory | bool | False | Fall back to localhost if inventory file missing |

Environment variables: VAULTADDR and VAULTTOKEN required for Vault integration.

Key Behaviors

• Secrets are never logged. SecretsProxy provides safe _repr/str_ and dictionary-like access. Secret bindings use fnmatch patterns to auto-inject secrets into module parameters — the audit trail receives pre-injection params to avoid leaking values.

• Policy enforcement runs before every module execution. Denied actions raise PolicyDeniedError. Every evaluation (permitted or denied) is appended to the audit file as a JSON line immediately (crash-safe). Policy can be hot-reloaded via await ftl.reloadpolicy() or auto-watched with await ftl.watchpolicy(interval=5.0).

• Replay is positional — action N in the current run matches action N in the replay log. Successful replayed actions are skipped with cached output; execution resumes from the first unmatched/failed action.

• Name collision warning: If a host or group name matches a module name, a UserWarning is emitted at init time. Use ftl.module.<name>() to disambiguate.

• State persistence (statefile) enables crash recovery — addhost() writes immediately, and dynamic hosts are restored on re-entry.

• Output modes: QUIET suppresses all output, NORMAL shows errors only, VERBOSE shows execution details, EVENTS emits structured dicts via the on_event callback.

• fail_fast=True raises AutomationError (which carries the ExecuteResult) on the first module failure. Default behavior continues execution and collects errors.

Relationships

• ModuleProxy (ftl2.automation.proxy) — handles ftl.<module_name>() attribute resolution and execution dispatch.
• Inventory / loadinventory / loadlocalhost (ftl2.inventory) — inventory loading and host resolution.
• SSHHost (ftl2.ssh) — SSH connection pool managed by the context (keyed in sshconnections).
• Policy (ftl2.policy) — policy engine loaded from YAML, supports evaluate(), fromfile(), fromdirectory().
• State (ftl2.state) — state file persistence, merged into inventory at startup.
• readvaultsecrets (ftl2.vault) — Vault KV v2 secret fetching.
• RemoteModuleRunner / Gate (ftl2.runners) — remote execution with pre-built module bundles.
• BundleCache (ftl2.module_loading.bundle) — caching for gate module bundles.
• listmodules (ftl2.ftlmodules) — used at init to detect host/module name collisions.