Overview

Date: 2026-05-11

Time: 15:42

Overview

This is an example/demo script that shows how to execute Ansible builtin modules (like ping, command, stat, file, tempfile) through FTL2's module_loading system. It demonstrates the subprocess-based Ansible module execution path, bundle building for remote execution, and includes a performance comparison between FTL2-native modules and Ansible modules. It serves as both documentation and a runnable tutorial for users migrating from or integrating with Ansible.

Usage Patterns

Run directly as a script:

python examples/ansible_builtin_modules.py

Key execution patterns demonstrated:

# Execute a module by FQCN with parameters
from ftl2.module_loading.executor import execute_local_fqcn
result = execute_local_fqcn("ansible.builtin.command", {"_raw_params": "echo hello"})
print(result.success, result.output.get("stdout"))

# Resolve FQCN to filesystem path
from ftl2.module_loading.fqcn import resolve_fqcn
path = resolve_fqcn("ansible.builtin.command")

# Build a bundle for remote execution
from ftl2.module_loading.bundle import build_bundle_from_fqcn
bundle = build_bundle_from_fqcn("ansible.builtin.command")

# Execute a bundle locally
from ftl2.module_loading.executor import execute_bundle_local
result = execute_bundle_local(bundle, {"_raw_params": "echo hello"})

# Execute remotely via SSH
from ftl2.module_loading.executor import execute_remote_with_staging
result = await execute_remote_with_staging(host, bundle, {"_raw_params": "hostname"})

API and Configuration

Dependencies: Requires ftlbuiltinmodules and ftlmoduleutils packages installed (pip install -e ../ftlbuiltinmodules and pip install -e ../ftlmoduleutils).

Module parameters follow Ansible conventions — each module takes a dict of parameters (e.g., {"path": "/etc/hosts"} for stat, {"rawparams": "echo hi"} for command, {"state": "touch", "path": "..."} for file).

Remote execution requires a Docker container with SSH access, configured via:

SSH_CONFIG = {
    "hostname": "localhost", "port": 2222,
    "username": "testuser", "password": "testpass",
    "disable_host_key_checking": True,
}

ExecutionResult fields: success (bool), output (dict), error (str|None), changed (bool).

Key Behaviors

• Name shadowing warning: Some Ansible modules (e.g., tempfile.py) shadow Python standard library modules, causing failures outside the full Ansible runtime. The script documents this as a known limitation.
• resolvefqcn maps dotted FQCN strings (like ansible.builtin.command) to filesystem paths via findansiblebuiltinpath().
• Bundle system: buildbundlefromfqcn packages a module with its dependencies into a transferable bundle (has fqcn, contenthash, size, dependency_count). Bundles can be executed locally or staged to remote hosts.
• Performance: The comparison example shows FTL-native modules are significantly faster than Ansible modules due to lower wrapper overhead (both execute the same underlying command).
• Remote execution is async — uses asyncio.run() and requires an SSHHost connection with await host.connect() / await host.disconnect().

Relationships

• Imports from ftl2.moduleloading: executor (executelocalfqcn, executebundlelocal, executeremotewithstaging, ExecutionResult), bundle (buildbundlefromfqcn), fqcn (resolvefqcn, findansiblebuiltin_path)
• Imports from ftl2.ftlmodules: ftlcommand — the native FTL2 command module, used in the performance comparison
• Imports from ftl2.ssh: SSHHost — for remote execution over SSH
• External packages: ftlbuiltinmodules (provides Ansible module Python files), ftlmoduleutils (Ansible module utility dependencies)
• Companion to: other examples in examples/ that demonstrate FTL2-native module usage, inventory, and policies