📊 Grafana Folder Terraform Module

Manages a Grafana folder and its full permission set — one grafana_folder_permission_item resource per principal — as one composite unit. Targets grafana/grafana (~> 4.0).

• 📁 Creates and manages a grafana_folder — title, optional custom uid, org scope, optional nested- folder parent, and optional prevent_destroy_if_not_empty guard.
• 🔐 Renders zero or more grafana_folder_permission_item bindings, for_each-keyed by a caller-chosen stable principal key — one Terraform resource per principal, never a single whole-list resource.
• 🧭 Deliberately does not use grafana_folder_permission (the whole-list alternative that re-renders the entire permission set, and removes any binding absent from that render, on every apply) — see §6 Schema notes that bite.
• 🆔 Emits uid as the primary output — the identity every sibling module placing content in this folder (terraform-grafana-dashboard, terraform-grafana-alerting-rule-group, terraform-grafana-synthetic-monitoring- check) and a subsequent nested-folder instance of this same module consume by reference.

💡 Why it matters: a folder's access boundary is a security-relevant property in a regulated environment. Managing the folder and its permission bindings as one composite unit means a caller who owns a folder's lifecycle also owns exactly who can access it — and adding or removing a single principal's binding never disturbs any other binding's state, unlike the whole-list alternative.

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 TD
 team["terraform-grafana-team\n(team principal)"]:::sibling
 user["terraform-grafana-user\n(user principal)"]:::sibling
 svcacct["terraform-grafana-service-account\n(service account principal)"]:::sibling
 folder["terraform-grafana-folder"]:::this
 parentfolder["terraform-grafana-folder\n(parent instance, nested folders)"]:::sibling
 dashboard["terraform-grafana-dashboard"]:::sibling
 rulegroup["terraform-grafana-alerting-rule-group"]:::sibling
 smcheck["terraform-grafana-synthetic-monitoring-check"]:::sibling

 team -- "team_id (permission principal)" --> folder
 user -- "user_id (permission principal)" --> folder
 svcacct -- "id (permission principal)" --> folder
 parentfolder -- "uid (parent_folder_uid)" --> folder
 folder -- "uid (folder_uid)" --> dashboard
 folder -- "uid (folder_uid)" --> rulegroup
 folder -- "uid (folder_uid)" --> smcheck

 classDef this fill:#F46800,color:#FFFFFF,stroke:#F46800;
 classDef sibling fill:#E8E8E8,color:#111217,stroke:#8A8A8A;

Validated via the Mermaid Chart MCP (valid: true) before embedding. terraform-grafana-team, terraform-grafana-user, and terraform-grafana-service-account feed permission-binding principal identities into this module; a separately-applied instance of this same module feeds parent_folder_uid for nested folders; this module's own uid output feeds three content-layer siblings that place dashboards, alert rule groups, and Synthetic Monitoring checks inside the folder.

flowchart LR
 subgraph inputs["Inputs"]
 varfolder["var.folder\n(object)"]
 varperms["var.permissions\n(map(object), default {})"]
 end

 keystone["grafana_folder.this\n(keystone)"]:::this
 bindings["grafana_folder_permission_item.bindings\n(for_each, keyed map)"]:::this

 varfolder -- "title, uid, org_id, parent_folder_uid, prevent_destroy_if_not_empty" --> keystone
 varperms -- "permission, role, team, user, org_id (per key)" --> bindings
 keystone -- "uid (folder_uid)" --> bindings

 keystone --> outuid["uid\n(primary_output)"]
 keystone --> outid["id"]
 keystone --> outtitle["title"]
 keystone --> outurl["url"]
 bindings --> outbindings["permission_bindings\n(map, per key)"]

 classDef this fill:#F46800,color:#FFFFFF,stroke:#F46800;

Validated via the Mermaid Chart MCP (valid: true) before embedding.

Resource inventory:

Schema notes that bite:

• uid is listed as Optional in the live v4.40.1 schema, with no separate "Computed"/"Force new" annotation surfaced in the rendered docs page. This suite's accumulated Known schema gotchas record (cross-checked during prior authoring) confirms: when omitted, Grafana generates a uid server-side; once a uid exists (caller-set or generated), changing it forces replacement of the folder — it is this resource's stable identity everywhere else in the API and in every sibling module's folder_uid consumption. Treat as immutable-after-set.
• parent_folder_uid requires the nestedFolders feature flag enabled on the target Grafana instance — the live schema's own field description states this explicitly. See §8 Grafana Prerequisites.
• prevent_destroy_if_not_empty requires Grafana 10.2 or later per the live schema's own field description; defaults to false. See §8 Grafana Prerequisites.
• grafana_folder.id is a String in the live schema ("The ID of this resource"), not a legacy numeric ID as earlier module planning assumed — this module's id output reflects that String type verbatim and is documented as informational-only; prefer uid for all cross-module wiring.
• This module uses grafana_folder_permission_item (one resource per principal), not grafana_folder_permission (a single resource holding the folder's entire permission set as a repeating permissions block). The provider's own docs state the whole-list resource "manages the entire set of permissions for a folder. Permissions that aren't specified when applying this resource will be removed" — it does not compose safely across independent for_each iterations or independent callers adding principals over time. _item avoids this: each principal binding gets its own resource identity and lifecycle, and the two resources are documented by the provider as conflicting if both target the same folder.
• Each grafana_folder_permission_item requires folder_uid and permission, plus exactly one of role / team / user — the live schema only enforces this "conflicts with" constraint at apply time; this module's variables.tf enforces it at terraform plan time instead (see §12 example 9).
• Unresolved identity-type ambiguity for team: the provider's own example usage for grafana_folder_permission_item passes team = grafana_team.team.id (the team resource's own id attribute), not team_uid. Both grafana_folder_permission and grafana_folder_permission_item link to the legacy folder-permissions HTTP API in their own docs (api-legacy/folder_permissions/), which is evidence — not a schema-confirmed fact — that the team field expects the string form of the team's legacy numeric ID (tostring(team_id)), not the newer team_uid. Verify with a live plan against a real team before depending on this in production; see §12 example 6 and §15 Architecture Notes.
• grafana_folder.id and grafana_team.id / grafana_user.id are all separately-documented id attributes on their respective resources — none of this library's sibling modules currently expose a plain id-named output for team, so this module's README recommends tostring(team_id) / tostring(user_id) / the service account's own id output as the practical wiring path (see §11).

Grafana core auth (see this suite's Authentication model, "Grafana core auth" table) — the auth provider argument (Service Account token). least-privilege convention for this module is an Editor/Admin-scoped Service Account token: Editor is sufficient to create and rename the folder itself; Admin is required if this module's permission bindings grant Admin-level access to any other principal, since a token cannot grant a permission level higher than its own. Choose the narrower Editor scope when this module's calling root module only ever grants Viewer/Editor bindings; step up to Admin only when an Admin-level binding is actually rendered. Configured once by the caller on whichever aliased grafana provider instance is passed into this module via providers = { grafana =... }; this module declares no alias or credential of its own.

• parent_folder_uid requires the nestedFolders feature flag enabled on the target Grafana instance. Only relevant when the caller sets this field — treat as feature-gated, not universally available.
• prevent_destroy_if_not_empty requires Grafana 10.2 or later. Version-gate this field's use; do not assume every target instance is new enough to support it.
• Folder identity (uid) is scoped per org/stack, not global — confirm the target org/stack context (e.g. via an org_id-scoping convention, where the calling root module wires one from terraform-grafana-organization) before applying.

terraform-grafana-folder/
├── providers.tf # required_providers: grafana/grafana ~> 4.0, required_version >= 1.12.0. No provider {} block.
├── variables.tf # var.folder (keystone object) + var.permissions (for_each-keyed permission bindings map)
├── main.tf # grafana_folder.this (keystone) + grafana_folder_permission_item.bindings (for_each)
├── outputs.tf # uid (primary), id, title, url, permission_bindings
├── README.md # this file
├── SCOPE.md # cross-module contract, auth/scope, prerequisites, provider gotchas
└── examples/ # runnable example(s)

module "platform_ops_folder" {
  source = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"

  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Platform Ops"
  }
}

The caller configures the grafana provider (with the alias this module's Editor/Admin-scoped Service Account token auth requires) once at the root module — this module never accepts its own url, auth, or org_id default.

Consumes

Emits

module "folder_minimal" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Observability"
  }
}

module "folder_explicit_uid" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Shared Dashboards"
    uid   = "shared-dashboards"
  }
}

module "folder_scoped_org" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title  = "Tenant B Reporting"
    org_id = "3"
  }
}

module "parent_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Engineering"
  }
}

module "child_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title             = "Engineering / Platform"
    parent_folder_uid = module.parent_folder.uid
  }
}

module "folder_least_privilege" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Read-Only Metrics"
  }

  permissions = {
    "role:viewer" = {
      role       = "Viewer"
      permission = "View"
    }
  }
}

module "analytics_team_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Analytics"
  }

  permissions = {
    "team:analytics" = {
      team       = tostring(module.analytics_team.team_id)
      permission = "Edit"
    }
  }
}

module "user_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Personal Sandbox"
  }

  permissions = {
    "user:analyst01" = {
      user       = tostring(module.analyst_user.user_id)
      permission = "Admin"
    }
  }
}

module "automation_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "CI/CD Provisioned Dashboards"
  }

  permissions = {
    "svcacct:ci-bot" = {
      user       = module.ci_service_account.id
      permission = "Edit"
    }
  }
}

module "folder_bad_binding" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Conflicting Binding"
  }

  permissions = {
    "bad:entry" = {
      role       = "Viewer"
      team       = tostring(module.analytics_team.team_id) # fails validation — do not do this
      permission = "Edit"
    }
  }
}

module "mixed_principal_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Shared Ops Dashboards"
  }

  permissions = {
    "role:viewer" = { role = "Viewer", permission = "View" }
    "team:ops"    = { team = tostring(module.ops_team.team_id), permission = "Edit" }
    "user:oncall" = { user = tostring(module.oncall_user.user_id), permission = "Admin" }
  }
}

locals {
  reporting_team_ids = {
    finance  = "12"
    treasury = "18"
    audit    = "27"
  }
}

module "reporting_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Regulatory Reporting"
  }

  permissions = {
    for name, team_id in local.reporting_team_ids :
    "team:${name}" => {
      team       = team_id
      permission = "View"
    }
  }
}

module "protected_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title                        = "Production Dashboards"
    prevent_destroy_if_not_empty = true
  }
}

module "folder_reporting_only" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Audit Trail"
  }
}

module "network_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Network Engineering"
  }
}

output "network_folder_uid" {
  value = module.network_folder.uid
}

output "network_folder_id" {
  value = module.network_folder.id
}

provider "grafana" {
  alias = "stack_primary"
  url   = "https://casey-primary.grafana.net"
  auth  = var.grafana_stack_service_account_token
}

module "analytics_team" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-team.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  team = {
    name = "Analytics"
  }
}

module "analyst_user" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-user.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  # See that module's own README for its real variable names/schema.
  # email = "[email protected]" / login = "analyst01" / password = var.analyst_password
}

module "ci_service_account" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-service-account.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  # See that module's own README for its real variable names/schema.
  # service_account = { name = "ci-bot", role = "Editor" }
}

module "analytics_folder" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-folder.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  folder = {
    title = "Analytics"
  }

  permissions = {
    "team:analytics" = {
      team       = tostring(module.analytics_team.team_id)
      permission = "Edit"
    }
    "user:analyst01" = {
      user       = tostring(module.analyst_user.user_id)
      permission = "View"
    }
    "svcacct:ci-bot" = {
      user       = module.ci_service_account.id
      permission = "Edit"
    }
  }
}

module "analytics_dashboard" {
  source    = "git::https://github.com/microsoftexpert/terraform-grafana-dashboard.git?ref=v1.0.0"
  providers = { grafana = grafana.stack_primary }

  # Illustrative only -- see that module's own README for its real variable names/schema.
  # folder_uid = module.analytics_folder.uid
  # config_json = file("${path.module}/dashboards/analytics-overview.json")
}

variable "folder" {
  type = object({
    title                        = string
    uid                          = optional(string)
    org_id                       = optional(string)
    parent_folder_uid            = optional(string)
    prevent_destroy_if_not_empty = optional(bool, false)
  })
}

variable "permissions" {
  type = map(object({
    permission = string           # "View" | "Edit" | "Admin"
    role       = optional(string) # "Viewer" | "Editor" | "Admin" -- mutually exclusive with team/user
    team       = optional(string) # mutually exclusive with role/user
    user       = optional(string) # mutually exclusive with role/team
    org_id     = optional(string) # per-binding override; falls back to var.folder.org_id
  }))
  default = {}
}

• _item over the whole-list resource, deliberately. grafana_folder_permission_item.bindings is for_each-keyed over var.permissions, giving every principal binding independent Terraform resource identity. The rejected alternative, grafana_folder_permission, renders the entire permission set as one resource and removes any binding not present in that render on every apply — it does not compose safely when different callers or for_each iterations add/remove principals independently over time.
• uid is immutable-after-set. Whether caller-supplied or Grafana-generated, changing an existing uid forces replacement of the folder — every sibling module's folder_uid consumption depends on this value staying stable across applies.
• Per-binding org_id falls back to the folder's own org_id. main.tf renders org_id = each.value.org_id != null ? each.value.org_id: try(var.folder.org_id, null) — a ternary, not try, since a null per-binding org_id is a valid (non-erroring) value and try only falls through on evaluation errors, not on null. This keeps a binding in the same org/stack scope as the folder it protects unless the caller explicitly overrides it.
• The team/user identity-type question is genuinely open. The provider's own example usage for grafana_folder_permission_item passes grafana_team.team.id / grafana_user.user.id, and both resources' docs reference the legacy folder-permissions HTTP API. This module's Example Library (§12 examples 6–8) wires tostring(team_id) / tostring(user_id) / the service account's own id output as the practical, evidence-based recommendation — but this was not independently confirmed with a live plan against a real Grafana instance this session. Verify before depending on it in production.
• for_each, never count, for permission bindings — this suite's mandate, followed here so adding or removing one principal never re-indexes or disturbs any other binding's state.
• Cloud vs. OSS applicability: grafana_folder and grafana_folder_permission_item both apply to Cloud-hosted and self-managed OSS/Enterprise Grafana instances alike; parent_folder_uid (nested folders) and prevent_destroy_if_not_empty are each separately feature/version-gated regardless of Cloud-vs-OSS (see §8 Grafana Prerequisites).

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

Pin consumers at ?ref=v1.0.0, never a branch. This module is plan-only in this authoring pipeline — no apply is ever run here; a human applies from CI against a real Grafana target.

terraform validate + terraform fmt -check together confirm: every field in var.folder and var.permissions type-checks against the schemas declared in variables.tf; the three validation {} blocks on permissions (permission enum, role enum, exactly-one-of role/team/user) are themselves syntactically valid; and the whole file set is canonically formatted. These checks run entirely offline — no GRAFANA_URL or Service Account token is required.

What this harness cannot catch: whether a uid value collides with an existing folder on a real instance, whether nestedFolders or Grafana 10.2+ are actually available on the target instance (both are platform-side checks, not Terraform-side ones), or whether team/user bindings actually expect the legacy numeric ID vs. team_uid as this README's Architecture Notes flags as unresolved — those surface only at plan/apply against a live Grafana instance.

$ terraform output

id = "3"
permission_bindings = {
 "team:analytics" = "12:team:12"
 "user:analyst01" = "12:user:47"
}
title = "Analytics"
uid = "adfhmxue45gnkb"
url = "/dashboards/f/adfhmxue45gnkb/analytics"

• Provider resource docs: grafana_folder, grafana_folder_permission_item, grafana_folder_permission (grafana/grafana provider, Terraform Registry)
• This module's SCOPE.md — cross-module contract, required auth/scope, Grafana prerequisites, provider gotchas, design decisions
• Sibling modules referenced above: terraform-grafana-team, terraform-grafana-user, terraform-grafana-service-account, terraform-grafana-dashboard, terraform-grafana-alerting-rule-group, terraform-grafana-synthetic-monitoring-check (dashboard/alerting-rule-group/synthetic-monitoring-check not yet authored as of this session — treat their example call shapes above as illustrative)