☁️ Azure Portal Dashboard Terraform Module

A shared dashboard is an ARM RESOURCE holding a JSON tile layout.
  - it lives in a resource group, so Azure RBAC decides who can open it
  - its tiles reference other resources by absolute ID
  - it renders per-viewer: a tile only shows data the VIEWER can read

ℹ️ "Shared" distinguishes it from a private dashboard, which lives in a user's own profile and is not an ARM resource at all. Only shared dashboards are manageable here.

💡 Which makes Terraform genuinely useful for them: a dashboard defined in code is reviewable, versioned, and reproducible across environments — unlike one somebody built by dragging tiles and never documented.

⚠️ But the JSON is a generated artifact, not something to author by hand (example 2), and it is full of absolute resource IDs (example 3). Those two facts shape everything else in this document.

dashboard_properties = file("${path.module}/dashboards/platform-health.json")

💡 Build the dashboard interactively in the portal, use Export to file, and commit the result. The format is generated: nested lenses, numbered parts, position objects and per-tile input arrays. It is readable enough to review and thoroughly unpleasant to write.

✅ Keep it in its own file. An inline heredoc of dashboard JSON makes every diff unreadable and hides the one thing worth reviewing — which resources the tiles point at.

✅ The module validates more than "is it JSON". A body with no top-level lenses object is rejected:

Error: Invalid value for variable

  dashboard_properties must carry a `lenses` object AT THE TOP LEVEL. The provider
  unmarshals this string directly into its DashboardProperties type and requires lenses
  to be present there, so a body shaped {"properties": {"lenses": ...}} is refused -
  that is the ARM-template wrapper around a dashboard rather than the dashboard body
  itself. Export the dashboard from the portal and pass the value of its `properties`
  field, not the whole template.

💡 That second check exists because "valid JSON" is a weak test here. The common mistake is exporting an ARM template — perfectly valid JSON, wrapping the dashboard body one or two levels down — and that mistake is detectable.

⚠️ The check requires lenses at the TOP LEVEL, and that is the provider's rule rather than a preference. validate.DashboardProperties unmarshals this string straight into the SDK's DashboardProperties type and errors with \`lenses\` is required in JSON payload when the field is absent — verified by driving a {"properties": {"lenses": {}}} literal through terraform validate. An earlier revision of this module accepted that wrapped shape and said so in its own error message, which let the exact mistake this check exists to catch through to be refused one layer later, by a message that does not mention wrapping.

ℹ️ tile_count_hint is emitted so an obviously empty dashboard shows up in a plan. It reads only the first lens, so treat it as a hint rather than a total.

"inputs": [{
  "name": "ComponentId",
  "value": { "SubscriptionId": "00000000-...", "ResourceGroup": "rg-prod", "Name": "law-prod" }
}]

🔴 Tiles reference their targets by absolute ARM ID, subscription included. So a dashboard JSON copied from another subscription keeps pointing at the ORIGINAL subscription's resources — it applies without error, renders without error, and shows the wrong data or none at all.

⚠️ Nothing catches this. The JSON is valid, the resource is created, the plan is clean. The only symptom is a dashboard that looks broken to whoever opens it.

✅ So template the JSON rather than copying it:

dashboard_properties = templatefile("${path.module}/dashboards/health.json.tftpl", {
  workspace_id   = module.law.id
  app_insights_id = module.appi.id
})

💡 Export once, replace the IDs with placeholders, and let Terraform substitute them. That turns a per-environment copy-paste problem into one file that works everywhere — and it makes the dependency real, so Terraform orders the workspace before the dashboard.

ℹ️ The module emits embeds_absolute_resource_ids as a constant true, because this is the fact that makes dashboard JSON non-portable and it is invisible in state.

display_name = "Platform health" # this module sets the `hidden-title` tag for you

⚠️ The portal reads the dashboard's title from a tag with the key hidden-title. There is no first-class argument for it — one of the odder corners of this provider. The thing an analyst reads is metadata.

🔴 Omit it and the portal shows the ARM name — which, for a dashboard originally created in the portal, is typically a GUID. A dashboard nobody can identify is a dashboard nobody uses.

✅ So this module exposes a normal display_name and merges it into the tag. That is a deliberate small divergence from the provider: mirroring it exactly would mean every caller rediscovering the quirk.

✅ And setting both is rejected, so the title has exactly one source:

display_name = "Platform health"
tags         = { "hidden-title" = "Something else" } # ❌

Error: Invalid value for variable

  Set either display_name or a `hidden-title` tag, not both — they are the same field
  and two sources would make the dashboard's title ambiguous. Prefer display_name.

ℹ️ The tag route is still available if you prefer it — leave display_name unset and put hidden-title in tags. has_display_name is emitted either way, so a review can spot a dashboard that will show a machine name.

A Markdown tile in this dashboard's JSON can hold:
  inline content        -> prohibited if the TENANT CONFIGURATION enforces private storage
  an external URI       -> always allowed

⚠️ That setting is a different resource, and it is tenant-wide — the sibling terraform-azurerm-portal-tenant-configuration module, a singleton whose Resource ID contains no subscription. With private_markdown_storage_enforced = true, inline Markdown tiles stop rendering their content across every dashboard in the tenant.

🔴 So a dashboard's JSON can be correct and its tiles still not behave as written. This module cannot see that setting, and nothing in a plan reconciles the two.

💡 Which is a reason to prefer external Markdown anyway. Content in a storage account is auditable and access-controlled; inline content is whatever the last editor typed, displayed inside the portal with the portal's implicit credibility.

ℹ️ If your tenant enforces private Markdown storage, treat inline Markdown in dashboard JSON as a defect to be fixed at export time rather than something to work around here.

Reader on the RESOURCE GROUP   -> can open the dashboard, and read the resource IDs in it
Reader on each TILE'S TARGET   -> is what makes that tile render data

⚠️ A dashboard does not grant visibility. Someone with Reader here but no access to the referenced workspace sees the dashboard, sees the tile, and sees no data in it. Tiles render per-viewer.

💡 Which is usually the behaviour you want — it means sharing a dashboard cannot leak data — but it does mean a dashboard can look broken to one person and fine to another, and that is a support call worth anticipating.

🔴 What Reader on the resource group DOES expose is the JSON itself, including every resource ID, workspace name and query in it. That is a modest information disclosure: the structure of your estate, if not its data.

✅ So put dashboards in a resource group whose Reader list you are comfortable with, and keep anything sensitive out of the JSON — including in Markdown tile text (example 7).

output "body" { value = module.dash.dashboard_properties } # not sensitive, deliberately

🔒 This module does not mark dashboard_properties sensitive, and the reasoning is worth stating. It is a layout definition readable by anyone with Reader on the resource group (example 6) — so redacting it in plan output would hide it from review while protecting nothing.

⚠️ And it would break the review that matters most: checking which resource IDs the tiles point at (example 3) requires reading the JSON in a diff.

🔴 The corollary is the actual rule: do not put anything sensitive in dashboard JSON. Not a token in a query string, not a connection detail in a Markdown tile, not a comment naming an unannounced system. It is readable by a wide audience and it is stored in Terraform state in plaintext.

💡 KQL queries embedded in tiles deserve a second look on this point. A query is code, and code sometimes carries context — an internal hostname, a customer identifier, an account number — that you would not choose to publish to everyone with Reader.

locals {
  dashboards = {
    platform = { title = "Platform health", file = "platform-health.json" }
    security = { title = "Security overview", file = "security.json" }
  }
}

module "dash" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-portal-dashboard.git?ref=v1.0.0"
  for_each = local.dashboards

  name                = each.key
  resource_group_name = module.rg.name
  location            = module.rg.location

  display_name         = each.value.title
  dashboard_properties = templatefile("${path.module}/dashboards/${each.value.file}.tftpl", {
    workspace_id = module.law.id
  })
}

💡 One dashboard per audience beats one dashboard with everything. Tiles render per-viewer (example 6), so a combined dashboard shows different people different amounts of blank space — and a focused dashboard is the one people actually keep open.

⚠️ Consider the resource group per audience too. Reader there exposes the JSON, so a security dashboard in a resource group the whole organisation can read is a small information-disclosure decision (example 7).

✅ templatefile per dashboard keeps the resource IDs correct across environments (example 3).

ℹ️ for_each lives in the caller; the module manages one dashboard.

output "dash_review" {
  value = {
    id       = module.dash.id
    title    = module.dash.display_name        # ⚠️ null means users see the ARM name
    titled   = module.dash.has_display_name    # assert true
    tiles    = module.dash.tile_count_hint     # 0 is worth a look
    portable = module.dash.embeds_absolute_resource_ids # always true
  }
}

⚠️ titled is the assertion worth encoding. false means the portal shows the ARM resource name, and for an imported dashboard that is a GUID (example 4).

⚠️ tiles at 0 usually means the wrong JSON was supplied — an ARM template wrapper, or an empty export. It is a hint and not a count (example 2).

ℹ️ portable is a constant true. Read it as "and this JSON names a specific subscription's resources" (example 3).

💡 What no output can tell you is whether the tiles point at resources that exist, or whether any of them render. That needs the portal.

terraform import 'module.dash.azurerm_portal_dashboard.this' \
  "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-observability/providers/Microsoft.Portal/dashboards/00000000-0000-0000-0000-000000000000"

ℹ️ Note the GUID as the dashboard name. A dashboard created in the portal gets one, which is why the provider's own import example shows it — and why the imported dashboard will keep it, since name is force-new.

💡 So importing a portal-built dashboard is usually the wrong move. Export its JSON, create a new dashboard through this module with a readable name, and delete the original. You end up with the same tiles and a name a human can use.

⚠️ If you do import, restate dashboard_properties from the export, or the first apply overwrites the dashboard with whatever your configuration says — an in-place change, so easy to miss in a plan.

⚠️ And check hidden-title. An imported dashboard usually has one already; supplying display_name as well is rejected (example 4), so pick one source and restate it.

terraform destroy on this module:
  removes the dashboard  ->  the tiles' TARGET RESOURCES are untouched
                         ->  no data, workspace or metric is affected
                         ->  anyone with it open sees it disappear

✅ This is a safe destroy. A dashboard is a view; deleting it deletes no data and breaks no system. The worst outcome is somebody's bookmark stops working.

💡 Which makes dashboards a good place to iterate. Unlike most resources in this library, getting one wrong and rebuilding it costs nothing.

The offline gate

terraform init -backend=false
terraform validate
terraform fmt -check

✅ What it proves: the JSON parses, it has a lenses object, the title has exactly one source, and the identity fields are non-empty.

💡 Proved by evaluating the conditions in terraform console inside the module, which does fire root-module variable validations — unlike terraform validate on a calling configuration. A body of {"properties":{"template":{}}} fires the lenses check, and supplying display_name alongside a hidden-title tag fires the both-sources check.

⚠️ What it cannot prove: that the referenced resources exist, that they are in this subscription, or that any tile renders. No cloud apply happens in this flow.

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-observability"
  location = "eastus"
}

module "law" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-log-analytics-workspace.git?ref=v1.0.0"

  name                = "law-platform"
  resource_group_name = module.rg.name
  location            = module.rg.location
  sku                 = "PerGB2018"
  retention_in_days   = 90
}

module "appi" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-application-insights.git?ref=v1.0.0"

  name                = "appi-platform"
  resource_group_name = module.rg.name
  location            = module.rg.location
  workspace_id        = module.law.id
}

# ── The dashboard: TEMPLATED, so the resource IDs are right (example 3) ────
module "dash" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-portal-dashboard.git?ref=v1.0.0"

  name                = "platform-health"
  resource_group_name = module.rg.name
  location            = module.rg.location

  # The title users read. A tag under the hood (example 4).
  display_name = "Platform health"

  # Placeholders substituted from the real modules, so this file works in any
  # subscription AND Terraform orders the workspace first (example 3).
  dashboard_properties = templatefile("${path.module}/dashboards/platform-health.json.tftpl", {
    workspace_id    = module.law.id
    app_insights_id = module.appi.id
  })

  tags = { owner = "platform" }
}

# ── The tenant-wide setting that constrains Markdown tiles (example 5) ─────
# ⚠️ A SINGLETON, and tenant-scoped — only ONE configuration in the tenant should
# own it, and it needs tenant-level permissions. Usually a separate root module.
# module "portal_config" {
#   source                            = "git::https://github.com/microsoftexpert/terraform-azurerm-portal-tenant-configuration.git?ref=v1.0.0"
#   private_markdown_storage_enforced = true
# }

output "dashboard_posture" {
  value = {
    title  = module.dash.display_name
    titled = module.dash.has_display_name # assert true
    tiles  = module.dash.tile_count_hint
  }
}

🔒 What the composition gets right: templatefile substituting real resource IDs so the JSON is portable and the dependency is real, a display_name so users see a title rather than a resource name, the dashboard in an observability resource group whose Reader list is a deliberate choice, and the tenant configuration shown commented out — because it is a tenant-scoped singleton that does not belong in a subscription-level root module.

⚠️ What no plan will tell you: whether the tiles render, whether the referenced resources are in this subscription, or whether the tenant enforces private Markdown storage.

💡 titled is the assertion to encode. Everything else here is a portal check.