Archetypes, Overrides and Architecture

Documentation for archetype definitions within the Sovereign Landing Zones Library, including their structure, configuration, and usage patterns.

Overview

The assets on the previous page - policy definitions, policy set definitions, role definitions, and policy assignments - will all be familiar to those working with governance on Azure and use the standard definition and assignment schemas for those resources.

The three constructs covered on this page are specific to the Azure Landing Zone library format, and control how those assets are used by the alz provider and by clients such as the Bicep and Terraform modules for management groups.

Those three constructs are:

Archetypes: Foundational building blocks that group together related policy and policy set definitions, policy assignments, and role definitions.
Archetype overrides: These define new archetypes as a delta from a base archetype definition.
Architecture: Define a management group hierarchy and the array of archetypes

Archetype

The assets in a library don’t do anything unless they are grouped into archetypes and used within an architecture definition.

archetype_definitions/<name>.alz_archetype_definition.json

Archetype Definition schema

Archetype example: nl_root

{
  "name": "nl_root",
  "policy_assignments": [
    "Audit-NL-BIO",
    "Deny-NL-Global"
  ],
  "policy_definitions": [
    "Enforce-KV-Premium"
  ],
  "policy_set_definitions": [
    "Deny-NL-Global",
    "Deny-NL-Confidential"
  ],
  "role_definitions": []
}

The archetype name in the file - nl_root - may be used in an architecture definition.
As with all entities in a library, the name must be unique.
The archetype name usually indicates the intended management group, but this is merely convention.
Definitions - for policy, policy sets and roles - are commonly defined at the root so that they can be used throughout the management group hierarchy.
Each array uses the names for the assets as described on the previous page.

Archetype Overrides

Archetype overrides define a delta against a base archetype, which add significant flexibility. Overrides are not intended for use in centralised libraries - they are more commonly used in local libraries so that end customers can add or remove from archetypes.

archetype_definitions/<name>.alz_archetype_override.json

Archetype Override schema

Override example: corp_custom

This is the default override file created by the accelerator in the local library for the corp archetype.

base_archetype: corp
name: corp_custom
policy_assignments_to_add: []
policy_assignments_to_remove: [
# To remove the private DNS zones policy for private endpoints
  # Deploy-Private-DNS-Zones,
]
policy_definitions_to_add: []
policy_definitions_to_remove: []
policy_set_definitions_to_add: []
policy_set_definitions_to_remove: []
role_definitions_to_add: []
role_definitions_to_remove: []

The base_archetype here is corp and the name is corp_custom.
Remember, all names in a library must be unique per type.
You would use the corp_custom name in the architecture definition.
You can add or remove assets from the baseline.
The example would remove Deploy-Private-DNS-Zones from the corp archetype.

Architecture Definitions

The architecture definitions finally bring everything together, defining the management group hierarchy, the IDs and displayNames, and the array of archetypes to be used at each scope point.

architecture_definitions/<name>.alz_architecture_definition.json

Architecture Definition schema

Architecture example #1: alz

This is the default architecture file used in the main Azure Landing Zone platform library.

flowchart LR subgraph alz[“alz”] alz_box[“alz”] end

{
  "$schema": "https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/architecture_definition.json",
  "name": "alz",
  "management_groups": [
    {
      "archetypes": [
        "root"
      ],
      "display_name": "Azure Landing Zones",
      "exists": false,
      "id": "alz",
      "parent_id": null
    },
    {
      "archetypes": [
        "platform"
      ],
      "display_name": "Platform",
      "exists": false,
      "id": "platform",
      "parent_id": "alz"
    },
    {
      "archetypes": [
        "landing_zones"
      ],
      "display_name": "Landing zones",
      "exists": false,
      "id": "landingzones",
      "parent_id": "alz"
    },
    {
      "archetypes": [
        "corp"
      ],
      "display_name": "Corp",
      "exists": false,
      "id": "corp",
      "parent_id": "landingzones"
    },
    {
      "archetypes": [
        "online"
      ],
      "display_name": "Online",
      "exists": false,
      "id": "online",
      "parent_id": "landingzones"
    },
    {
      "archetypes": [
        "sandbox"
      ],
      "display_name": "Sandbox",
      "exists": false,
      "id": "sandbox",
      "parent_id": "alz"
    },
    {
      "archetypes": [
        "security"
      ],
      "display_name": "Security",
      "exists": false,
      "id": "security",
      "parent_id": "platform"
    },
    {
      "archetypes": [
        "management"
      ],
      "display_name": "Management",
      "exists": false,
      "id": "management",
      "parent_id": "platform"
    },
    {
      "archetypes": [
        "connectivity"
      ],
      "display_name": "Connectivity",
      "exists": false,
      "id": "connectivity",
      "parent_id": "platform"
    },
    {
      "archetypes": [
        "identity"
      ],
      "display_name": "Identity",
      "exists": false,
      "id": "identity",
      "parent_id": "platform"
    },
    {
      "archetypes": [
        "decommissioned"
      ],
      "display_name": "Decommissioned",
      "exists": false,
      "id": "decommissioned",
      "parent_id": "alz"
    }
  ]
}

The architecture name here is alz, must be unique, and is used as the value of the architecture_name in the avm-ptn-alz Terraform module.
There is usually a maximum of one architecture file in a library.

Architecture example #2: alz_custom

This is the architecture file used in the local library.

alz_custom

The architecture name here is alz_custom, so the value of the architecture_name in the avm-ptn-alz Terraform module call would need to be updated.
The management group hierarchy itself is unchanged.
The only difference is the archetype names which reflect the override archetype names, e.g. corp_custom rather than corp.

Architecture example #3: alz_custom + slz

This is the same architecture file in the local library after it has been updated with the additional Sovereign Landing Zone archetypes and management groups.

alz_custom with slz

Note that the update steps do not change the file name or architecture name.
The value of the architecture_name in the avm-ptn-alz Terraform module stays as alz_custom to limit the terraform plan diff.
The management group hierarchy is extended with Public, Confidential Corp, and Confidential Online.
The new archetypes are associated to those new management group scopes.
The root (alz) management group includes both the root_custom and sovereign_root_custom archetypes.

Architecture example #4: nl_slz_custom

This final version includes the is the same architecture file in the local library after it has been updated with the additional Sovereign Landing Zone archetypes and management groups.