Overview

Date: 2026-05-11

Time: 15:45

Overview

This example demonstrates FTL2's Fully Qualified Collection Name (FQCN) module access pattern, which lets users call Ansible collection modules using Python's dot-notation attribute chaining (e.g., ftl.amazon.aws.ec2instance(...)). It shows how NamespaceProxy enables this syntax by building up namespace paths through successive getattr_ calls, ultimately producing a callable that executes the module via the automation context.

Usage Patterns

Two module access styles are supported within the automation() context manager:

Simple (FTL-native) modules — direct attribute access:


async with automation() as ftl:
    await ftl.file(path="/tmp/test", state="touch")
    await ftl.command(cmd="echo hello")

FQCN modules — chained namespace access for Ansible collections:


async with automation() as ftl:
    await ftl.amazon.aws.ec2_instance(name="web-server", instance_type="t3.micro")
    await ftl.ansible.builtin.debug(msg="Hello from FQCN!")
    await ftl.community.general.slack(token=ftl.secrets["SLACK_TOKEN"], channel="#deploy", msg="Done")

Both styles can be freely mixed in the same script. Simple modules are noted as "250x faster" since they're FTL-native rather than delegating to Ansible collections.

API and Configuration

automation() — async context manager; accepts secrets=["KEYNAME", ...] to bind secrets for use via ftl.secrets["KEYNAME"].
AutomationContext() — the underlying context object; can be instantiated directly outside the context manager for inspection.
NamespaceProxy — returned by any unknown attribute access on the context; builds up a dotted FQCN path and becomes callable at the leaf level.
Error checking — ftl.failed (bool) and ftl.errors (list with .error attribute) for post-execution error inspection.

Key Behaviors

Accessing an unknown attribute on the context returns a NamespaceProxy, not an error. Each subsequent attribute access extends the namespace path ("amazon" → "amazon.aws" → "amazon.aws.ec2_instance").
Calling the final proxy (e.g., await ftl.amazon.aws.ec2_instance(...)) executes the module via context.execute().
FQCN modules require the corresponding Ansible collection to be installed (e.g., amazon.aws).
The script itself is purely demonstrative — it prints syntax examples and proxy types but does not actually execute any cloud modules.

Relationships

Imports from ftl2: automation, AutomationContext, NamespaceProxy (from ftl2.automation).
Ansible collections: FQCN modules delegate to installed Ansible collections (amazon.aws, community.general, community.docker, kubernetes.core, ansible.builtin).
Secrets integration: ftl.secrets["KEY"] is used to access Vault-bound secrets within module calls.
Run method: Executed standalone via uv run python examplefqcnmodules.py.