Overview

Date: 2026-05-11

Time: 15:14

Overview

FTL modules are in-process Python functions that replace traditional subprocess-based module execution, achieving 250x+ speedups. This page covers the example scripts demonstrating local execution, remote SSH execution, Ansible module compatibility via the module_loading system, and the two primary APIs (direct function calls and the async Executor API).

Key Concepts

• In-process execution — FTL modules run as native Python functions inside the same process, eliminating subprocess overhead (fork/exec per task).
• Two API surfaces — Direct function calls (ftlfile(), ftlcommand(), etc.) for simple use, and the async Executor API (execute, run, executeonhosts) for production patterns.
• Async-first design — The Executor API and SSH transport are fully async (asyncio), enabling concurrent execution across multiple hosts.
• Ansible module compatibility — The module_loading system resolves FQCN names (e.g. ansible.builtin.command), builds ZIP bundles with dependencies, and executes them locally or remotely.
• Result contract — All modules return a dict with at least changed (bool) and content-specific keys (stdout, stderr, etc.). The Executor wraps this in a result object with .success, .changed, .output.
• LocalHost abstraction — LocalHost(name=...) lets you treat local execution with the same host-list pattern used for remote targets.
• SSHHost for remote — SSHHost manages async SSH connections with async with host: context manager; supports host.run() for raw commands and integration with the Executor via host= parameter.

Commands and Syntax

Running examples:

uv run python example_local.py          # No setup required
docker-compose up -d                     # Start test containers for remote
uv run python example_remote.py
docker-compose down

Direct function calls:

from ftl2.ftl_modules import ftl_file, ftl_command, ftl_copy
result = ftl_file(path="/tmp/test.txt", state="touch")
result = ftl_command(cmd="echo hello")
result = ftl_copy(src="/tmp/source.txt", dest="/tmp/dest.txt")

Executor API (async, recommended):

from ftl2.ftl_modules import execute, execute_on_hosts, run, LocalHost

result = await execute("file", {"path": "/tmp/test.txt", "state": "touch"})
result = await run("command", cmd="uptime")

hosts = [LocalHost(name=f"host{i}") for i in range(10)]
results = await execute_on_hosts(hosts, "command", {"cmd": "echo hello"})

SSH remote execution:

from ftl2.ssh import SSHHost
host = SSHHost(hostname="localhost", port=2222, username="testuser",
               password="testpass", disable_host_key_checking=True)
async with host:
    stdout, stderr, rc = await host.run("uptime")
    result = await execute("command", {"cmd": "hostname"}, host=host)

Available modules: file, copy, template, command, shell, uri, geturl, pip — each with a corresponding ftl<name>() function.

Relationships

• SSH transport (ftl2.ssh.SSHHost) — remote execution depends on the async SSH layer; the Executor falls back to Ansible module bundling when running remotely.
• Module loading / FQCN — the module_loading system bridges Ansible modules into FTL, resolving fully-qualified collection names to file paths and building deployment bundles.
• Inventory — LocalHost and SSHHost are the host abstractions that connect to the broader inventory system (groups, host vars).
• Gate modules — pre-built bundles for remote execution relate to the performance story here (eliminating per-task bundling overhead).
• Ansible migration — understanding which Ansible builtins have FTL equivalents (file, copy, command, template, uri, pip) is central to migration planning.

Exam-Relevant Points

• FTL modules achieve 330x speedup for file operations, 84x for HTTP/uri, 7x for command execution vs subprocess.
• The Executor API (execute/run/executeonhosts) is the recommended API, not direct function calls.
• executeonhosts enables concurrent execution across a host list — this is the primary scaling pattern.
• Remote execution via SSHHost falls back to Ansible module bundling when using the Executor — it does not run FTL functions in-process on the remote side.
• disablehostkey_checking=True is only for test containers — know the security implication.
• Ansible module compatibility requires ftlbuiltinmodules and ftlmoduleutils to be installed.
• Eight built-in FTL modules exist: file, copy, template, command, shell, uri, get_url, pip.
• Results expose .success, .changed, and .output on the Executor result object; raw functions return a dict with changed key.