Overview

Date: 2026-05-11

Time: 15:19

Overview

This page documents how to provision and manage Hetzner Cloud infrastructure using FTL2, leveraging the hetzner.hcloud Ansible collection. It covers setup, a web stack example, the full module catalog, datacenter locations, and server type naming conventions.

Key Concepts

• FTL2 calls Hetzner modules via FQCN syntax (e.g., hetzner.hcloud.server), wrapping Ansible collection modules in Python-native async calls.
• The HCLOUD_TOKEN environment variable authenticates all Hetzner API operations; FTL2 injects it via secret bindings so it never appears in scripts or logs.
• State tracking uses .ftl2-state-hetzner.json to record provisioned resources, enabling idempotent re-runs.
• Ordered teardown deletes resources in reverse dependency order (server network attachments before networks, etc.).
• ftl.add_host() bridges provisioning and configuration — create a server, then SSH into it in the same script.
• Check mode (--check) enables dry runs before actual provisioning.

Commands and Syntax

Setup:

ansible-galaxy collection install hetzner.hcloud
export HCLOUD_TOKEN="your-api-token"
export HETZNER_SSH_PUBKEY_FILE="~/.ssh/id_ed25519.pub"

Running the web stack example:

uv run python example_hetzner_web_stack.py --check      # dry run
uv run python example_hetzner_web_stack.py               # provision
uv run python example_hetzner_web_stack.py --teardown    # teardown

Python call syntax:

await ftl.hetzner.hcloud.server(name="web01", ...)

Web stack provisions (in order): SSH key → private network + subnet (10.0.0.0/16) → firewall (SSH/HTTP/HTTPS/ICMP) → CX22 server → network attachment → Nginx install via SSH.

Relationships

• Module usage — Hetzner modules follow the same FQCN calling convention as all FTL2 modules; parameters and return values follow standard patterns.
• Secret bindings / Vault integration — HCLOUD_TOKEN injection is an instance of FTL2's secret binding system.
• State & idempotency — .ftl2-state-hetzner.json is a concrete example of FTL2 state files for crash recovery and re-entrancy.
• Check mode — --check flag is the same global dry-run mechanism used across all FTL2 scripts.
• add_host() / dynamic hosts — ties into inventory management (adding hosts discovered at runtime).
• Gate modules — Hetzner collection modules can be pre-built for performance.

Exam-Relevant Points

• The state file for Hetzner is .ftl2-state-hetzner.json — know the naming pattern.
• Teardown order is reverse dependency order, not arbitrary.
• CX22 spec: 2 vCPU, 4GB RAM, 40GB SSD (shared Intel/AMD).
• Server type prefixes: cx = shared Intel/AMD, cax = shared ARM/Ampere, cpx = dedicated AMD, ccx = dedicated high-memory AMD.
• Six datacenter locations: nbg1, fsn1, hel1 (EU), ash (US East), hil (US West), sin (APAC).
• The collection is installed via ansible-galaxy collection install hetzner.hcloud, not pip.
• ftl.add_host() is how you transition from cloud provisioning to host configuration within a single script.
• Secret bindings ensure HCLOUD_TOKEN is injected but never logged — a security and audit feature.