Managed Postgres Terraform 참고

ClickHouse Managed Postgres 서비스는 ClickHouse Terraform 프로바이더의 clickhouse_postgres_service 리소스를 사용해 생성하고 관리할 수 있습니다. 이 페이지에서는 이 리소스와 관련 데이터 소스를 위한 프로바이더 설정 및 구성 예시를 설명합니다.

이 리소스는 알파 단계이므로 향후 프로바이더 버전에서 동작이 변경될 수 있습니다. 일반 프로바이더 빌드에 포함되어 있습니다. 이 페이지는 자격 증명 관리 방식이 변경된 프로바이더 버전 v3.21.0 이상을 문서화합니다. 이전 버전은 다르게 동작하며, 2026-07-31 기준으로 더 이상 올바르게 작동하지 않습니다. 자세한 내용은 provider releases를 참조하십시오.

2026-07-31 이전에 프로바이더 v3.21.0으로 업그레이드하세요2026-07-31부터 Managed Postgres API는 응답에서 더 이상 슈퍼유저 password와 connection string을 반환하지 않습니다. 자격 증명은 서비스를 생성하거나 password를 재설정할 때만 반환됩니다. 프로바이더 버전 v3.21.0 이상은 이 변경 전후에 동일하게 동작합니다. 이전 프로바이더 버전은 API가 자격 증명을 다시 반환하는 동작에 의존합니다. 2026-07-31 기준으로 이러한 버전은 더 이상 connection_string을 채우지 않으며, 구성에 password를 지정하지 않고 서비스를 생성하면 생성 자체는 성공하더라도 생성된 password는 어디에도 저장되지 않습니다.2026-07-31 이전에 업그레이드하십시오. Terraform state는 v3.21.0에서 첫 번째 계획 또는 적용 시 자동으로 마이그레이션됩니다. 서비스 중 서버가 생성한 password에 의존하는 항목이 있다면(구성에 password가 없는 경우), v3.21.0에서는 표준 서비스에 password 또는 password_wo가 필요하므로 먼저 terraform state pull로 해당 값을 복구한 뒤 구성에 선언하십시오.

프로바이더 설정

Terraform 구성에 ClickHouse 프로바이더를 추가하세요:

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
}

프로바이더에서 사용할 API Key를 만드는 방법은 API Key 관리를 참조하십시오.

리소스 개요

clickhouse_postgres_service 리소스에는 다음 인수가 있습니다:

인수	필수	설명
`name`	예	서비스의 사람이 읽기 쉬운 이름입니다. 변경할 수 없으며, 값을 변경하면 서비스가 삭제된 후 다시 생성됩니다.
`cloud_provider`	일반 생성 시	인스턴스를 호스팅하는 클라우드 제공업체입니다. 현재는 `aws`만 지원됩니다. 읽기 레플리카 또는 특정 시점 복원 시에는 생략하십시오(소스에서 상속됨).
`region`	일반 생성 시	클라우드 리전입니다(예: `us-east-1`). 읽기 레플리카 또는 특정 시점 복원 시에는 생략하십시오(소스에서 상속됨).
`size`	일반 생성 시	인스턴스 크기(VM SKU)입니다(예: `m6gd.large`). 현재 위치에서 크기 조정할 수 있습니다. 특정 시점 복원 시에는 생략하십시오(복원된 인스턴스는 백업 크기로 시작함).
`postgres_version`	아니요	Postgres의 메이저 버전입니다(예: `18`). 메이저 버전을 변경하면 서비스가 삭제된 후 다시 생성됩니다.
`ha_type`	아니요	고가용성 모드입니다: `none`, `async`, 또는 `sync`. 고가용성를 참조하십시오.
`password`	일반 생성 시, 단 `password_wo`가 설정되지 않은 경우	구성에서 관리되는 슈퍼유저 비밀번호입니다. Terraform은 이를 API에서 다시 읽지 않습니다. (민감한) state에 저장됩니다. 읽기 레플리카 또는 특정 시점 복원 시에는 생략하십시오(각각 상속되거나 소스 백업의 값이 유지됨).
`password_wo`	일반 생성 시, 단 `password`가 설정되지 않은 경우	쓰기 전용 슈퍼유저 비밀번호입니다. 서비스에는 적용되지만 state에는 저장되지 않습니다. `password_wo_version`이 필요하며, Terraform 1.11 이상이 필요합니다.
`password_wo_version`	`password_wo`와 함께	`password_wo`의 버전 번호입니다. 현재 `password_wo` 값으로 교체하려면 이 값을 변경하십시오.
`pg_config`	아니요	키-값 맵 형태의 Postgres 서버 매개변수입니다.
`pgbouncer_config`	아니요	키-값 맵 형태의 PgBouncer 연결 풀러 매개변수입니다.
`tags`	아니요	키-값 맵 형태의 리소스 태그입니다.
`read_replica_of`	아니요	복제할 기본 서비스의 ID입니다. 읽기 레플리카를 참조하십시오. `restore_to_point_in_time`와는 함께 사용할 수 없습니다.
`restore_to_point_in_time`	아니요	다른 서비스를 특정 시점으로 복원하여 서비스를 생성합니다. 특정 시점 복원를 참조하십시오. `read_replica_of`와는 함께 사용할 수 없습니다.

다음 속성은 읽기 전용이며 생성 후 ClickHouse Cloud가 값을 채웁니다: id, state, created_at, is_primary, hostname, port, 그리고 username. connection_string 속성은 없습니다(v3.21.0에서 제거됨). 연결 URI는 hostname, port, username, 그리고 선언한 비밀번호를 사용해 직접 구성하십시오. 예: postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require.

The password는 Terraform state에 평문으로 저장됩니다. 따라서 state 파일을 적절히 보호하십시오. 예를 들어 저장 시 암호화가 적용된 원격 백엔드를 사용하거나, password_wo를 사용해 비밀번호가 state에 전혀 저장되지 않도록 하십시오.

서비스 생성

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"
  }
}

표준 서비스는 password 또는 password_wo를 선언해야 합니다. 이 값은 최소 12자여야 하며, 소문자 1개 이상, 대문자 1개 이상, 숫자 1개 이상을 포함해야 합니다. password_wo(password_wo_version과 함께 사용)는 동일한 password 규칙을 적용하지만 state에는 저장되지 않으며, 교체하려면 password_wo_version을 변경하세요. API는 자격 증명을 반환하지 않으므로 password는 Terraform만 유일하게 쓰도록 유지해야 합니다. Terraform 외부에서 password를 교체하면(console 또는 API) 이 변경은 감지되지 않으며, 다음 Terraform 기반 교체 시 선언된 값이 다시 적용됩니다.

고가용성

ha_type 인수는 대기 레플리카 수를 제어합니다:

`ha_type`	대기 인스턴스	복제
`none`	없음(프라이머리만)	—
`async`	대기 인스턴스 1개	비동기 — 대기 인스턴스를 기다리지 않고 쓰기 commit이 완료됩니다
`sync`	대기 인스턴스 2개	동기 — 프라이머리는 최소 1개의 대기 인스턴스로부터 응답을 받을 때까지 기다립니다

ha_type는 생성 후에도 변경할 수 있으며, 변경하면 HA 전환이 시작됩니다. 자세한 내용은 고가용성을 참조하십시오.

읽기 레플리카

스트리밍 읽기 레플리카를 생성하려면 read_replica_of를 기본 서비스의 id로 설정합니다. 레플리카는 프라이머리의 cloud_provider, region, postgres_version, 그리고 슈퍼유저를 상속하므로, 이 항목들(password 포함)은 생략합니다:

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

자세한 내용은 읽기 레플리카를 참조하십시오.

특정 시점 복원

다른 서비스의 백업을 특정 시점으로 복원하여 서비스를 생성하려면 restore_to_point_in_time을 설정합니다. cloud_provider, region, postgres_version은 원본 서비스에서 상속되므로 지정하지 마십시오. size와 ha_type도 생략해야 합니다:

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"
  }
}

이 전체 블록은 생성 시에만 설정할 수 있습니다. source_id 또는 restore_target을 변경하거나 이 블록을 제거하면 service가 삭제된 뒤 다시 생성됩니다. 자세한 내용은 백업 및 복원을 참조하십시오.

데이터 소스

기존 서비스를 조회할 수 있는 보조 데이터 소스 3개가 제공됩니다:

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

# All 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
}

기존 서비스 가져오기

기존 Managed Postgres 서비스는 서비스 ID를 사용해 Terraform state로 가져올 수 있습니다:

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

가져오는 과정에서 비밀번호는 복원되지 않습니다(API가 이를 반환하지 않기 때문입니다). 가져온 후 처음 apply를 실행하면 서비스는 구성에 선언된 password 또는 password_wo로 교체됩니다.

지원되지 않는 작업

다음 항목은 리소스 스키마에서 의도적으로 제외되어 있습니다:

운영 명령(restart, promote, switchover)
IP 허용 목록, 프라이빗 엔드포인트, 백업 구성, 유지 관리 기간, 고객 관리형 암호화 키 및 BYOC
구성 가능한 수명 주기 timeout — timeouts {} 블록은 제공되지 않습니다.

시작하기

기능

벤치마크

가격 책정

ClickHouse 통합

마이그레이션

모니터링

FAQ

프로바이더 설정

리소스 개요

서비스 생성

고가용성

읽기 레플리카

특정 시점 복원

데이터 소스

기존 서비스 가져오기

지원되지 않는 작업

​프로바이더 설정

​리소스 개요

​서비스 생성

​고가용성

​읽기 레플리카

​특정 시점 복원

​데이터 소스

​기존 서비스 가져오기

​지원되지 않는 작업

프로바이더 설정

리소스 개요

서비스 생성

고가용성

읽기 레플리카

특정 시점 복원

데이터 소스

기존 서비스 가져오기

지원되지 않는 작업