ClickPipes 向け Terraform および OpenAPI の一般提供 (GA) を開始

TL;DR
Terraform と OpenAPI を使用して、ClickPipes リソースを「コードとして」プロビジョニングおよび管理できるようになりました。すべてのコネクタに対応し、使いやすさも向上しています。

ClickOps(ユーザーインターフェース上のボタンをクリックする操作)は、新しい製品を使い始める際には便利ですが、本番環境への移行が進むにつれて、より自動化されバージョン管理された方法でリソースを管理するアプローチ、すなわち「Infrastructure as Code」に移行するのが一般的です。

ClickHouse Cloud を開発するにあたり、私たちの目標の 1 つは API ファーストにすることです。ユーザーインターフェースから実行できるあらゆる操作は、既存のデプロイワークフローに組み込める(そしてエージェントからも活用できる 🤖)プログラムインターフェース経由でも利用できるようにすべきだと考えています。ClickHouse Cloud のフルマネージドデータ取り込みプラットフォームである ClickPipes も例外ではありません。

本記事の公開に合わせて、Terraform における ClickPipes リソースおよび OpenAPI におけるエンドポイントの一般提供 (GA) を発表します！2025年にこれらのインターフェースのベータサポートを発表しましたが、一部の機能や使い勝手の面で不足があり、すべての ユーザーが ClickPipes をコードとして管理できる状態ではありませんでした。特にコネクターの対応範囲が完全ではありませんでしたが、今回のアップデートにより、CDC ClickPipes (Postgres、MySQL、MongoDB) もコードとして作成できるようになりました！

サポートされる内容 #

CDC ClickPipes のサポートに加えて、提供開始に合わせて両方のインターフェースに新しい ClickPipes コネクターと機能 (例: BigQuery および Azure Blob Storage コネクター、S3 および GCS の unordered モード) を追加しました。さらに、リバースプライベートエンドポイントの作成と管理のサポートなど、重要な機能の不足も解消しています。これにより、ClickPipes UI にあって OpenAPI や Terraform 経由で公開されていない機能はほとんどなくなりました。SSH トンネリングは例外ですが、現在対応を進めています！

現在、すべての操作が ClickHouse Terraform provider のリソースまたは OpenAPI エンドポイント に明確に対応しています:

ClickPipe をゼロからプロビジョニングする場合は、手順: 新しい ClickPipe の設定 から始めてください。すでに稼働中のパイプラインがあり、それらをバージョン管理下に置きたい場合は、手順: 既存の ClickPipes のインポート を確認してください。

手順: 新しい ClickPipe の設定 #

Cloud API キーの作成 #

1. ClickHouse Terraform provider は ClickHouse Cloud サービスとの連携に Cloud API を使用するため、認証用に有効な API キーが必要です。このプロバイダーを初めて利用する場合は、まず新しい API キーを作成します。Organization > API keys > New API key に移動し、表示される Key ID と Key Secret のペアを控えておくか、ダウンロードします。

2. 次に、プロバイダーを設定します。認証情報をソース管理から除外するため、Terraform 変数 と、.gitignore に追加できる terraform.tfvars ファイルの使用を推奨します:

variables.tf

1variable "organization_id" {
2  description = "ClickHouse Cloud organization ID"
3  type        = string
4}
5
6variable "service_id" {
7  description = "ClickHouse Cloud service ID"
8  type        = string
9}
10
11variable "token_key" {
12  description = "ClickHouse Cloud API key ID"
13  type        = string
14  sensitive   = true
15}
16
17variable "token_secret" {
18  description = "ClickHouse Cloud API key secret"
19  type        = string
20  sensitive   = true
21}
22...

terraform.tfvars

1organization_id   = "" # your org ID from cloud.clickhouse.com
2service_id        = "" # target ClickHouse service ID
3token_key         = "" # API key ID
4token_secret      = "" # API key secret
5...

ClickPipes リソースの設定 #

この例では、Postgres データベースから ClickHouse へニアリアルタイムで継続的に変更を取り込むための Postgres CDC ClickPipe リソースを設定します。注意点として、CDC ClickPipe を作成する前に、データソースの設定ガイドに従って、アップストリームでのレプリケーションを有効にしておいてください。

1. ClickPipe を作成する準備ができたら、ソース属性に postgres を指定した新しい clickhouse_clickpipe リソース を Terraform 設定に追加します。以下は、単一の Postgres テーブル (public.firenibble) を同期し、source_table の新しい変更 (つまり 挿入、更新、削除) を cdc を使用して ClickHouse Cloud の target_table に反映する単一の ClickPipe を作成する基本的な設定例です。

main.tf

1terraform {
2 required_providers {
3   clickhouse = {
4     source  = "ClickHouse/clickhouse"
5     version = ">= 3.14.0"
6   }
7 }
8}
9
10provider "clickhouse" {
11 organization_id = var.organization_id
12 token_key       = var.token_key
13 token_secret    = var.token_secret
14}
15
16resource "clickhouse_clickpipe" "pg_pipe" {
17 name       = "tf-postgres-clickpipe"
18 service_id = var.service_id
19
20 source = {
21   postgres = {
22     host     = var.postgres_host
23     port     = 5432
24     database = var.postgres_database
25
26     credentials = {
27       username = var.postgres_user
28       password = var.postgres_password
29     }
30
31     settings = {
32       replication_mode = "cdc"
33     }
34
35     table_mappings = [
36       {
37         source_schema_name = "public"
38         source_table       = "firenibble"
39         target_table       = "public_firenibble"
40       }
41     ]
42   }
43 }
44
45 destination = {
46   database = "default"
47 }
48}

2. Cloud API の認証情報とリソース設定を Terraform に渡したので、デプロイの準備が整いました。terraform init を実行して ClickHouse プロバイダーをインストールし、次に terraform apply を実行してパイプラインをプロビジョニングします。Terraform は実行計画を出力し、デプロイ前に計画された変更の確認を求めます:

1terraform apply
2
3...
4Plan: 1 to add, 0 to change, 0 to destroy.
5
6Do you want to perform these actions?
7  Terraform will perform the actions described above.
8  Only 'yes' will be accepted to approve.
9
10  Enter a value: yes
11
12clickhouse_clickpipe.pg_pipe: Creating...
13clickhouse_clickpipe.pg_pipe: Still creating... [00m10s elapsed]
14clickhouse_clickpipe.pg_pipe: Creation complete after 11s [id=10128f88-100c-4830-b480-e242fa89570f]

以上で完了です！プログラムによって作成された最初の CDC ClickPipe が稼働しました。ClickHouse Cloud コンソールに移動し、(Data sources > ClickPipes の配下に) パイプラインが存在し、データ取り込みを順調に処理していることを確認してください。

さまざまなパイプタイプ、取り込みモード、ネットワーク構成に応じた Terraform での ClickPipes 設定例は、プロバイダーのリポジトリ で確認できます。

手順: 既存の ClickPipes のインポート #

以下の手順は HashiCorp Terraform v1.5+ でテストされています。インポートのワークフローは代替実装 (OpenTofu など) とも広く互換性があるはずですが、最小バージョンや基本的な手法が異なる場合があります。

すでに ClickHouse Terraform provider を使用しているプロジェクトがある場合は、手動で設定する代わりに、既存の ClickPipes を Terraform state にインポートしてコードとして管理できます。

1. Cloud API を使用して、対象の組織およびサービスに存在する ClickPipes を取得します:

1curl -s \
2  "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/clickpipes" \
3  -u "$KEY_ID:$KEY_SECRET" | jq -r '.result[] | "\(.id)\t\(.name)"'
4
51667855d-1646-4693-8cac-60e1c386ccb1    existing_pg_pipe
62e4c3974-025e-47a0-861b-4c200b6c0249    existing_mysql_pipe
776a42195-ef25-40fc-ae3d-31733d377f77    existing_mongo_pipe

2. 設定ファイルを編集し、Terraform にインポートしたい ClickPipes の import ブロックを追加します:

1...
2import {
3  to = clickhouse_clickpipe.existing_pg_pipe
4  id = "<service_id>:1667855d-1646-4693-8cac-60e1c386ccb1"
5}
6...

3. 既存のリソースから Terraform のリソース設定を生成します:

1terraform plan -generate-config-out=generated.tf

generated.tf を確認し、Terraform が state から取得できない機密フィールド (認証情報など) を入力します。

1# __generated__ by Terraform
2# Please review these resources and move them into your main configuration files.
3
4# __generated__ by Terraform
5resource "clickhouse_clickpipe" "pg_pipe" {
6…
7credentials    = {
8username = var.postgres_user
9password = var.postgres_password
10}
11…}

4. terraform plan を実行して予期しない差分がないことを確認し、terraform apply を実行して完了します。

注: Postgres CDC ClickPipes の場合、terraform apply を実行する前にリソース設定で stopped = true を設定する必要があります。Terraform はパイプを一時停止し、1 回のパスで認証情報を state に書き込みます。完了したら、stopped = false に設定して再度 apply を実行し、再開します。これは 既知の制限事項 です。

今後の展開 #

ClickPipes リソースは v3.14.0 以降の ClickHouse Terraform provider の安定版リリースで利用可能であり、OpenAPI エンドポイントもベータを終了しました (仕様書)。ClickPipes の進化に伴い、私たちは Terraform と OpenAPI を「完了の定義」の一部を成すファーストクラスのインターフェースとして扱い続けます。上記のような複雑な使い勝手に関する制限事項の解消に積極的に取り組んでいるほか、要望の多い SSH トンネリング 設定のサポートにも取り組んでいます！

Terraform や OpenAPI を使用した ClickPipes の設定および管理についてフィードバックがある場合や問題が発生した場合は、私たちのチームまでご連絡ください。間もなく、最近リリースされた ClickHouse CLI でも ClickPipes が利用できるようになります。数週間以内に詳細をお知らせします！