Apps en DNS beheren met Terraform

Beheer je je infrastructuur al met Terraform, dan kunnen je Headpat-apps, eigen hostnamen en DNS-records daar ook in. De headpat-provider praat met dezelfde API als het paneel, met een API-sleutel als authenticatie. Deze gids installeert de provider, maakt een app met een hostnaam en een DNS-record, en legt de ene stap uit die Terraform niet voor je kan doen: betalen.

Wat je nodig hebt

• Terraform 1.5 of nieuwer (OpenTofu werkt op dezelfde manier).
• Een API-sleutel met de scopes apps:read, apps:write, dns:read en dns:write; zie Het paneel automatiseren met API-sleutels en de CLI voor hoe je die maakt.

1. Installeer de provider

De provider staat nog niet in het openbare Terraform-register, dus je vertelt Terraform waar hij staat. Download de zip voor je platform van de nieuwste Terraform-providerrelease (de releases heten Terraform provider x.y.z) en pak het binaire bestand uit in een map naar keuze, bijvoorbeeld ~/.terraform.d/headpat.

Wijs Terraform daarna naar die map met een dev override in je CLI-configuratiebestand, ~/.terraformrc op Linux en macOS, %APPDATA%\terraform.rc op Windows:

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

Met een dev override slaat Terraform terraform init voor deze provider over en meldt het bij elke run dat het een lokale build gebruikt. Dat is normaal.

2. Stel hem in

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

provider "headpat" {}

De provider leest de sleutel uit de omgevingsvariabele HEADPAT_API_KEY. Je kunt ook api_key in het providerblok zetten, bijvoorbeeld vanuit een Terraform-variabele; zet de sleutel zelf nooit in versiebeheer.

3. Beschrijf een app, een hostnaam en een DNS-record

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 en tier zijn de slugs uit de catalogus; data.headpat_app_catalog.all.templates somt ze op met prijzen. Het wijzigen van image, port, env of volume_path werkt de draaiende app bij; het wijzigen van template, tier of naam vervangt hem. Voor de andere templates, zoals WordPress of PostgreSQL, laat je de Container App-attributen weg.

headpat_app_domain geeft alles terug wat het paneel voor een eigen hostnaam toont: het CNAME-doel, het A-record-alternatief voor apex-namen en het TXT-record dat eigendom bewijst. Die invoeren in headpat_dns_record zoals hierboven betekent dat één terraform apply de app maakt, de hostnaam koppelt en de records publiceert die hem valideren.

export HEADPAT_API_KEY=...
terraform plan
terraform apply

4. Betalen voor nieuwe diensten

Terraform kan geen Stripe-afrekening afronden. Betaalt je account per dienst, dan levert het aanmaken van een headpat_app een concept en een checkout_url op, en eindigt de apply met een waarschuwing die de URL noemt. Open de URL, betaal, en de app wordt opgezet; de volgende terraform plan of terraform refresh toont hem als running. Accounts die anders worden gefactureerd slaan deze stap over en de provider wacht tot de app draait (create_timeout_minutes, standaard tien).

Bestaande diensten importeren

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

De id's staan in de URL's van het paneel en in headpat apps list --json en headpat dns zones --json van de CLI.

Verwijderen

terraform destroy op een headpat_app zegt het abonnement standaard op aan het einde van de factureringsperiode, dus de app blijft tot dan draaien. Zet delete_immediately = true op de resource als hij meteen moet verdwijnen; de data gaat dan mee.

Naslag

De resources en databronnen, met elk attribuut, staan beschreven in terraform/docs in de releaserepository, naast een compleet voorbeeld. Nu beschikbaar: headpat_app, headpat_app_domain, headpat_dns_zone, headpat_dns_record, en de databronnen headpat_app_catalog, headpat_app en headpat_dns_zones.