Overview

Date: 2026-05-11

Time: 15:17

Overview

The FTL2 automation context manager provides a Pythonic, async interface for writing automation scripts. Using async with automation() as ftl:, users access modules as attributes (ftl.file(...), ftl.copy(...)), manage inventory and secrets, run in check mode, handle errors, and control output — all without boilerplate. The interface is designed to be AI-friendly and runs FTL native modules in-process at 250x the speed of subprocess-based execution.

Key Concepts

• Context manager pattern: async with automation() as ftl: is the entry point for all automation scripts
• Module-as-attribute: Any module is called as await ftl.module_name(param=value) — no string lookups or dictionaries
• Result tracking: ftl.results accumulates all module execution results; each has .module, .success, and other fields
• Module restriction: automation(modules=["file", "copy"]) limits which modules can be called; unauthorized access raises AttributeError
• Inventory integration: Load from YAML file or Python dict via automation(inventory=...). Access hosts with ftl.hosts["group"], ftl.hosts.all, ftl.hosts.groups
• runon() method: Execute modules on specific hosts or groups — await ftl.runon("webservers", "file", path=..., state=...)
• Secrets proxy: automation(secrets=["KEY1", "KEY2"]) loads from environment variables. Values are never exposed in print()/repr(). Access via ftl.secrets["KEY"] or .get("KEY", default)
• Check mode (dry run): automation(check_mode=True) previews changes without applying them
• Output modes: verbose=True (with timing), quiet=True (no output), on_event=callback (structured events), and normal (default)
• Error handling: ftl.failed (bool), ftl.errors (list of error objects with .host, .module, .error), ftl.error_messages (string list)
• Fail fast: automation(fail_fast=True) raises AutomationError on first failure instead of accumulating
• FQCN modules: Dotted notation (ftl.amazon.aws.ec2_instance(...)) via NamespaceProxy chaining — enables Ansible collection modules alongside native FTL modules
• 250x performance: Native FTL modules run in-process, not as subprocesses

Commands and Syntax

Basic script structure:

from ftl2 import automation

async with automation() as ftl:
    await ftl.file(path="/tmp/test", state="directory")
    await ftl.copy(src="config.yml", dest="/etc/app/config.yml")
    await ftl.command(cmd="systemctl restart myapp")

Running examples: uv run python examplephase1basic.py

Inventory from YAML: automation(inventory="hosts.yml")

Inventory from dict: automation(inventory={"group": {"hosts": {"host01": {"ansible_host": "1.2.3.4"}}}})

Host access API:

• ftl.hosts["web01"] — specific host
• ftl.hosts["webservers"] — all hosts in group
• ftl.hosts.all — all hosts
• ftl.hosts.groups — group names
• ftl.hosts.keys() — all host names
• len(ftl.hosts) / "web01" in ftl.hosts

Secrets: automation(secrets=["AWSACCESSKEYID", "APITOKEN"]) then ftl.secrets["AWSACCESSKEYID"], .get("KEY", "default"), .loadedkeys()

Check mode: automation(check_mode=True)

Fail fast with exception handling:

from ftl2.automation import AutomationError
try:
    async with automation(fail_fast=True) as ftl:
        await ftl.file(path="/nonexistent", state="touch")
except AutomationError as e:
    print(f"Module: {e.result.module}")

FQCN: await ftl.amazon.aws.ec2instance(name="my-instance", instancetype="t3.micro")

Relationships

• Inventory management: The automation(inventory=...) parameter connects directly to FTL2's YAML inventory system and host configuration
• Module system: ftl.module_name() is the user-facing surface of FTL2's module execution engine; FQCN modules bridge to Ansible collections
• Secrets/Vault: ftl.secrets provides environment-variable-based secrets; relates to the broader Vault integration topic
• Check mode / State: Check mode connects to FTL2's idempotency and state management — validates what *would* change
• Error handling: ftl.failed, ftl.errors, and fail_fast are the primary error handling mechanisms, connecting to FTL2's result tracking
• Output/Events: Event callbacks (on_event) connect to FTL2's event streaming and audit/replay capabilities

Exam-Relevant Points

• The automation() context manager accepts: modules, verbose, quiet, checkmode, failfast, inventory, secrets, on_event
• Restricting modules with modules=[...] causes AttributeError (not a runtime module error) when accessing disallowed modules
• ftl.secrets never exposes values in print/repr — this is a security feature
• Accessing a secret not in the requested list raises KeyError: not requested; a requested but unset secret raises KeyError: not set in environment
• ftl.secrets.keys() returns all *requested* names; ftl.secrets.loaded_keys() returns only those actually set in the environment
• Check mode output is annotated with [CHECK MODE]
• fail_fast=True raises AutomationError which has .result.module for identifying the failing module
• FQCN resolution works by chaining NamespaceProxy objects: ftl.amazon -> NamespaceProxy("amazon") -> .aws -> NamespaceProxy("amazon.aws") -> .ec2instance(...) executes "amazon.aws.ec2instance"
• Native FTL modules are 250x faster than Ansible because they run in-process
• The validation workflow pattern: run with checkmode=True first, inspect ftl.results, then run with checkmode=False
• Output modes: NORMAL, VERBOSE, QUIET, EVENTS — accessible via ftl.output_mode
• ftl.results is a list accumulated across all module calls in a context; check with len(ftl.results) or iterate