Proveedor de Terraform

Cloady tiene un proveedor de Terraform en el registro público, así que los espacios de trabajo, las aplicaciones, las variables de entorno y los dominios propios pueden declararse como código y revisarse, versionarse y desplegarse como el resto de tu infraestructura.

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 lo instala desde el registro. No hay nada más que configurar.

Autenticación

Crea un token en Account → API tokens y expórtalo:

export CLOADY_TOKEN=cldy_xxxxxxxxxxxxxxxx

El proveedor lee CLOADY_TOKEN de forma predeterminada; define token en el bloque del proveedor para sustituirlo, y base_url (o CLOADY_CONTROL_PLANE_URL) para apuntar a una instalación de Cloady distinta de https://cloady.com.

Crear espacios de trabajo y cambiar la facturación requieren un token con alcance full. Todo lo demás funciona con deploy, y las lecturas, con read. Además, tu rol en el espacio de trabajo se sigue aplicando: un token full no puede eliminar nada en un espacio de trabajo donde eres viewer.

Recursos

Dos fuentes de datos leen el estado existente sin gestionarlo: cloady_workspace, y cloady_regions para las regiones en las que puedes desplegar. Todas las regiones aceptan apps de cualquier espacio de trabajo, gratuito o de pago.

La referencia completa de atributos está en el Terraform Registry.

Un stack completo

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
}

Cada aplicación se ejecuta en una región y un entorno, y su nombre debe ser único dentro de ese espacio de trabajo y ese entorno. environment vale production por defecto allí donde se acepta; usa preview o development para los otros entornos. Las claves de las variables van en SCREAMING_SNAKE_CASE.

Lee esto antes de tu primer apply

El modelo de Terraform es «hacer que la realidad coincida con la configuración», y elimina y vuelve a crear un recurso siempre que cambias un atributo que no puede modificar. En una aplicación con datos, recrearla significa perder los datos.

• Algunos atributos fuerzan la sustitución. Una aplicación se crea en una región, en un entorno, en un espacio de trabajo y a partir de un origen, y se queda ahí. Cambiar region, environment, workspace o la URL del repositorio de Git supone destruirla y crearla de nuevo: datos vacíos, una dirección nueva y tiempo de inactividad.
• Los volúmenes solo crecen. Reducir un valor de volume_sizes se rechaza durante el plan. Para usar un volumen más pequeño, haz una copia de seguridad y crea una aplicación nueva.
• Los cambios de variables llegan a la app en su siguiente despliegue. Un apply que solo toca cloady_variable no reinicia nada; ejecuta después cloady redeploy acme api si la app necesita el valor ya.
• Los valores de las variables se guardan en texto plano en el estado de Terraform, secretos incluidos. is_secret oculta el valor en Cloady, pero no cifra tu archivo de estado. Usa un backend remoto con cifrado en reposo y prefiere entradas var. a valores literales.
• En cloady_domain, solo redirect_to cambia in situ. Cambiar host o is_primary sustituye el registro; la app sigue funcionando, pero el nuevo host necesita que su DNS apunte a Cloady antes de que HTTPS funcione en él.
• Un apply correcto no significa una aplicación sana. La creación termina en cuanto empieza el despliegue, así que status refleja lo que Cloady vio en ese momento, no si la app está lista. Sigue el despliegue en el panel o con la CLI.

La escala es un multiplicador sobre lo que pide la aplicación, no un tamaño absoluto: cpu_scale = 2 lo duplica. Los valores van de 0.5 a 4 en pasos de 0.25, y todo lo que se ejecuta en el espacio de trabajo (en cualquier región y en cualquier entorno) cuenta para lo que paga el espacio de trabajo.

Mientras el stack aplicado quepa en la asignación gratuita del espacio de trabajo, no se cobra nada. Si la supera, se cobra la diferencia a la tarjeta registrada mientras se ejecuta el apply; sin tarjeta, o si la tarjeta se rechaza, Cloady responde payment_required y Terraform se detiene. El propietario del espacio de trabajo añade una tarjeta en Account → Billing; después, vuelve a ejecutar el apply.

Importar aplicaciones existentes

Todo lo creado en el panel se puede adoptar sin recrearlo. El ID de importación es la dirección del recurso, con sus partes separadas por barras:

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>

Los ids de variables y dominios se obtienen con listVars y listAppDomains de la API, o con la CLI.

Relación con las demás interfaces

El proveedor llama a la misma API REST que el panel, la CLI, los SDK y el servidor MCP, con las mismas comprobaciones de alcance y de rol. Lo que cambia es para qué sirve: la CLI y el servidor MCP ejecutan acciones, mientras que Terraform converge hacia un estado final declarado y deshará cualquier drift en el siguiente apply.

Por eso no encaja bien con operaciones puntuales. Reiniciar un servicio, ejecutar un comando en un contenedor, revertir un despliegue o leer logs son acciones sin un estado deseado al que converger, y siguen siendo cosa de la CLI y la API.