Hetzner Cloud

Status: available · package wg-flow-plugin-hetzner 0.1.0 · provider hetzner · category cloud.

The plugin calls the Hetzner Cloud API and sends the project into inventory. It needs a project API token. The token stays in the agent YAML.

Create the token in the Cloud project: Security → API tokens. The plugin only sends GET. One source is one project.

SSH keys, images, snapshots and ISOs are not emitted in 0.1.0.

Install

The agent must be connected to the API.

docker compose exec agent wg-flow-agent plugin install hetzner
# or
wg-flow-agent plugin install hetzner

Then the local UI → Connections → hetzner, or YAML.

What lands in inventory

Hetzner object	resource_type	Notes
Cloud server	server	provider_resource_id = server:{id}. running → active, off → stopped, transitional states → pending. Public IPv4 → metadata.primary_ipv4
Volume	storage	volume:{id}. available → active, creating → pending. Size in metadata.size_gb
Load balancer	load_balancer	lb:{id}. Public network enabled: false → stopped
Floating IP	network	floating-ip:{id}. blocked → error. IPv4 is also metadata.primary_ipv4
Primary IP	network	primary-ip:{id}, including an address that is not assigned to a server
Private network	network	network:{id}. Region is the subnet network_zone
Firewall	firewall	firewall:{id}. Compact rule list in metadata
Certificate	certificate	certificate:{id}. Unusable or issuance error → pending / error. not_valid_after is the expiry

There is no separate ip type in inventory, so addresses are network with metadata.product floating_ip or primary_ip.

Collection pieces can be turned off separately. A disabled piece is omitted from the next successful sync, and inventory then marks those rows inactive. An API error fails the whole source, so a partial list is not sent.

Several projects are several sources. provider_account is the label you choose; the token itself selects the project.

YAML

plugins:
  hetzner:
    enabled: true
    sources:
      - id: prod
        provider_account: "hz-prod"
        sync_interval_seconds: 300
        url: "https://api.hetzner.cloud/v1"
        token: "…"
        collect_servers: true
        collect_volumes: true
        collect_load_balancers: true
        collect_floating_ips: true
        collect_primary_ips: true
        collect_networks: true
        collect_firewalls: true
        collect_certificates: true

Source fields

Field	Required	Description
id	yes	Log key (hetzner/prod)
provider_account	yes	Project label in inventory
url	no	Default https://api.hetzner.cloud/v1
token	yes	Project API token; masked in the UI
collect_*	no	Default true. See the table above
sync_interval_seconds	no	Minimum 300

Check

wg-flow-agent status
wg-flow-agent dry-run

JSON shows provider: hetzner. Health calls GET /servers?per_page=1. The token is not stored in inventory.

Common errors

Symptom	What to check
401 / 403	Token belongs to this project and was copied in full
Empty servers	collect_servers is on; the project actually has servers
Volumes disappeared after a sync	collect_volumes was turned off; inventory deactivates omitted rows
No public address on a server	The server has no IPv4 (public_net.ipv4 is null). IPv6 is metadata.ipv6
Duplicates with another plugin	different provider is expected; merge in the console