📉 Grafana Adaptive Metrics Segment Terraform Module

Manages a single grafana-adaptive-metrics_segment resource against a Grafana Cloud tenant's hosted Adaptive Metrics endpoint. Targets grafana/grafana-adaptive-metrics pinned exactly at 0.3.6 — the smaller of this library's two provider sources, not Grafana core.

• 📐 Defines a single Adaptive Metrics segment — the addressable scope that grafana-adaptive-metrics_ruleset, _rule, and _exemption resources reference to target a subset of a tenant's metrics traffic instead of the tenant's unsegmented default scope.
• 🆔 Emits the platform-issued ULID (id) that every sibling resource must reference back to this segment.
• 🔗 Optionally wires an Adaptive Metrics policy (policy_id) by reference — this module never creates a policy itself.
• 🧱 Standalone: one keystone resource, no owned children.

💡 Why it matters: Adaptive Metrics recommendations, rulesets, and exemptions are meaningless without a stable segment to scope them to. This module is the entry point every downstream Adaptive Metrics authoring module in this library depends on.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart LR
 policy["terraform-grafana-adaptive-metrics-policy"]
 segment["terraform-grafana-adaptive-metrics-segment<br/>(this module)"]
 ruleset["terraform-grafana-adaptive-metrics-ruleset"]
 rule["terraform-grafana-adaptive-metrics-rule"]
 exemption["terraform-grafana-adaptive-metrics-exemption"]
 recconfig["terraform-grafana-adaptive-metrics-recommendations-config"]
 tenant[["Grafana Cloud Adaptive Metrics Tenant"]]

 policy -->|"id -> policy_id (optional)"| segment
 segment -->|"id -> segment reference"| ruleset
 segment -->|"id -> segment reference"| rule
 segment -->|"id -> segment reference"| exemption
 segment -.->|"scoped to"| tenant
 ruleset -.->|"scoped to"| tenant
 rule -.->|"scoped to"| tenant
 exemption -.->|"scoped to"| tenant
 recconfig -.->|"tenant-wide singleton"| tenant

 style segment fill:#F46800,color:#ffffff
 style tenant fill:#111217,color:#ffffff
 style policy fill:#E8EAED,color:#111217
 style ruleset fill:#E8EAED,color:#111217
 style rule fill:#E8EAED,color:#111217
 style exemption fill:#E8EAED,color:#111217
 style recconfig fill:#E8EAED,color:#111217

terraform-grafana-adaptive-metrics-segment (orange) optionally consumes a policy by reference and feeds its own id forward to every rule-authoring sibling. recommendations_config is a tenant-wide singleton unrelated to any one segment's lifecycle — shown only for family context, with no direct edge to this module. Validated valid: true via the Mermaid Chart MCP before embedding.

flowchart LR
 subgraph Inputs
 name["name (required string)"]
 selector["selector (required string)"]
 auto_apply_in["auto_apply (optional object)"]
 fallback_in["fallback_to_default (optional bool)"]
 policy_in["policy_id (optional string)"]
 end

 resource(["grafana-adaptive-metrics_segment.this"])

 subgraph Outputs
 id_out["id (primary, ULID)"]
 name_out["name"]
 selector_out["selector"]
 policy_out["policy_id"]
 fallback_out["fallback_to_default"]
 autoapply_out["auto_apply"]
 end

 name -->|"name"| resource
 selector -->|"selector"| resource
 auto_apply_in -->|"auto_apply"| resource
 fallback_in -->|"fallback_to_default"| resource
 policy_in -->|"policy_id"| resource
 resource -->|"id"| id_out
 resource -->|"name"| name_out
 resource -->|"selector"| selector_out
 resource -->|"policy_id"| policy_out
 resource -->|"fallback_to_default"| fallback_out
 resource -->|"auto_apply"| autoapply_out

 style resource fill:#F46800,color:#ffffff

Resource inventory: exactly one resource — grafana-adaptive-metrics_segment.this. No for_each children; no data sources. Validated valid: true via the Mermaid Chart MCP before embedding.

Schema notes that bite:

• id is genuinely computed (Read-Only, "A ULID that uniquely identifies the segment") — re-verified directly against the live provider schema (provider_doc_id 11215735) rather than assumed, since only three resources in this provider's whole catalog (segment, policy, exemption) expose an id at all.
• auto_apply is a nested Attributes object ({ enabled = optional(bool) }), not a plain boolean — do not flatten it into a top-level auto_apply_enabled-style variable.
• policy_id carries this exact, verbatim warning in the live provider schema: "WARNING: contact Grafana Cloud support before use. This feature is in private preview and may change without notice, including in ways that may break your configuration."
• Neither fallback_to_default nor auto_apply.enabled documents an explicit provider-side default in the live schema output — this module leaves both null rather than fabricating true/false.
• The live schema output carries no "Forces new resource" annotation on any argument (unlike some other providers' segment-named resources). Treat this as not positively confirmed either way — the absence of a ForceNew annotation in the fetched docs is not the same as a confirmed in-place-update guarantee; verify against a real plan before assuming name/selector changes update in place.
• Adaptive Metrics is a Grafana Cloud-only capability — there is no OSS/Enterprise equivalent of grafana-adaptive-metrics_segment.

Adaptive Metrics auth (per this module suite's Authentication model convention → Adaptive Metrics auth (grafana/grafana-adaptive-metrics)). Requires a single provider instance configured with url (the Grafana Cloud hosted Prometheus/Adaptive Metrics endpoint) and api_key in the literal "<tenant-id>:<access-policy-token>" format, scoped to the target tenant. This module accepts no url, api_key, or GRAFANA_AM_*-shaped variable of its own — the caller configures and passes in one grafana-adaptive-metrics provider instance per tenant/segment scope at the call site.

• Adaptive Metrics must be enabled for the target Grafana Cloud tenant.
• Platform ceiling of 50 grafana-adaptive-metrics_segment resources per tenant. Terraform cannot see other callers' or other workspaces' state, so this module cannot enforce the ceiling at plan time — a root module instantiating this module at scale via for_each must track its own running segment count itself. Exceeding it fails at apply time with an opaque platform API error, not a Terraform-side validation error.
• policy_id wiring depends on the target tenant having Grafana Cloud Adaptive Metrics' policy feature enabled — a private-preview capability per the live provider schema's own warning. Contact Grafana Cloud support before relying on it in a production root module.

terraform-grafana-adaptive-metrics-segment/
├── providers.tf # required_providers pin: grafana/grafana-adaptive-metrics = 0.3.6, no provider {} block
├── variables.tf # name, selector (required); auto_apply, fallback_to_default, policy_id (optional)
├── main.tf # keystone resource "this" (grafana-adaptive-metrics_segment); 50-segment ceiling comment
├── outputs.tf # id (primary) + name, selector, policy_id, fallback_to_default, auto_apply
├── SCOPE.md # lightweight standalone cross-module contract
├── README.md # this file
└── examples/ # runnable examples

provider "grafana-adaptive-metrics" {
  url     = "https://tenant-primary.adaptive-metrics.grafana.net"
  api_key = var.grafana_am_api_key # "<tenant-id>:<access-policy-token>", sensitive, caller-supplied
}

module "mimir_team_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "mimir team"
  selector = "{namespace=\"mimir\"}"
}

⚠️ Always pin the module by tag (?ref=v1.0.0), never a branch — tags are immutable once consumers reference them. The caller configures the grafana-adaptive-metrics provider instance and its api_key; this module never accepts either as a variable.

Consumes

Emits

module "mimir_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "mimir team"
  selector = "{namespace=\"mimir\"}"
}

module "payments_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name                = "payments team"
  selector            = "{namespace=\"payments\"}"
  fallback_to_default = true
}

module "compliance_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name                = "compliance reporting"
  selector            = "{namespace=\"compliance\"}"
  fallback_to_default = false
}

module "loans_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "loans platform"
  selector = "{namespace=\"loans-platform\"}"

  auto_apply = {
    enabled = true
  }
}

module "loans_segment_no_enabled" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "loans platform staging"
  selector = "{namespace=\"loans-platform-staging\"}"

  auto_apply = {}
}

module "risk_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-policy.git?ref=v1.0.0"

  name                  = "risk-metrics-policy"
  usage_sources         = ["dashboard", "rules", "queries"]
  unused_metrics_action = "drop_custom_labels"
}

module "risk_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name      = "risk metrics"
  selector  = "{namespace=\"risk-metrics\"}"
  policy_id = module.risk_policy.id
}

variable "existing_policy_id" {
  type        = string
  description = "A pre-existing Adaptive Metrics policy ULID, not managed by this root module."
}

module "existing_policy_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name      = "legacy onboarded segment"
  selector  = "{namespace=\"legacy-onboarded\"}"
  policy_id = var.existing_policy_id
}

module "search_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "search team"
  selector = "{namespace=\"search\"}"
}

module "billing_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "billing team"
  selector = "{namespace=\"billing\"}"
}

module "prod_cluster_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "prod cluster wide"
  selector = "{cluster=\"prod-us-east\"}"
}

module "canary_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "canary - checkout"
  selector = "{namespace=\"checkout\", environment=\"canary\"}"

  fallback_to_default = true
}

variable "team_segments" {
  type = map(object({
    selector = string
  }))
  description = "One entry per team segment to create."
}

module "team_segments" {
  source   = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"
  for_each = var.team_segments

  name     = each.key
  selector = each.value.selector
}

module "fraud_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "fraud detection"
  selector = "{namespace=\"fraud-detection\"}"
}

output "fraud_segment_id" {
  value       = module.fraud_segment.id
  description = "ULID for downstream ruleset/rule/exemption wiring."
}

output "fraud_segment_name" {
  value = module.fraud_segment.name
}

module "platform_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "platform engineering"
  selector = "{namespace=\"platform-eng\"}"

  fallback_to_default = true

  auto_apply = {
    enabled = false
  }
}

module "orders_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name     = "orders service"
  selector = "{namespace=\"orders\"}"
}

# Conceptual only — see terraform-grafana-adaptive-metrics-ruleset's own README for the real interface.
module "orders_ruleset" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-ruleset.git?ref=v1.0.0"

  segment = module.orders_segment.id
  rules = [
    {
      metric       = "http_requests_total"
      aggregations = ["sum:counter"]
    }
  ]
}

provider "grafana-adaptive-metrics" {
  url     = "https://tenant-primary.adaptive-metrics.grafana.net"
  api_key = var.grafana_am_api_key
}

module "checkout_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-policy.git?ref=v1.0.0"

  name                  = "checkout-recommendations-policy"
  usage_sources         = ["dashboard", "rules", "queries"]
  unused_metrics_action = "drop_custom_labels"
  min_query_usages      = 5
}

module "checkout_segment" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-segment.git?ref=v1.0.0"

  name      = "checkout"
  selector  = "{namespace=\"checkout\"}"
  policy_id = module.checkout_policy.id

  fallback_to_default = true
  auto_apply = {
    enabled = false
  }
}

# Conceptual only — see terraform-grafana-adaptive-metrics-ruleset's own README for the real interface.
module "checkout_ruleset" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-adaptive-metrics-ruleset.git?ref=v1.0.0"

  segment = module.checkout_segment.id
  rules = [
    {
      metric       = "checkout_latency_seconds"
      aggregations = ["avg:gauge"]
    }
  ]
}

output "checkout_segment_id" {
  value = module.checkout_segment.id
}

variable "name" {
  type = string
}

variable "selector" {
  type = string
}

variable "auto_apply" {
  type = object({
    enabled = optional(bool)
  })
  default = null
}

variable "fallback_to_default" {
  type    = bool
  default = null
}

variable "policy_id" {
  type    = string
  default = null
}

No output in this module carries a credential or secret value — grafana-adaptive-metrics_segment has no secret-shaped attributes in its live schema.

• for_each key stability (root-module concern): this module has no internal for_each, but Example 11 shows the intended root-module pattern — key the map by a stable team/segment identifier (e.g. a team slug), never by list position, so adding or removing a segment never forces an unrelated segment to be recreated.
• auto_apply is rendered as a conditional object literal, not a dynamic block — it is a nested Attributes schema (Plugin Framework SingleNestedAttribute), not a repeating classic-SDK block, so main.tf assigns it directly (auto_apply = var.auto_apply == null ? null: { enabled =... }) rather than using dynamic "auto_apply" {... }.
• No secret/sensitive handling required at the module-variable level — all of this resource's fields are non-secret identifiers, selectors, and booleans. The only credential in this module's entire dependency chain is the provider-level api_key, which is strictly the caller's concern (see §7) and never touches this module's variables.tf/outputs.tf.
• Cloud-only applicability — every Adaptive Metrics resource, this one included, only makes sense against a Grafana Cloud tenant with Adaptive Metrics enabled; there is no OSS/Enterprise equivalent to fall back to.
• Ordering hazard belongs to siblings, not this module — this module itself has no ruleset/rule conflict risk (per this module suite's Adaptive Metrics ordering/conflict convention), but Example 14 calls it out because callers frequently author segment + ruleset together in the same root module.

None of this module suite's "Secure-by-default" convention rows map directly onto grafana-adaptive-metrics_segment creation itself — checked explicitly, field by field, rather than force-fit:

This module's own default posture, where the live schema left real ambiguity:

• fallback_to_default and auto_apply.enabled default to null (omitted from the rendered resource) rather than a fabricated true/false, since the live schema documents no explicit provider-side default for either.
• policy_id defaults to null and is never hard-coded — always meant to be wired from a sibling policy module's output, with the provider's own private-preview warning surfaced verbatim in variables.tf and this README rather than silently treated as GA.

cd C:\GitHubCode\newgrafanamodules\terraform-grafana-adaptive-metrics-segment
terraform init -backend=false
terraform validate
terraform fmt -check

Pin the module by tag (?ref=v1.0.0) at every call site, never a branch. This is a plan-only posture module in this authoring workflow — no apply is ever performed here; a human applies from CI against a real Grafana Cloud tenant.

terraform validate + terraform fmt -check are offline, plan-time checks — they confirm this module's own HCL is internally type-consistent and canonically formatted without ever reaching the Adaptive Metrics API. They catch: missing required arguments (name/selector), type mismatches against auto_apply's object({ enabled = optional(bool) }) schema, and invalid block nesting.

They do not catch: whether name, selector, auto_apply, fallback_to_default, or policy_id actually match the live 0.3.6 schema's real argument names (a typo'd argument that is internally consistent HCL will still pass validate), whether a for_each key chosen at the root module (Example 11) is actually stable in production, or whether a policy_id value is valid against a real tenant's policies — those are only exercised by a real terraform plan/apply against a live Grafana Cloud tenant, which is explicitly out of scope for this offline-authoring process.

$ terraform output

auto_apply = {
 "enabled" = false
}
fallback_to_default = true
id = "01J8X8N3K5QZ7T2VYB4HGRS6DM"
name = "checkout"
policy_id = "01J8X7C1RZQK9F3T6YB2HN5WGX"
selector = "{namespace=\"checkout\"}"

• Provider resource docs: grafana-adaptive-metrics_segment (provider_doc_id 11215735, grafana/grafana-adaptive-metrics v0.3.6, Terraform Registry)
• Sibling modules: terraform-grafana-adaptive-metrics-policy, terraform-grafana-adaptive-metrics-ruleset, terraform-grafana-adaptive-metrics-rule, terraform-grafana-adaptive-metrics-exemption, terraform-grafana-adaptive-metrics-recommendations-config
• This module's own SCOPE.md