Overview

Date: 2026-05-11

Time: 15:49

Overview

This is a complete Azure infrastructure provisioning example that demonstrates FTL2's cloud automation capabilities. It provisions a full web application stack — resource group, virtual network, subnets, security group, public IP, NIC, and a Linux VM — then configures the VM with nginx over SSH. It showcases FTL2's async context manager API, Ansible collection integration (azure.azcollection), secret bindings, state management, dynamic host registration, and check mode, all in a single Python script.

Usage Patterns

Three invocation modes via CLI flags:

uv run python example_azure_web_stack.py            # Full provision + configure
uv run python example_azure_web_stack.py --check     # Dry run (no changes)
uv run python example_azure_web_stack.py --teardown   # Delete everything

The core pattern is async with automation(...) as ftl: — the automation context manager handles setup, collection installation, and cleanup. Modules are called via dot-notation on the ftl object using the FQCN path:

await ftl.azure.azcollection.azure_rm_resourcegroup(
    name=RESOURCE_GROUP,
    location=LOCATION,
    tags={"environment": "demo", "managed_by": "ftl2"},
)

After provisioning, the script dynamically registers the new VM as a host and runs commands against it using host targeting (ftl[VM_NAME].command(...)).

API and Configuration

automation() context manager parameters used:

• autoinstalldeps=True — automatically installs the azure.azcollection if missing
• check_mode=bool — enables dry-run mode (no actual changes)
• verbose=True — detailed output
• secret_bindings — maps module FQCN patterns to env var names for credential injection (wildcard azure.azcollection.* applies to all modules in the collection)
• state_file — path to a JSON file for persisting provisioned resource state across runs

Required environment variables:

• AZURECLIENTID, AZURESECRET, AZURESUBSCRIPTIONID, AZURETENANT — Azure service principal credentials
• AZUREVMSSH_PUBKEY (optional) — SSH public key for VM access

State API:

• ftl.state.add(key, dict) — persist resource metadata
• ftl.state.remove(key) — remove on teardown

Dynamic host registration:

• ftl.addhost(hostname, ansiblehost, ansible_user, groups) — register a host for immediate use

Key Behaviors

• Sequential provisioning: Resources are created in dependency order (resource group → vnet → subnet → NSG → IP → NIC → VM), each awaited before the next.
• Post-provision configuration gate: VM configuration (apt-get, nginx) only runs when not check_mode and not ftl.failed — avoids configuring a VM that wasn't actually created.
• Teardown via resource group deletion: Uses state="absent" and forcedeletenonempty=True on the resource group, which cascades to all contained resources.
• Result introspection: After all operations, ftl.results provides a list with .success and .changed attributes; ftl.errors gives structured error objects with .module and .error fields.
• ftl.failed flag: A boolean that tracks whether any operation has failed during the session.
• Host-targeted execution: ftl[VMNAME].command(...) and ftl[VMNAME].ansible.builtin.service(...) show how to run modules against a specific registered host rather than all hosts.

Relationships

• Imports: ftl2.automation — the main user-facing entry point for FTL2
• Collection dependency: azure.azcollection (installed via ansible-galaxy collection install or auto-installed by autoinstalldeps)
• Modules used: azurermresourcegroup, azurermvirtualnetwork, azurermsubnet, azurermsecuritygroup, azurermpublicipaddress, azurermpublicipaddressinfo, azurermnetworkinterface, azurerm_virtualmachine, ansible.builtin.command, ansible.builtin.service
• State file: .ftl2-state-azure.json — shared between provision and teardown runs for tracking what was created
• Pattern relationship: This example parallels the AWS example pattern but for Azure, demonstrating that FTL2's collection-based module system works identically across cloud providers