Referencia de Terraform de ClickHouse Managed Postgres

Los servicios de ClickHouse Managed Postgres se pueden crear y administrar mediante el recurso clickhouse_postgres_service del proveedor de Terraform de ClickHouse. Esta página describe la configuración del proveedor y ofrece ejemplos de configuración para este recurso y sus fuentes de datos asociadas.

Este recurso está en alpha y su comportamiento puede cambiar en futuras versiones del proveedor. Se distribuye en el build habitual del proveedor. Esta página documenta la versión v3.21.0 del proveedor y posteriores. Consulta las releases del proveedor para más detalles.

Configuración del proveedor

Añada el proveedor de ClickHouse a su configuración de Terraform:

terraform {
  required_providers {
    clickhouse = {
      source  = "ClickHouse/clickhouse"
      version = ">= 3.21.0"
    }
  }
}

provider "clickhouse" {
  organization_id = var.organization_id
  token_key       = var.token_key
  token_secret    = var.token_secret
}

Consulta Gestión de claves de API para ver instrucciones sobre cómo crear una clave de API para usarla con el proveedor.

Resumen del recurso

El recurso clickhouse_postgres_service tiene los siguientes argumentos:

Argumento	Obligatorio	Descripción
`name`	Sí	Nombre del servicio legible para humanos. Es inmutable: si se cambia, el servicio se destruye y se vuelve a crear.
`cloud_provider`	Para una creación estándar	Proveedor de Cloud que aloja la instancia. Actualmente solo se admite `aws`. Omítalo para una réplica de lectura o una restauración a un momento dado (se hereda del origen).
`region`	Para una creación estándar	Región de Cloud (por ejemplo, `us-east-1`). Omítala para una réplica de lectura o una restauración a un momento dado (se hereda del origen).
`size`	Para una creación estándar	Tamaño de la instancia (SKU de VM), por ejemplo `m6gd.large`. Se puede redimensionar sin recrearla. Omítalo para una restauración a un momento dado (la instancia restaurada se inicia con el tamaño de la copia de seguridad).
`postgres_version`	No	Versión principal de Postgres (por ejemplo, `18`). Cambiar la versión principal destruye y vuelve a crear el servicio.
`ha_type`	No	Modo de alta disponibilidad: `none`, `async` o `sync`. Consulte Alta disponibilidad.
`password`	Para una creación estándar, a menos que se establezca `password_wo`	Contraseña del superusuario, gestionada desde su configuración. Terraform nunca la vuelve a leer desde la API. Se almacena en el estado como dato sensible. Omítala para una réplica de lectura (se hereda) o una restauración a un momento dado (se conserva de la copia de seguridad de origen).
`password_wo`	Para una creación estándar, a menos que se establezca `password`	Contraseña de superusuario de solo escritura: se aplica al servicio, pero nunca se almacena en el estado. Requiere `password_wo_version`; requiere Terraform 1.11 o posterior.
`password_wo_version`	Con `password_wo`	Número de versión para `password_wo`. Cámbielo para rotar al valor actual de `password_wo`.
`pg_config`	No	Parámetros del servidor Postgres como un mapa de clave-valor.
`pgbouncer_config`	No	Parámetros del agrupador de conexiones PgBouncer como un mapa de clave-valor.
`tags`	No	Etiquetas del recurso como un mapa de clave-valor.
`read_replica_of`	No	ID de un servicio primario que se va a replicar. Consulte Réplicas de lectura. Es mutuamente excluyente con `restore_to_point_in_time`.
`restore_to_point_in_time`	No	Crea el servicio restaurando otro servicio a un momento dado. Consulte Restauración a un momento dado. Es mutuamente excluyente con `read_replica_of`.

Los siguientes atributos son de solo lectura y ClickHouse Cloud los completa después de la creación: id, state, created_at, is_primary, hostname, port y username. No existe el atributo connection_string: construya los URI de conexión a partir de hostname, port, username y la contraseña que declare, por ejemplo postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require.

El valor de password se almacena en texto sin formato en el estado de Terraform. Proteja su archivo de estado en consecuencia, por ejemplo, con un backend remoto que use cifrado en reposo, o use password_wo para mantener la contraseña completamente fuera del estado.

Crear un servicio

resource "clickhouse_postgres_service" "example" {
  name           = "my-postgres"
  cloud_provider = "aws"
  region         = "us-east-1"
  size           = "m6gd.large"
  password       = var.postgres_password

  # High-availability mode — number of standby replicas:
  #   "none"  – primary only, no standby (default)
  #   "async" – 1 standby, asynchronous replication
  #   "sync"  – 2 standbys, synchronous replication
  ha_type = "async"

  tags = {
    environment = "production"
    team        = "data"
  }
}

Un servicio estándar debe declarar password o password_wo. El valor debe tener al menos 12 caracteres, con al menos una letra minúscula, una mayúscula y un dígito. password_wo (con password_wo_version) aplica las mismas reglas de contraseña, pero nunca se almacena en el estado; cambia password_wo_version para rotarla. Como la API no devuelve credenciales, Terraform debe seguir siendo el único que establezca la contraseña: una contraseña rotada fuera de Terraform (Console o API) no se detecta, y la siguiente rotación gestionada por Terraform vuelve a aplicar el valor declarado.

Alta disponibilidad

El argumento ha_type controla el número de réplicas standby:

`ha_type`	Standbys	Replicación
`none`	Ninguna (solo primaria)	—
`async`	1 standby	Asíncrona — el commit de las escrituras se realiza sin esperar a la standby
`sync`	2 standbys	Sincrónica — la primaria espera la confirmación de al menos una standby

ha_type puede modificarse tras su creación; cambiarlo desencadena una transición de HA. Consulta Alta disponibilidad para obtener más información.

Réplicas de lectura

Establece read_replica_of con el id de un servicio primario para crear una réplica de lectura en streaming. Una réplica hereda el cloud_provider, la región, la postgres_version y el superusuario del primario; omítelos (y la contraseña):

resource "clickhouse_postgres_service" "replica" {
  name            = "my-postgres-replica"
  size            = "m6gd.large"
  read_replica_of = clickhouse_postgres_service.example.id
}

Consulta réplicas de lectura para más información.

Restauración a un momento dado

Configura restore_to_point_in_time para crear un servicio restaurando la copia de seguridad de otro servicio a un momento determinado. cloud_provider, region y postgres_version se heredan del servicio de origen (omítelos); size y ha_type también deben omitirse:

resource "clickhouse_postgres_service" "restored" {
  name = "my-postgres-restored"

  restore_to_point_in_time = {
    source_id      = clickhouse_postgres_service.example.id
    restore_target = "2026-06-01T12:00:00Z"
  }
}

Todo el bloque solo se usa durante la creación: cambiar source_id o restore_target, o eliminar el bloque, destruye y vuelve a crear el servicio. Consulta Copia de seguridad y restauración para más detalles.

Fuentes de datos

Tres fuentes de datos complementarias le permiten consultar los servicios existentes:

# A single service by ID.
data "clickhouse_postgres_service" "example" {
  id = clickhouse_postgres_service.example.id
}

# All ClickHouse Managed Postgres services in the organization.
data "clickhouse_postgres_services" "all" {}

# The CA certificates for a service, for TLS connections.
data "clickhouse_postgres_service_ca_certificates" "certs" {
  service_id = clickhouse_postgres_service.example.id
}

Importación de servicios existentes

Los servicios existentes de ClickHouse Managed Postgres se pueden importar al estado de Terraform mediante el ID del servicio:

terraform import clickhouse_postgres_service.example xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

La contraseña no se recupera al importar (la API no la devuelve). Después de importar, el primer apply cambia la contraseña del servicio a la password o password_wo declarada en su configuración.

Operaciones no admitidas

Los siguientes elementos se omiten intencionadamente del esquema del recurso:

Comandos operativos (restart, promote, switchover).
Listas de direcciones IP permitidas, endpoints privados, configuración de copias de seguridad, ventanas de mantenimiento, claves de cifrado gestionadas por el cliente y BYOC.
Tiempos de espera configurables del ciclo de vida: no hay ningún bloque timeouts {}.

Primeros pasos

Características

Precios

Integración de ClickHouse

Migraciones

Monitoring

FAQ

Referencia de Terraform de ClickHouse Managed Postgres

Configuración del proveedor

Resumen del recurso

Crear un servicio

Alta disponibilidad

Réplicas de lectura

Restauración a un momento dado

Fuentes de datos

Importación de servicios existentes

Operaciones no admitidas

​Configuración del proveedor

​Resumen del recurso

​Crear un servicio

​Alta disponibilidad

​Réplicas de lectura

​Restauración a un momento dado

​Fuentes de datos

​Importación de servicios existentes

​Operaciones no admitidas

Configuración del proveedor

Resumen del recurso

Crear un servicio

Alta disponibilidad

Réplicas de lectura

Restauración a un momento dado

Fuentes de datos

Importación de servicios existentes

Operaciones no admitidas