☁️ Azure Management Group Template Deployment Terraform Module

Deploys an ARM template at management-group scope (azurerm_management_group_template_deployment) for the tenant- and subscription-level constructs Terraform cannot express directly. Targets hashicorp/azurerm ~> 4.0.

• 🌉 Deploys an ARM template at management-group scope as a keystone resource named this — a deliberate bridge for ARM-only capabilities, not a general escape hatch.
• 🔀 Restates the template-source exclusive-or with a module-level message. The provider already enforces this through the SDK's ExactlyOneOf on both fields, so setting neither or both is rejected at plan -- not at apply. The module keeps its own check because it names a module input and produces an actionable message, but it is a better message for an existing guarantee, not a missing one. Note the two fields are not symmetrical: template_content is optional-and-computed, template_spec_version_id is optional only.
• 📦 Steers reuse toward a template spec version, which is versioned and access-controlled in Azure rather than living in whichever repository ran the apply.
• 🔐 Documents parameters_content and debug_level as secret-disclosure paths, because both write values into the management group's deployment history.
• 📤 Passes the template's own outputs back as output_content for jsondecode().
• ⏱️ Gives create and update real timeout headroom — management-group deployments run long.

💡 Why it matters: A management-group deployment can create subscription- and tenant-level resources, so its reach is wider than any resource-group deployment — but Terraform's plan shows a JSON string, not the resources. The two things that actually go wrong are an ambiguous template source and secrets leaking through deployment history, so this module makes the first fail at plan and the second loudly documented.

If this module saves you time, please consider supporting its continued development:

• ⭐ Star the repository on GitHub.
• 🤝 Connect on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

flowchart LR
  mg["terraform-azurerm-management-group"]
  spec["Azure template spec version"]
  kv["terraform-azurerm-key-vault"]
  this["terraform-azurerm-management-group-template-deployment"]
  dep["azurerm_management_group_template_deployment"]
  arm["subscription and tenant level resources ARM creates"]
  typed["terraform-azurerm-policy-definition and other typed modules"]

  mg -->|"management_group_id"| this
  spec -->|"template_spec_version_id"| this
  kv -->|"ARM parameter reference at deploy time"| dep
  this -->|"creates"| dep
  dep -->|"deploys"| arm
  typed -->|"preferred where a typed resource exists"| arm

  classDef me fill:#0078D4,stroke:#004578,color:#fff;
  classDef keystone fill:#004578,stroke:#001f3f,color:#fff;
  classDef sib fill:#eef2f7,stroke:#b8c4d0,color:#1b1b1b;
  class this me;
  class dep keystone;
  class mg,spec,kv,arm,typed sib;

flowchart TB
  ident["name and location: deployment metadata only"]
  tc["template_content: file or jsonencode"]
  tsv["template_spec_version_id: versioned in Azure"]
  xor["validation: exactly one template source"]
  pc["parameters_content: recorded in deployment history"]
  dbg["debug_level: secret disclosure control, leave null"]
  this["terraform-azurerm-management-group-template-deployment"]
  dep["azurerm_management_group_template_deployment.this"]
  hist["management group deployment history"]
  arm["resources ARM creates, outside Terraform state"]
  out["output_content: whatever the template emitted"]

  tc -->|"one source"| xor
  tsv -->|"or the other"| xor
  xor -->|"enforced at plan"| this
  ident -->|"identity"| this
  pc -->|"template inputs"| this
  dbg -->|"leave null in production"| this
  this -->|"creates"| dep
  dep -->|"records inputs in"| hist
  dep -->|"deploys"| arm
  dep -->|"emits"| out

  classDef me fill:#0078D4,stroke:#004578,color:#fff;
  classDef keystone fill:#004578,stroke:#001f3f,color:#fff;
  classDef sib fill:#eef2f7,stroke:#b8c4d0,color:#1b1b1b;
  class this me;
  class dep keystone;
  class ident,tc,tsv,xor,pc,dbg,hist,arm,out sib;

Resource inventory

Schema notes that bite (verified against the live provider schema):

• The template source is an exclusive-or the PROVIDER enforces. The provider already enforces this through the SDK's ExactlyOneOf on both fields, so setting neither or both is rejected at plan -- not at apply. The module keeps its own check because it names a module input and produces an actionable message, but it is a better message for an existing guarantee, not a missing one. Note the two fields are not symmetrical: template_content is optional-and-computed, template_spec_version_id is optional only. The module's check lives on template_content and references the other variable one-directionally, because Terraform rejects validations that reference each other.
• name, management_group_id, and location are force-new.
• location stores the deployment metadata, not the deployed resources — a management group has no region of its own, and the template decides where its resources go.
• parameters_content values are recorded in the management group's deployment history, readable by anyone with read access to the group. This is the main secret-leakage path for this resource type.
• debug_level is a secret-disclosure control, not a verbosity dial: enabling request or response content writes template inputs and outputs into that same history. debug_level IS a closed provider enum -- StringInSlice over exactly none, requestContent, responseContent and requestContent, responseContent, compared case-sensitively. The space after the comma in the fourth value is part of the string. Spelling none explicitly produces a perpetual diff, because the provider's flatten returns the empty string for it while the attribute is not Computed -- leave it unset to mean none.
• Terraform does not manage what the template creates. Destroying this resource removes the deployment record; the resources the template created are unaffected.
• The template must declare the management-group deployment schema ($schema ending in managementGroupDeploymentTemplate.json#). A resource-group-scoped template is rejected.
• output_content is a pass-through: anything the template emits lands in Terraform state.

• Contributor at the target management group covers the deployment itself (Microsoft.Resources/deployments/*), but the operative constraint is that the identity needs whatever rights the template's own resources require. A template that creates policy definitions needs Microsoft.Authorization/policyDefinitions/write; one that creates management groups needs Microsoft.Management/managementGroups/write.
• To deploy from a template spec, Microsoft.Resources/templateSpecs/versions/read on that version.
• Because a management-group deployment can create subscription- and tenant-level resources, the permission set here is effectively the union of everything the template touches. Grant it at the smallest management group that works, and review the template as you would review a role definition.

• An existing management group, and the caller's identity onboarded to the management-group hierarchy.
• Every resource provider the template uses registered on the subscriptions it targets — a template deployment does not register them for you.
• A template that declares the correct schema for management-group scope.
• For a template spec: the spec and the specific version already published.
• The caller configures the provider "azurerm" { features {} } block, auth, and subscription.

terraform-azurerm-management-group-template-deployment/
├── providers.tf   # required_version >= 1.12.0; azurerm ~> 4.0; no provider block
├── variables.tf   # template-source exclusive-or validation + tags/timeouts tail
├── main.tf        # keystone azurerm_management_group_template_deployment.this; dynamic timeouts
├── outputs.tf     # id, name, management_group_id, location, output_content
├── README.md      # this document
├── SCOPE.md       # cross-module contract
├── LICENSE        # MIT
└── .gitignore     # canonical library ignore set

provider "azurerm" {
  features {}
}

module "mg_deployment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"

  name                = "enable-defender-plans-2026-08"
  management_group_id = "/providers/Microsoft.Management/managementGroups/mg-platform"
  location            = "eastus2"

  template_content = file("${path.module}/templates/defender-plans.json")

  parameters_content = jsonencode({
    pricingTier = { value = "Standard" }
  })

  tags = { environment = "prod", owner = "platform-governance" }
}

ℹ️ The caller owns the provider, its authentication, and the mandatory features {} block. This module never declares them.

Consumes

Emits

module "mg_deployment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"

  name                = "baseline-arm-2026-08"
  management_group_id = var.management_group_id
  location            = "eastus2"

  template_content = file("${path.module}/templates/baseline.json")
}

template_spec_version_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-governance/providers/Microsoft.Resources/templateSpecs/mg-baseline/versions/1.2.0"

# ❌ Neither source set — fails at plan, not at apply.
module "bad" {
  source              = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"
  name                = "no-template"
  management_group_id = var.management_group_id
  location            = "eastus2"
}

Error: Invalid value for variable

  Exactly one of template_content or template_spec_version_id must be set. This check
  is placed on template_content because a validation may only reference its own
  variable, so it names template_spec_version_id even when you were editing this one.
  The provider declares the same pairing with ExactlyOneOf and would reject it too,
  one step later.

template_content = jsonencode({
  "$schema"      = "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#"
  contentVersion = "1.0.0.0"
  parameters     = {}
  resources      = []
})

parameters_content = jsonencode({
  pricingTier    = { value = "Standard" }
  allowedRegions = { value = ["eastus", "eastus2"] }
})

parameters_content = jsonencode({
  adminPassword = {
    reference = {
      keyVault = { id = var.key_vault_id }
      secretName = "arm-deployment-admin"
    }
  }
})

locals {
  arm_outputs = jsondecode(module.mg_deployment.output_content)
}

output "created_definition_id" {
  value = local.arm_outputs.policyDefinitionId.value
}

# Diagnosing a specific failure, on a deployment carrying no sensitive values.
debug_level = "requestContent, responseContent" # the space is part of the value

module "tenant_construct" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"

  name                = "tenant-only-feature-2026-08"
  management_group_id = var.tenant_root_management_group_id
  location            = "eastus2"

  template_content = file("${path.module}/templates/tenant-feature.json")
}

timeouts = {
  create = "1h"
  read   = "10m"
  update = "1h"
  delete = "1h"
}

name = "policy-baseline-2026-08" # date- or ticket-stamped, so history is legible

tags = {
  environment = "prod"
  owner       = "platform-governance"
  ticket      = "GOV-1503"
}

locals {
  arm_deployments = {
    defender = { template = "defender-plans.json", params = { pricingTier = { value = "Standard" } } }
    diagnostics = { template = "diagnostics-policy.json", params = {} }
  }
}

module "arm" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"
  for_each = local.arm_deployments

  name                = "${each.key}-2026-08"
  management_group_id  = var.management_group_id
  location            = "eastus2"
  template_content    = file("${path.module}/templates/${each.value.template}")
  parameters_content  = jsonencode(each.value.params)
}

# terraform destroy removes the deployment RECORD.
# The policy definitions, management groups, or role definitions the template
# created are unaffected — Terraform never tracked them.

provider "azurerm" {
  features {}
}

# 1 · The management group everything is scoped to.
module "platform_mg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group.git?ref=v1.0.0"

  display_name = "Platform"
  name         = "mg-platform"
}

# 2 · A Key Vault holding any secret the template needs, resolved by ARM at deploy time.
module "governance_vault" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault.git?ref=v1.0.0"

  name                = "kv-governance-eastus2"
  resource_group_name = var.governance_resource_group_name
  location            = "eastus2"
  tenant_id           = var.tenant_id
}

# 3 · The ARM-only construct — this module.
module "arm_bridge" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-management-group-template-deployment.git?ref=v1.0.0"

  name                = "arm-only-feature-2026-08"
  management_group_id = module.platform_mg.id
  location            = "eastus2"

  template_content = file("${path.module}/templates/arm-only-feature.json")

  # Secrets stay out of Terraform: ARM resolves the reference at deployment time.
  parameters_content = jsonencode({
    allowedRegions = { value = ["eastus", "eastus2"] }
    sharedSecret = {
      reference = {
        keyVault   = { id = module.governance_vault.id }
        secretName = "arm-shared-secret"
      }
    }
  })

  # Left null deliberately — enabling it would write parameter values into deployment history.
  debug_level = null

  timeouts = { create = "1h", update = "1h" }

  tags = { environment = "prod", owner = "platform-governance", ticket = "GOV-1503" }
}

# 4 · Anything with a typed resource uses the typed module instead of the template.
module "cost_center_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-policy-definition.git?ref=v1.0.0"

  name                = "require-cost-center-tag"
  display_name        = "Require a costCenter tag"
  policy_type         = "Custom"
  mode                = "Indexed"
  management_group_id = module.platform_mg.id
}

# 5 · Consume an ID the template produced.
locals {
  arm_outputs = jsondecode(module.arm_bridge.output_content)
}

Required: name, management_group_id, location.

Template source (exactly one, enforced at plan): template_content, template_spec_version_id.

Template inputs: parameters_content.

Diagnostics (secret-disclosure control): debug_level.

Universal tail: tags, timeouts.

variable "name"                { type = string }
variable "management_group_id" { type = string }
variable "location"            { type = string } # deployment metadata region only

variable "template_content" {
  type    = string # JSON; mutually exclusive with template_spec_version_id
  default = null
  # validation: exactly one of template_content / template_spec_version_id
}

variable "template_spec_version_id" {
  type    = string # preferred for anything reused
  default = null
}

variable "parameters_content" {
  type    = string # JSON; recorded in deployment history — no secrets
  default = null
}

variable "debug_level" {
  type    = string # null = no debug logging; values defined by the ARM API, not a provider enum
  default = null
}

variable "tags" { type = map(string), default = {} }

variable "timeouts" {
  type    = object({ create = optional(string), read = optional(string), update = optional(string), delete = optional(string) })
  default = null
}

No secret is accepted as a dedicated input and none is emitted deliberately. output_content reflects whatever the template chose to emit; treat it as untrusted with respect to secrets and do not have templates emit them.

• This is a bridge, not an escape hatch. Anything with a first-class azurerm_* resource belongs in its own module, where it can be reviewed as typed configuration and where the type system catches a malformed input at parse time. A template is an opaque JSON payload to Terraform: the plan shows a string, so the review has to happen on the template itself.
• Terraform does not manage what the template creates. State holds a deployment record, not an inventory. Destroying this resource removes the record; the resources the template created persist. That asymmetry is the strongest argument for keeping the template's surface small.
• The exclusive-or is enforced twice, deliberately. The provider's ExactlyOneOf already rejects zero or two at plan, so this is not a gap the module closes -- it is a better error message for a guarantee that already exists. The check lives on template_content and reads template_spec_version_id one-directionally, because Terraform rejects validations that reference each other; a matching check on the other variable would create a cycle.
• Deployment history is the leakage path. parameters_content values are recorded there, and debug_level extends that to the template's full request and response content. Anyone with read access to the management group can read both. The safe pattern for a secret is an ARM Key Vault parameter reference, resolved by ARM at deployment time so the value never enters Terraform.
• debug_level is a closed provider enum, and the module mirrors it. debug_level IS a closed provider enum -- StringInSlice over exactly none, requestContent, responseContent and requestContent, responseContent, compared case-sensitively. The space after the comma in the fourth value is part of the string. Spelling none explicitly produces a perpetual diff, because the provider's flatten returns the empty string for it while the attribute is not Computed -- leave it unset to mean none.
• location is metadata, not placement. A management group has no region. This field is where the deployment record lives; the template decides where its resources go.
• Scope reaches further than it looks. A management-group deployment can create subscription- and tenant-level resources, so the effective permission set is the union of everything the template touches.
• features {} dependence. The module carries no provider {} block. If it appears not to initialize in isolation, the cause is a missing caller-side provider "azurerm" { features {} }.

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

• Pin the module with ?ref=v1.0.0 — never a branch.
• This library is plan-only during authoring; a human runs terraform plan / apply from CI against real credentials. For this module the plan shows a JSON string rather than resources, so review the template alongside it.

• terraform validate proves the configuration is internally consistent and type-correct against the pinned provider schema, and exercises the template-source exclusive-or.
• terraform fmt -check enforces canonical formatting.
• Neither command validates the template itself. Whether the ARM JSON is well-formed, declares the right deployment schema, and passes ARM's own validation are apply-time facts -- as is whether the identity holds the rights the template's resources require. terraform plan does not pre-flight the template at all: the provider's template-validation call is made only from Create and Update, and there is no CustomizeDiff on this resource, so plan reaches ARM for the refresh and nothing more.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

id                  = "/providers/Microsoft.Management/managementGroups/mg-platform/providers/Microsoft.Resources/deployments/arm-only-feature-2026-08"
name                = "arm-only-feature-2026-08"
management_group_id = "/providers/Microsoft.Management/managementGroups/mg-platform"
location            = "eastus2"
output_content      = "{\"policyDefinitionId\":{\"type\":\"String\",\"value\":\"/providers/Microsoft.Management/managementGroups/mg-platform/providers/Microsoft.Authorization/policyDefinitions/arm-authored-control\"}}"

• azurerm provider — azurerm_management_group_template_deployment
• Management group deployments with ARM templates
• Use Key Vault to pass a secure parameter value
• Azure template specs
• Sibling modules: terraform-azurerm-management-group, terraform-azurerm-subscription-template-deployment and terraform-azurerm-tenant-template-deployment (the narrower and the wider deployment scopes — each needs its own template $schema), terraform-azurerm-policy-definition, terraform-azurerm-management-group-policy-set-definition, terraform-azurerm-key-vault.
• This module's SCOPE.md.

💙 "Infrastructure as Code should be standardized, consistent, and secure."