Overview

Date: 2026-05-11

Time: 15:48

Overview

This is an example script demonstrating ping() — FTL2's connectivity verification module. It tests the full execution pipeline (TCP → SSH → Gate setup → Command execution → Response round-trip). When ping() succeeds, module execution is guaranteed to work. The file serves as both documentation and runnable reference for common ping patterns.

Usage Patterns

Basic local ping:

async with automation(quiet=True) as ftl:
    result = await ftl.local.ping()       # {'ping': 'pong'}

FQCN (Ansible-style) module name:

result = await ftl.local.ansible.builtin.ping()

Remote host ping (via inventory):

result = await ftl.web01.ping()

Pre-flight connectivity check before work:

try:
    await ftl.db_primary.ping()
    # safe to proceed with operations
except TimeoutError:
    # handle unreachable host

Post-provisioning readiness check:

ftl.add_host("new-server", ansible_host=ip, ansible_user="root", groups=["webservers"])
await ftl.new_server.wait_for_ssh(timeout=120, delay=10)
result = await ftl.new_server.ping()

API and Configuration

• automation(inventory=..., quiet=True) — async context manager; inventory is a dict of groups/hosts, quiet suppresses output.
• ftl.<hostname>.ping() — tests connectivity to a named host. Hostnames with dashes are accessed via underscores (db-primary → ftl.db_primary).
• ftl.local.ping() — tests local execution pipeline.
• ftl.addhost(name, ansiblehost=, ansible_user=, groups=[]) — dynamically registers a host at runtime.
• ftl.<host>.waitforssh(timeout=120, delay=10) — polls until SSH is available; timeout in seconds, delay between retries.
• Inventory dict structure: { "groupname": { "hosts": { "hostname": { "ansiblehost": "...", "ansibleuser": "..." } } } }

Key Behaviors

• Dash-to-underscore conversion: Host names containing dashes (db-primary) are accessed as Python attributes with underscores (ftl.dbprimary). When iterating hosts, use getattr(ftl, name.replace("-", "")).
• Pipeline verification order: TCP → SSH → Gate → Command → Response. A successful ping confirms all five stages.
• Error types: TimeoutError for unreachable hosts, ftl2.exceptions.ConnectionError for connection failures, generic Exception for other issues.
• Group iteration: ftl.hosts["group_name"] returns host configs; use .name to get the hostname string.
• ping() returns {'ping': 'pong'} on success.

Relationships

• Imports: ftl2.automation (main entry point), ftl2.exceptions.ConnectionError (error handling).
• Pattern context: Ping is used as a prerequisite check before module calls like command(), dnf(), service(), and provisioning modules like community.general.linode_v4.
• Connects to: SSH subsystem (authentication), Gate process (remote execution), inventory system (host resolution and group membership), dynamic host registration (add_host).