Overview of Libraries

What is in a library?

The Azure Landing Zones library format is a prescribed structure containing JSON and YAML files to provide assets and controls for use by the Terraform alz provider.

The sole purpose it to define the management group structure used to govern environments and associated assets. This is known as the architecture.

The architecture describes the management group names and display names, plus the list of archetypes that are used at that management group scope.

The archetypes are collections of assets that are used at that scope point. Multiple archetypes can be used at any management group. You can also define archetype overrides that define a delta from the base archetype.

The assets are comprised of

• policy definitions
• policy set definitions (also known as policy initiatives)
• policy assignments
• RBAC role definitions

The policy assignments can assign any combination of built-in and custom policy and policy initiatives.

The metadata JSON file defined the library’s name, display name, description, and any dependencies it has on other libraries.

Finally, the optional policy default values file allows the definition of policy assignment values that can be used consistently across multiple policy assignments in the library.

Library structure

Note that there can be multiple of all files. The bottom row are collectively called assets.

File and directory naming

The filename convention for each file type is very specific. The directory structure is not strictly forced, but is highly recommended as a standard. The link on the folder names in the tables below take you to the official documentation page for each asset type.

The last two rows have an asterisk as they are usually located in the root of the library. JSON is supported for all assets. Certain file types also support YAML with either .yaml or .tml extensions.

The contents of the files are based on the public Azure schema definitions for the policy and role files, plus the schemas in the schemas folder for the main Azure Landing ZOne library.

Modularity and extensibility

The system supports multiple library sources and dependency chains, enabling organizations to build upon Microsoft baselines while adding custom requirements.

All library components follow semantic versioning principles, ensuring predictable updates and backward compatibility.

Azure Landing Zone Library

These are your platform libraries. All are found in the platform folder of Azure/Azure-Landing-Zones-Library and are maintained by Microsoft with semantic versioning for the releases.

• Microsoft ALZ Library: Core Azure Landing Zone definitions

  Example release: platform/alz/2025.09.3

  provider "alz" {
    library_references = [
      {
        path = "platform/alz"
        ref  = "2025.09.3"
      }
    ]
  }
  
  No dependencies.
  

• Microsoft SLZ Library: Sovereign Landing Zone extensions

  This is stacked on top of Azure Landing Zone with additional management groups and archetypes for sovereignty scenarios.

  Example release: platform/slz/2025.10.1

  provider "alz" {
    library_references = [
      {
        path = "platform/slz"
        ref  = "2025.10.1"
      }
    ]
  }
  

  The metadata file has a dependency on ALZ.

• Microsoft AMBA Library: Azure Monitoring Baseline Alerts

  Additional platform library with policies relating to Azure Monitoring Baseline Alerts. Can be used standalone or in addition to ALZ/SLZ.

  Example release: platform/amba/2025.11.0

  provider "alz" {
    library_references = [
      {
        path = "platform/amba"
        ref  = "2025.11.0"
      }
    ]
  }
  

  No dependencies.

Local libraries

Local libraries are commonly used, enabling archetype_overrides so that customers can define deltas from the default baselines in the main libraries.

• ./lib: Local override library

  Example override library for ALZ.

  provider "alz" {
    library_references = [
      {
        custom_url = "${path.root}/lib"
      }
    ]
  }
  

  Customer specific assets can also be included if they need bespoke policies or role definitions.

  Example lib/alz_library_metadata.json in a local library, stacked on top the Azure Landing Zone library.

  {
    "$schema": "https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/library_metadata.json",
    "name": "local",
    "display_name": "ALZ Accelerator - Azure Verified Modules for SLZ Platform Landing Zone",
    "description": "This library allows overriding policies, archetypes, and management group architecture in the ALZ Accelerator.",
    "dependencies": [
      {
        "path": "platform/alz",
        "ref": "2025.09.3"
      }
    ]
  }
  

Centralised Custom Libraries

There is no restriction on how custom libraries are used, but here are a few examples for reuse.

• Partner Libraries: Libraries of partner IP fo accelerating customer governance

• Country Packs: Sovereign requirements for specific regions

  nl/bio/2026.01.0: My example country pack for The Netherlands’ BIO compliancy.

  In this example the local metadata file is using both the slz and bio libraries.

  {
    "$schema": "https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/library_metadata.json",
    "name": "local",
    "display_name": "ALZ Accelerator - Azure Verified Modules for SLZ Platform Landing Zone",
    "description": "This library allows overriding policies, archetypes, and management group architecture in the ALZ Accelerator.",
    "dependencies": [
      {
        "path": "platform/slz",
        "ref": "2025.10.1"
      },
      {
        "custom_url": "github.com/richeney-org/Sovereign-Landing-Zone-Packs//country/nl/bio?ref=2026.01.0"
      }
    ]
  }
  

• Industry Packs: Industry-specific governance patterns

References

• https://aka.ms/alz/library
• https://aka.ms/alz/library/site

Next

We’ll look at the example BIO custom library for The Netherlands.