Apps und DNS mit Terraform verwalten

Wenn du deine Infrastruktur schon in Terraform hältst, können deine Headpat-Apps, eigenen Hostnamen und DNS-Einträge dort ebenfalls leben. Der headpat-Provider spricht mit derselben API wie das Panel, authentifiziert mit einem API-Schlüssel. Diese Anleitung installiert ihn, legt eine App mit Hostname und DNS-Eintrag an und erklärt den einen Schritt, den Terraform nicht für dich erledigen kann: das Bezahlen.

Was du brauchst

• Terraform 1.5 oder neuer (OpenTofu funktioniert genauso).
• Einen API-Schlüssel mit den Scopes apps:read, apps:write, dns:read und dns:write; wie du ihn anlegst, steht in Das Panel mit API-Schlüsseln und der CLI automatisieren.

1. Provider installieren

Der Provider ist noch nicht in der öffentlichen Terraform-Registry, deshalb sagst du Terraform, wo er liegt. Lade die Zip-Datei für dein System aus dem neuesten Terraform-Provider-Release (die Releases heißen Terraform provider x.y.z) und entpacke die Binärdatei in einen Ordner deiner Wahl, zum Beispiel ~/.terraform.d/headpat.

Dann zeigst du Terraform mit einem Dev Override in der CLI-Konfigurationsdatei auf diesen Ordner, ~/.terraformrc unter Linux und macOS, %APPDATA%\terraform.rc unter Windows:

provider_installation {
  dev_overrides {
    "headpatcloud/headpat" = "/home/you/.terraform.d/headpat"
  }
  direct {}
}

Mit einem Dev Override überspringt Terraform terraform init für diesen Provider und warnt bei jedem Lauf, dass es einen lokalen Build verwendet. Das ist so gewollt.

2. Provider konfigurieren

terraform {
  required_providers {
    headpat = {
      source = "headpatcloud/headpat"
    }
  }
}

provider "headpat" {}

Der Provider liest den Schlüssel aus der Umgebungsvariable HEADPAT_API_KEY. Du kannst auch api_key im Provider-Block setzen, etwa aus einer Terraform-Variable; der Schlüssel selbst gehört nie ins Repository.

3. App, Hostname und DNS-Eintrag beschreiben

data "headpat_app_catalog" "all" {}

resource "headpat_dns_zone" "example" {
  zone_name = "example.com"
}

resource "headpat_app" "api" {
  template = "container-app"
  tier     = "standard"
  name     = "api"
  image    = "ghcr.io/acme/api:1.4.0"
  port     = 3000
  env = {
    NODE_ENV = "production"
  }
  volume_path = "/data"
}

resource "headpat_app_domain" "api" {
  app_id   = headpat_app.api.id
  hostname = "api.example.com"
}

resource "headpat_dns_record" "api" {
  zone_id = headpat_dns_zone.example.id
  name    = "api.example.com"
  type    = "CNAME"
  values  = [headpat_app_domain.api.dns_target]
}

resource "headpat_dns_record" "api_ownership" {
  zone_id = headpat_dns_zone.example.id
  name    = "${headpat_app_domain.api.ownership_txt_label}.api.example.com"
  type    = "TXT"
  values  = ["\"${headpat_app_domain.api.ownership_txt_value}\""]
}

output "hostname" {
  value = headpat_app.api.hostname
}

template und tier sind die Slugs aus dem Katalog; data.headpat_app_catalog.all.templates listet sie mit Preisen. Änderungen an image, port, env oder volume_path aktualisieren die laufende App; Änderungen an Template, Tier oder Name ersetzen sie. Bei den anderen Templates, etwa WordPress oder PostgreSQL, lässt du die Container-App-Attribute weg.

headpat_app_domain liefert alles, was das Panel zu einem eigenen Hostnamen zeigt: das CNAME-Ziel, die A-Record-Alternative für Apex-Namen und den TXT-Eintrag, der den Besitz nachweist. Werden diese Werte wie oben in headpat_dns_record eingespeist, legt ein einziges terraform apply die App an, hängt den Hostnamen an und veröffentlicht die Einträge, die ihn validieren.

export HEADPAT_API_KEY=...
terraform plan
terraform apply

4. Neue Dienste bezahlen

Terraform kann keinen Stripe-Checkout abschließen. Zahlt dein Konto pro Dienst, liefert das Anlegen einer headpat_app einen Entwurf und eine checkout_url, und der Apply endet mit einer Warnung, die die URL nennt. Öffne sie, bezahle, und die App wird eingerichtet; der nächste terraform plan oder terraform refresh zeigt sie als running. Anders abgerechnete Konten überspringen diesen Schritt, und der Provider wartet, bis die App läuft (create_timeout_minutes, standardmäßig zehn).

Bestehende Dienste importieren

terraform import headpat_app.api <app-id>
terraform import headpat_app_domain.api <app-id>/<domain-id>
terraform import headpat_dns_zone.example <zone-id>
terraform import headpat_dns_record.api <zone-id>/api.example.com/CNAME

Die IDs stehen in den URLs des Panels sowie in headpat apps list --json und headpat dns zones --json der CLI.

Löschen

terraform destroy auf einer headpat_app kündigt das Abonnement standardmäßig zum Ende des Abrechnungszeitraums, die App läuft also bis dahin weiter. Setze delete_immediately = true auf der Ressource, wenn sie sofort verschwinden soll; die Daten gehen damit verloren.

Referenz

Die Ressourcen und Datenquellen mit allen Attributen sind unter terraform/docs im Release-Repository dokumentiert, daneben liegt ein vollständiges Beispiel. Heute verfügbar: headpat_app, headpat_app_domain, headpat_dns_zone, headpat_dns_record sowie die Datenquellen headpat_app_catalog, headpat_app und headpat_dns_zones.