Terraform-Provider

Cloady hat einen Terraform-Provider in der öffentlichen Registry. Damit lassen sich Workspaces, Anwendungen, Umgebungsvariablen und eigene Domains als Code deklarieren und wie der Rest deiner Infrastruktur reviewen, versionieren und ausrollen.

terraform {
  required_providers {
    cloady = {
      source  = "cloady/cloady"
      version = "~> 0.1"
    }
  }
}

provider "cloady" {} # reads CLOADY_TOKEN

resource "cloady_app" "api" {
  workspace = "acme"
  name      = "API"
  region    = "eu1"
  git       = { repository_url = "https://github.com/acme/api" }
}

output "url" {
  value = cloady_app.api.endpoints[0].url
}

terraform init installiert ihn aus der Registry. Sonst musst du nichts einrichten.

Authentifizieren

Erstelle unter Account → API tokens ein Token und exportiere es:

export CLOADY_TOKEN=cldy_xxxxxxxxxxxxxxxx

Der Provider liest standardmäßig CLOADY_TOKEN; mit token im Provider-Block überschreibst du das, und mit base_url (oder CLOADY_CONTROL_PLANE_URL) zeigst du auf eine andere Cloady-Installation als https://cloady.com.

Um Workspaces anzulegen und die Abrechnung zu ändern, brauchst du ein Token mit Scope full. Alles andere geht mit deploy, Lesezugriffe mit read. Deine Workspace-Rolle gilt zusätzlich: Ein full-Token kann in einem Workspace, in dem du Viewer bist, nichts löschen.

Ressourcen

Zwei Data Sources lesen bestehenden State, ohne ihn zu verwalten: cloady_workspace und cloady_regions für die Regionen, in die du deployen kannst. Jede Region nimmt Apps aus jedem Workspace an, ob kostenlos oder bezahlt.

Die vollständige Attributreferenz findest du in der Terraform Registry.

Ein kompletter Stack

data "cloady_regions" "all" {}

resource "cloady_workspace" "acme" {
  slug = "acme"
  name = "Acme"
}

resource "cloady_app" "db" {
  workspace = cloady_workspace.acme.slug
  name      = "Postgres"
  region    = "eu1"
  catalog   = "postgres"

  volume_sizes = { data = 20 }

  lifecycle {
    prevent_destroy = true
  }
}

resource "cloady_app" "api" {
  workspace    = cloady_workspace.acme.slug
  name         = "API"
  region       = "eu1"
  cpu_scale    = 2
  memory_scale = 2

  git = {
    repository_url = "https://github.com/acme/api"
    branch         = "main"
    auto_deploy    = true
  }
}

resource "cloady_variable" "database_url" {
  workspace = cloady_workspace.acme.slug
  app       = cloady_app.api.slug
  region    = cloady_app.api.region
  key       = "DATABASE_URL"
  value     = var.database_url
  is_secret = true
}

resource "cloady_domain" "api" {
  workspace  = cloady_workspace.acme.slug
  app        = cloady_app.api.slug
  region     = cloady_app.api.region
  host       = "api.acme.com"
  is_primary = true
}

Jede Anwendung läuft in einer Region und einer Umgebung, und ihr Name muss innerhalb dieses Workspaces und dieser Umgebung eindeutig sein. environment ist überall, wo es angegeben werden kann, standardmäßig production; für die anderen Umgebungen setzt du preview oder development. Variablenschlüssel sind SCREAMING_SNAKE_CASE.

Lies das vor deinem ersten Apply

Terraform folgt dem Prinzip „die Realität an die Konfiguration anpassen“ und wird eine Ressource löschen und neu anlegen, sobald sich ein Attribut ändert, das es nicht direkt ändern kann. Bei einer Anwendung mit Daten bedeutet das Neuanlegen Datenverlust.

• Manche Attribute erzwingen ein Ersetzen. Eine Anwendung wird in einer Region, in einer Umgebung, in einem Workspace und aus einer Quelle angelegt und bleibt dort. Eine Änderung von region, environment, workspace oder der URL des Git-Repositorys bedeutet Zerstören und anschließendes Neuanlegen: leere Daten, eine neue Adresse, Ausfallzeit.
• Volumes wachsen nur. Wenn du einen Wert in volume_sizes verringerst, wird das schon beim Plan abgelehnt. Für kleinere Volumes legst du ein Backup an und erstellst eine neue Anwendung.
• Geänderte Variablen erreichen die App beim nächsten Deploy. Ein Apply, der nur cloady_variable betrifft, startet nichts neu; führe danach cloady redeploy acme api aus, wenn die App den Wert sofort braucht.
• Variablenwerte landen im Klartext im Terraform-State, auch Secrets. is_secret verbirgt den Wert in Cloady, verschlüsselt aber nicht deine State-Datei. Nutze ein Remote-Backend mit Verschlüsselung im Ruhezustand und verwende lieber var.-Eingaben als Literale.
• Bei cloady_domain ändert sich nur redirect_to direkt. Eine Änderung von host oder is_primary ersetzt den Eintrag; die App läuft weiter, aber die DNS-Einträge des neuen Hosts müssen auf Cloady zeigen, bevor HTTPS dort funktioniert.
• Ein erfolgreicher Apply heißt nicht, dass die Anwendung gesund ist. Das Anlegen gilt als abgeschlossen, sobald der Deploy startet; status meldet also, was Cloady in diesem Moment gesehen hat, nicht die Betriebsbereitschaft. Verfolge den Deploy im Dashboard oder mit der CLI.

Die Skalierung ist ein Multiplikator für das, was die Anwendung anfordert, keine absolute Größe: cpu_scale = 2 verdoppelt es. Die Werte reichen von 0,5 bis 4 in Schritten von 0,25, und alles, was im Workspace läuft – in jeder Region, in jeder Umgebung –, zählt zu dem, was der Workspace bezahlt.

Solange der angewendete Stack in das Gratis-Kontingent des Workspaces passt, wird nichts berechnet. Darüber hinaus wird die hinterlegte Karte mit der Differenz belastet, während der Apply läuft; ohne Karte oder bei einer abgelehnten Karte antwortet Cloady mit payment_required, und Terraform bricht ab. Der Inhaber des Workspaces hinterlegt unter Account → Billing eine Karte; danach führst du den Apply erneut aus.

Bestehende Anwendungen importieren

Alles, was im Dashboard angelegt wurde, kannst du übernehmen, ohne es neu anzulegen. Die Import-ID ist die Adresse der Ressource, getrennt durch Schrägstriche:

terraform import cloady_workspace.acme acme
terraform import cloady_app.api        acme/api/production/eu1
terraform import cloady_variable.db    acme/api/production/eu1/<variable-id>
terraform import cloady_domain.api     acme/api/production/eu1/<domain-id>

Die IDs von Variablen und Domains bekommst du über listVars und listAppDomains in der API oder über die CLI.

Verhältnis zu den anderen Schnittstellen

Der Provider ruft dieselbe REST-API auf wie das Dashboard, die CLI, die SDKs und der MCP-Server, mit denselben Prüfungen von Scope und Rolle. Er unterscheidet sich im Zweck: CLI und MCP-Server führen Aktionen aus, während Terraform auf einen deklarierten Endzustand hinarbeitet und Drift beim nächsten Apply rückgängig macht.

Deshalb eignet er sich schlecht für einmalige Vorgänge. Einen Service neu starten, einen Befehl in einem Container ausführen, einen Deploy zurückrollen oder Logs lesen sind Aktionen ohne Zielzustand, auf den man hinarbeiten könnte, und sie bleiben Sache der CLI und der API.