Overview

Date: 2026-05-11

Time: 15:10

Overview

This page traces FTL2's development chronologically from February 5-11, covering the evolution from core architecture through modules, event streaming, the automation context API, gate-based remote execution, native modules, state management, dependency tracking, audit/replay, the policy engine, inventory formats, and Vault integration. It reveals the design motivations and performance rationale behind each subsystem.

Key Concepts

• In-process module execution is FTL2's core performance win — runs Ansible modules as Python functions, not subprocesses, achieving 3-17x speedup over ansible-playbook
• FQCN resolution parses fully-qualified collection names (e.g. community.general.slack) to locate actual module files
• Gate system — remote execution via SSH gate process; cached zipapps with baked-in modules eliminate repeated transfer; SSH subsystem registration removes shell startup overhead
• FTL modules vs Ansible modules — FTL modules sent by name (gate already has them), Ansible modules sent as bundles
• Native modules (copy, template, fetch, shell, swap, ping, wait_for) skip Ansible module machinery entirely for maximum speed
• State file (.ftl2-state.json) tracks dynamically provisioned hosts/resources; loaded on context enter for crash recovery and idempotent provisioning
• Secret bindings auto-inject credentials and are never visible in logs
• Audit records capture every module execution with secrets redacted; replay skips previously successful actions
• Policy engine uses YAML rules with fnmatch patterns; first matching deny rule raises PolicyDeniedError; evaluated on both local and remote execution paths
• Vault integration maps names to path#field references; reads grouped by path to minimize API calls; hvac is optional (pip install ftl2[vault])
• Inventory auto-detection — load_inventory() handles executable scripts, JSON (Ansible --list format), or YAML transparently

Commands and Syntax

Automation context:

async with automation(inventory="hosts.yml", secret_bindings={...}) as ftl:
    await ftl.file(path="/tmp/test", state="directory")
    await ftl.run_on("webservers", "dnf", name="nginx", state="present")

Host-scoped access: ftl["hostname"].module() — bracket notation supports host names with dashes

Dynamic hosts: add_host() persists to state immediately

Event listening: await ftl.listen() for persistent monitoring (inotify, metrics)

Audit/replay:

• Record: record="audit.json"
• Replay: replay="audit.json" — skips successful actions, resumes from first failure

Vault secrets: vaultsecrets parameter maps names to path#field; uses VAULTADDR/VAULT_TOKEN env vars; accessed via ftl.secrets["NAME"]

Dependency files: .ftl2-deps.txt (Python requirements), .ftl2-modules.txt (module names for gate building)

Gate cache location: ~/.ftl per user

Relationships

• Gate system ↔ Module bundling — gate builder creates zipapps; FTL modules are pre-baked, Ansible modules are bundled on demand
• State management ↔ Dynamic provisioning — add_host() writes to state; state reloaded on context enter enables crash recovery
• Audit/replay ↔ State management — both support crash recovery from different angles (replay skips completed work; state preserves provisioned resources)
• Policy engine ↔ Module execution — policies evaluated in both execute() (local) and executeon_host() (remote) paths
• Vault secrets ↔ Secret bindings — vault-sourced secrets flow through the same binding mechanism as env var secrets
• Dependency management ↔ Gate building — .ftl2-modules.txt feeds the gate builder to know which modules to bake in
• JSON inventory ↔ Ansible interop — can consume ansible-inventory --list output directly, bridging existing dynamic inventory plugins

Exam-Relevant Points

• FTL2 achieves 3-17x speedup by running modules as Python functions in-process
• Gate cache location is ~/.ftl per user
• State file is .ftl2-state.json; dependency file is .ftl2-deps.txt; module list is .ftl2-modules.txt
• load_inventory() auto-detects three formats: executable scripts, JSON, YAML
• Policy engine uses fnmatch for module matching and match conditions include module, host, environment, param.<name>
• First matching deny rule raises PolicyDeniedError — it's first-match, not most-specific
• Audit records redact secrets automatically
• Replay resumes from the first failure, not the last success
• Vault integration requires pip install ftl2[vault] (hvac is optional)
• Vault reads are grouped by path to minimize API calls
• FTL modules are sent to gate by name; Ansible modules are sent as bundles
• add_host() persists to state immediately (not at context exit)
• Policy.empty() exists for backward compatibility