Openobserve Terraform

OpenObserve Terraform provider

Everything here was verified against a live OpenObserve server. Where a rule is stated, it is because the server rejected the alternative.

Before writing anything

Two questions decide most of the work:

1. Which resource? See the inventory below.
2. Is this open source or Enterprise, and which features are switched on? Roles and groups need Enterprise with OpenFGA. Synthetics needs ZO_SYNTHETICS_ENABLED=true on either edition. Everything else, including SLOs, works on both with no flag.

If the answer to either is unclear from the task, read the relevant reference file before writing HCL. Guessing at the shape of query_condition, an SLO indicator, or a dashboard panel is the single most common way to produce configuration that plans cleanly and then fails on apply.

Provider setup

terraform {
  required_providers {
    openobserve = {
      source  = "openobserve/openobserve"
      version = "~> 1.4"
    }
  }
}

provider "openobserve" {
  endpoint = "https://openobserve.example.com"
  username = "admin@example.com"
  password = var.oo_password
  org_id   = "default"
}

Prefer the environment for credentials: OPENOBSERVE_ENDPOINT, OPENOBSERVE_USERNAME, OPENOBSERVE_PASSWORD, OPENOBSERVE_ORG_ID. Every resource takes an optional org_id that falls back to the provider's, and it is RequiresReplace everywhere because an object cannot move between organizations.

The provider is published to both registries:

• Terraform: registry.terraform.io/providers/openobserve/openobserve
• OpenTofu: search.opentofu.org/provider/openobserve/openobserve

The source address is the same for both. It speaks plugin protocol 6.0, so it needs Terraform 1.0+ or any OpenTofu version.

Resource inventory

18 resources:

33 data sources: singular and plural forms of the above, plus openobserve_user_roles, openobserve_resources †, openobserve_composite_alert_references, openobserve_pipelines, and openobserve_synthetic_locations ‡.

† Enterprise with OpenFGA (ZO_OPENFGA_ENABLED=true). On open source these return a diagnostic naming the feature, not a bare HTTP 403.

‡ Requires ZO_SYNTHETICS_ENABLED=true. When it is off the routes are not registered at all, so every path answers 404 and a missing check is indistinguishable from a disabled feature. The provider detects this and says which it is.

Every resource supports terraform import.

Where to read next

Load the reference file for the area being worked on. They are detailed on purpose; do not reconstruct their content from memory.

Runnable configuration is in examples/. scripts/dev-server.sh starts a throwaway OpenObserve in Docker for verifying a change against a real server.

The mental model

OpenObserve's API is not uniformly shaped, and the provider exists largely to absorb that. Four patterns recur, and recognising them explains most of the provider's behaviour:

Deltas, not desired state. Stream list settings and role permissions take {add, remove} rather than an absolute value, so those resources read before every write.

Adjacently tagged enums. A discriminant and its payload sit in sibling keys: {"sli_type": "count", "config": {...}}. SLO indicators do this twice over.

Separate endpoints for single fields. Enabling an SLO, moving an alert between folders, and rotating a service account token are each their own endpoint. Writing the field into the update body silently does nothing.

Read and write shapes differ. Partition keys are sent as an array and returned as a map keyed by level. Dashboards are sent bare and returned inside a versioned envelope. Composite expressions are sent as written and stored canonicalized.

Rules that prevent most failures

These are the ones worth knowing before reading anything else.

An alert needs a destination, and a destination needs a template. A destination created without a template becomes a pipeline destination and cannot be used by an alert. Always create the pair.

A stream must exist before an alert can query it. Creating an alert against a stream that does not exist fails with a bare HTTP 404: Stream <name> not found. In a live system ingestion creates streams; in a fresh org, declare them.

SLOs live in alert folders. Synthetics do not. There is no SLO folder type, so folder_id on an openobserve_slo refers to a folder with folder_type = "alerts". Synthetics do have their own type, and pointing a check at an alert folder fails with an opaque FOREIGN KEY constraint failed (787). The four types are dashboards, alerts, reports, synthetics.

An SLO alert has no count gate. Omit trigger_condition.threshold and operator entirely. Every other family uses them; this one rejects them.

A composite alert accepts no query or schedule. No stream_name, no query_condition, no period, frequency or threshold. silence is the only scheduling attribute it takes.

A partition key cannot also be a secondary index field. Keep the two lists disjoint.

A pipeline's function and destination must be referenced, not named. Writing openobserve_function.x.name rather than "x" is what orders creation and teardown. The server refuses to delete either while a pipeline still uses it.

Role and group names outside [a-zA-Z0-9_] are silently rewritten by the server. The provider rejects them during plan rather than tracking a name that does not exist.

Threshold value is a string in HCL. The provider sends it as a JSON number when it parses as one and a JSON string otherwise, so value = "100" is the number 100 and value = "error" is the string. An aggregation's having.value must be numeric.

Expect one diff on the first plan after terraform import. Import populates state from the server with no configuration to compare against. Applying converges and recreates nothing.

An ingestion token cannot be deleted, and its name cannot be reused. There is no delete endpoint, so removing the resource disables the token instead and leaves the record behind. Because names are unique, re-adding a token with the same name then fails. Cycling a credential means a new name, not the old one.

A deleted stream blocks its own name for up to an hour. Deletion marks the stream and the data retention job clears the marker, on ZO_COMPACT_DATA_RETENTION_INTERVAL (3600s by default). Until then, recreating it fails with stream [name] is being deleted. This makes destroy-then-apply cycles fail on streams, which is expected rather than a provider bug.

A synthetic check's run time is capped by a fixed budget, not by its schedule. ZO_SYNTHETICS_MAX_CHECK_BUDGET_SECS (840s) bounds combos x (attempts x per_attempt + retries x wait_before_retry_secs). Running a check hourly does not buy it more room than running it every minute.

Operators mean different things in the four places they appear, and conflating them is the easiest way to write an alert that will not apply:

The word operators are Contains, NotContains, IsNull, IsNotNull, IsEmpty, IsNotEmpty.

aggregation threshold (having.value) is not numeric is about the value, not the operator: operator = ">=" with value = "boom" produces it, and a unary operator with a numeric value is accepted. The provider now catches both cases during plan.

Failed to parse V1 conditions: data did not match any variant of untagged enum ConditionList means the conditions document did not parse, and it names nothing. Any of these produce it: a missing value or column, an unknown operator, an unrecognized top-level key, {}, or the UI's filterType/logicalOperator group shape, which the API does not accept.

pending_period_sec is a top-level alert attribute, a sibling of trigger_condition, not a field inside it.

Verifying work

The provider's own test suite treats a change as unverified until five steps pass. Apply the same standard to configuration:

1. terraform apply succeeds
2. terraform apply again reports no changes
3. terraform plan reports no changes
4. terraform state rm then terraform import, then one apply, then a clean plan
5. terraform destroy succeeds, and re-running it is not an error

Most bugs surface at steps 3 and 4, not step 1. A configuration that applies once is not a working configuration.

Against a local single-node server, use terraform apply -parallelism=1. SQLite code: 517 is metastore write contention, not an API error.

Style when writing configuration for a user

• Reference resources rather than hardcoding IDs. openobserve_alert.x.alert_id is what tells Terraform about ordering; a literal ID silently loses it, which matters most for composite alerts and SLO alerts.
• Put alerts and SLOs in a named folder rather than default. Folders are how OpenObserve scopes permissions.
• Set tags and priority on alerts. They cost nothing and make a large installation navigable.
• Do not set owner, last_triggered_at, updated_at or other server-managed fields. They are computed.