Overview

Date: 2026-05-11

Time: 15:45

I'll create a summary entry for this dynamic hosts example.

Overview

This example demonstrates FTL2's dynamic host registration and host-scoped proxy syntax — two features that enable provisioning workflows where infrastructure is created and immediately configured in the same script. It shows how to add hosts at runtime with ftl.addhost(), then target them using the cleaner ftl.<host>.module() proxy syntax instead of the older ftl.runon() API.

Usage Patterns

Dynamic host registration — add hosts at runtime rather than defining them in static inventory:

ftl.add_host(
    hostname="web01",
    ansible_host="192.168.1.10",
    groups=["webservers", "production"],
    db_type="postgres",  # arbitrary custom host variables
)

Host-scoped proxy — target hosts or groups with attribute-style access:

await ftl.web01.command(cmd="echo 'target one host'")
await ftl.webservers.command(cmd="echo 'target a group'")
await ftl.localhost.command(cmd="echo 'target localhost'")

FQCN modules with proxy syntax — fully-qualified collection names chain through the proxy:

await ftl.webservers.ansible.builtin.command(cmd="echo 'FQCN works!'")
await ftl.databases.community.postgresql.postgresql_db(name="myapp")

Provisioning workflow — provision, register, configure in sequence:

server = await ftl.community.general.linode_v4(label="web03", ...)
ftl.add_host("web03", ansible_host=server["instance"]["ipv4"][0], groups=["webservers"])
await ftl.web03.apt(name="nginx", state="present")
await ftl.web03.service(name="nginx", state="started")

API and Configuration

| API | Parameters | Purpose |

|-----|-----------|---------|

| ftl.addhost() | hostname, ansiblehost, groups=[], **kwargs (custom host vars) | Register a host at runtime |

| ftl.<name>.module() | Module-specific kwargs | Run module on host or group by name |

| ftl.run_on() | target, module, **kwargs | Older explicit targeting (still supported) |

| ftl.hosts | dict-like | Access registered hosts; .keys(), .groups, ['group_name'] |

| ftl.results | list | All results collected during the session |

| ftl.failed | bool | Whether any task failed |

Key Behaviors

• Host-scoped proxy resolves dynamically — ftl.web01 works for hosts added via add_host() as well as those from static inventory. The name can be a hostname or a group name.
• Group targeting fans out — ftl.webservers.command(...) runs on all hosts in the webservers group.
• Custom host variables — extra **kwargs passed to addhost() become host variables (e.g., dbtype="postgres").
• runon() still works — the proxy syntax is syntactic sugar; ftl.runon("db01", "command", cmd=...) remains valid.
• FQCN chaining — dotted module names like ansible.builtin.command chain through the proxy without issue.

Relationships

• Imports ftl2.automation.automation — the main async context manager entry point.
• Pairs with static inventory (inventory.yml) — add_host() supplements or replaces static definitions.
• Used in provisioning scripts — the pattern shown here mirrors real deployment scripts in ftl2-deployments where cloud modules create infrastructure and add_host() registers it for immediate configuration.
• Host/group access via ftl.hosts — same data structure populated by inventory loading.