☁️ Azure API Management Policy Fragment Terraform Module

Stores one reusable XML policy snippet on an Azure API Management service, for other policies to include by name. Targets hashicorp/azurerm ~> 4.0.

• 🧩 Creates one azurerm_api_management_policy_fragment — a reusable snippet of policy statements.
• 🔗 Emits the exact <include-fragment .../> element to paste, because the reference is hand-written XML that Terraform cannot track.
• 🔁 Explains the perpetual-diff trap: a wrong format loops rather than failing, because it decides how value is read back as well as sent.
• 📥 Warns that an imported fragment always arrives as xml, whatever it was authored as.
• 🔒 States plainly that the snippet is stored and returned in clear — credentials belong in a named value.
• 🏷️ Carries no tags — the resource has none. The universal tail is timeouts only.

💡 Why it matters: a policy fragment's only interface is its name, used as a bare string inside someone else's XML. Terraform creates no dependency, enforces no ordering, and reports nothing when a rename orphans an include. This module makes that link as explicit as it can be made.

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"]
  kv["terraform-azurerm-key-vault"]
  apim["terraform-azurerm-api-management"]
  nv["terraform-azurerm-api-management-named-value"]
  this["terraform-azurerm-api-management-policy-fragment"]
  api["terraform-azurerm-api-management-api"]
  svcpol["terraform-azurerm-api-management-policy"]

  rg -->|"name"| apim
  apim -->|"id"| this
  apim -->|"name"| nv
  kv -->|"secret behind a named value"| nv
  nv -->|"referenced from the fragment as a double-brace token"| this
  this -->|"name, pasted into an include-fragment element"| api
  this -->|"name, pasted into an include-fragment element"| svcpol

  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,kv,nv,api,svcpol 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 that both downstream edges are dashed in practice rather than in Terraform: a policy includes this fragment by writing its name into XML, so nothing in the graph above is an actual resource reference until include_fragment_snippet is interpolated into the consuming document.

flowchart TB
  subgraph inputs["Inputs"]
    ident["name plus api_management_id, both force-new"]
    content["value, the XML snippet"]
    fmt["format, xml or rawxml"]
    desc["description"]
  end

  this["azurerm_api_management_policy_fragment.this"]

  subgraph outputs["Outputs"]
    oid["id, name, include_fragment_snippet"]
    oval["value, format, description"]
    oshape["value_looks_like_a_full_policy_document, references_a_named_value"]
    ofact["the_include_is_a_string_terraform_cannot_see, a_wrong_format_loops_instead_of_failing"]
  end

  ident --> this
  content --> this
  fmt -->|"decides how value is sent AND read back"| this
  desc --> this
  this --> oid
  this --> oval
  this --> oshape
  this --> ofact

  classDef me fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef sib fill:#eef3f8,stroke:#b9c7d6,color:#1b2a3a;
  class this me;
  class ident,content,fmt,desc,oid,oval,oshape,ofact sib;

Resource inventory

Schema notes that bite

• name and api_management_id are force-new, and both inherit that from provider helpers rather than from this resource's own field list. Everything else updates in place.
• format decides how value is read back as well as sent. A mismatch returns a differently-encoded string on every read, so Terraform proposes the same update forever — one that applies successfully and comes straight back.
• An imported fragment always arrives as xml. The provider's import callback sets it unconditionally, because the API only reports a format when one was requested and it is not xml.
• A format change deliberately re-sends value, because the same string means something different under the other format.
• The diff suppression strips all whitespace and unescapes XML entities before comparing. Reformatting produces no plan — and neither does a genuine change in literal whitespace inside a text value, or a change purely in escaping.
• Delete has no not-found tolerance, unlike the sibling azurerm_api_management_policy — wrapped by the terraform-azurerm-api-management-policy module — which does tolerate it. A fragment removed out of band makes terraform destroy fail rather than converge.
• value is validated by nothing. The provider accepts any string, including one that is not XML at all.
• No tags, no location. The universal tail is timeouts only.

• Microsoft.ApiManagement/service/policyFragments/* — write and delete, scoped to the parent API Management service. A custom role at the service is enough; API Management Service Contributor on the service, or Contributor on its resource group, both cover it more broadly than necessary.
• Microsoft.ApiManagement/service/policyFragments/read on the service, for the existence check before creating and for every refresh.

🔒 This resource holds no credential — provided the fragment does not contain one. Reading it returns the fragment's full content, so plan access is content access: anyone who can refresh this resource can read every policy statement in it. That is a reason to reference a named value rather than paste a key into the XML, not a reason to restrict the plan.

• An existing API Management service.
• Any named value the snippet references must already exist on the same service. Nothing validates the reference — a {{missing}} token applies cleanly and fails at request time.
• A policy that includes the fragment, if it is to do anything at all.
• The caller configures provider "azurerm" { features {} }, authentication and subscription.

terraform-azurerm-api-management-policy-fragment/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # deeply-typed inputs; the unambiguous content mistakes rejected at plan time
├── main.tf         # the single keystone resource
├── outputs.tf      # id first, then the include key, the content, and 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 "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 orders and payments API policies."
}

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

⚠️ This creates the snippet and nothing more. Until a policy writes <include-fragment fragment-id="cors-standard" />, nothing runs it.

Consumes

Emits

module "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 "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: orders API, payments API, service-wide inbound."
}

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

  name              = "rate-limit-by-subscription"
  api_management_id = module.apim.id
  format            = "rawxml"
  value             = file("${path.module}/fragments/rate-limit.xml")
}

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

  name              = "backend-auth"
  api_management_id = module.apim.id
  format            = "rawxml"

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

module "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")
}

# The include is a STRING, so build it from the module output rather than
# retyping the name. This also gives Terraform a real dependency edge.
resource "azurerm_api_management_policy" "service" {
  api_management_id = module.apim.id

  xml_content = <<-XML
    <policies>
      <inbound>
        <base />
        ${module.fragment.include_fragment_snippet}
      </inbound>
      <backend><base /></backend>
      <outbound><base /></outbound>
      <on-error><base /></on-error>
    </policies>
  XML
}

locals {
  fragments = {
    cors        = { file = "cors-standard.xml", format = "xml", note = "Standard CORS." }
    rate_limit  = { file = "rate-limit.xml", format = "rawxml", note = "Per-subscription rate limit." }
    correlation = { file = "correlation-id.xml", format = "xml", note = "Propagates a correlation header." }
  }
}

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

  name              = replace(each.key, "_", "-")
  api_management_id = module.apim.id
  value             = file("${path.module}/fragments/${each.value.file}")
  format            = each.value.format
  description       = each.value.note
}

output "fragment_includes" {
  value = { for k, m in module.fragments : k => m.include_fragment_snippet }
}

fragment_includes = {
  "correlation" = "<include-fragment fragment-id=\"correlation-id\" />"
  "cors"        = "<include-fragment fragment-id=\"cors-standard\" />"
  "rate_limit"  = "<include-fragment fragment-id=\"rate-limit\" />"
}

module "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")

  # Import arrives as xml regardless of how the fragment was authored.
  # If it was rawxml, set that AFTER importing and apply the correction.
  format = "xml"
}

terraform import 'module.fragment.azurerm_api_management_policy_fragment.this' \
  "/subscriptions/$SUB/resourceGroups/rg-platform-apim/providers/Microsoft.ApiManagement/service/apim-platform-prod/policyFragments/cors-standard"

output "fragment_format_as_azure_reports_it" {
  value = module.fragment.format
}

output "fragment_content_matches_configuration" {
  value = module.fragment.value_matches_configuration
}

output "fragment_content_fingerprint" {
  value = module.fragment.value_fingerprint
}

module "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")

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

output "fragments_wrapped_as_full_documents" {
  value = [for k, m in module.fragments : k if m.value_looks_like_a_full_policy_document]
}

output "fragments_with_an_xml_prolog" {
  value = [for k, m in module.fragments : k if m.value_declares_an_xml_prolog]
}

output "fragments_not_using_a_named_value" {
  value = [for k, m in module.fragments : k if !m.references_a_named_value]
}

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"
}

# The secret the fragment needs, held as a named value rather than in the XML.
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 "backend_auth_fragment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-api-management-policy-fragment.git?ref=v1.0.0"

  name              = "backend-auth"
  api_management_id = module.apim.id
  format            = "rawxml"
  description       = "Adds the backend auth header from the backend-api-key named value."

  # References {{backend-api-key}}; carries no secret itself.
  value = file("${path.module}/fragments/backend-auth.xml")

  depends_on = [module.backend_key]
}

# The include is a string, so interpolate it to create a real dependency.
resource "azurerm_api_management_policy" "service" {
  api_management_id = module.apim.id

  xml_content = <<-XML
    <policies>
      <inbound>
        <base />
        ${module.backend_auth_fragment.include_fragment_snippet}
      </inbound>
      <backend><base /></backend>
      <outbound><base /></outbound>
      <on-error><base /></on-error>
    </policies>
  XML
}

name              = string   # force-new; 1-80 chars, alphanumeric plus - and _; also the include key
api_management_id = string   # force-new; the SERVICE id, not its name

value       = string                     # required; the XML snippet, validated by nothing at the provider
format      = optional(string, "xml")    # "xml" | "rawxml", lower case
description = optional(string)

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

The fragment's content is emitted, deliberately: it is configuration rather than a credential, Azure returns it on every read, and it is the only drift signal this resource has.

The name is the interface, and Terraform cannot see it being used. A policy includes a fragment by writing <include-fragment fragment-id="NAME" /> into its XML. That is a string, not a reference: no dependency is created, no ordering is enforced, and no plan reports that a rename has orphaned an include. Where the fragment and its consumers share a configuration, interpolating include_fragment_snippet is the one way to turn the string back into a dependency.

A wrong format loops instead of failing. The provider requests the fragment's value from Azure in whatever format is configured, so a mismatch returns a differently-encoded string on every read and Terraform proposes the same update forever — one that applies successfully and comes straight back. The published documentation describes the symptom without naming the cause. Switch the format; do not reformat the value.

Import is lossy in exactly one field. The API only reports a format when one was explicitly requested and it is not xml, so the provider's import callback sets xml unconditionally. A rawxml fragment therefore imports as xml and shows a diff until corrected — an in-place update, during which the provider deliberately re-sends the value.

The diff suppression is generous in both directions. It parses both sides as XML to absorb element ordering, and falls back to a string comparison with every space, tab, newline and indent stripped and XML entities unescaped. Reformatting a fragment file produces no plan, which is convenient. A genuine change in literal whitespace inside a text value, or in escaping alone, is equally invisible — which is not.

Destroy is stricter here than elsewhere in the family. The delete path has no not-found tolerance, so a fragment removed through the portal makes terraform destroy fail rather than converge. terraform state rm is the recovery. Azure may also refuse to delete a fragment a policy still includes; the provider surfaces whatever Azure says and adds no check of its own.

The content is not protected and should not need to be. It is stored on the service in clear and returned on every read, so it lands in state and in every refreshing plan. This module emits it because it is the only drift signal available. The correct response is to keep secrets out of the snippet by referencing a named value.

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.

terraform validate covers the name pattern, the service-ID shape (including an ID that already carries a /policyFragments/ segment), the format enum with its lower-case requirement, and the three content checks — non-empty, contains XML at all, and is not plainly a file path.

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: a fully populated positive fixture is what catches a check that is wrong in the accepting direction, and 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, whether the name collides with an existing fragment, and whether Azure accepts the XML. What nothing reaches, at any stage: whether any policy includes the fragment, whether a referenced named value exists, and whether the format matches how the content is actually written — that last one surfaces as a diff that will not settle.

id                                       = "/subscriptions/.../service/apim-platform-prod/policyFragments/backend-auth"
name                                     = "backend-auth"
include_fragment_snippet                 = "<include-fragment fragment-id=\"backend-auth\" />"
api_management_id                        = "/subscriptions/.../service/apim-platform-prod"
api_management_name                      = "apim-platform-prod"
resource_group_name                      = "rg-platform-apim"
format                                   = "rawxml"
description                              = "Adds the backend auth header from the backend-api-key named value."
value                                    = "<set-header name=\"Authorization\" exists-action=\"override\"><value>{{backend-api-key}}</value></set-header>"
value_looks_like_a_full_policy_document  = false
value_declares_an_xml_prolog             = false
uses_raw_xml_format                      = true
references_a_named_value                 = true
force_new_fields                         = [
  "name",
  "api_management_id",
]
the_include_is_a_string_terraform_cannot_see = true
a_wrong_format_loops_instead_of_failing      = true

• azurerm_api_management_policy_fragment — provider resource reference
• Reuse policy configurations in Azure API Management — what a fragment is and how a policy includes one
• API Management policy reference — the statements a fragment may contain
• Sibling modules: terraform-azurerm-api-management, terraform-azurerm-api-management-policy, terraform-azurerm-api-management-named-value, terraform-azurerm-api-management-api
• This module's SCOPE.md — the cross-module contract, permissions and prerequisites

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