What is a library?

Overview of the Azure Landing Zones Library system.

Introduction

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. Understanding libraries and how they are used is vital when going beyond the defaults for governed Azure environment and when you are looking to override, modify and extend.

The sole purpose of a library is to help define the management group structure - and the associated policies and roles - used to govern environments assets.

The architecture describes the management group names and display names, plus the list of archetypes that are used at that management group scope.
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.
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

--- title: Azure Landing Zone structure --- graph TD M([Metadata]) A([Architecture]) V([Policy Default Values]) A --> AT[Archetype] A --> AO(Archetype Overrides) AO --> AT AT --> PA[Policy Assignments] AT --> PS[Policy Set Definitions] AT --> PD[Policy Definitions] AT --> RD[Role Definitions]

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

Example Libraries

Platform Libraries

These libraries are maintained by Microsoft’s Customer Architecture and Engineering team (CAE) and are hosted in the main Azure Landing Zone library repo and supporting documentation. They are semantically versions with controlled releases, changelogs, and issue tracking.

Azure Landing Zones Library (alz)
Sovereign Landing Zones Library (slz)
Azure Landing Zones Library (amba)

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.

Links

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