ALZ Terraform Module

Warning

This module is still in development but is ready for initial testing and feedback via GitHub Issues.

• This repository contains a Terraform module for deploying Azure Landing Zones (ALZs).
• Make sure to review the examples.

Important

Make sure to add .alzlib to your .gitignore file to avoid committing the downloaded ALZ library to your repository.

Features

• Deploy management groups according to the supplied architecture (defaut is ALZ)
• Deploy policy assets (definitions, assignments, and initiatives) according to the supplied architecture ands associated archetyes
• Modify policy assignments:
  • Enforcement mode
  • Identity
  • Non-compliance messages
  • Overrides
  • Parameters
  • Resource selectors
• Create the required role assignments for Azure Policy, including support for the assign permissions metadata tag, just like the Azure Portal
• Deploy custom role definitions

Unknown Values

This module uses the ALZ Terraform provider. This uses a data source which must be read prior to creating the plan. If you pass an unknown (known after apply) value into the module, it will not be able to read the data source until the plan is being applied. This may cause resources to be unnecessarily recreated.

Such unknown values include resource ids. For example, if you are creating a resource and passing the id of the resource group to the module, this will cause the issue.

Instead, use string interpolation to pass the values. For example:

Recommended

This is the recommended way to use this module:

Note

We assume that all variable inputs are literals.

locals {
  foo_resource_id = "/subscriptions/${data.azurerm_client_config.current.subscription_id}/resourceGroups/${var.resource_group_name}/providers/Microsoft.FooResourceProvider/${var.foo_resource_name}"
}

module "example" {
  source = "Azure/terraform-azurerm-avm-ptn-alz/azurerm"

  policy_assignments_to_modify = {
    alzroot = {
      policy_assignments = {
        mypolicy = {
          parameters = {
            parameterName = jsonencode({ value = local.foo_resource_id })
          }
        }
      }
    }
  }
}

Deferred Actions

We are awaiting the results of the upstream Terraform language experiment deferred actions. This may provide a solution to this issue. See the release notes here for more information.

Requirements

The following requirements are needed by this module:

• terraform (~> 1.6)

• alz (~> 0.13)

• azapi (~> 1.14)

• modtm (~> 0.3)

• random (~> 3.6)

• time (~> 0.9)

Resources

The following resources are used by this module:

• azapi_resource.hierarchy_settings (resource)
• azapi_resource.subscription_placement (resource)
• azapi_update_resource.hierarchy_settings (resource)
• modtm_telemetry.telemetry (resource)
• random_uuid.telemetry (resource)
• time_sleep.after_management_groups (resource)
• time_sleep.after_policy_definitions (resource)
• time_sleep.after_policy_set_definitions (resource)
• alz_architecture.this (data source)
• azapi_client_config.hierarchy_settings (data source)
• azapi_client_config.telemetry (data source)
• modtm_module_source.telemetry (data source)

Required Inputs

The following input variables are required:

architecture_name

Description: The name of the architecture to create. This needs to be of the *.alz_architecture_definition.[json|yaml|yml] files.

Type: string

location

Description: The default location for resources in this management group. Used for policy managed identities.

Type: string

parent_resource_id

Description: The resource id of the parent management group. Use the tenant id to create a child of the tenant root group.
The azurerm_client_config/azapi_client_config data sources are able to retrieve the tenant id.

Type: string

Optional Inputs

The following input variables are optional (have default values):

delays

Description: A map of delays to apply to the creation and destruction of resources.
Included to work around some race conditions in Azure.

Type:

object({
    after_management_group = optional(object({
      create  = optional(string, "30s")
      destroy = optional(string, "0s")
    }), {})
    after_policy_definitions = optional(object({
      create  = optional(string, "30s")
      destroy = optional(string, "0s")
    }), {})
    after_policy_set_definitions = optional(object({
      create  = optional(string, "30s")
      destroy = optional(string, "0s")
    }), {})
  })

Default: {}

enable_telemetry

Description: This variable controls whether or not telemetry is enabled for the module.
For more information see https://aka.ms/avm/telemetryinfo.
If it is set to false, then no telemetry will be collected.

Type: bool

Default: true

management_group_hierarchy_settings

Description: Set this value to configure the hierarchy settings. Options are:

• default_management_group_name - (Required) The name of the default management group.
• require_authorization_for_group_creation - (Optional) By default, all Entra security principals can create new management groups. When enabled, security principals must have management group write access to create new management groups. Defaults to true.
• update_existing - (Optional) Update existing hierarchy settings rather than create new. Defaults to false.

Type:

object({
    default_management_group_name            = string
    require_authorization_for_group_creation = optional(bool, true)
    update_existing                          = optional(bool, false)
  })

Default: null

policy_assignments_to_modify

Description: A map of policy assignment objects to modify the ALZ architecture with.
You only need to specify the properties you want to change.

The key is the id of the management group. The value is an object with a single attribute, policy_assignments.
The policy_assignments value is a map of policy assignments to modify.
The key of this map is the assignment name, and the value is an object with optional attributes for modifying the policy assignments.

• enforcement_mode - (Optional) The enforcement mode of the policy assignment. Possible values are Default and DoNotEnforce.
• identity - (Optional) The identity of the policy assignment. Possible values are SystemAssigned and UserAssigned.
• identity_ids - (Optional) A set of ids of the user assigned identities to assign to the policy assignment.
• non_compliance_message - (Optional) A set of non compliance message objects to use for the policy assignment. Each object has the following properties:
  • message - (Required) The non compliance message.
  • policy_definition_reference_id - (Optional) The reference id of the policy definition to use for the non compliance message.
• parameters - (Optional) The parameters to use for the policy assignment. The map key is the parameter name and the value is an JSON object containing a single Value attribute with the values to apply. This to mitigate issues with the Terraform type system. E.g. { defaultName = jsonencode({Value = \"value\"}) }.
• resource_selectors - (Optional) A list of resource selector objects to use for the policy assignment. Each object has the following properties:
  • name - (Required) The name of the resource selector.
  • selectors - (Optional) A list of selector objects to use for the resource selector. Each object has the following properties:
    • kind - (Required) The kind of the selector. Allowed values are: resourceLocation, resourceType, resourceWithoutLocation. resourceWithoutLocation cannot be used in the same resource selector as resourceLocation.
    • in - (Optional) A set of strings to include in the selector.
    • not_in - (Optional) A set of strings to exclude from the selector.
• overrides - (Optional) A list of override objects to use for the policy assignment. Each object has the following properties:
  • kind - (Required) The kind of the override.
  • value - (Required) The value of the override. Supported values are policy effects: https://learn.microsoft.com/azure/governance/policy/concepts/effects.
  • selectors - (Optional) A list of selector objects to use for the override. Each object has the following properties:
    • kind - (Required) The kind of the selector.
    • in - (Optional) A set of strings to include in the selector.
    • not_in - (Optional) A set of strings to exclude from the selector.

Type:

map(object({
    policy_assignments = map(object({
      enforcement_mode = optional(string, null)
      identity         = optional(string, null)
      identity_ids     = optional(list(string), null)
      parameters       = optional(map(string), null)
      non_compliance_messages = optional(set(object({
        message                        = string
        policy_definition_reference_id = optional(string, null)
      })), null)
      resource_selectors = optional(list(object({
        name = string
        selectors = optional(list(object({
          kind   = string
          in     = optional(set(string), null)
          not_in = optional(set(string), null)
        })), [])
      })))
      overrides = optional(list(object({
        kind  = string
        value = string
        selectors = optional(list(object({
          kind   = string
          in     = optional(set(string), null)
          not_in = optional(set(string), null)
        })), [])
      })))
    }))
  }))

Default: {}

policy_default_values

Description: A map of default values to apply to policy assignments. The key is the default name as defined in the library, and the value is an JSON object containing a single value attribute with the values to apply. This to mitigate issues with the Terraform type system. E.g. { defaultName = jsonencode({ value = \"value\"}) }

Type: map(string)

Default: null

subscription_placement

Description: A map of subscriptions to place into management groups. The key is deliberately arbitrary to avoid issues with known after apply values. The value is an object:

• subscription_id - (Required) The id of the subscription to place in the management group.
• management_group_name - (Required) The name of the management group to place the subscription in.

Type:

map(object({
    subscription_id       = string
    management_group_name = string
  }))

Default: {}

timeouts

Description: A map of timeouts to apply to the creation and destruction of resources.

Type:

object({
    management_group = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
    role_definition = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
    policy_definition = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
    policy_set_definition = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
    policy_assignment = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
    policy_role_assignment = optional(object({
      create = optional(string, "10m")
      delete = optional(string, "10m")
      update = optional(string, "10m")
      read   = optional(string, "10m")
      }), {}
    )
  })

Default: {}

Outputs

The following outputs are exported:

management_group_resource_ids

Description: A map of management group names to their resource ids.

policy_assignment_identity_ids

Description: A map of policy assignment names to their identity ids.

policy_assignment_resource_ids

Description: A map of policy assignment names to their resource ids.

policy_definition_resource_ids

Description: A map of policy definition names to their resource ids.

policy_role_assignment_resource_ids

Description: A map of policy role assignments to their resource ids.

policy_set_definition_resource_ids

Description: A map of policy set definition names to their resource ids.

role_definition_resource_ids

Description: A map of role definition names to their resource ids.

Modules

The following Modules are called:

management_groups_level_0

Source: ./modules/azapi_helper

Version:

management_groups_level_1

Source: ./modules/azapi_helper

Version:

management_groups_level_2

Source: ./modules/azapi_helper

Version:

management_groups_level_3

Source: ./modules/azapi_helper

Version:

management_groups_level_4

Source: ./modules/azapi_helper

Version:

management_groups_level_5

Source: ./modules/azapi_helper

Version:

management_groups_level_6

Source: ./modules/azapi_helper

Version:

policy_assignment

Source: ./modules/azapi_helper

Version:

policy_definitions

Source: ./modules/azapi_helper

Version:

policy_role_assignments

Source: ./modules/azapi_helper

Version:

policy_set_definitions

Source: ./modules/azapi_helper

Version:

role_definitions

Source: ./modules/azapi_helper

Version:

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.