Add a local override library

Insert a local override library into your repo to give yourself more flexibility to add or remove definitions and assignments from the standard archetypes in the alz and slz platform libraries.

Creating a local override library

Local libraries are commonly used, enabling archetype_overrides so that customers can define deltas from the default baselines in the main libraries. By convention these local library are stored in the ./lib folder, and contain only archetype override and architecture files. However you could also add customer specific assets if they require bespoke policies or role definitions.

This is the recommended approach even if you are not overriding anything on day one.

Adding in a local override library after you have deployed Azure Landing Zones or Sovereign Landing Zones has a greater impact based on resource names in the Terraform state file.

This way you can easily choose to override the archetypes later. Or you have the option to add in a hosted custom library by either

side loading a hosted custom library by extending the array in the alz provider block
inserting a new dependency in the local library’s metadata dependencies

and then updating the architecture definition.

Creating an ALZ local override library

These commands are designed for Bash on a Linux/macOS system. Ensure that you are in the root of your Azure Landing Zone repo.

tmp=$(mktemp -d)
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
lib_folder_path="templates/platform_landing_zone/lib"
git -C "$tmp" sparse-checkout set --no-cone "$lib_folder_path"
git -C "$tmp" checkout
cp -r "$tmp/$lib_folder_path" .
rm -rf "$tmp"

These commands are designed for PowerShell on a Windows system. Ensure that you are in the root of your Azure Landing Zone repo.

$tmp = Join-Path $env:TEMP (New-Guid)
New-Item -ItemType Directory -Path $tmp
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
$lib = "templates/platform_landing_zone/lib"
git -C $tmp sparse-checkout set --no-cone $lib
git -C $tmp checkout
Copy-Item -Path "$tmp/$lib" -Recurse -Force
Remove-Item -Path $tmp -Recurse -Force

The code blocks creates a local library using similar logic to the documentation for the Azure Landing Zone accelerator, and pulls the example lib folder from the ALZ Accelerator repo.

The process for Sovereign Landing Zone is two-step and follows the official Microsoft documentation:

Create a standard local override library using exactly the same process as you would for the Azure Landing Zone platform library
Then update with additional files (and overwrites) specific to the Sovereign Landing Zone’s additional management groups and archetypes

The update step below warns which files will be overwritten by step two.

First create a standard local override library

These commands are designed for Bash on a Linux/macOS system. Ensure that you are in the root of your Azure Landing Zone repo.

tmp=$(mktemp -d)
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
lib_folder_path="templates/platform_landing_zone/lib"
git -C "$tmp" sparse-checkout set --no-cone "$lib_folder_path"
git -C "$tmp" checkout
cp -r "$tmp/$lib_folder_path" .
rm -rf "$tmp"

These commands are designed for PowerShell on a Windows system. Ensure that you are in the root of your Azure Landing Zone repo.

$tmp = Join-Path $env:TEMP (New-Guid)
New-Item -ItemType Directory -Path $tmp
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
$lib = "templates/platform_landing_zone/lib"
git -C $tmp sparse-checkout set --no-cone $lib
git -C $tmp checkout
Copy-Item -Path "$tmp/$lib" -Recurse -Force
Remove-Item -Path $tmp -Recurse -Force

The code blocks creates a local library using similar logic to the documentation for the Azure Landing Zone accelerator, and pulls the example lib folder from the ALZ Accelerator repo.

Then extend for the Sovereign Landing Zone

As you are using the Sovereign Landing Zone then run these commands to extend the default local library with additional override files for the additional archetypes found in the Sovereign Landing Zone.

⚠️ As well as adding the additional override files, these commands will also overwrite the following files:

lib/alz_library_metadata.json - library dependency on the Sovereign Landing Zone, which has its own dependency on the Azure Landing Zone
lib/architecture_definitions/alz_custom.alz_architecture_definition.yaml - additional archetype overrides

These commands are designed for Bash on a Linux/macOS system. Ensure that you are in the root of your Azure Landing Zone repo.

tmp=$(mktemp -d)
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
lib_folder_path="templates/platform_landing_zone/examples/slz/lib"
git -C "$tmp" sparse-checkout set --no-cone "$lib_folder_path"
git -C "$tmp" checkout
cp -r "$tmp/$lib_folder_path" .
rm -rf "$tmp"

These commands are designed for PowerShell on a Windows system. Ensure that you are in the root of your Azure Landing Zone repo.

$tmp = Join-Path $env:TEMP (New-Guid)
New-Item -ItemType Directory -Path $tmp
git clone -n --depth=1 --filter=tree:0 "https://github.com/Azure/alz-terraform-accelerator" "$tmp"
$lib = "templates/platform_landing_zone/examples/slz/lib"
git -C $tmp sparse-checkout set --no-cone $lib
git -C $tmp checkout
Copy-Item -Path "$tmp/$lib" -Recurse -Force
Remove-Item -Path $tmp -Recurse -Force

These code blocks are fundamentally the same as the ones used to initialise the local library, but extend it using the slz lib add on folder from the same ALZ Accelerator repo.

Note that the alz_architecture_definition.yaml architecture file’s architecture name (and file prefix) is unchanged and uses alz_custom rather than slz_custom.

The reason for this approach is that the Sovereign Landing Zone scenario is designed to gracefully handle brownfield scenarios, uplifting existing Azure Landing Zone deployments to include the additional Sovereignty Landing Zone assets.

Metadata dependencies

The dependencies in the local library’s metadata file are now an additional control point for you.

Note that the local metadata library is stacked on top the Azure Landing Zone library, and specifies the release version.

{
  "$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 ALZ Platform Landing Zone",
  "description": "This library allows overriding policies, archetypes, and management group architecture in the ALZ Accelerator.",
  "dependencies": [
    {
      "path": "platform/alz",
      "ref": "2026.01.0"
    }
  ]
}

Note that it is stacked on top the Sovereign Landing Zone library, and specifies the release version.

{
  "$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": "2026.01.0"
    }
  ]
}

The Sovereign Landing Zone platform library is itself stacked on top of the Azure Landing Zone.

Overrides

Check the custom library section for an overview of the library format and standard files including the archetype override files and architecture files found in your local override library.

Update your Terraform config

You now need to make a few changes to repoint your Terraform config to use the local override library.

Configure the alz provider block

Update the library reference in the provider block to use a custom_url to the local ./lib folder.

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

Module block

View the management groups module in main.tf.

This is the module with source = "Azure/avm-ptn-alz/azurerm".

Update the architecture name

Update to `architecture_name = “alz_custom” to match the name in your local override libraries
```
module "management_groups" {
  source  = "Azure/avm-ptn-alz/azurerm"
  version = "0.20.2"

  architecture_name  = "alz_custom"
```
The rest of the block is killed here to keep it short.
Check the remaining arguments and values

For example, policy_default_values and policy_assignments_to_modify objects.

OK, the local override library is in place. Note that the ALZ Accelerator will automate much of this process, although the Sovereign Landing Zone update to the local library is still a manual step. The local override library is very useful and flexible.

In addition to the standard archetype overrides, it also allows a local space to create

custom policy and policy set definitions
custom role definitions
custom assignments
new archetypes
updated architectures to include the new archetypes
new default values

See the Custom Library series for creating and testing assets in custom libraries.

An override library is not necessarily designed for these, but there is technically nothing stopping for using it that way. Or you could have a second local library and include that as a second library in the alz provider library_reference array if you wanted to keep the archetype overrides separate from your custom definitions.

This would be a valid approach for a single repo and its landing zone deployment, but look at hosted custom libraries if reuse is important.

In the next page you will locally test the repo to give yourself the best chance of passing the CI workflow.

Add a local override library

Table of Contents

Creating a local override library

Creating an ALZ local override library

First create a standard local override library

Then extend for the Sovereign Landing Zone

Metadata dependencies

Overrides

Update your Terraform config

Configure the alz provider block

Module block

Next