[User Guide] Getting Started

Initial considerations

Before getting started with this module, please take note of the following considerations:

1. This module requires a minimum azurerm provider version of 3.19.0.

2. This module requires a minimum Terraform version 1.3.1.

   NOTE: New releases of the module may contain features which require the minimum supported versions to be increased, but changes will be clearly documented in the release notes, user guide, and readme.

3. This module has a single mandatory variable root_parent_id which is used to set the parent ID to use as the root for deployment. All other variables are optional but can be used to customize your deployment.

4. We recommend providing the root_parent_id value needed by the module using one of the following options:

   • Explicitly using an input variable in your root module, with the value specified via command-line using -var 'root_parent_id={{ tenant_id }}' or your preferred method of specifying variables at runtime.

   • Implicitly using the azurerm_client_config data resource in your root module to extract the tenant_id value from the current logged in user context (see our examples).

     NOTE: Using the azurerm_subscription data resource to provide a tenant_id value from the current context for root_parent_id should be avoided. This has been observed to generate a warning that Terraform cannot determine the number of resources to create during the plan stage. Terraform will ask to run terraform apply -target=resource against the azurerm_subscription data resource. This is due to the root_parent_id being used within the module to generate values which are used as keys within the for-each loops for resource creation. To avoid this error, please use one of the recommended methods above.

5. As of version 0.0.8 this module now supports the creation of Role Assignments for any valid Policy Assignment deployed using the module. This feature enumerates the appropriate role(s) needed by the assigned Policy Definition or Policy Set Definition and creates the necessary Role Assignments for the auto-generated Managed Identity at the same scope as the Policy Assignment. This capability provides feature parity with the Azure Portal experience when creating Policy Assignments using the DeployIfNotExists or Modify effects. If the Policy Assignment needs to interact with resources not under the same scope as the Policy Assignment, you will need to create additional Role Assignments at the appropriate scope.

6. In release version 0.1.0 onwards, there are a number of major updates to policies and roles which should be considered before upgrading. Please refer to the upgrade guide for more information.

7. In release version 0.2.0 onwards, there are further updates to policies which should be considered before upgrading. Please refer to the upgrade guide for more information.

8. Release version 0.2.0 also adds new functionality to enable deployment of Management and monitoring resources into the current Subscription context. Please refer to the Deploy Management Resources page on our Wiki for more information about how to use this.

9. The v0.3.0 release focuses mainly on updating the test framework, but also introduces a breaking change which removes the need (and support for) wrapping user-defined parameters in jsonencode(). When upgrading to this release, please ensure to update your code to use native HCL values as documented in the release notes.

10. In release version 0.4.0 onwards, we have added significant new functionality to support deployment of Identity and Connectivity resources directly into the specified Subscriptions. There are also updates to policies which should be considered before upgrading. Please refer to the upgrade guide for more information.

Additional considerations when deploying Landing Zone resources with Terraform

Although you may be considering managing your platform using this module, the Azure landing zone guidance is not prescriptive on how application teams deploy resources inside landing zone subscriptions. To enable application team autonomy, the Azure landing zone guidance recommends that application teams should be free to use their preferred method to deploy resources into their own subscriptions. This could be Bicep, ARM templates, or Terraform, and using this module has no downstream impact on this decision. However, when application teams choose to deploy resources with Terraform, the following additional considerations apply:

1. Deny-Subnet-Without-NSG Policy Assignment

   The reference architecture assigns the this policy to the Landing Zones management group. In the event that a landing zone subscription is managed by Terraform, this policy will prevent Terraform from deploying azurerm_subnet resources due to the way that the Azure Terraform provider interacts with the Azure network resource provider.

   One remediation is to override the policy assignment and change the policy effect from deny to audit.

2. Use of DeployIfNotExists and Modify Policy Effects

   Terraform expects to be authoritative over the resources that it manages. Any changes to the managed properties of Terraform managed resources in Azure will be rectified by Terraform during the next plan/apply cycle.

   The reference architecture uses Azure policy with DeployIfNotExists and modify effects that can modify properties of the Terraform managed resources.

   The combination of DeployIfNotExists/modify policy and Terraform can result in a loop, with resources being continuously remediated by Azure Policy, then reverted by Terraform, then again remediated by Policy.

   Create guidance for landing zone owners so that they understand the effects of these policies and can deploy resources in a compliant manner.

   Notable exceptions to this are DeployIfNotExists policies that do not modify the in-scope resource. For example: Policies that deploy diagnostic settings.

Provisioning instructions

Copy and paste the following 'module' block into your Terraform configuration, insert the required and optional variables needed for your configuration, and run terraform init:

module "caf-enterprise-scale" {
  source  = "Azure/caf-enterprise-scale/azurerm"
  version = "<version>" # change this to your desired version, https://www.terraform.io/language/expressions/version-constraints

  providers = {
    azurerm              = azurerm
    azurerm.connectivity = azurerm
    azurerm.management   = azurerm
  }

  # insert the 1 required variable here
}

For more detailed instructions, follow the next steps listed below or go straight to our Examples.

Next steps

Learn how to use the Module Variables to customize the module configuration.