clickstack-config

Sources, dashboards, alerts and webhooks as Terraform, for both targets in _base/. This is the shared asset the roadmap's labs/dashboards-alerts and labs/clickstack-cloud slots will both build on -- clicking through the UI is not reproducible across a workshop room.

The official ClickHouse/clickhouse Terraform provider has first-class ClickStack resources (beta, provider v3.25+), designed to work against both self-hosted ClickStack and ClickHouse Cloud. That is why this is one configuration, not two.

OSS and Cloud differ in exactly two places

1. The provider block (terraform/provider.tf) is empty. Every clickhouse_clickstack_* credential is optional and env-settable, and which ones are set selects the mode:

Mode	Attributes	Env vars
self-hosted (oss)	clickstack_endpoint + clickstack_api_key	CLICKSTACK_ENDPOINT, CLICKSTACK_API_KEY
Cloud	clickstack_service_id + organization_id + token_key + token_secret	CLICKSTACK_SERVICE_ID, CLICKHOUSE_ORG_ID, CLICKHOUSE_CLOUD_API_KEY, CLICKHOUSE_CLOUD_API_SECRET

One root module, one state per environment (terraform apply -var-file=envs/oss.tfvars vs. envs/cloud.tfvars), switched entirely by which credentials are in the environment.

2. clickhouse_clickstack_connection (terraform/connection.tf), the only fork in the .tf files themselves. On Cloud, the connections endpoint is not exposed at all: each service gets a single self-connection the platform creates, so this resource is for self-hosted ClickStack only.

resource "clickhouse_clickstack_connection" "main" {
  count = var.deployment == "oss" ? 1 : 0
  ...
}

locals {
  connection_id = var.deployment == "oss"
    ? clickhouse_clickstack_connection.main[0].id
    : var.cloud_connection_id
}

There is no clickstack_source data source, so on Cloud the connection id cannot be looked up automatically -- it has to come in as var.cloud_connection_id, read once from an existing source (GET /api/v2/sources, or the UI). Everything downstream -- sources.tf, dashboards.tf, alerts.tf, webhooks.tf -- takes local.connection_id and is byte-identical between the two.

The team attribute on every resource is portable by design: it is sent as the x-hdx-team header, honoured by multi-team (EE) deployments and ignored by single-team OSS. On ClickHouse Cloud it is rejected outright (a Cloud service is a single team). Leave var.team = "" unless you are on multi-team EE.

Quickstart (oss, against _base/)

cd _base && cp .env.example .env && docker compose up -d && ./bin/check.sh   # if not already up

cd ../clickstack-config/terraform
cp envs/oss.tfvars.example envs/oss.tfvars   # fill in webhook_url at least
cp envs/oss.env.example envs/oss.env         # fill in CLICKSTACK_API_KEY
# CLICKSTACK_API_KEY: ClickStack UI -> Team Settings -> API & Agents ->
# Personal API access key. Same key _base/bin/check.sh wants as
# HYPERDX_API_KEY.

set -a && source envs/oss.env && set +a
terraform init
terraform plan  -var-file=envs/oss.tfvars
terraform apply -var-file=envs/oss.tfvars

Cloud is the same shape with envs/cloud.* and a separate Terraform state (a different -state= or working directory -- this repository does not prescribe one; keep OSS and Cloud state apart however your setup already separates environments).

Layout

clickstack-config/
├── README.md              this file
├── docs/authoring.md      the UI -> export -> commit loop, and the caveats that bite
└── terraform/
    ├── provider.tf         provider "clickhouse" {}  -- empty, env-driven
    ├── variables.tf        deployment = "oss" | "cloud", and everything else
    ├── connection.tf        the one fork
    ├── sources.tf           log, trace, metric
    ├── dashboards.tf        templatefile(), so sourceId is injected per environment
    ├── alerts.tf             one tile alert
    ├── webhooks.tf           its notification channel
    ├── dashboards/*.json.tftpl
    └── envs/{oss,cloud}.tfvars.example + {oss,cloud}.env.example

.tfvars files (copied from the .tfvars.example ones above, with real values) are gitignored; .terraform.lock.hcl, once terraform init creates it, is not -- commit it so everyone plans against the same provider build.

Beta resources

clickhouse_clickstack_* are beta as of provider v3.25 (terraform/provider.tf pins >= 3.25.0, < 4.0.0). They emit a "Beta Resource" warning on every create, update and import -- on apply, not on plan. Set CLICKHOUSE_SUPPRESS_BETA_WARNINGS=true in the environment (see envs/*.env.example) to silence it once acknowledged.

The caveats

Read docs/authoring.md before changing a dashboard or an alert -- several of the provider's own documented behaviors are easy to trip over and expensive to debug from the symptom alone (an "invalid index" or "Tile not found" plan error, or a UI edit that Terraform never mentions). Short version:

• A dashboard's dashboard_json is the sole source of truth. A UI edit is not reported as drift; it survives until dashboard_json itself changes, and then the whole dashboard is replaced.
• A tile alert is bound to its tile's name, via the dashboard's computed tile_ids map. Renaming a tile mints a new id and detaches the alert.
• Only line, stacked bar and number tiles can be alerted on.
• Importing a dashboard does not import its tile alerts; import each alert separately.

Verification

Per AGENTS.md, a Verified on ... line here waits for a real terraform apply against both an OSS instance and a Cloud service, confirmed by SQL or GET /api/v2/dashboards -- not a screenshot. See this PR's description for how far this initial version actually got.

---

resource "clickhouse_clickstack_connection" "main" {
  count = var.deployment == "oss" ? 1 : 0
  ...
}

locals {
  connection_id = var.deployment == "oss"
    ? clickhouse_clickstack_connection.main[0].id
    : var.cloud_connection_id
}

cd _base && cp .env.example .env && docker compose up -d && ./bin/check.sh   # 아직 안 띄웠다면

cd ../clickstack-config/terraform
cp envs/oss.tfvars.example envs/oss.tfvars   # 최소한 webhook_url을 채우세요
cp envs/oss.env.example envs/oss.env         # CLICKSTACK_API_KEY를 채우세요
# CLICKSTACK_API_KEY: ClickStack UI -> Team Settings -> API & Agents ->
# Personal API access key. _base/bin/check.sh가 HYPERDX_API_KEY로 요구하는
# 것과 같은 키입니다.

set -a && source envs/oss.env && set +a
terraform init
terraform plan  -var-file=envs/oss.tfvars
terraform apply -var-file=envs/oss.tfvars

clickstack-config/
├── README.md              이 파일
├── docs/authoring.md      UI -> export -> commit 루프, 그리고 걸리기 쉬운 함정들
└── terraform/
    ├── provider.tf         provider "clickhouse" {}  -- 비어 있음, 환경변수로 결정
    ├── variables.tf        deployment = "oss" | "cloud" 등
    ├── connection.tf        유일한 분기점
    ├── sources.tf           log, trace, metric
    ├── dashboards.tf        templatefile() -- 환경별로 sourceId 주입
    ├── alerts.tf             타일 알림 1개
    ├── webhooks.tf           그 알림의 알림 채널
    ├── dashboards/*.json.tftpl
    └── envs/{oss,cloud}.tfvars.example + {oss,cloud}.env.example