ClickHouse Terraform プロバイダーにおける ClickStack サポートのお知らせ

あるサービス向けに構築したダッシュボードが、1つの環境だけで使われ続けることはめったにありません。フィルター、保存済み検索、アラートとともに、ステージング環境や本番環境にも再作成されます。そうした複製が複数存在する場合、それらの同期を維持するにはUI上で同じ変更を繰り返し行い、各環境を手動で確認しなければなりません。

ClickStack の構成も、ほかのインフラと同じワークフローに統合できるようになりました。公式の ClickHouse Terraform プロバイダーが、セルフホスト環境と ClickHouse Cloud の両方において ClickStack リソースをサポートするようになりました。ダッシュボード、アラート、ソース、保存済み検索、接続、Webhook をバージョン管理下に置き、コードレビューを通したうえで、terraform plan や terraform apply で適用できます。

セルフホスト型 ClickStack と Managed ClickStack リソースのサポートは、v3.25 から通常のプロバイダーリリースにてベータ版として利用可能です。本番環境からのフィードバックを受けて、動作や設定内容が変更される可能性があります。

ClickHouse Terraform プロバイダー #

ClickHouse は、役割の異なる2つの公式 Terraform プロバイダーを提供しています。

• ClickHouse/clickhouse: サービス、プライベートエンドポイント、ClickPipes、組織アクセス、ClickHouse Managed Postgres を含む、ClickHouse Cloud コントロールプレーンのリソースを管理します。
• ClickHouse/clickhousedbops: ClickHouse インスタンスに接続し、データベースレベルのユーザー、ロール、権限、データベースを管理します。

ClickStack のサポートは ClickHouse/clickhouse に属します。ClickStack ユーザーからのフィードバックでは、セルフホスト環境と Cloud 環境の双方で Terraform への対応が最も要望の多い項目でした。当初は個別の取り組みとして開発を進めていましたが、別のプロバイダーとして公開するとリリースの作業、テスト、ドキュメント、認証コードの重複が生じることがわかりました。

そのため、ClickStack プロバイダーは既存の ClickHouse/clickhouse プロバイダー内の専用サービスモジュールとして追加され、そのリソースとデータソースは ClickHouse Cloud や Postgres の実装から分離されています。ユーザーは単一のプロバイダーをインストールし、同じリリースパスを利用し続けられます。

これにより、ClickHouse Cloud における認証の一貫性も保たれます。ClickStack リソースはプロバイダーの他のリソースと同じ組織 ID と Cloud API 認証情報を使用し、ClickStack サービス ID で対象のデプロイを識別します。セルフホストのオープンソース版 ClickStack は、自身のエンドポイントと個人用 API アクセスキーを使用します。設定方法は後ほど両方紹介します。

ClickStack API 上への構築 #

Terraform リソースには、予測可能な API コントラクトが必要です。リソース識別子は読み取りや更新をまたいでも一定である必要があります。作成、更新、削除、インポートの動作も明確でなければなりません。エラーにも、plan 時にどのフィールドで問題が起きたかをユーザーに示せる十分な構造が求められます。

2026年初めの ClickStack API の取り組みにより、既存の ClickHouse Cloud サービスパスを通じてオブザーバビリティリソースが公開されました。

/v1/organizations/{organizationId}/services/{serviceId}/clickstack/…

インフラストラクチャツールのサポートにあたり、API 定義の変更も必要でした。インラインスキーマは名前付きの型に置き換えられ、数値フィールドは整数型として一貫して定義され、バリデーションエラーには構造化されたエラー詳細が追加されました。これらの変更により、自動生成されたクライアントから OpenAPI コントラクトを利用できるようになり、Terraform が設定エラーを明確に報告するのに十分な情報が得られるようになりました。

ダッシュボードの管理には追加の要件がありました。ダッシュボードの定義は JSON 形式で提供され、適用前にバリデーションを行う必要があります。terraform plan の実行時、プロバイダーはエンドポイントが利用可能であれば ClickStack のバリデーション API に定義を送信します。これにより、無効な設定は terraform apply が変更を加える前に検知されます。

注意: 以前のバージョンの ClickStack などによってバリデーションエンドポイントが利用できない場合、プロバイダーは terraform plan をブロックする代わりに警告を出力します。その場合、バリデーションは terraform apply まで延期されます。

これらの変更により、オープンソース版と Managed ClickStack デプロイの両方で、ClickHouse Terraform プロバイダーを介して ClickStack リソースを管理できるようになりました。

ClickStack リソースの使用 #

以下の例では ClickHouse Cloud 上の Managed ClickStack を構成するためにプロバイダーを使用していますが、同じ clickhouse_clickstack_dashboard リソースはオープンソースのセルフホスト型 ClickStack でも動作します。リソースの定義は同じですが、認証とチームスコープの設定が両デプロイ方式で異なります。

Terraform 1.5 以降、ClickHouse プロバイダーのバージョン 3.25 以上、既存の Managed ClickStack サービスが必要です。また、以下のダッシュボードの例では、OpenTelemetry ログソースと ClickHouse 接続が構成済みであることを前提としています。

ClickHouse Cloud API キーの作成 #

プロバイダーはお使いの環境に代わって ClickHouse Cloud API を呼び出します。ClickHouse Cloud コンソールで Organization → API keys を開き、New API key を選択して、Service Admin または Org Admin 権限を持つキーを作成します。キー ID とシークレットを安全な場所に保存してください。

また、秘密情報ではない 2 つの識別子も必要です。

• ClickHouse Cloud 組織の組織 ID。
• Terraform で管理したい Managed ClickStack サービスのサービス ID。

両方とも Cloud コンソールからコピーしてください。サービス ID は、同じ組織内の別の ClickHouse サービスではなく、ClickStack を開く対象のサービスのものであることを確認してください。

> Cloud とセルフホストの認証情報 - ClickHouse Cloud では、組織 ID、Cloud API キー ID、Cloud API シークレット、ClickStack サービス ID を使用します。Managed ClickStack サービスは 1 つのチームに対応するため、Cloud リソースでチームを設定しないでください。一方、セルフホストの ClickStack では、代わりに CLICKSTACK_ENDPOINT と CLICKSTACK_API_KEY を使用します。このキーは、ClickStack UI で作成したパーソナル API アクセスキーである必要があります。デフォルト以外のチームの場合は、リソースの team 属性に対象のチーム ID を設定します。エイリアスのない同一の provider ブロック内で、Cloud とセルフホストの認証情報を混在させて設定しないでください。

Cloud 認証情報のエクスポート #

プロバイダーは環境変数から認証情報を読み取ります。これにより、Terraform ファイルから認証情報を排除し、`terraform.tfvars` へのシークレットのコミットを防ぐことができます。

1export CLICKHOUSE_ORG_ID="<organization-id>"
2export CLICKSTACK_SERVICE_ID="<managed-clickstack-service-id>"
3export CLICKHOUSE_CLOUD_API_KEY="<api-key-id>"
4export CLICKHOUSE_CLOUD_API_SECRET="<api-key-secret>"

> セルフホスト環境の場合は、上記の Cloud 向け環境変数を以下に置き換えます:

1export CLICKSTACK_ENDPOINT="https://clickstack.example.com"
2export CLICKSTACK_API_KEY="<personal-api-access-key>"

デプロイパイプラインで Terraform を実行する場合は、CI システムのシークレットストアを使用してください。変数名は同じままで構いません。

今回の例では、ダッシュボードオブジェクトを読み込みます。これらは ClickStack のソースとコネクションを ID で参照します。利用可能な値は、上記でエクスポートした認証情報を使って ClickStack API から取得できます。

1curl --silent \
2  --user "${CLICKHOUSE_CLOUD_API_KEY}:${CLICKHOUSE_CLOUD_API_SECRET}" \
3"https://api.clickhouse.cloud/v1/organizations/${CLICKHOUSE_ORG_ID}/services/${CLICKSTACK_SERVICE_ID}/clickstack/sources" \
4| jq -r '["SOURCE_ID","KIND","CONNECTION_ID","NAME"], (.result[] | [.id, .kind, .connection, .name]) | @tsv' \
5| column -t -s $'\t'

ダッシュボードでクエリを実行したいログソースと、それに対応するコネクションの ID をコピーします。それらを Terraform の入力変数として渡します:

1export TF_VAR_logs_source_id="68d20d409bc8769c8984585f"
2export TF_VAR_connection_id="68b6b6dd5d2cada7d1c593ac"

プロバイダーの設定 #

サンプルのための空ディレクトリを作成し、[main.tf](http://main.tf) に以下のプロバイダー設定を追加します:

1terraform {
2  required_version = ">= 1.5.0"
3
4  required_providers {
5    clickhouse = {
6      source  = "ClickHouse/clickhouse"
7      version = "~> 3.24.0"
8    }
9  }
10}
11
12provider "clickhouse" {}
13
14variable "logs_source_id" {
15  type = string
16}
17
18variable "connection_id" {
19  type = string
20}

> 上記の 4 つの環境変数から Cloud の設定が提供されるため、ここでの provider ブロックは空になっています。セルフホスト環境でデフォルト以外のチームを対象とする場合にのみ、ダッシュボードリソースに team = var.team_id を追加してください。

ダッシュボードの定義 #

main.tf にダッシュボードリソースを追加します。この例では、サービスごとのイベント数を時系列でカウントするログチャートを 1 つ作成します:

1variable "logs_source_id" {
2  description = "ID of the ClickStack logs source used by the dashboard"
3  type        = string
4}
5
6resource "clickhouse_clickstack_dashboard" "simple_logs" {
7  dashboard_json = jsonencode({
8    name    = "simple logs dashboard"
9
10    tiles = [
11      {
12        name = "Log count over time by service",
13        id = "9kcn995dbkdxjlw3jj28k"
14        x  = 0
15        y  = 0
16        w  = 24
17        h  = 11
18
19        config = {
20          name                        = "Logs over time"
21          sourceId                    = var.logs_source_id
22          displayType                 = "line"
23          granularity                 = "auto"
24          alignDateRangeToGranularity = true
25
26          select = [
27            {
28              aggFn                = "count"
29              aggCondition         = ""
30              aggConditionLanguage = "lucene"
31              valueExpression      = ""
32            }
33          ]
34
35          where         = ""
36          whereLanguage = "lucene"
37          groupBy       = "ServiceName"
38        }
39      }
40    ]
41
42    filters    = []
43    containers = []
44  })
45}
46
47output "dashboard_id" {
48  value = clickhouse_clickstack_dashboard.simple_logs.id
49}

dashboard_json の値は ClickStack v2 ダッシュボード API に対応しています。これを jsonencode 内に記述することで、JSON 文字列を手動で組み立てることなく Terraform 変数を利用できます。

変更の計画と適用 #

ディレクトリを初期化し、設定のフォーマットと検証を行ってから、実行計画を確認します。

1terraform init
2terraform fmt
3terraform validate
4terraform plan

ClickStack リソースはベータ版です。Terraform は検証時および計画時にベータ版に関する警告を出力しますが、これは想定通りの挙動です。実行計画に追加対象の clickhouse_clickstack_dashboard リソースが 1 つ含まれていることを確認し、適用します。

1dalemcdiarmid@Mac clickstack_terraform % terraform apply
2
3Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
4  + create
5
6Terraform will perform the following actions:
7
8  # clickhouse_clickstack_dashboard.simple_logs will be created
9  + resource "clickhouse_clickstack_dashboard" "simple_logs" {
10      + dashboard_json  = jsonencode(
11            {
12              + containers = []
13              + filters    = []
14              + name       = "simple logs dashboard"
15              + tiles      = [
16                  + {
17                      + config = {
18                          + alignDateRangeToGranularity = true
19                          + displayType                 = "line"
20                          + granularity                 = "auto"
21                          + groupBy                     = "ServiceName"
22                          + name                        = "Logs over time"
23                          + select                      = [
24                              + {
25                                  + aggCondition         = ""
26                                  + aggConditionLanguage = "lucene"
27                                  + aggFn                = "count"
28                                  + valueExpression      = ""
29                                },
30                            ]
31                          + sourceId                    = "68d20d409bc8769c8984585f"
32                          + where                       = ""
33                          + whereLanguage               = "lucene"
34                        }
35                      + h      = 11
36                      + id     = "9kcn995dbkdxjlw3jj28k"
37                      + name   = "Log count over time by service"
38                      + w      = 24
39                      + x      = 0
40                      + y      = 0
41                    },
42                ]
43            }
44        )
45      + id              = (known after apply)
46      + normalized_json = (known after apply)
47    }
48
49Plan: 1 to add, 0 to change, 0 to destroy.
50
51Do you want to perform these actions?
52  Terraform will perform the actions described above.
53  Only 'yes' will be accepted to approve.
54
55  Enter a value: yes
56
57Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
58
59Outputs:
60
61dashboard_id = "6a7daffaecf5dee21ed130c6"

適用が完了したら、対象サービスの ClickStack → Dashboards を開きます。新しいダッシュボードには両方のタイルが含まれているはずであり、Terraform はそのダッシュボード ID を出力として表示します。

> 信頼できる情報源(Single Source of Truth)を 1 つに保つ: ダッシュボードの管理は、Terraform か ClickStack UI のどちらか一方のみで行ってください。ダッシュボードリソースは UI での編集をドリフトとして検出しません。これらの変更は dashboard_json が更新されるまで維持されますが、更新された時点で Terraform がダッシュボード定義を置き換えるため、上書きされる可能性があります。

ダッシュボード名、タグ、またはタイルの設定を変更し、再度 terraform plan を実行して、適用前に更新内容を確認します。一時的なテストデプロイの場合は、作業完了後にダッシュボードを削除します。

1terraform destroy

既存ダッシュボードの管理 #

既存のダッシュボードは、terraform import を使って Terraform の管理下に置くことができます。まず対応するリソースブロックを追加し、ダッシュボードを ID でインポートします。

1terraform import clickhouse_clickstack_dashboard.collectors <dashboard-id>

デフォルト以外のチームにあるセルフホスト型ダッシュボードの場合は、インポート ID として <team-id>/<dashboard-id> を使用します。完全なスキーマとインポートの動作については、ClickStack ダッシュボードリソースのドキュメントに記載されています。

これまでリソースを手動で作成してきた方向けに、既存の ClickHouse リソースを Terraform 設定へ簡単にインポートできるようにもしました。ClickStack 上で Terraform の管理下に置きたいリソース(下図のダッシュボードなど)を開き、Terraform アイコンを選択して、生成された import ブロックを .tf ファイルにコピーし、terraform plan -generate-config-out=generated-dashboard.tf コマンドを実行するだけです。このワークフローには Terraform 1.5 以降が必要です。

既存のリソースをすべて一括エクスポートして、リソース設定を生成することもできます。

エクスポートしたファイルを使用すれば、ClickStack のデプロイ全体を Terraform の管理下に置くことができます。例えば以下のようになります。

1cp ~/Downloads/hyperdx-import.tf . 
2terraform init
3terraform plan -generate-config-out=generated-dashboard.tf

まとめ #

ClickStack リソースも、他のインフラストラクチャと同じレビューおよびデプロイプロセスに従えるようになりました。これにより、各チームは環境間でオブザーバビリティ設定を再現したり、適用前に変更内容を確認したり、インポート機能によって既存リソースを Terraform の管理下に置くことができます。

この取り組みを ClickHouse/clickhouse に統合したことで、Managed ClickStack においてもプロバイダーが 1 つにまとまり、リリースパスと認証方法が一貫したものになります。また、エンドポイントと個人用の API アクセスキーを指定すれば、同じリソースをオープンソースのセルフホスト版 ClickStack に対しても使用できます。

ClickStack のサポートは、プロバイダーのバージョン 3.25.0 から利用可能です。まずはプロバイダーのドキュメントを確認し、既存のダッシュボードで試してみてください。問題や予期しない挙動を見つけた場合は、プロバイダーの GitHub リポジトリからご報告をお願いします。