BYOC, 백업, Cloud API, Terraform (운영 자동화)

이 글의 범위

콘솔을 손으로 누르는 단계를 지나, 서비스를 코드로 만들고 백업을 검증하고 업그레이드를 예측 가능하게 만드는 운영 단계의 이야기입니다. 서비스 자체의 구조는 ClickHouse Cloud 개요, 크기 조정은 컴퓨트와 스케일링, 접근 제어는 네트워크와 보안 에 있습니다.

BYOC (Bring Your Own Cloud)

BYOC 는 제어 평면(콘솔, 프로비저닝, 모니터링 수집)은 ClickHouse 의 계정에, 데이터 평면(클러스터, 데이터, 백업)은 고객의 클라우드 계정에 두는 배포 방식입니다. 데이터가 고객 계정 밖으로 나가지 않아야 하는 규제 요건을 맞추면서 운영은 ClickHouse 에 맡길 수 있습니다. AWS, GCP, Azure 모두 GA 이고, 약정 계약이 전제입니다.

지원되는 기능과 아직 안 되는 기능을 구분해 두어야 설계 때 놀라지 않습니다.

주의 BYOC 는 "우리 계정에 있으니 우리가 고친다" 가 되지 않습니다. 클러스터 노드나 Kubernetes 리소스를 직접 바꾸면 지원 대상에서 벗어납니다. 고객이 하는 일은 계정, 네트워크, 권한을 준비하고 비용을 내는 것까지입니다.

ClickHouse Private 와 Government

• ClickHouse Private 는 메모리 2 TB 를 넘는 대형 환경이나 완전한 격리가 필요할 때의 선택지로, EKS 와 S3, GKE 와 GCS, 온프레미스 Kubernetes 와 MinIO AIStor 조합을 지원하고 AKS 와 Blob 은 프리뷰입니다.
• ClickHouse Government 는 미국 공공 부문용으로 FIPS 140-3 검증 OpenSSL 을 씁니다. 국내 고객이 만날 일은 드물지만 "FIPS 모드가 되느냐" 는 질문의 답이 여기에 있습니다.

백업

관리형 백업은 전체 백업 하나에 증분 백업이 이어지는 체인 구조입니다. 기본은 하루 1회, 24시간 보존이고, 저장과 같은 단가로 따로 과금됩니다. Scale 과 Enterprise 는 보존 기간(1일에서 45일), 주기(6시간에서 48시간), 시작 시각을 바꿀 수 있고, 시작 시각을 정하면 주기보다 우선합니다.

# Terraform 으로 백업 설정 (보존 7일, 매일 UTC 18시 창 시작 = 한국 03시)
# backup_start_time 을 쓰면 하루 1회가 되고 backup_period_in_hours 는 비워 둡니다
resource "clickhouse_service" "prod" {
  # ... 서비스 기본 설정 ...
  backup_configuration = {
    backup_retention_period_in_hours = 168
    backup_start_time                = "18:00"
  }
}

콘솔의 서비스 설정 화면에서도 같은 값을 바꿀 수 있고, Cloud API 의 서비스 백업 설정 엔드포인트로도 가능합니다.

복원은 콘솔에서 백업을 골라 새 서비스로 복원하는 방식입니다. 기존 서비스 위에 덮어쓰지 않으므로, 복원한 서비스에서 필요한 테이블만 원래 서비스로 옮기거나 애플리케이션의 엔드포인트를 바꿉니다.

자기 계정 버킷으로 내보내는 백업은 규제상 장기 보존이나 리전 간 복구에 씁니다. 지원팀을 통해 BACKUP 권한을 받은 뒤 SQL 로 실행하고, 네이티브 복사가 아니라 느립니다. 클라우드를 가로지르는 백업은 이 명령으로만 가능합니다.

-- 자기 S3 버킷으로 데이터베이스 백업 (증분은 base_backup 지정)
BACKUP DATABASE analytics
TO S3('https://my-bucket.s3.ap-northeast-2.amazonaws.com/ch-backups/2026-10-21',
      '<access key id>', '<secret key>');

-- 복원
RESTORE DATABASE analytics
FROM S3('https://my-bucket.s3.ap-northeast-2.amazonaws.com/ch-backups/2026-10-21',
        '<access key id>', '<secret key>');

팁 리전 간 자동 페일오버는 없습니다. 재해 복구 목표(RTO)가 있다면 분기마다 한 번 실제로 복원해서 걸리는 시간을 재 두세요. 복원 시간은 데이터 크기에 거의 비례하고, 처음 복원한 서비스는 캐시가 비어 있어 첫 쿼리들이 느립니다. 자체 호스팅의 백업 절차는 백업과 업그레이드 에 있습니다.

Cloud API

OpenAPI 명세를 따르는 REST API 이고, 기본 주소는 https://api.clickhouse.cloud/v1 입니다. 조직당 API 키 100개, 키당 10초에 10 요청의 제한이 있습니다. 서비스 생성, 스케일링, IP 목록, 백업 설정, 멤버와 역할, 키 관리, ClickPipes 까지 콘솔에서 하는 거의 모든 일을 할 수 있습니다.

# 서비스 목록
curl -s -u "$KEY_ID:$KEY_SECRET" \
  "https://api.clickhouse.cloud/v1/organizations/$ORG/services" \
  | jq '.result[] | {id, name, state}'

# 서비스 상태 변경 (command 는 start, stop, awake)
curl -s -u "$KEY_ID:$KEY_SECRET" -X PATCH \
  "https://api.clickhouse.cloud/v1/organizations/$ORG/services/$SVC/state" \
  -H 'Content-Type: application/json' -d '{"command": "stop"}'

# 레플리카 크기와 수 변경 (예전 /scaling 경로는 폐기 예정)
curl -s -u "$KEY_ID:$KEY_SECRET" -X PATCH \
  "https://api.clickhouse.cloud/v1/organizations/$ORG/services/$SVC/replicaScaling" \
  -H 'Content-Type: application/json' \
  -d '{"minReplicaMemoryGb": 32, "maxReplicaMemoryGb": 120, "numReplicas": 3}'

Prometheus 지표도 API 로 노출됩니다. /v1/organizations/<org>/services/<svc>/prometheus?filtered_metrics=true 를 API 키 기본 인증으로 스크래핑하면 되고, 서비스 디스커버리용 /prometheus/discovery 엔드포인트도 있습니다. 조직 전체 엔드포인트(/organizations/<org>/prometheus)는 폐기 예정으로 2027년 1월 1일에 꺼지므로 서비스 단위나 디스커버리 방식으로 바꿔 둡니다. 대시보드 구성은 모니터링 을 보세요.

참고 API 응답의 서비스 객체에서 tier 필드는 제거되었습니다. 예전 스크립트가 티어로 분기하고 있다면 조직 단위 정보로 바꿔야 합니다.

clickhousectl

공식 CLI 입니다. 설치는 한 줄이고 chctl 별칭이 함께 잡힙니다. API 키로 로그인하면 쓰기 작업까지, 브라우저 OAuth 로그인은 읽기 전용입니다.

curl https://clickhouse.com/cli | sh
clickhousectl cloud auth login --api-key "$KEY_ID" --api-secret "$KEY_SECRET"

clickhousectl cloud service list
clickhousectl cloud service create --name dev-kim --provider aws --region ap-northeast-2
clickhousectl cloud service scale "$SVC" \
  --min-replica-memory-gb 16 --max-replica-memory-gb 64 --num-replicas 3
clickhousectl cloud service get "$SVC"
clickhousectl cloud service query --id "$SVC" -q 'SELECT version()'

팁 당직 런북에 "새벽 장애 시 레플리카 메모리 상한 두 배로" 같은 조치를 CLI 한 줄로 적어 두면, 콘솔 메뉴 위치를 기억하지 못하는 사람도 실수 없이 실행합니다.

Terraform

공식 프로바이더는 두 개입니다. ClickHouse/clickhouse 는 Cloud 리소스(서비스, 스케일링, 업그레이드 창, 콘솔 역할, API 키, 프라이빗 엔드포인트, ClickPipes, ClickStack 알림, Managed Postgres)를 다루고, ClickHouse/clickhousedbops 는 데이터베이스 안의 객체(사용자, 역할, 권한, 데이터베이스)를 다룹니다. 인증은 환경 변수 CLICKHOUSE_CLOUD_API_KEY 와 CLICKHOUSE_CLOUD_API_SECRET 으로 넣습니다.

terraform {
  required_providers {
    clickhouse = { source = "ClickHouse/clickhouse" }
  }
}

provider "clickhouse" {
  organization_id = var.org_id
}

resource "clickhouse_service" "prod" {
  name                  = "prod-analytics"
  cloud_provider        = "aws"
  region                = "ap-northeast-2"
  idle_scaling          = false
  min_replica_memory_gb = 32
  max_replica_memory_gb = 120
  num_replicas          = 3
  password_hash         = var.default_user_password_sha256
  release_channel       = "slow"   # default, fast, slow

  endpoints = {
    mysql = { enabled = false }
  }

  ip_access = [
    { source = "10.20.0.0/16", description = "prod vpc" },
    { source = "203.0.113.10/32", description = "office" },
  ]

  backup_configuration = {
    backup_retention_period_in_hours = 168
    backup_start_time                = "18:00"
  }

  lifecycle { prevent_destroy = true }
}

• 개발 서비스는 idle_scaling = true 와 idle_timeout_minutes(5 이상)를 함께 넣습니다. 유휴를 켜면 타임아웃이 필수입니다.
• 수평 오토스케일링이 조직에 열려 있으면 autoscaling_mode = "horizontal" 과 min_replicas, max_replicas 로 레플리카 수 범위를 줄 수 있습니다. 이때 num_replicas 는 쓰지 않고 레플리카 메모리 최소와 최대는 같은 값이어야 합니다.
• 웨어하우스의 부 서비스는 warehouse_id 에 주 서비스의 값을 넣고, 읽기 전용이면 readonly = true 를 더합니다.
• 베타 상태의 리소스는 terraform plan 때 경고를 냅니다. clickhouse_udf 는 GA 이고, 실행 가능 UDF 는 2026년 10월 Cloud 에서 GA 가 되었습니다.
• 서비스 비밀번호는 평문 대신 SHA-256 해시로 넣고, 해시는 Vault 나 SOPS 로 관리합니다.
• 리전, 클라우드, 인스턴스 프로파일처럼 재생성이 필요한 속성을 바꾸면 서비스가 삭제되고 다시 만들어집니다. 상용 서비스에는 prevent_destroy 를 걸어 둡니다.

주의 Terraform 상태 파일에 서비스 ID 와 엔드포인트가 들어가므로 원격 백엔드에 암호화해 두고, 콘솔에서 손으로 바꾼 설정은 다음 apply 에서 되돌아갑니다. 콘솔과 코드를 섞어 쓰지 않는 규칙을 팀에 먼저 세웁니다.

업그레이드와 릴리스 채널

ClickHouse Cloud 는 자동으로 업그레이드되고, 그 속도를 릴리스 채널로 고릅니다.

• Enterprise 는 예약 업그레이드로 요일과 시간 창을 정할 수 있습니다. 보안 패치는 예외로 창 밖에서도 적용될 수 있습니다.
• 업그레이드는 Make Before Break 로 진행되어 새 레플리카가 준비된 뒤 옛 레플리카를 내립니다. 단일 레플리카 서비스만 짧게 끊깁니다.
• compatibility 설정은 서비스를 만들 때의 버전으로 고정되고, 바꾸려면 지원팀에 요청합니다. 새 기본값을 쓰고 싶은데 동작이 예전 그대로라면 이 설정을 의심합니다.
• 유지보수 모드 동안의 컴퓨트는 과금되지 않습니다.

-- 지금 버전과 호환성 설정 확인
SELECT version();
SELECT name, value, changed FROM system.settings WHERE name = 'compatibility';

팁 스테이징은 fast, 상용은 slow 로 두면 상용에 올 변화를 약 한 달 먼저 봅니다. 새 버전의 동작 변화는 2026년 ClickHouse 주요 변화 에 정리되어 있습니다.

운영 준비 체크리스트

1. 환경(개발, 스테이징, 상용)마다 서비스를 나누고, 상용은 전용 조직이나 전용 역할로 격리합니다.
2. 상용은 사설 연결만 허용하고, 콘솔은 SAML 과 MFA 로 들어옵니다.
3. 모든 서비스는 Terraform 으로 만들고, 수동 변경 금지 규칙을 세웁니다.
4. Prometheus 스크래핑과 알림(PagerDuty 등)을 연결하고, 지출 알림도 함께 켭니다.
5. 백업 보존과 주기를 정하고, 분기마다 실제 복원 연습으로 RTO 를 측정합니다.
6. 릴리스 채널을 환경별로 다르게 두고, 업그레이드 창을 배치 시간과 겹치지 않게 잡습니다.
7. API 키는 용도별로 발급하고 IP 액세스 리스트와 만료 관리를 붙입니다.

공식 문서

• BYOC overview
• Backups
• Export backups to your own cloud account
• Cloud API overview
• Terraform provider: clickhouse
• Upgrades and release channels