☁️ Azure API Management Policy Terraform Module

Owns the global policy of an Azure API Management service — the document that applies to every API, at the broadest of the five policy scopes. Targets hashicorp/azurerm ~> 4.0.

• 🌐 Owns the global policy of an API Management service — one document, applying to every API.
• 🧨 States the behaviour no other module in this family has: creating it overwrites whatever global policy already existed, with no warning at plan or apply.
• 🆔 Corrects a reasonable assumption: this resource's Resource ID is the service's own ID, byte for byte.
• 🚪 Surfaces the bypass — a narrower policy that drops <base /> silently opts out of everything here — and names the Azure Policy definition that can enforce it.
• 🔗 Explains that xml_link is fetched once and never read back, so it is not a live link.
• 🔒 Emits no policy content — only a fingerprint, a length and a match flag.
• 🏷️ Carries no tags — the resource has none. The universal tail is timeouts only.

💡 Why it matters: a global policy is where organisations put the controls they most want to be universal — authentication, logging, rate limiting, IP filtering. Two things undermine that: the first apply replaces whatever was already there, and any API team can step out of it by deleting one element. Neither is visible in a plan, so both are stated here as outputs.

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 TB
  rg["terraform-azurerm-resource-group"]
  apim["terraform-azurerm-api-management"]
  nv["terraform-azurerm-api-management-named-value"]
  frag["terraform-azurerm-api-management-policy-fragment"]
  cache["terraform-azurerm-api-management-redis-cache"]
  this["terraform-azurerm-api-management-policy"]
  api["terraform-azurerm-api-management-api"]
  pa["terraform-azurerm-subscription-policy-assignment"]

  rg -->|"name"| apim
  apim -->|"id, which is also this record's own id"| this
  nv -->|"referenced as a double-brace token"| this
  frag -->|"name, pasted into an include-fragment element"| this
  cache -->|"makes an external cache available to a cache-store element"| this
  this -->|"applies to every API, unless one drops the base element"| api
  api -->|"an API policy without base bypasses this one entirely"| this
  pa -->|"audits or denies a missing base element"| api

  classDef me fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef keystone fill:#004578,stroke:#002b4d,color:#ffffff;
  classDef sib fill:#eef3f8,stroke:#b9c7d6,color:#1b2a3a;
  class this me;
  class apim keystone;
  class rg,nv,frag,cache,api,pa sib;

The API Management family is large, so this diagram names only this module's direct neighbours rather than every api-management-* module in the library. Note the edge running back from the API module: an API-scoped policy that omits <base /> bypasses this document entirely, which makes the relationship bidirectional in effect even though only one direction is a Terraform reference. The policy-assignment edge is the only mechanism that turns this global policy into a floor rather than a default.

flowchart TB
  subgraph inputs["Inputs"]
    svc["api_management_id, the only force-new field"]
    content["xml_content, the document inline"]
    link["xml_link, fetched once by Azure"]
  end

  this["azurerm_api_management_policy.this"]
  prop["the service's global policy, one per service"]

  subgraph outputs["Outputs"]
    oid["id, which IS the service id"]
    ofp["policy_fingerprint, policy_length_in_characters, policy_matches_configuration"]
    oshape["has_policies_root, contains_an_inert_base_element, declares_forward_request_in_backend"]
    ofact["creating_this_overwrites_any_existing_global_policy, a_narrower_policy_without_base_bypasses_this_one"]
  end

  svc --> this
  content -->|"exactly one of the two"| this
  link -->|"exactly one of the two"| this
  this -->|"replaces whatever was there"| prop
  this --> oid
  this --> ofp
  this --> oshape
  this --> ofact

  classDef me fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef keystone fill:#004578,stroke:#002b4d,color:#ffffff;
  classDef sib fill:#eef3f8,stroke:#b9c7d6,color:#1b2a3a;
  class this me;
  class prop keystone;
  class svc,content,link,oid,ofp,oshape,ofact sib;

Resource inventory

Schema notes that bite

• No import-exists check, by design. Every other resource in this family refuses to adopt an existing object; this one replaces it. The provider's own source comment explains why: the API always returns a policy, so "unset" and "set by someone else" are indistinguishable.
• The Resource ID is the service's Resource ID. id and api_management_id are the same string.
• api_management_id is the only force-new field. Both document fields update in place.
• xml_content and xml_link are ExactlyOneOf and ConflictsWith; the create function additionally errors with either `xml_content` or `xml_link` must be set at apply when neither is given.
• xml_link is never read back. Azure downloads the document and stores its content; xml_content is Optional and Computed, so it fills with whatever was downloaded.
• Switching from xml_link to xml_content clears the link inside the update function, with a d.Set("xml_link", "") on a non-new resource.
• The diff suppression strips all whitespace and unescapes the five XML entities before comparing — so reformatting and re-escaping are both invisible.
• Read applies HTML unescaping, which is wider than XML's five entities.
• SchemaVersion is 3, with three state upgraders for state written by older provider versions.
• No tags, no location. The universal tail is timeouts only.

• Microsoft.ApiManagement/service/policies/* — write and delete, scoped to the parent API Management service. API Management Service Contributor on the service is the smallest built-in role that covers it; Contributor on the resource group covers it more broadly than necessary.
• Microsoft.ApiManagement/service/read on the service, which the read path uses before fetching the policy.

🔒 Plan access is policy-content access. Refreshing this resource returns the whole global policy document, which routinely carries backend URLs and named-value references. That is a reason to keep credentials out of the document — reference a named value — rather than a reason to restrict the plan.

• An existing API Management service.
• Knowledge of the service's current global policy. Creating this resource replaces it without warning, so a service managed by hand or by another pipeline must have its policy exported and reconciled into the configuration first.
• Any named value or policy fragment the document references must already exist on the same service. Nothing validates either — a missing one fails at request time.
• For xml_link, a URL Azure can reach anonymously.
• The caller configures provider "azurerm" { features {} }, authentication and subscription.

terraform-azurerm-api-management-policy/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # deeply-typed inputs; the unambiguous document mistakes rejected at plan time
├── main.tf         # the single keystone resource
├── outputs.tf      # id first (with its caveat), then the fingerprint, then the silent behaviours
├── README.md       # this document
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore      # the canonical library ignore set

provider "azurerm" {
  features {}
}

module "apim_global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id
  xml_content       = file("${path.module}/policies/global.xml")
}

ℹ️ The caller configures the provider, including the mandatory features {} block. This module declares none.

⚠️ This replaces the service's existing global policy on the first apply. Export the current one first if the service was not created by this configuration.

Consumes

Emits

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id
  xml_content       = file("${path.module}/policies/global.xml")
}

<policies>
  <inbound>
    <ip-filter action="allow">
      <address-range from="10.0.0.0" to="10.255.255.255" />
    </ip-filter>
  </inbound>
  <backend>
    <forward-request />
  </backend>
  <outbound />
  <on-error />
</policies>

module "cors_fragment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy-fragment.git?ref=v1.0.0"

  name              = "cors-standard"
  api_management_id = module.apim.id
  value             = file("${path.module}/fragments/cors-standard.xml")
}

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id

  xml_content = <<-XML
    <policies>
      <inbound>
        ${module.cors_fragment.include_fragment_snippet}
      </inbound>
      <backend><forward-request /></backend>
      <outbound />
      <on-error />
    </policies>
  XML
}

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id

  # The XML references {{backend-api-key}} rather than carrying the key.
  xml_content = file("${path.module}/policies/global.xml")

  depends_on = [module.backend_key]
}

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id
  xml_link          = "https://policies.contoso.com/apim/global.xml"
}

# Export the current global policy BEFORE the first apply. This resource has no
# import-exists check: applying without this step replaces it silently.
az apim api policy show --resource-group rg-platform-apim \
  --service-name apim-platform-prod --api-id '*' 2>/dev/null

terraform import 'module.global_policy.azurerm_api_management_policy.this' \
  "/subscriptions/$SUB/resourceGroups/rg-platform-apim/providers/Microsoft.ApiManagement/service/apim-platform-prod"

output "global_policy_matches_terraform" {
  value = module.global_policy.policy_matches_configuration
}

output "global_policy_fingerprint" {
  value = module.global_policy.policy_fingerprint
}

output "policy_fingerprints_by_environment" {
  value = { for k, m in module.global_policies : k => m.policy_fingerprint }
}

policy_fingerprints_by_environment = {
  "dev"  = "b1e4...c92a"
  "prod" = "b1e4...c92a"
  "uat"  = "7f30...11de"   # <- UAT has drifted
}

output "policies_missing_a_policies_root" {
  value = [for k, m in module.global_policies : k if m.has_policies_root == false]
}

output "policies_with_an_inert_base_element" {
  value = [for k, m in module.global_policies : k if m.contains_an_inert_base_element == true]
}

output "policies_not_forwarding_requests" {
  value = [for k, m in module.global_policies : k if m.declares_forward_request_in_backend == false]
}

module "enforce_base_element" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-subscription-policy-assignment.git?ref=v1.0.0"

  name                 = "apim-policies-must-inherit-base"
  subscription_id      = data.azurerm_subscription.current.id
  policy_definition_id = "/providers/Microsoft.Authorization/policyDefinitions/d5448c98-e503-4fdd-bcd2-784960c00d04"
  display_name         = "API Management policies should inherit parent scope policies using <base />"
}

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id
  xml_content       = file("${path.module}/policies/global.xml")

  timeouts = {
    create = "45m"
    read   = "10m"
    update = "45m"
    delete = "45m"
  }
}

variable "api_management_ids" {
  description = "Service Resource IDs, keyed by environment."
  type        = map(string)
}

module "global_policies" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"
  for_each = var.api_management_ids

  api_management_id = each.value
  xml_content       = file("${path.module}/policies/global.xml")
}

provider "azurerm" {
  features {}
}

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

  name     = "rg-platform-apim"
  location = "eastus2"
}

module "apim" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management.git?ref=v1.0.0"

  name                = "apim-platform-prod"
  resource_group_name = module.rg.name
  location            = module.rg.location
  publisher_name      = "Platform Engineering"
  publisher_email     = "platform-engineering@example.com"
  sku_name            = "Developer_1"
}

module "backend_key" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-named-value.git?ref=v1.0.0"

  name                = "backend-api-key"
  resource_group_name = module.rg.name
  api_management_name = module.apim.name
  display_name        = "backend-api-key"
  secret              = true
  value               = var.backend_api_key
}

module "cors_fragment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy-fragment.git?ref=v1.0.0"

  name              = "cors-standard"
  api_management_id = module.apim.id
  value             = file("${path.module}/fragments/cors-standard.xml")
  description       = "Standard CORS. Included by the global policy."
}

module "global_policy" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy.git?ref=v1.0.0"

  api_management_id = module.apim.id

  xml_content = <<-XML
    <policies>
      <inbound>
        ${module.cors_fragment.include_fragment_snippet}
        <set-header name="X-Backend-Key" exists-action="override">
          <value>{{backend-api-key}}</value>
        </set-header>
      </inbound>
      <backend><forward-request /></backend>
      <outbound />
      <on-error />
    </policies>
  XML

  depends_on = [module.backend_key]
}

# Without this, any API can step out of the global policy by deleting <base />.
module "enforce_base_element" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-subscription-policy-assignment.git?ref=v1.0.0"

  name                 = "apim-policies-must-inherit-base"
  subscription_id      = data.azurerm_subscription.current.id
  policy_definition_id = "/providers/Microsoft.Authorization/policyDefinitions/d5448c98-e503-4fdd-bcd2-784960c00d04"
  display_name         = "API Management policies should inherit parent scope policies using <base />"
}

api_management_id = string   # force-new; the SERVICE id -- and also this resource's own id

# Exactly one of the two. Neither is force-new.
xml_content = optional(string)   # the full <policies> document, inline
xml_link    = optional(string)   # a publicly reachable URL; fetched once, never read back

timeouts = optional(object({ create, read, update, delete }))

No policy content is emitted — only a fingerprint, a length and a match flag. This follows the convention the api-management-api-operation module already sets for policy XML.

The first apply is the dangerous one. Every other resource in this family refuses to adopt an existing object and tells you to import it. This one replaces it, and the provider's own source comment explains that it has no choice: the API always returns a policy — a default one when nobody has set one — so "unset" and "set by someone else" are indistinguishable. Export the current global policy before adopting a service you did not create.

The Resource ID is not an identifier for this record. It is the API Management service's ID, byte for byte, because there is one global policy per service and it has no identity of its own. Using it as a policy identifier, or as a lock scope intended for the policy, silently addresses the whole service.

A global policy is a default, not a floor. Microsoft: "If you remove the base element at the API scope, only policies configured at the API scope will be applied. Policies configured at product and broader scopes won't be applied." So an API team can step out of global authentication, logging and rate limiting by deleting one element — no failure, no warning, and nothing here reporting which scopes have done so. The built-in Azure Policy definition that audits or denies a missing <base /> is the only mechanism that closes it.

<base /> in this document is inert. Microsoft again: "A globally scoped policy has no parent scope, and using the base element in it has no effect." Harmless, and worth surfacing, because its presence suggests inheritance that is not happening.

A linked document is fetched once. Azure downloads it at apply time and stores the content; the link is never read back, and no plan depends on the file's contents. Drift between the URL and the service is invisible in both directions, which makes xml_link a poor fit for anything that changes.

The diff suppression is generous in both directions. It parses both sides as XML, then falls back to a string comparison with all whitespace stripped and the five XML entities unescaped. Reformatting produces no plan, which is convenient. A change purely in escaping, or in literal whitespace inside a value, is equally invisible — which is not.

The content stays out of the outputs. Policy documents carry backend URLs, subscription keys and authorization headers. This module emits a fingerprint, a length and a match flag, which support every comparison a consumer needs without copying the document into another configuration's state.

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

Pin the module by immutable tag — ?ref=v1.0.0 — never a branch. This module is plan-only from the library's point of view: a human applies from CI against a reviewed plan. Treat the first apply against an existing service as a control change, not a bookkeeping one.

terraform validate covers the service-ID shape (including an ID that addresses a narrower scope), the exactly-one-of rule, and the document checks — non-empty, contains XML, is not plainly a file path — plus the link checks: it must be an http/https URL, and must not be a policy document pasted into the wrong field.

A variables-only terraform plan fires the same validations against a .tfvars file and is also the cheapest way to confirm the derived flags. Drive both directions, and note the third case this resource needs: an xml_link fixture, where every content-derived output must read null rather than false. Terraform skips a validation whose referenced variable has already failed, so a short error list is not proof a check is missing.

What only a real plan or apply reaches: whether the service exists, and whether Azure accepts the XML. What nothing reaches, at any stage: what the service's global policy was before this configuration replaced it, whether any narrower scope has dropped <base />, and whether a referenced named value or fragment exists.

id                                                  = "/subscriptions/.../providers/Microsoft.ApiManagement/service/apim-platform-prod"
api_management_id                                   = "/subscriptions/.../providers/Microsoft.ApiManagement/service/apim-platform-prod"
api_management_name                                 = "apim-platform-prod"
resource_group_name                                 = "rg-platform-apim"
policy_source                                       = "xml_content"
policy_fingerprint                                  = "b1e4c0a97f2d5e8143aa6c0b7e91d2f4c3358a10bb47e6d9f0c2a5b83e71d94c"
policy_length_in_characters                         = 412
policy_matches_configuration                        = true
xml_link                                            = null
xml_link_uses_plaintext_http                        = false
has_policies_root                                   = true
contains_an_inert_base_element                      = false
declares_forward_request_in_backend                 = true
references_a_named_value                            = true
force_new_fields                                    = [
  "api_management_id",
]
creating_this_overwrites_any_existing_global_policy = true
id_is_the_api_management_service_id                 = true
a_narrower_policy_without_base_bypasses_this_one    = true

• azurerm_api_management_policy — provider resource reference
• Policies in Azure API Management — the five scopes and how they combine
• How to set or edit Azure API Management policies — the base element and policy evaluation order
• Azure Policy built-in definitions for API Management — including the definition that enforces <base />
• Sibling modules: terraform-azurerm-api-management, terraform-azurerm-api-management-policy-fragment, terraform-azurerm-api-management-named-value, terraform-azurerm-api-management-api, terraform-azurerm-subscription-policy-assignment
• This module's SCOPE.md — the cross-module contract, permissions and prerequisites

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