terraform-provider-clickstack

Terraform Provider for ClickStack

Terraform provider for managing dashboards, alerts, and saved searches on ClickStack (HyperDX on ClickHouse Cloud).

Requirements

• Terraform >= 1.0
• Go >= 1.25 (to build the provider)

Installation

Terraform Registry

terraform {
  required_providers {
    clickstack = {
      source  = "registry.terraform.io/teamlapse/clickstack"
      version = "~> 0.1"
    }
  }
}

Local Development

go install .

The binary will be installed to $GOPATH/bin/terraform-provider-clickstack.

Authentication

The provider authenticates with the ClickHouse Cloud API using an API key pair. You can configure credentials via provider arguments or environment variables:

provider "clickstack" {
  organization_id = var.clickstack_organization_id
  service_id      = var.clickstack_service_id
  api_key_id      = var.clickstack_api_key_id
  api_key_secret  = var.clickstack_api_key_secret
}

Resources

• clickstack_dashboard — Manage observability dashboards with tiles, filters, and queries.
• clickstack_alert — Manage threshold-based alerts from dashboard tiles or saved searches.
• clickstack_saved_search — Manage reusable search queries.

Data Sources

• clickstack_sources — List available data sources (log, trace, metric, session).
• clickstack_webhooks — List configured webhooks (Slack, PagerDuty, etc.).

Quick Start

data "clickstack_sources" "all" {}

# Create a saved search for error logs
resource "clickstack_saved_search" "errors" {
  name      = "API Errors"
  source_id = data.clickstack_sources.all.sources[0].id
  where     = "ServiceName:api-gateway AND SeverityText:ERROR"
  order_by  = "Timestamp DESC"
}

# Alert when errors exceed threshold
resource "clickstack_alert" "high_errors" {
  name                    = "High Error Rate"
  source                  = "saved_search"
  saved_search_id         = clickstack_saved_search.errors.id
  threshold               = 50
  threshold_type          = "above"
  interval                = "5m"
  num_consecutive_windows = 3

  channel {
    type             = "email"
    email_recipients = ["oncall@example.com"]
  }
}

num_consecutive_windows is optional and must be at least 1. Omit it to retain single-window alert evaluation.

See the examples/ directory for more complete usage.

Development

Building

go build -o terraform-provider-clickstack .

Testing

Acceptance tests require a live ClickStack instance. Set the environment variables above, then:

TF_ACC=1 go test ./... -v

Generating Documentation

go generate ./...

This runs tfplugindocs to regenerate the docs/ directory from schema descriptions and example files.

License

This project is licensed under the Mozilla Public License 2.0.