Terraform SigNoz Provider

The SigNoz Provider lets Terraform manage SigNoz observability resources as code, on both SigNoz Cloud and self-hosted deployments.

📖 Provider documentation on the Terraform Registry

Usage

terraform {
  required_providers {
    signoz = {
      source = "signoz/signoz"
    }
  }
}

provider "signoz" {
  # SigNoz Cloud region URL, or the UI URL of a self-hosted deployment. Also reads
  # SIGNOZ_ENDPOINT; defaults to http://localhost:8080.
  endpoint = "http://localhost:8080"

  # API access token from a service account. Prefer the SIGNOZ_ACCESS_TOKEN
  # environment variable to keep the secret out of configuration and state.
  access_token = var.signoz_access_token
}

Create an access token from a SigNoz service account. See the registry documentation for every resource, data source, and example.

Requirements

• Terraform >= 1.4, or OpenTofu >= 1.6
• Go >= 1.25 (only to build the provider from source)

Why Terraform 1.4 and not 1.0

The provider is built on the Terraform Plugin Framework, and models much of the SigNoz API as nested attributes — objects inside objects, several levels deep, whose inner fields are both optional and computed: you may set them, and the server supplies whatever you leave out.

Terraform 1.3 and older do not round-trip that shape. After a successful apply, the values the server filled in for attributes the configuration left unset are not reconciled with the plan, and the next plan proposes them as changes all over again. The effect is perpetual drift — the apply succeeds, and every subsequent plan wants to make the identical change. No change to the configuration avoids it.

Resources whose attributes are all flat scalars are unaffected, so an older CLI looks fine right up until a deeply nested resource is used. Terraform 1.4 is the first release that handles it. OpenTofu inherits the fix, its first release having been forked from Terraform 1.5.

Building the provider

1. Clone the repository.
2. Enter the repository directory.
3. Build the provider with the Go install command:

go install

Adding dependencies

This provider uses Go modules. To add a new dependency github.com/author/dependency:

go get github.com/author/dependency
go mod tidy

Then commit the changes to go.mod and go.sum.

Documentation

Documentation is generated with terraform-plugin-docs from the provider schema, the prose templates in templates/, and the examples in examples/. Edit those sources, then regenerate:

go generate ./...

The files in docs/ are auto-generated — do not edit them by hand. CI re-runs generation and fails if docs/ is out of date.

Developing the provider

You'll need Go >= 1.25 (see Requirements). To compile the provider, run go install; the binary lands in $GOPATH/bin. After changing the schema, examples, or templates, run go generate ./... to refresh docs/.