Skip to content

Init annex: Hetzner

Status: Stable (Public)
Version: 1.0

This annex defines Hetzner-specific requirements and outputs for hyops init hetzner.

Global rules are defined in hyops init contract.

1. Config

Default config path:

  • <root>/config/hetzner.conf

Config format is line-oriented KEY=value.

1.1 Required keys (non-secret)

No non-secret required keys are mandated by this annex.

1.2 Optional keys (non-secret)

  • HCLOUD_API (optional; default: https://api.hetzner.cloud)

  • HCLOUD_TFVARS_OUT (optional)
    Override credentials tfvars output path.

2. Vault keys

Default vault path:

  • <root>/vault/bootstrap.vault.env

Optional secrets used:

  • HCLOUD_TOKEN

Rules:

  • HCLOUD_TOKEN MAY be provided via:
  • shell env (HCLOUD_TOKEN), or
  • runtime vault bundle (HCLOUD_TOKEN), or
  • interactive prompt (TTY only), or
  • config file (discouraged; implementation SHOULD warn)

3. Behaviour

3.1 Token resolution

The implementation MUST resolve a token using best-effort precedence:

  1. CLI override (--token) (discouraged)
  2. Shell env (HCLOUD_TOKEN)
  3. Runtime vault (HCLOUD_TOKEN) when decryptable
  4. Config file (HCLOUD_TOKEN) as a backwards-compatible fallback with warning
  5. Interactive hidden prompt (TTY only) when token is still missing and not in --non-interactive mode

Token validation MUST be performed before writing outputs.

3.2 Non-interactive mode

When --non-interactive is set:

  • interactive prompts MUST NOT be used
  • init MUST fail fast with guidance when HCLOUD_TOKEN cannot be resolved

When --non-interactive is not set and token validation fails for a resolved token:

  • implementation MAY prompt once for a replacement token in hidden-input mode
  • replacement token MUST still pass validation before outputs are written

3.3 Token validation

Token validation MUST confirm that the token can authenticate to HCLOUD_API. Validation MUST complete successfully before:

  • readiness marker is written
  • credentials tfvars file is written
  • prompted token is persisted into runtime vault (when vault auth is available)

4. Outputs

4.1 Credentials tfvars

Default path:

  • <root>/credentials/hetzner.credentials.tfvars

The file MUST be mode 0600.

The tfvars file MUST include:

  • hcloud_token (sensitive)
  • hcloud_api

4.2 Readiness marker

Default path:

  • <root>/meta/hetzner.ready.json

The marker MUST reflect status=ready only when:

  • token validation succeeds, and
  • the credentials tfvars file is written successfully.

4.3 Evidence

Evidence MUST be written under:

  • <root>/logs/init/hetzner/<run_id>/

Evidence MUST NOT include HCLOUD_TOKEN.

5. Failure semantics

  • If --non-interactive is set and HCLOUD_TOKEN is missing or vault decrypt fails, init MUST fail with exit code 21.
  • If token validation fails, init MUST fail with exit code 20.
  • If credentials file writing fails, init MUST fail with exit code 30.