ClickHouse Cloud API
개요
ClickHouse Cloud API는 개발자가 ClickHouse Cloud에서 조직과 서비스를 쉽게 관리할 수 있도록 설계된 REST API입니다. Cloud API를 사용하면 서비스를 생성 및 관리하고, API 키를 프로비저닝하며, 조직의 구성원을 추가하거나 제거하는 등의 작업을 수행할 수 있습니다.
첫 번째 API 키를 생성하고 ClickHouse Cloud API 사용을 시작하는 방법을 알아보십시오.
Swagger (OpenAPI) 엔드포인트와 UI
ClickHouse Cloud API는 클라이언트에서 예측 가능하게 활용할 수 있도록 오픈소스 OpenAPI 사양을 기반으로 구축되었습니다. ClickHouse Cloud API 문서를 프로그래밍 방식으로 사용해야 하는 경우, https://api.clickhouse.cloud/v1에서 JSON 기반 Swagger 엔드포인트를 제공합니다. 또한 Swagger UI를 통해서도 API 문서를 확인할 수 있습니다.
조직이 새 요금제 중 하나로 마이그레이션되었으며 OpenAPI를 사용하는 경우, 서비스 생성 POST 요청에서 tier 필드를 제거해야 합니다.
서비스 티어를 더 이상 사용하지 않으므로 서비스 객체에서 tier 필드가 제거되었습니다.
이는 POST, GET, PATCH 서비스 요청에서 반환되는 객체에 영향을 줍니다. 따라서 이러한 API를 사용하는 코드는 이러한 변경 사항을 처리할 수 있도록 수정이 필요할 수 있습니다.
Rate limits
개발자는 조직별로 최대 100개의 API 키를 생성할 수 있습니다. 각 API 키는 10초 동안 최대 10회의 요청만 허용됩니다. 조직에 대해 허용되는 API 키 개수 또는 10초당 요청 한도를 늘려야 하는 경우 [email protected]으로 문의하십시오.
Terraform provider
공식 ClickHouse Terraform Provider를 사용하면 코드형 인프라(Infrastructure as Code)를 통해 예측 가능하고 버전 관리되는 구성을 정의하여 배포 과정에서의 오류 발생 가능성을 크게 줄일 수 있습니다.
Terraform Provider 문서는 Terraform Registry에서 확인할 수 있습니다.
ClickHouse Terraform Provider에 기여하려는 경우, 소스 코드는 GitHub 리포지토리에서 확인할 수 있습니다.
조직이 새 요금제 중 하나로 마이그레이션된 경우, ClickHouse Terraform Provider 2.0.0 이상 버전을 반드시 사용해야 합니다. 이 업그레이드는 서비스의 tier 속성 변경을 처리하기 위해 필요합니다. 요금제가 마이그레이션된 이후에는 tier 필드가 더 이상 허용되지 않으며, 이에 대한 모든 참조를 제거해야 합니다.
또한 이제 서비스 리소스의 속성으로 num_replicas 필드를 지정할 수도 있습니다.
Terraform 프로바이더 릴리스
ClickHouse는 2개의 공식 Terraform 프로바이더를 제공합니다. 하나는 클라우드 인프라용 ClickHouse Cloud 프로바이더이고, 다른 하나는 데이터베이스 수준의 객체용 DBops 프로바이더입니다. 두 프로바이더는 모두 동일한 릴리스 모델을 따릅니다.
안정 버전과 alpha 버전
안정 버전(예: 3.11.1, 1.9.0)에는 일반 제공 기능에 대한 리소스만 포함됩니다. Alpha 버전(예: 3.12.0-alpha2, 1.10.0-alpha1)에는 안정 버전에 포함된 모든 항목에 더해 아직 베타 또는 비공개 프리뷰 단계인 기능에 대한 리소스도 포함되며, 이를 사용하려면 해당 버전을 명시적으로 고정해야 합니다.
버전 관리
두 프로바이더 모두 시맨틱 버전 관리(MAJOR.MINOR.PATCH)를 사용합니다. 메이저 버전은 호환성이 깨지는 변경이 있을 때 증가하고, 마이너 버전은 새 기능이나 리소스가 추가될 때 증가하며, 패치 버전은 버그 수정 시 증가합니다. 알파 릴리스는 다음 마이너 버전에 사전 릴리스 접미사를 붙입니다(예: 3.12.0-alpha1). 그리고 일반 제공으로 승격되기 전에 추가 수정이나 변경이 반영되면 알파 번호가 증가합니다(예: alpha1 → alpha2 → alpha3). 릴리스는 고정된 일정에 따라 이루어지는 것이 아니라 필요할 때 생성됩니다. 아직 일반 제공이 아닌 기능에 대한 리소스가 추가되거나, 수정 사항에 대한 조기 검증이 필요할 때 새 알파 릴리스가 생성됩니다. 누적된 변경 사항(그사이 일반 제공에 도달한 기능 포함)이 프로덕션에 배포할 준비가 되면, 일반적으로 고객 피드백 기간을 거친 뒤 새 안정 릴리스가 생성됩니다. 여러 알파 마이너 버전이 누적된 후 하나의 안정 릴리스로 통합될 수 있습니다.
알파에서 안정 버전으로 승격
Terraform 기능이 일반 제공 단계에 이를 준비가 되면, 다음 안정 릴리스에서 해당 Terraform 리소스가 알파에서 안정 버전으로 승격됩니다. 그전까지는 해당 리소스를 알파 빌드에서만 사용할 수 있습니다.
Terraform 및 OpenAPI 신규 요금제: 레플리카 설정 설명
각 서비스가 생성될 때의 기본 레플리카 수는 Scale 및 Enterprise 티어에서는 3, Basic 티어에서는 1입니다.
Scale 및 Enterprise 티어에서는 서비스 생성 요청에 numReplicas 필드를 포함하여 이 값을 조정할 수 있습니다.
웨어하우스에서 첫 번째 서비스의 경우 numReplicas 필드 값은 2 이상 20 이하여야 합니다. 기존 웨어하우스에 생성되는 서비스는 레플리카 수를 최소 1까지 설정할 수 있습니다.
지원
빠른 지원을 받으려면 먼저 Slack 채널을 방문하시기 바랍니다. API와 해당 기능에 대해 추가적인 도움이 필요하거나 더 많은 정보를 원하시면 https://console.clickhouse.cloud/support 에서 ClickHouse Support로 문의하십시오.
