diff --git a/.github/workflows/wiki-sync.yml b/.github/workflows/wiki-sync.yml new file mode 100644 index 000000000..62388bd98 --- /dev/null +++ b/.github/workflows/wiki-sync.yml @@ -0,0 +1,53 @@ +name: Docs/Wiki Sync + +on: + push: + branches: + - main + paths: + - "docs/wiki/**" + +env: + wiki_source_repo: "Azure/terraform-azurerm-caf-enterprise-scale" + wiki_source_repo_dir: "Azure/terraform-azurerm-caf-enterprise-scale/docs/wiki" + wiki_target_repo: "Azure/terraform-azurerm-caf-enterprise-scale.wiki" + github_user_name: "github-actions" + github_email: "github-actions@github.com" + github_commit_message: "GitHub Action syncing wiki from docs/wiki" + +jobs: + sync-wiki: + name: Sync Wiki + if: github.repository == 'Azure/terraform-azurerm-caf-enterprise-scale' + runs-on: ubuntu-latest + steps: + - name: Checkout Source Repo + uses: actions/checkout@v2 + with: + repository: ${{ env.wiki_source_repo }} + path: ${{ env.wiki_source_repo }} + + - name: Checkout Wiki Repo + uses: actions/checkout@v2 + with: + repository: ${{ env.wiki_target_repo }} + path: ${{ env.wiki_target_repo }} + + - name: Configure Local Git + run: | + git config --global user.name $github_user_name + git config --global user.email $github_email + working-directory: ${{ env.GITHUB_WORKSPACE }} + + - name: Sync docs/wiki Into Wiki Repo + run: | + rsync -avzr --delete --exclude='.git/' "$wiki_source_repo_dir/" "$wiki_target_repo" + working-directory: ${{ env.GITHUB_WORKSPACE }} + + - name: Stage & Push Files Into Wiki Repo + run: | + git add . + git commit -m "$github_commit_message [$GITHUB_ACTOR/${GITHUB_SHA::8}]" + git push --set-upstream https://$GITHUB_TOKEN@github.com/$wiki_target_repo.git master + working-directory: ${{ env.wiki_target_repo }} + diff --git a/docs/wiki/Contributing-to-Code.md b/docs/wiki/Contributing-to-Code.md new file mode 100644 index 000000000..84221a049 --- /dev/null +++ b/docs/wiki/Contributing-to-Code.md @@ -0,0 +1,19 @@ +Please ensure you have read our [Contributing](./Contributing) page before going any further. + +## Checklist + +- Fixes a bug or feature reported and accepted in our [Issues][Issues] log +- New features should be relevant to, and improve upon, existing core functionality +- PR contains updated [Unit Tests][Unit-Tests] where appropriate +- PR contains updated [E2E Tests][E2E-Tests] where appropriate +- PR contains documentation update +- PR is able to pass all [Unit Tests][Unit-Tests] and [E2E Tests][E2E-Tests] +- PR is rebased against the latest `main` branch +- PR is squashed into one commit per logical change +- PR commit message should be concise but descriptive (will be used to generate release notes) + + + +[Issues]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/issues "Our issues log" +[Unit-Tests]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/blob/main/tests/pipelines/tests-unit.yml "Unit tests YAML" +[E2E-Tests]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/blob/main/tests/pipelines/tests-e2e.yml "E2E tests YAML" \ No newline at end of file diff --git a/docs/wiki/Contributing-to-Documentation.md b/docs/wiki/Contributing-to-Documentation.md new file mode 100644 index 000000000..6dff1cf0d --- /dev/null +++ b/docs/wiki/Contributing-to-Documentation.md @@ -0,0 +1,3 @@ +Please ensure you have read our [Contributing](./Contributing) page before going any further. + +_More information coming soon_ \ No newline at end of file diff --git a/docs/wiki/Contributing.md b/docs/wiki/Contributing.md new file mode 100644 index 000000000..4ca2bb00b --- /dev/null +++ b/docs/wiki/Contributing.md @@ -0,0 +1,19 @@ +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.opensource.microsoft.com](https://cla.opensource.microsoft.com). + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments. + +Please familiarise yourself with our [Code of Conduct][Code-of-Conduct] and the [MIT License][License] associated with this repository to ensure all code contributions are submitted in accordance with these terms. + +## Next steps + +- [Raising an Issue](./Raising-an-Issue) +- [Feature Requests](./Feature-Requests) +- [Contributing to Code](./Contributing-to-Code) +- [Contributing to Documentation](./Contributing-to-Documentation) + + + +[Code-of-Conduct]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/blob/main/CODE_OF_CONDUCT.md "Our Code-of-Conduct" +[License]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/blob/main/LICENSE "Our license" diff --git a/docs/wiki/Examples.md b/docs/wiki/Examples.md new file mode 100644 index 000000000..717eb45f5 --- /dev/null +++ b/docs/wiki/Examples.md @@ -0,0 +1,28 @@ +The following examples are designed to help build an understanding of how to use the module, ranging from basic deployments covering the core resource hierarchy from Enterprise-scale, through to more advanced scenarios. + +Use the links below to explore these examples in more detail. + +### Basic (Level 100) + +- [Deploy Default Configuration][wiki_deploy_default_configuration] +- [Deploy Demo Landing Zone Archetypes][wiki_deploy_demo_landing_zone_archetypes] + +### Intermediate (Level 200) + +- [Deploy Custom Landing Zone Archetypes][wiki_deploy_custom_landing_zone_archetypes] +- [Expand Built-in Archetype Definitions][wiki_expand_built_in_archetype_definitions] + +### Advanced (Level 300) + +- [Deploy Using Module Nesting][wiki_deploy_using_module_nesting] +- [Override Module Role Assignments][wiki_override_module_role_assignments] + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[wiki_deploy_default_configuration]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Default-Configuration "Wiki - Deploy Default Configuration" +[wiki_deploy_demo_landing_zone_archetypes]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Demo-Landing-Zone-Archetypes "Wiki - Deploy Demo Landing Zone Archetypes" +[wiki_deploy_custom_landing_zone_archetypes]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Custom-Landing-Zone-Archetypes "Wiki - Deploy Custom Landing Zone Archetypes" +[wiki_deploy_using_module_nesting]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Using-Module-Nesting "Wiki - Deploy Using Module Nesting" +[wiki_expand_built_in_archetype_definitions]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Expand-Built-in-Archetype-Definitions "Wiki - Expand Built-in Archetype Definitions" +[wiki_override_module_role_assignments]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Override-Module-Role-Assignments "Wiki - Override Module Role Assignments" diff --git a/docs/wiki/Feature-Requests.md b/docs/wiki/Feature-Requests.md new file mode 100644 index 000000000..c42ff62a5 --- /dev/null +++ b/docs/wiki/Feature-Requests.md @@ -0,0 +1 @@ +_Coming soon_ \ No newline at end of file diff --git a/docs/wiki/Frequently-Asked-Questions.md b/docs/wiki/Frequently-Asked-Questions.md new file mode 100644 index 000000000..c42ff62a5 --- /dev/null +++ b/docs/wiki/Frequently-Asked-Questions.md @@ -0,0 +1 @@ +_Coming soon_ \ No newline at end of file diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 000000000..08fde1746 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,122 @@ +# Terraform Module for Cloud Adoption Framework Enterprise-scale + +The [Terraform Module for Cloud Adoption Framework Enterprise-scale][terraform-registry-caf-enterprise-scale] provides an opinionated approach for delivering the core platform capabilities needed to start building Azure landing zones using Terraform. + +This module deploys the foundations of the [Cloud Adoption Framework enterprise-scale landing zone architecture][ESLZ-Architecture], with a focus on the central resource hierarchy and governance: + +![Enterprise-scale Landing Zone Architecture][TFAES-Overview] + +## Critical design areas + +The module provides a consistent approach for deploying and managing resources relating to the following Enterprise-scale critical design areas: + +- [Management Group and Subscription organisation][management-group-and-subscription-organization] + - Create the Management Group resource hierarchy + - Assign Subscriptions to Management Groups + - Create custom Policy Assignments, Policy Definitions and Policy Set Definitions (Initiatives) +- [Identity and access management][identity-and-access-management] + - Create custom Role Assignments and Role Definitions +- [Management and monitoring][management-and-monitoring] + - Create a central Log Analytics workspace and Automation Account + - Link Log Analytics workspace to the Automation Account + - Deploy recommended Log Analytics Solutions + - Enable Azure Defender + +## Resources + +The [Terraform Module for Cloud Adoption Framework Enterprise-scale][terraform-registry-caf-enterprise-scale] provides an opinionated approach for delivering Azure landing zones using Terraform. +Depending on the selected options, this module is able to deploy different groups of resources as needed. + +This is currently split logically into the following capabilities: + +- Core resources +- Management resources + +The following sections outline the different resource types deployed and managed by this module, depending on the configuration options specified. + +### Core resources + +The core capability of this module deploys the foundations of the [Cloud Adoption Framework enterprise-scale landing zone architecture][ESLZ-Architecture], with a focus on the central resource hierarchy and governance: + +![Enterprise-scale Core Landing Zones Architecture][TFAES-Overview] + +The following resource types are deployed and managed by this module when using the core capabilities: + +| | Azure Resource | Terraform Resource | +| --- | -------------- | ------------------ | +| Management Groups | [`Microsoft.Management/managementGroups`][arm_management_group] | [`azurerm_management_group`][azurerm_management_group] | +| Management Group Subscriptions | [`Microsoft.Management/managementGroups/subscriptions`][arm_management_group_subscriptions] | [`azurerm_management_group`][azurerm_management_group] | +| Policy Assignments | [`Microsoft.Authorization/policyAssignments`][arm_policy_assignment] | [`azurerm_policy_assignment`][azurerm_policy_assignment] | +| Policy Definitions | [`Microsoft.Authorization/policyDefinitions`][arm_policy_definition] | [`azurerm_policy_definition`][azurerm_policy_definition] | +| Policy Set Definitions | [`Microsoft.Authorization/policySetDefinitions`][arm_policy_set_definition] | [`azurerm_policy_set_definition`][azurerm_policy_set_definition] | +| Role Assignments | [`Microsoft.Authorization/roleAssignments`][arm_role_assignment] | [`azurerm_role_assignment`][azurerm_role_assignment] | +| Role Definitions | [`Microsoft.Authorization/roleDefinitions`][arm_role_definition] | [`azurerm_role_definition`][azurerm_role_definition] | + +The exact number of resources created depends on the module configuration, but you can expect upwards of `100` resources to be created by this module for a default installation based on the example below. + +> **NOTE:** None of these resources are deployed at the Subscription scope, however Terraform still requires a Subscription to establish an authenticated session with Azure. + +### Management resources + +From release `v0.2.0` onwards, the module includes new functionality to enable deployment of [Management and monitoring][ESLZ-Management] resources into the current Subscription context. +This brings the benefit of being able to manage the full lifecycle of these resources using Terraform, with native integration into the corresponding Policy Assignments to ensure full policy compliance. + +![Enterprise-scale Management Landing Zone Architecture][TFAES-Management] + +The following resource types are deployed and managed by this module when the Management resources capabilities are enabled: + +| | Azure Resource | Terraform Resource | +| --- | -------------- | ------------------ | +| Resource Groups | [`Microsoft.Resources/resourceGroups`][arm_resource_group] | [`azurerm_resource_group`][azurerm_resource_group] | +| Log Analytics Workspace | [`Microsoft.OperationalInsights/workspaces`][arm_log_analytics_workspace] | [`azurerm_log_analytics_workspace`][azurerm_log_analytics_workspace] | +| Log Analytics Solutions | [`Microsoft.OperationsManagement/solutions`][arm_log_analytics_solution] | [`azurerm_log_analytics_solution`][azurerm_log_analytics_solution] | +| Automation Account | [`Microsoft.Automation/automationAccounts`][arm_automation_account] | [`azurerm_automation_account`][azurerm_automation_account] | +| Log Analytics Linked Service | [`Microsoft.OperationalInsights/workspaces /linkedServices`][arm_log_analytics_linked_service] | [`azurerm_log_analytics_linked_service`][azurerm_log_analytics_linked_service] | + +Please refer to the [Deploy Management Resources](./%5BUser-Guide%5D-Deploy-Management-Resources) page on our Wiki for more information about how to use this capability. + +## Next steps + +Check out the [User Guide](./User-Guide), or go straight to our [Examples](./Examples). + + [//]: # (*****************************) + [//]: # (INSERT IMAGE REFERENCES BELOW) + [//]: # (*****************************) + +[TFAES-Overview]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/media/terraform-caf-enterprise-scale-overview.png "Diagram showing the Cloud Adoption Framework Enterprise-scale Landing Zone architecture deployed by this module." +[TFAES-Management]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/media/terraform-caf-enterprise-scale-management.png "Diagram showing the Management resources for Cloud Adoption Framework Enterprise-scale Landing Zone architecture deployed by this module." + + [//]: # (************************) + [//]: # (INSERT LINK LABELS BELOW) + [//]: # (************************) + +[ESLZ-Architecture]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/architecture "Enterprise-scale Reference Architecture" +[terraform-registry-caf-enterprise-scale]: https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest "Terraform Registry: Terraform Module for Cloud Adoption Framework Enterprise-scale" +[management-group-and-subscription-organization]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/management-group-and-subscription-organization "Cloud Adoption Framework: Management group and subscription organization" +[identity-and-access-management]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/identity-and-access-management "Cloud Adoption Framework: Identity and access management" +[management-and-monitoring]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/management-and-monitoring "Cloud Adoption Framework: Management and monitoring" + +[arm_management_group]: https://docs.microsoft.com/en-us/azure/templates/microsoft.management/managementgroups +[arm_management_group_subscriptions]: https://docs.microsoft.com/en-us/azure/templates/microsoft.management/managementgroups/subscriptions +[arm_policy_assignment]: https://docs.microsoft.com/en-us/azure/templates/microsoft.authorization/policyassignments +[arm_policy_definition]: https://docs.microsoft.com/en-us/azure/templates/microsoft.authorization/policydefinitions +[arm_policy_set_definition]: https://docs.microsoft.com/en-us/azure/templates/microsoft.authorization/policysetdefinitions +[arm_role_assignment]: https://docs.microsoft.com/en-us/azure/templates/microsoft.authorization/roleassignments +[arm_role_definition]: https://docs.microsoft.com/en-us/azure/templates/microsoft.authorization/roledefinitions +[arm_resource_group]: https://docs.microsoft.com/en-us/azure/templates/microsoft.resources/resourcegroups +[arm_log_analytics_workspace]: https://docs.microsoft.com/en-us/azure/templates/microsoft.operationalinsights/workspaces +[arm_log_analytics_solution]: https://docs.microsoft.com/en-us/azure/templates/microsoft.operationsmanagement/solutions +[arm_automation_account]: https://docs.microsoft.com/en-us/azure/templates/microsoft.automation/automationaccounts +[arm_log_analytics_linked_service]: https://docs.microsoft.com/en-us/azure/templates/microsoft.operationalinsights/workspaces/linkedservices + +[azurerm_management_group]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/management_group +[azurerm_policy_assignment]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/policy_assignment +[azurerm_policy_definition]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/policy_definition +[azurerm_policy_set_definition]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/policy_set_definition +[azurerm_role_assignment]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_assignment +[azurerm_role_definition]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_definition +[azurerm_resource_group]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group +[azurerm_log_analytics_workspace]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/log_analytics_workspace +[azurerm_log_analytics_solution]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/log_analytics_solution +[azurerm_automation_account]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/automation_account +[azurerm_log_analytics_linked_service]: https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/log_analytics_linked_service diff --git a/docs/wiki/Raising-an-Issue.md b/docs/wiki/Raising-an-Issue.md new file mode 100644 index 000000000..c42ff62a5 --- /dev/null +++ b/docs/wiki/Raising-an-Issue.md @@ -0,0 +1 @@ +_Coming soon_ \ No newline at end of file diff --git a/docs/wiki/Troubleshooting.md b/docs/wiki/Troubleshooting.md new file mode 100644 index 000000000..0a531a35c --- /dev/null +++ b/docs/wiki/Troubleshooting.md @@ -0,0 +1,31 @@ +Having trouble using the module and unable to find a solution in the Wiki? + +If it isn't listed below, let us know about it in our [Issues][Issues] log. We'll do our best to help and you may find your issue documented here in the future! + +[Issues]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/issues "Terraform Module for Cloud Adoption Framework Enterprise-scale: Report an Issue" + +#### Errors creating Role Definitions and Role Assignments + +
+ Error: authorization.RoleDefinitionsClient#Get: Failure responding to request: StatusCode=404 -- Original Error: autorest/azure: Service returned an error. Status=404 Code="RoleDefinitionDoesNotExist" Message="The specified role definition with ID '<redacted>' does not exist." + +
+
Description:
+
+

This error is a transient error which may occur when the Resource Provider in ARM is yet to complete replication of the newly created Role Definition.

+
+
Solution:
+
+

If the Role Definition has been successfully created in Azure but has not been committed to the terraform state you will need to run terraform import to add the Resource to the state file. Due to caching in ARM, it could take up to 10 minutes before you can successfully import the Resource.

+

This problem has been identified and logged on GitHub against the AzureRM Provider: #10442

+
+
+
+ +
+ Error: authorization.RoleAssignmentsClient#Get: Failure responding to request: StatusCode=404 -- Original Error: autorest/azure: Service returned an error. Status=404 Code="RoleAssignmentNotFound" Message="The role assignment '<redacted>' is not found." +
+
Description:
+
Coming soon
+
+
diff --git a/docs/wiki/User-Guide.md b/docs/wiki/User-Guide.md new file mode 100644 index 000000000..48561d50a --- /dev/null +++ b/docs/wiki/User-Guide.md @@ -0,0 +1,43 @@ +## Table of Contents + +- [Getting Started][Getting Started] +- [Module Variables][Module Variables] + - [root_parent_id][root_parent_id] + - [archetype_config_overrides][archetype_config_overrides] + - [custom_landing_zones][custom_landing_zones] + - [default_location][default_location] + - [deploy_core_landing_zones][deploy_core_landing_zones] + - [deploy_demo_landing_zones][deploy_demo_landing_zones] + - [library_path][library_path] + - [root_id][root_id] + - [root_name][root_name] + - [subscription_id_overrides][subscription_id_overrides] + - [template_file_variables][template_file_variables] + - [create_duration_delay][template_file_variables] + - [destroy_duration_delay][template_file_variables] +- [Archetype Definitions][Archetype Definitions] +- [Upgrade from v0.0.8 to v0.1.0][Upgrade from v0.0.8 to v0.1.0] + + + [//]: # (************************) + [//]: # (INSERT LINK LABELS BELOW) + [//]: # (************************) + +[Getting Started]: ./%5BUser-Guide%5D-Getting-Started "Getting Started" +[Module Variables]: ./%5BUser-Guide%5D-Module-Variables "Module Variables" +[Archetype Definitions]: ./%5BUser-Guide%5D-Archetype-Definitions "Archetype Definitions" +[Upgrade from v0.0.8 to v0.1.0]: ./%5BUser-Guide%5D-Upgrade-from-v0.0.8-to-v0.1.0.md "Upgrade from v0.0.8 to v0.1.0" + +[root_parent_id]: ./%5BVariables%5D-root_parent_id "Instructions for how to use the root_parent_id variable." +[root_id]: ./%5BVariables%5D-root_id "Instructions for how to use the root_id variable." +[root_name]: ./%5BVariables%5D-root_name "Instructions for how to use the root_name variable." +[deploy_core_landing_zones]: ./%5BVariables%5D-deploy_core_landing_zones "Instructions for how to use the deploy_core_landing_zones variable." +[archetype_config_overrides]: ./%5BVariables%5D-archetype_config_overrides "Instructions for how to use the archetype_config_overrides variable." +[subscription_id_overrides]: ./%5BVariables%5D-subscription_id_overrides "Instructions for how to use the subscription_id_overrides variable." +[deploy_demo_landing_zones]: ./%5BVariables%5D-deploy_demo_landing_zones "Instructions for how to use the deploy_demo_landing_zones variable." +[custom_landing_zones]: ./%5BVariables%5D-custom_landing_zones "Instructions for how to use the custom_landing_zones variable." +[library_path]: ./%5BVariables%5D-library_path "Instructions for how to use the library_path variable." +[template_file_variables]: ./%5BVariables%5D-template_file_variables "Instructions for how to use the template_file_variables variable." +[default_location]: ./%5BVariables%5D-default_location "Instructions for how to use the default_location variable." +[create_duration_delay]: ./%5BVariables%5D-create_duration_delay "Instructions for how to use the create_duration_delay variable." +[destroy_duration_delay]: ./%5BVariables%5D-destroy_duration_delay "Instructions for how to use the destroy_duration_delay variable." \ No newline at end of file diff --git a/docs/wiki/[Examples]-Deploy-Custom-Landing-Zone-Archetypes.md b/docs/wiki/[Examples]-Deploy-Custom-Landing-Zone-Archetypes.md new file mode 100644 index 000000000..4fb54f6a5 --- /dev/null +++ b/docs/wiki/[Examples]-Deploy-Custom-Landing-Zone-Archetypes.md @@ -0,0 +1,187 @@ +## Overview + +This page describes how to deploy Enterprise-scale with a custom configuration, including guidance on how to customise the Management Group hierarchy. + +In this example, we take a default configuration and make the following changes: + +- Create a new custom archetype definition named `customer_online` which will create two Policy Assignments, `Deny-Resource-Locations` and `Deny-RSG-Locations` at the associated scope with a set of pre-configured default parameter values. +- Add a new Management Group for standard workloads using the `customer_online` archetype definition: + - Management Group ID: `myorg-3-online-example-1` + - Management Group Name: `MYORG-3 Online Example 1` + - Parent Management Group ID: `myorg-3-landing-zones` + - Allowed location list: _default_ +- Add a new Management Group for geo-restricted workloads using the `customer_online` archetype definition: + - Management Group ID: `myorg-3-online-example-2` + - Management Group Name: `MYORG-3 Online Example 2` + - Parent Management Group ID: `myorg-3-landing-zones` + - Allowed location list: `["eastus"]` + +> IMPORTANT: Ensure the module version is set to the latest + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +## Example root module + +> NOTE: Although only `root_parent_id` is required, we recommend setting `root_id` and `root_name` to something more meaningful. Changing `root_id` will result in the entire deployment to be re-provisioned. + +To make the code easier to maintain when extending your configuration, we recommend splitting the root module into multiple files. For the purpose of this example, we use the following: + +- `terraform.tf` +- `variables.tf` +- `main.tf` +- `lib/archetype_definition_customer_online.json` + +**`terraform.tf`** + +The `terraform.tf` file is used to set the provider configuration, including pinning to a specific version (or range of versions) for the AzureRM Provider. For production use, we recommend pinning to a specific version, and not using ranges. + +```hcl +# Configure Terraform to set the required AzureRM provider +# version and features{} block. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} +``` + +**`variables.tf`** + +The `variables.tf` file is used to declare a couple of example variables which are used to customise deployment of this root module. Defaults are provided for simplicity, but these should be replaced or over-ridden with values suitable for your environment. + +```hcl +# Use variables to customise the deployment + +variable "root_id" { + type = string + default = "myorg-3" +} + +variable "root_name" { + type = string + default = "My Organization 3" +} +``` + +**`main.tf`** + +The `main.tf` file contains the `azurerm_client_config` resource, which is used to determine the Tenant ID from your user connection to Azure. This is used to ensure the deployment will target your `Tenant Root Group` by default. + +It also contains the module declaration for this module, containing a number of customisations as needed to meet the specification defined in the overview above. + +To allow the declaration of custom templates, you must create a custom library folder within the root module and include the path to this folder using the `library_path` variable within the module configuration. + +> NOTE: For more information regarding configuration of this module, please refer to the [Module Variables](./%5BUser-Guide%5D-Module-Variables) documentation. + +```hcl +# Get the current client configuration from the AzureRM provider. +# This is used to populate the root_parent_id variable with the +# current Tenant ID used as the ID for the "Tenant Root Group" +# Management Group. + +data "azurerm_client_config" "current" {} + +# Declare the Terraform Module for Cloud Adoption Framework +# Enterprise-scale and provide a base configuration. + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = var.root_id + root_name = var.root_name + library_path = "${path.root}/lib" + + custom_landing_zones = { + "${var.root_id}-online-example-1" = { + display_name = "${upper(var.root_id)} Online Example 1" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = {} + access_control = {} + } + } + "${var.root_id}-online-example-2" = { + display_name = "${upper(var.root_id)} Online Example 2" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = { + Deny-Resource-Locations = { + listOfAllowedLocations = ["eastus",] + } + Deny-RSG-Locations = { + listOfAllowedLocations = ["eastus",] + } + } + access_control = {} + } + } + } + +} +``` + +**`lib/archetype_definition_customer_online.json`** + +> IMPORTANT: Please ensure you create this file in the `/lib` directory within your root module. + +The `lib/archetype_definition_customer_online.json` file contains a custom "archetype definition". This is a custom JSON format used specifically by the Terraform Module for Cloud Adoption Framework Enterprise-scale. + +In this example, we are using this archetype definition to create an archetype called `customer_online`. This archetype definition includes the creation of Policy Assignments for `Deny-Resource-Locations` and `Deny-RSG-Locations`, with default values pre-defined in the archetype definition template. + +For more details about working with archetype definitions, please refer to the [archetype definition user guide](./%5BUser-Guide%5D-Archetype-Definitions). + +```json +{ + "customer_online": { + "policy_assignments": ["Deny-Resource-Locations", "Deny-RSG-Locations"], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": { + "Deny-Resource-Locations": { + "listOfAllowedLocations": [ + "eastus", + "eastus2", + "westus", + "northcentralus", + "southcentralus" + ] + }, + "Deny-RSG-Locations": { + "listOfAllowedLocations": [ + "eastus", + "eastus2", + "westus", + "northcentralus", + "southcentralus" + ] + } + }, + "access_control": {} + } + } +} +``` + +## **Deployed Management Groups** + +![Deploy-Default-Configuration](./media/examples-deploy-custom-demo-landing-zone-archetypes.png) + +You have successfully created the default Management Group resource hierarchy including additional Management Groups for demonstrating custom Landing Zone archetypes, along with the recommended Azure Policy and Access control (IAM) settings for Enterprise-scale. + +> TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 140 resources to be created by this module for a default installation. diff --git a/docs/wiki/[Examples]-Deploy-Default-Configuration.md b/docs/wiki/[Examples]-Deploy-Default-Configuration.md new file mode 100644 index 000000000..ae0cdd828 --- /dev/null +++ b/docs/wiki/[Examples]-Deploy-Default-Configuration.md @@ -0,0 +1,62 @@ +## Overview + +This example code will deploy the minimum recommended management group and subscription organization from the enterprise-scale reference architecture. +You can then start to customize your deployment once you've got this up and running. + +This is a good starting point when first discovering what resources are created by this module. + +> IMPORTANT: Ensure the module version is set to the latest + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +## Example root module + +> TIP: Although only `root_parent_id` is required, we recommend setting `root_id` and `root_name` to something more meaningful. Changing `root_id` will result in the entire deployment to be re-provisioned. + +To keep things simple, the root module for this example is based on a single file: + +**`main.tf`** + +```hcl +# We strongly recommend using the required_providers block to set the +# Azure Provider source and version being used. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} + +# You can use the azurerm_client_config data resource to dynamically +# extract the current Tenant ID from your connection settings. + +data "azurerm_client_config" "current" {} + +# Call the caf-enterprise-scale module directly from the Terraform Registry +# pinning to the latest version + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = "myorg-1" + root_name = "My Organization 1" + +} +``` + +## **Deployed Management Groups** + +![Deploy-Default-Configuration](./media/examples-deploy-default-configuration.png) + +You have successfully created the default Management Group resource hierarchy, along with the recommended Azure Policy and Access control (IAM) settings for Enterprise-scale. + +> TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 140 resources to be created by this module for a default installation. diff --git a/docs/wiki/[Examples]-Deploy-Demo-Landing-Zone-Archetypes.md b/docs/wiki/[Examples]-Deploy-Demo-Landing-Zone-Archetypes.md new file mode 100644 index 000000000..0519e2582 --- /dev/null +++ b/docs/wiki/[Examples]-Deploy-Demo-Landing-Zone-Archetypes.md @@ -0,0 +1,71 @@ +## Overview + +This page describes how to deploy Enterprise-scale with a starter configuration based mainly on module defaults, including the additional Management Groups used for demonstrating the Enterprise-scale Landing Zone archetypes: + +- Corp +- Online +- SAP + +These demo Landing Zone archetypes provides a good way to learn about archetypes within the Enterprise-scale architecture but should not be used for production workloads. + +> IMPORTANT: Ensure the module version is set to the latest + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +> TIP: What is an archetype? +> An archetype defines which Azure Policy and Access control (IAM) settings are needed to secure and configure the Landing Zones with everything needed for safe handover to the Landing Zone owner. +> The archetype is what fundamentally transforms Management Groups and Subscriptions into Landing Zones. + +## Example root module + +> NOTE: Although only `root_parent_id` is required, we recommend setting `root_id` and `root_name` to something more meaningful. Changing `root_id` will result in the entire deployment to be re-provisioned. + +To keep things simple, the root module for this example is based on a single file: + +**`main.tf`** + +```hcl +# We strongly recommend using the required_providers block to set the +# Azure Provider source and version being used. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} + +# You can use the azurerm_client_config data resource to dynamically +# extract the current Tenant ID from your connection settings. + +data "azurerm_client_config" "current" {} + +# Declare the Terraform Module for Cloud Adoption Framework +# Enterprise-scale and provide a base configuration. + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = "myorg-2" + root_name = "My Organization 2" + + deploy_demo_landing_zones = true + +} +``` + +## **Deployed Management Groups** + +![Deploy-Default-Configuration](./media/examples-deploy-demo-landing-zone-archetypes.png) + +You have successfully created the default Management Group resource hierarchy including additional Management Groups for demonstrating Landing Zone archetypes, along with the recommended Azure Policy and Access control (IAM) settings for Enterprise-scale. + +> TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 140 resources to be created by this module for a default installation. diff --git a/docs/wiki/[Examples]-Deploy-Using-Module-Nesting.md b/docs/wiki/[Examples]-Deploy-Using-Module-Nesting.md new file mode 100644 index 000000000..54701bd9a --- /dev/null +++ b/docs/wiki/[Examples]-Deploy-Using-Module-Nesting.md @@ -0,0 +1,252 @@ +## Overview + +This page describes how to deploy Enterprise-scale with a nested module instance. This example is building on top of +[Deploy Custom Landing Zone Archetypes](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Custom-Landing-Zone-Archetypes) +and creates a nested management group, in the previously deployed custom landing zones. + +The extra code needed to extend your configuration, is the following: + +```hcl + +# Enterprise scale nested landing zone instance + +module "enterprise_scale_nested_landing_zone" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + + root_parent_id = "${var.root_id}-landing-zones" + root_id = var.root_id + deploy_core_landing_zones = false + library_path = "${path.root}/lib" + + custom_landing_zones = { + "${var.root_id}-module-instance" = { + display_name = "${upper(var.root_id)} Online Example 3 (nested)" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = {} + access_control = {} + } + } + } + + depends_on = [ + module.enterprise_scale, + ] + +} + +``` + +In this example, we set and update the following values: + +- root_parent_id: `${var.root_id}-landing-zones` +- deploy_core_landing_zones: `false` +- display_name: `${upper(var.root_id)} Online Example 3 (nested)` +- depends_on: `module.enterprise_scale` + +Check the **`main.tf`** later on the example, for the full modules declaration. + +> IMPORTANT: Ensure the module version is set to the latest + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +## Example root module + +> NOTE: Although only `root_parent_id` is required, we recommend setting `root_id` and `root_name` to something more meaningful. Changing `root_id` will result in the entire deployment to be re-provisioned. + +To make the code easier to maintain when extending your configuration, we recommend splitting the root module into multiple files. For the purpose of this example, we use the following: + +- `terraform.tf` +- `variables.tf` +- `main.tf` +- `lib/archetype_definition_customer_online.json` + +**`terraform.tf`** + +The `terraform.tf` file is used to set the provider configuration, including pinning to a specific version (or range of versions) for the AzureRM Provider. For production use, we recommend pinning to a specific version, and not using ranges. + +```hcl +# Configure Terraform to set the required AzureRM provider +# version and features{} block. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} +``` + +**`variables.tf`** + +The `variables.tf` file is used to declare a couple of example variables which are used to customise deployment of this root module. Defaults are provided for simplicity, but these should be replaced or over-ridden with values suitable for your environment. + +```hcl +# Use variables to customise the deployment + +variable "root_id" { + type = string + default = "myorg-3" +} + +variable "root_name" { + type = string + default = "My Organization 3" +} +``` + +**`main.tf`** + +The `main.tf` file contains the `azurerm_client_config` resource, which is used to determine the Tenant ID from your user connection to Azure. This is used to ensure the deployment will target your `Tenant Root Group` by default. + +It also contains the module declaration for this module, containing a number of customisations as needed to meet the specification defined in the overview above. + +To allow the declaration of custom templates, you must create a custom library folder within the root module and include the path to this folder using the `library_path` variable within the module configuration. + +> NOTE: For more information regarding configuration of this module, please refer to the [Module Variables](./%5BUser-Guide%5D-Module-Variables) documentation. + +```hcl +# Get the current client configuration from the AzureRM provider. +# This is used to populate the root_parent_id variable with the +# current Tenant ID used as the ID for the "Tenant Root Group" +# Management Group. + +data "azurerm_client_config" "current" {} + +# Declare the Terraform Module for Cloud Adoption Framework +# Enterprise-scale and provide a base configuration. + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = var.root_id + root_name = var.root_name + library_path = "${path.root}/lib" + + custom_landing_zones = { + "${var.root_id}-online-example-1" = { + display_name = "${upper(var.root_id)} Online Example 1" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = {} + access_control = {} + } + } + "${var.root_id}-online-example-2" = { + display_name = "${upper(var.root_id)} Online Example 2" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = { + Deny-Resource-Locations = { + listOfAllowedLocations = ["eastus",] + } + Deny-RSG-Locations = { + listOfAllowedLocations = ["eastus",] + } + } + access_control = {} + } + } + } + +} + +# Enterprise scale nested landing zone instance + +module "enterprise_scale_nested_landing_zone" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + + root_parent_id = "${var.root_id}-landing-zones" + root_id = var.root_id + deploy_core_landing_zones = false + library_path = "${path.root}/lib" + + custom_landing_zones = { + "${var.root_id}-module-instance" = { + display_name = "${upper(var.root_id)} Online Example 3 (nested)" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = {} + access_control = {} + } + } + } + + depends_on = [ + module.enterprise_scale, + ] + +} +``` + +**`lib/archetype_definition_customer_online.json`** + +> IMPORTANT: Please ensure you create this file in the `/lib` directory within your root module. + +The `lib/archetype_definition_customer_online.json` file contains a custom "archetype definition". This is a custom JSON format used specifically by the Terraform Module for Cloud Adoption Framework Enterprise-scale. + +In this example, we are using this archetype definition to create an archetype called `customer_online`. This archetype definition includes the creation of Policy Assignments for `Deny-Resource-Locations` and `Deny-RSG-Locations`, with default values pre-defined in the archetype definition template. + +For more details about working with archetype definitions, please refer to the [archetype definition user guide](./%5BUser-Guide%5D-Archetype-Definitions). + +```json +{ + "customer_online": { + "policy_assignments": ["Deny-Resource-Locations", "Deny-RSG-Locations"], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": { + "Deny-Resource-Locations": { + "listOfAllowedLocations": [ + "eastus", + "eastus2", + "westus", + "northcentralus", + "southcentralus" + ] + }, + "Deny-RSG-Locations": { + "listOfAllowedLocations": [ + "eastus", + "eastus2", + "westus", + "northcentralus", + "southcentralus" + ] + } + }, + "access_control": {} + } + } +} +``` + +## **Deployed Management Groups** + +![Deploy-Using-Module-Nesting](./media/examples-deploy-using-module-nesting.png) + +You have successfully created the default Management Group resource hierarchy including additional Management Groups for demonstrating custom Landing Zone archetypes, along with the recommended Azure Policy and Access control (IAM) settings for Enterprise-scale, using module nesting. + +> TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 140 resources to be created by this module for a default installation. diff --git a/docs/wiki/[Examples]-Expand-built-in-archetype-definitions.md b/docs/wiki/[Examples]-Expand-built-in-archetype-definitions.md new file mode 100644 index 000000000..a65497c5a --- /dev/null +++ b/docs/wiki/[Examples]-Expand-built-in-archetype-definitions.md @@ -0,0 +1,186 @@ +## Overview + +This page describes how to deploy Enterprise-scale with a basic configuration based mainly on module defaults, including guidance on how to expand the built-in archetype definitions. + +> NOTE: This feature is available from version 0.2.0. + +We will use the `es_landing_zones` configuration as an example. + +The built-in definition contains the following settings: + +```json +{ + "es_landing_zones": { + "policy_assignments": [ + "Deny-IP-Forwarding", + "Deny-RDP-From-Internet", + "Deny-Storage-http", + "Deny-Subnet-Without-Nsg", + "Deploy-AKS-Policy", + "Deploy-SQL-DB-Auditing", + "Deploy-VM-Backup", + "Deploy-SQL-Security", + "Deny-Priv-Escalation-AKS", + "Deny-Priv-Containers-AKS", + "Deny-http-Ingress-AKS" + ], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": {}, + "access_control": {} + } + } +} +``` + +We will update the built-in configuration by adding 2 new settings: + +- Create an extension `extend_es_landing_zones` which will **add** a Policy Assignment `Deny-Resource-Locations` and set the parameters of this Policy Assignment. + +- Create an exclusion `exclude_es_landing_zones` which will **remove** a set of Policy Assignments `Deny-Priv-Escalation-AKS`, `Deny-Priv-Containers-AKS` and `Deny-http-Ingress-AKS`. + +> IMPORTANT: Ensure the module version is set to the latest. + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +## Example root module + +To make the code easier to maintain when extending your configuration, we recommend splitting the root module into multiple files. For the purpose of this example, we use the following: + +- `main.tf` +- `lib/archetype_extension_es_landing_zones.tmpl.json` +- `lib/archetype_exclusion_es_landing_zones.tmpl.json` + +![Expand-Built-In-Archetype-Definitions](./media/examples-expand-built-in-archetype-definitions.png) + +**`main.tf`** + +The `main.tf` file contains the `azurerm_client_config` resource, which is used to determine the Tenant ID from your user connection to Azure. This is used to ensure the deployment will target your `Tenant Root Group` by default. + +This example code will deploy the minimum recommended management group and subscription organization from the enterprise-scale reference architecture. + +To allow the declaration of custom or expanded templates, you must create a custom library folder within the root module and include the path to this folder using the `library_path` variable within the module configuration. In our example, the directory is `/lib`. + +> NOTE: For more information regarding configuration of this module, please refer to the [Module Variables](./%5BUser-Guide%5D-Module-Variables) documentation. + +```hcl +# We strongly recommend using the required_providers block to set the +# Azure Provider source and version being used. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} + +# You can use the azurerm_client_config data resource to dynamically +# extract the current Tenant ID from your connection settings. + +data "azurerm_client_config" "current" {} + +# Call the caf-enterprise-scale module directly from the Terraform Registry +# pinning to the latest version + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.3.0" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = "myorg-1" + root_name = "My Organization 1" + library_path = "${path.root}/lib" + +} + +``` + +### To enable the extension function + +- In the `/lib` directory create an `**/archetype_extension_*.json` file. + +- In the file `**/archetype_extension_*.json` add the `extend_` prefix to the name of the desired built-in archetype definition and your custom settings. + +> IMPORTANT: Please ensure you create this file in the `/lib` directory within your root module. + +**`lib/archetype_extension_es_landing_zones.tmpl.json`** + +In this example, we want to add the policy assignment `"Deny-Resource-Locations"` and its related parameters in the built-in archetype `es_landing_zones` + +- In the `/lib` directory create an `archetype_extension_es_landing_zones.tmpl.json` file. + + - In the file `archetype_extension_es_landing_zones.tmpl.json` add this code: + +```json +{ + "extend_es_landing_zones": { + "policy_assignments": ["Deny-Resource-Locations"], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": { + "Deny-Resource-Locations": { + "listOfAllowedLocations": ["eastus", "westus"] + } + }, + "access_control": {} + } + } +} +``` + +### **Extended Policy Assignment** + +![Expand-Built-In-Archetype-Definitions-01](./media/examples-expand-built-in-archetype-definitions-01.png) + +### To enable the exclusion function + +- In the `/lib` directory create an `**/archetype_exclusion_*.json` file. + +- In the file `**/archetype_exclusion_*.json` add the `exclude_` prefix to the name of the desired built-in archetype definition and your custom settings. + +> IMPORTANT: Please ensure you create this file in the `/lib` directory within your root module. + +**`lib/archetype_exclusion_es_landing_zones.tmpl.json`** + +In this example, we want to remove the policy assignments `"Deny-Priv-Escalation-AKS"`, `Deny-Priv-Containers-AKS` and `Deny-http-Ingress-AKS` from the built-in archetype `es_landing_zones` + +- In the `/lib` directory create an `archetype_exclusion_es_landing_zones.tmpl.json` file. + + - In the file `archetype_exclusion_es_landing_zones.tmpl.json` add this code: + +```json +{ + "exclude_es_landing_zones": { + "policy_assignments": [ + "Deny-Priv-Escalation-AKS", + "Deny-Priv-Containers-AKS", + "Deny-http-Ingress-AKS" + ], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": {}, + "access_control": {} + } + } +} +``` + +### **Excluded Policy Assignments** + +![Expand-Built-In-Archetype-Definitions-02](./media/examples-expand-built-in-archetype-definitions-02.png) + +You have successfully expanded the archetype(s) by adding or removing configuration settings from the built-in archetype definitions for Enterprise-scale. + +> TIP: The exact number of resources created depends on the module configuration, but you can expect upwards of 140 resources to be created by this module for a default installation. diff --git a/docs/wiki/[Examples]-Override-Module-Role-Assignments.md b/docs/wiki/[Examples]-Override-Module-Role-Assignments.md new file mode 100644 index 000000000..05d468b5d --- /dev/null +++ b/docs/wiki/[Examples]-Override-Module-Role-Assignments.md @@ -0,0 +1,280 @@ +## Overview + +This page describes how to deploy Enterprise-scale with a custom configuration, including guidance on how to override the dynamically generated Role Assignments for a specific Policy Assignment with Managed Identity. + +> NOTE: This feature is available from version 0.2.2. + +We will use the `Deploy-HITRUST-HIPAA` and `Deploy-SQL-Auditing` policy assignments as an example. + +On deployment, the module will auto-generate the role assignments necessary for any Policy Assignment when a Managed Identity is required to support policies using `Modify` or `DeployIfNotExists` effects. + +- For `Deploy-HITRUST-HIPAA` the module will generate 5 role assignments: + ![Override-Module-Role-Assignments](./media/examples-override-module-role-assignments.png) + +- For `Deploy-SQL-Auditing`the module will generate 2 role assignments: + ![Override-Module-Role-Assignments-01](./media/examples-override-module-role-assignments-01.png) + +We will update the built-in configuration following these steps: + +- Create the policy assignment definitions `Deploy-HITRUST-HIPAA` and `Deploy-SQL-Auditing` + +- Create the custom archetype definition `customer_online` + +- Override the dynamically generated Role Assignments for `Deploy-HITRUST-HIPAA` and `Deploy-SQL-Auditing` Policy Assignments in a custom Landing Zone Management Group. + +- Enable the role assignment override with `custom_policy_roles` + +> IMPORTANT: Ensure the module version is set to the latest. + +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Azure/terraform-azurerm-caf-enterprise-scale?style=flat-square) + +## Example root module + +To make the code easier to maintain when extending your configuration, we recommend splitting the root module into multiple files. For the purpose of this example, we use the following: + +- `terraform.tf` +- `variables.tf` +- `main.tf` +- `lib/policy_assignments/policy_assignment_dhh_policy_set_definition.json` +- `lib/policy_assignments/policy_assignment_dsa_policy_set_definition.json` +- `lib/archetype_definitions/archetype_definition_customer_online.json` + +**`terraform.tf`** + +The `terraform.tf` file is used to set the provider configuration, including pinning to a specific version (or range of versions) for the AzureRM Provider. For production use, we recommend pinning to a specific version, and not using ranges. + +```hcl +# Configure Terraform to set the required AzureRM provider +# version and features{} block. + +terraform { + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 2.46.1" + } + } +} + +provider "azurerm" { + features {} +} +``` + +**`variables.tf`** + +The `variables.tf` file is used to declare a couple of example variables which are used to customise deployment of this root module. Defaults are provided for simplicity, but these should be replaced or over-ridden with values suitable for your environment. + +```hcl +# Use variables to customise the deployment + +variable "root_id" { + type = string + default = "myorg-3" +} + +variable "root_name" { + type = string + default = "My Organization 3" +} +``` + +**`main.tf`** + +The `main.tf` file contains the `azurerm_client_config` resource, which is used to determine the Tenant ID from your user connection to Azure. This is used to ensure the deployment will target your `Tenant Root Group` by default. + +It also contains the module declaration for this module, containing a number of customizations as needed to meet the specification defined in the overview above. The `custom_policy_roles` is explained later in this example. + +To allow the declaration of custom templates, you must create a custom library folder within the root module and include the path to this folder using the `library_path` variable within the module configuration. In our example, the directory is `/lib`. + +> NOTE: For more information regarding configuration of this module, please refer to the [Module Variables](./%5BUser-Guide%5D-Module-Variables) documentation. + +```hcl +# Get the current client configuration from the AzureRM provider. +# This is used to populate the root_parent_id variable with the +# current Tenant ID used as the ID for the "Tenant Root Group" +# Management Group. + +data "azurerm_client_config" "current" {} + +# Declare the Terraform Module for Cloud Adoption Framework +# Enterprise-scale and provide a base configuration. + +module "enterprise_scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.2.2" + + root_parent_id = data.azurerm_client_config.current.tenant_id + root_id = var.root_id + root_name = var.root_name + library_path = "${path.root}/lib" + + custom_policy_roles = { + "/providers/Microsoft.Authorization/policySetDefinitions/a169a624-5599-4385-a696-c8d643089fab" = [ + "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c", + "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" + ], + "/providers/Microsoft.Authorization/policyDefinitions/f4c68484-132f-41f9-9b6d-3e4b1cb55036" = [ + "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635" + ] + } + + custom_landing_zones = { + "${var.root_id}-customer-corp" = { + display_name = "Custom" + parent_management_group_id = "${var.root_id}-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "customer_online" + parameters = { + Deploy-HITRUST-HIPAA = { + CertificateThumbprints = jsonencode("") + DeployDiagnosticSettingsforNetworkSecurityGroupsrgName = jsonencode("true") + DeployDiagnosticSettingsforNetworkSecurityGroupsstoragePrefix = jsonencode(var.root_id) + installedApplicationsOnWindowsVM = jsonencode("") + }, + Deploy-SQL-Auditing = { + retentionDays = jsonencode("10") + storageAccountsResourceGroup = jsonencode("") + } + } + access_control = {} + } + } + } +} +``` + +**`lib/policy_assignments/policy_assignment_dhh_policy_set_definition.json`** + +In the `/lib` directory create a `policy_assignments` subdirectory. + +In the subdirectory `policy_assignments` create a `policy_assignment_dhh_policy_set_definition.json` file. This files contains the Policy Assignment definition for `Deploy-HITRUST-HIPAA` + +```json +{ + "name": "Deploy-HITRUST-HIPAA", + "type": "Microsoft.Authorization/policyAssignments", + "apiVersion": "2019-09-01", + "properties": { + "description": "This assignment includes audit and virtual machine extension deployment policies that address a subset of HITRUST/HIPAA controls. Additional policies will be added in upcoming releases. For more information, visit https://aka.ms/hipaa-blueprint.", + "displayName": "Assign policies for HITRUST and HIPAA controls", + "notScopes": [], + "parameters": { + "installedApplicationsOnWindowsVM": { + "value": null + }, + "DeployDiagnosticSettingsforNetworkSecurityGroupsstoragePrefix": { + "value": null + }, + "DeployDiagnosticSettingsforNetworkSecurityGroupsrgName": { + "value": null + }, + "CertificateThumbprints": { + "value": null + } + }, + "policyDefinitionId": "/providers/Microsoft.Authorization/policySetDefinitions/a169a624-5599-4385-a696-c8d643089fab", + "scope": "${current_scope_resource_id}" + }, + "location": "${default_location}", + "identity": { + "type": "SystemAssigned" + } +} +``` + +**`lib/policy_assignments/policy_assignment_dsa_policy_set_definition.json`** + +In the subdirectory `policy_assignments` create a `policy_assignment_dsa_policy_set_definition.json` file. This files contains the Policy Assignment definition for `Deploy-SQL-Auditing` + +```json +{ + "name": "Deploy-SQL-Auditing", + "type": "Microsoft.Authorization/policyAssignments", + "apiVersion": "2019-09-01", + "properties": { + "description": "Deploy Auditing on SQL servers.", + "displayName": "Deploy Auditing on SQL servers", + "notScopes": [], + "parameters": { + "retentionDays": { + "value": null + }, + "storageAccountsResourceGroup": { + "value": null + } + }, + "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/f4c68484-132f-41f9-9b6d-3e4b1cb55036", + "scope": "${current_scope_resource_id}" + }, + "location": "${default_location}", + "identity": { + "type": "SystemAssigned" + } +} +``` + +> IMPORTANT: Please ensure you create this file in the `/lib` directory within your root module. + +**`lib/archetype_definitions/archetype_definition_customer_online.json`** + +In the `/lib` directory create an `archetype_definitions` subdirectory. + +In the subdirectory `archetype_definitions` create an `archetype_definition_customer_online.json` file. This file contains a custom "archetype definition" including the creation of Policy Assignments for `Deploy-HITRUST-HIPAA` and `Deploy-SQL-Auditing` + +- **`lib/archetype_definitions/archetype_definition_customer_online.json`** + +```json +{ + "customer_online": { + "policy_assignments": ["Deploy-HITRUST-HIPAA", "Deploy-SQL-Auditing"], + "policy_definitions": [], + "policy_set_definitions": [], + "role_definitions": [], + "archetype_config": { + "parameters": {}, + "access_control": {} + } + } +} +``` + +### Override the dynamically generated Role Assignments + +To map a Role Definition against the Policy Assignments we need to assign the role definition id(s) to the policy definition id. +This is the definition of the variable `custom_policy_roles` and the theoretical expected values: + +```hcl +custom_policy_roles= { + policy_definition_resource_id_1 = [ + "role_definition_resource_id_1", + "role_definition_resource_id_2", + ] + policy_definition_resource_id_2 = [ + "role_definition_resource_id_1", + ] +} +``` + +For this example the`custom_policy_roles` is this: + +```hcl + custom_policy_roles = { + "/providers/Microsoft.Authorization/policySetDefinitions/a169a624-5599-4385-a696-c8d643089fab" = [ + "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c", + "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" + ], + "/providers/Microsoft.Authorization/policyDefinitions/f4c68484-132f-41f9-9b6d-3e4b1cb55036" = [ + "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635" + ] + } +``` + +### **Override Module Role Assignments** + +![Override-Module-Role-Assignments-03](./media/examples-override-module-role-assignments-03.png) + +![Override-Module-Role-Assignments-04](./media/examples-override-module-role-assignments-04.png) + +You have successfully override the built-in role definitions using the `custom_policy_roles` feature of Enterprise-scale module. diff --git a/docs/wiki/[User-Guide]-Archetype-Definitions.md b/docs/wiki/[User-Guide]-Archetype-Definitions.md new file mode 100644 index 000000000..a525a2b00 --- /dev/null +++ b/docs/wiki/[User-Guide]-Archetype-Definitions.md @@ -0,0 +1,155 @@ +## What is an archetype? + +Archetypes are used in the Enterprise-scale architecture to describe the Landing Zone configuration using a template-driven approach. The archetype is what fundamentally transforms ***Management Groups*** and ***Subscriptions*** into ***Landing Zones***. + +An archetype defines which Azure Policy and Access control (IAM) settings are needed to secure and configure the Landing Zones with everything needed for safe handover to the Landing Zone owner. This covers critical platform controls and configuration items, such as: + +- Consistent role-based access control (RBAC) settings +- Guardrails for security settings +- Guardrails for common workload configurations (e.g. SAP, AKS, WVD, etc.) +- Automate provisioning of critical platform resources such as monitoring and networking solutions in each Landing Zone + +This approach provides improved autonomy for application teams, whilst ensuring security policies and standards are enforced. + +## Working with archetype definitions and the custom library + +The `archetype_definition` is a template file written in JSON or YAML. The default archetype definitions can be found in the [built-in module library][TFAES-Library], but custom archetype definitions can also be added to a custom library in the root module. +The archetype definition is associated to the scope (i.e. Management Group) by specifying the `archetype_id` within the ***Landing Zone*** configuration object. + +Both the built-in and custom libraries are also used to store ARM based templates for the Policy Assignments, Policy Definitions, Policy Set Definitions (Initiatives) and Role Definitions. Role Assignments are an exception as these are defined as part of the `archetype_config` instead. + +To use a custom library, simply create a folder in your root module (e.g. `/lib`) and tell the module about it using the `library_path` variable (e.g. `library_path = "${path.root}/lib"`). Save your custom templates in the custom library location and as long as they are valid templates for the resource type and match the following naming conventions, the module will automatically import and use them: + +| Resource Type | File Name Pattern | +| ------------- | ----------------- | +| Archetype Definitions | `**/archetype_definition_*.{json,yml,yaml}` | +| Policy Assignments | `**/policy_assignment_*.{json,yml,yaml}` | +| Policy Definitions | `**/policy_definition_*.{json,yml,yaml}` | +| Policy Set Definitions | `**/policy_set_definition_*.{json,yml,yaml}` | +| Role Definitions | `**/role_definition_*.{json,yml,yaml}` | + +> The decision to store Policy Assignments, Policy Definitions, Policy Set Definitions (Initiatives) and Role Definitions as native ARM was based on a number of factors: +> +>- Policies in Terraform require you to understand how to write significant sections of the resource configuration in the native ARM format, and then convert this to a JSON string within Terraform resource. +>- Using a native ARM format makes copying these template assets between ARM and Terraform much easier. +>- Terraform doesn't support importing data objects from native Terraform file formats (`.hcl`, `.tf` or `.tfvar`) so we had to use an alternative to be able to support the custom library model for extensibility and customisation. +> +> **PRO TIP:** The module also supports YAML for these files as long as they match the ARM schema. + +This template driven approach is designed to simplify the process of defining an archetype and forms the foundations for how the module is able to provide feature-rich defaults, whilst also allowing a great degree of extensibility and customisation through the input variables instead of having to fork and modify the module. + +The `archetype_definition` template contains lists of the Policy Assignments, Policy Definitions, Policy Set Definitions (Initiatives) and Role Definitions you want to create when assigning the archetype to a Management Group. It also includes the ability to set default values for parameters associated with Policy Assignments, and set default Role Assignments. + +To keep the `archetype_definition` template as lean as possible, we simply declare the value of the `name` field from the resource templates (by type). The exception is Role Definitions which must have a GUID for the `name` field, so we use the `roleName` value from `properties` instead. + +As long as you follows these patterns, you can create your own archetype definitions to start advanced customisation of your Enterprise-scale deployment. + +This template-based approach was chosen to make the desired-state easier to understand, simplify the process of managing configuration and versioning, reduce code duplication (DRY), and to improve consistency in complex environments. + +### Example archetype definition + +```json +{ + "archetype_id": { + "policy_assignments": [ + // List of Policy Assignments, as per the "name" field in the library templates + "Policy-Assignment-Name-1", + "Policy-Assignment-Name-2", + "Policy-Assignment-Name-3" + ], + "policy_definitions": [ + // List of Policy Definitions, as per the "name" field in the library templates + // We recommend only creating Policy Definitions at the root_id scope + "Policy-Definition-Name-1", + "Policy-Definition-Name-2", + "Policy-Definition-Name-3", + "Policy-Definition-Name-4", + "Policy-Definition-Name-5", + "Policy-Definition-Name-6" + ], + "policy_set_definitions": [ + // List of Policy Set Definitions, as per the "name" field in the library templates + // We recommend only creating Policy Set Definitions at the root_id scope + "Policy-Set-Definition-Name-1", + "Policy-Set-Definition-Name-2" + ], + "role_definitions": [ + // List of Role Definitions, as per the "properties.roleName" field in the library templates + // We recommend only creating Role Definitions at the root_id scope + "Role-Definition-Name-1" + ], + "archetype_config": { + "parameters": { + // Map of parameters, grouped by Policy Assignment + // Key should match the "name" field from Policy Assignment + // Value should be a map containing key-value pairs for each parameter + "Policy-Assignment-Name-1": { + "parameterName1": "myStringValue", + "parameterName2": 100, + "parameterName3": true, + "parameterName4": [ + "myListValue1", + "myListValue2", + "myListValue3" + ], + "parameterName5": { + "myObjectKey1": "myObjectValue1", + "myObjectKey2": "myObjectValue2", + "myObjectKey3": "myObjectValue3" + } + } + }, + "access_control": { + // Map of Role Assignments to create, grouped by Role Definition name + // Key should match the "name" of the Role Definition to assign + // Value should be a list of strings, specifying the Object Id(s) (from Azure AD) of all identities to assign to the role + "Reader": [ + "00000000-0000-0000-0000-000000000000", + "11111111-1111-1111-1111-111111111111", + "22222222-2222-2222-2222-222222222222" + ], + "Role-Definition-Name-1": [ + "33333333-3333-3333-3333-333333333333" + ] + } + } + } +} +``` + +> **WARNING** The `jsondecode()` function used by Terraform doesn't support comments in JSON. Please also note that HCL objects are Case-Sensitive so the JSON object must be created with the correct character case on anything referenced by Terraform. +> Typically this applies to each `key` in an object but there are also situations where the `value` also needs to be interpreted by the module. For archetype definitions, the case of all values within each section must match those used in the mapped field for each template being assigned. Incorrect casing can result in `terraform plan` identifying unnecessary resource updates. +> For example, the Azure REST API returns `"type": "String"` in parameter blocks, regardless of what case was used to create the resource. Not using the same casing in your source templates can result in Terraform trying to update resources when no real changes have occurred. + +### Using the `default_empty` archetype definition + +Specifying an `archetype_id` value is mandatory for all Management Groups created by the module. + +The default library includes a `default_empty` archetype definition which is useful when defining Management Groups which only require Role Assignments, or are being used for logical segregation of Landing Zones under a parent arcehtype. You can assign this to any Landing Zone definition, using the `archetype_config` > `archetype_id` value as per the following `custom_landing_zones` example: + +```hcl + custom_landing_zones = { + example-landing-zone-id = { + display_name = "Example Landing Zone" + parent_management_group_id = "tf-landing-zones" + subscription_ids = [] + archetype_config = { + archetype_id = "default_empty" + parameters = {} + access_control = {} + } + } + } +``` + +This is equivalent to creating a standard Management Group without creating any custom Policy Assignments, Policy Definitions, Policy Set Definitions (Initiatives) or Role Definitions. + +Role Assignments can be created using the `custom_landing_zones.${management_group_id}.archetype_config.access_control` object scope. + +> Note that you still need to provide a full and valid Landing Zone object as per the example above. + + [//]: # (************************) + [//]: # (INSERT LINK LABELS BELOW) + [//]: # (************************) + +[TFAES-Library]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/tree/main/modules/archetypes/lib diff --git a/docs/wiki/[User-Guide]-Deploy-Management-Resources.md b/docs/wiki/[User-Guide]-Deploy-Management-Resources.md new file mode 100644 index 000000000..3c2fcf74b --- /dev/null +++ b/docs/wiki/[User-Guide]-Deploy-Management-Resources.md @@ -0,0 +1 @@ +_coming soon_ \ No newline at end of file diff --git a/docs/wiki/[User-Guide]-Getting-Started.md b/docs/wiki/[User-Guide]-Getting-Started.md new file mode 100644 index 000000000..9f33c5e9b --- /dev/null +++ b/docs/wiki/[User-Guide]-Getting-Started.md @@ -0,0 +1,59 @@ +## Considerations + +Before getting started with this module, please take note of the following considerations: + +1. This module requires a minimum `azurerm` provider version of `2.41.0`. + +2. This module requires a minimum Terraform version `0.13.2`. + + > **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 customise 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](./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][wiki_upgrade_from_v0_0_8_to_v0_1_0] 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][wiki_upgrade_from_v0_1_2_to_v0_2_0] for more information. + +8. Release version `0.2.0` also adds new functionality to enable deployment of [Management and monitoring][ESLZ-Management] resources into the current Subscription context. +Please refer to the [Deploy Management Resources][wiki_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](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/releases/tag/v0.3.0). + +## Provisioning Instructions + +Copy and paste the following 'module' block into your Terraform configuration, insert the required and optional [variables](%5BUser-Guide%5D-Module-Variables) needed for your configuration, and run `terraform init`: + +```hcl +module "caf-enterprise-scale" { + source = "Azure/caf-enterprise-scale/azurerm" + version = "0.2.0" + # insert the 1 required variable here +} +``` + +For more detailed instructions, follow the [next steps](#next-steps) listed below or go straight to our [Examples](./Examples). + +## Next steps + +Learn how to use the [Module Variables](%5BUser-Guide%5D-Module-Variables) to customise the module configuration. + + +[wiki_upgrade_from_v0_0_8_to_v0_1_0]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Upgrade-from-v0.0.8-to-v0.1.0 "Wiki - Upgrade from v0.0.8 to v0.1.0" +[wiki_upgrade_from_v0_1_2_to_v0_2_0]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Upgrade-from-v0.1.2-to-v0.2.0 "Wiki - Upgrade from v0.1.2 to v0.2.0" +[wiki_deploy_management_resources]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Deploy-Management-Resources "Wiki - Deploy Management Resources" + +[ESLZ-Management]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/management-and-monitoring diff --git a/docs/wiki/[User-Guide]-Module-Variables.md b/docs/wiki/[User-Guide]-Module-Variables.md new file mode 100644 index 000000000..ae8601629 --- /dev/null +++ b/docs/wiki/[User-Guide]-Module-Variables.md @@ -0,0 +1,160 @@ +The module can be customised using the following input variables (click on each `input name` for more details): + +## Required Inputs + +These variables must be set in the `module` block when using this module. + +
+ +[**root_parent_id**][root_parent_id] `string` + +The root_parent_id is used to specify where to set the root for all Landing Zone deployments. Usually the Tenant ID when deploying the core Enterprise-scale Landing Zones. + +
+ +## Optional Inputs + +These variables have default values and don't have to be set to use this module. You may set these variables in the `module` block to override their default values. + +
+ +[**archetype_config_overrides**][archetype_config_overrides] `map(any)` + +If specified, will set custom Archetype configurations to the default Enterprise-scale Management Groups. + +Default: `{}` + +
+ +[**create_duration_delay**][create_duration_delay] `map(string)` + +Used to tune `terraform apply` when faced with errors caused by API caching or eventual consistency. Sets a custom delay period after creation of the specified resource type. + +Default: + +```hcl +{ + azurerm_management_group = "30s" + azurerm_policy_assignment = "30s" + azurerm_policy_definition = "30s" + azurerm_policy_set_definition = "30s" + azurerm_role_assignment = "0s" + azurerm_role_definition = "60s" +} +``` + +
+ +[**custom_landing_zones**][custom_landing_zones] `map( object({ display_name = string parent_management_group_id = string subscription_ids = list(string) archetype_config = object({ archetype_id = string parameters = any access_control = any }) }) )` + +If specified, will deploy additional Management Groups alongside Enterprise-scale core Management Groups. + +Default: `{}` + +
+ +[**default_location**][default_location] `string` + +If specified, will use set the default location used for resource deployments where needed. #check_value will use set the default == is wording right? + +Default: `"eastus"` + +
+ +[**deploy_core_landing_zones**][deploy_core_landing_zones] `bool` + +If set to true, will include the core Enterprise-scale Management Group hierarchy. + +Default: `true` + +
+ +[**deploy_demo_landing_zones**][deploy_demo_landing_zones] `bool` + +If set to true, will include the demo "Landing Zone" Management Groups. + +Default: `false` + +
+ +[**destroy_duration_delay**][destroy_duration_delay] `map(string)` + +Used to tune terraform deploy when faced with errors caused by API caching or eventual consistency. Sets a custom delay period after destruction of the specified resource type. ##check_value tune terraform deploy == terraform destroy? + +Default: + +```hcl +{ + azurerm_management_group = "0s" + azurerm_policy_assignment = "0s" + azurerm_policy_definition = "0s" + azurerm_policy_set_definition = "0s" + azurerm_role_assignment = "0s" + azurerm_role_definition = "0s" +} +``` + +
+ +[**library_path**][library_path] `string` + +If specified, sets the path to a custom library folder for archetype artefacts. #check_value artefacts == is it artifacts? Update the code vars code + +Default: `""` +
+ +[**root_id**][root_id] `string` + +If specified, will set a custom Name (ID) value for the Enterprise-scale "root" Management Group, and append this to the ID for all core Enterprise-scale Management Groups. + +Default: `"es"` + +
+ +[**root_name**][root_name] `string` + +If specified, will set a custom DisplayName value for the Enterprise-scale "root" Management Group. + +Default: `"Enterprise-Scale"` + +
+ +[**subscription_id_overrides**][subscription_id_overrides] `map(list(string))` + +If specified, will be used to assign subscription_ids to the default Enterprise-scale Management Groups. + +Default: `{}` + +
+ +[**template_file_variables**][template_file_variables] `map(any)` + +If specified, provides the ability to define custom template variables used when reading in template files from the built-in and custom library_path. + +Default: `{}` + +
+ +A summary of these variables can also be found on the [Inputs][estf-inputs] tab of the module entry in Terraform Registry. + +## Next steps + +Now you understand how to customize your deployment using the input variables, check out our [Examples](./Examples). + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[estf-inputs]: https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest?tab=inputs "Terraform Registry: Terraform Module for Cloud Adoption Framework Enterprise-scale - Inputs" +[root_parent_id]: ./%5BVariables%5D-root_parent_id "Instructions for how to use the root_parent_id variable." +[root_id]: ./%5BVariables%5D-root_id "Instructions for how to use the root_id variable." +[root_name]: ./%5BVariables%5D-root_name "Instructions for how to use the root_name variable." +[deploy_core_landing_zones]: ./%5BVariables%5D-deploy_core_landing_zones "Instructions for how to use the deploy_core_landing_zones variable." +[archetype_config_overrides]: ./%5BVariables%5D-archetype_config_overrides "Instructions for how to use the archetype_config_overrides variable." +[subscription_id_overrides]: ./%5BVariables%5D-subscription_id_overrides "Instructions for how to use the subscription_id_overrides variable." +[deploy_demo_landing_zones]: ./%5BVariables%5D-deploy_demo_landing_zones "Instructions for how to use the deploy_demo_landing_zones variable." +[custom_landing_zones]: ./%5BVariables%5D-custom_landing_zones "Instructions for how to use the custom_landing_zones variable." +[library_path]: ./%5BVariables%5D-library_path "Instructions for how to use the library_path variable." +[template_file_variables]: ./%5BVariables%5D-template_file_variables "Instructions for how to use the template_file_variables variable." +[default_location]: ./%5BVariables%5D-default_location "Instructions for how to use the default_location variable." +[create_duration_delay]: ./%5BVariables%5D-create_duration_delay "Instructions for how to use the create_duration_delay variable." +[destroy_duration_delay]: ./%5BVariables%5D-destroy_duration_delay "Instructions for how to use the destroy_duration_delay variable." diff --git a/docs/wiki/[User-Guide]-Upgrade-from-v0.0.8-to-v0.1.0.md b/docs/wiki/[User-Guide]-Upgrade-from-v0.0.8-to-v0.1.0.md new file mode 100644 index 000000000..73e0f464c --- /dev/null +++ b/docs/wiki/[User-Guide]-Upgrade-from-v0.0.8-to-v0.1.0.md @@ -0,0 +1,257 @@ +## Overview + +As part of upgrade from release 0.0.8 to 0.1.0, the [Terraform Module for Cloud Adoption Framework Enterprise-scale][terraform-registry-caf-enterprise-scale] has undergone a significant update to the included `Policy Assignments`, `Policy Definitions` and `Policy Set Definitions`. + +This update was needed to bring this module up to date with the latest reference architecture published in the [Azure/Enterprise-Scale][azure/enterprise-scale] repository. + +## Required actions + +Anyone using this module should be aware of the following when planning to upgrade from release 0.0.8 to 0.1.0: + +1. Due to the extent of updates, all policies and roles provided as part of this module will be redeployed. Please carefully review the output of `terraform plan` to ensure there are no issues with any custom configuration within your root module. +1. If you are using custom templates, you will need to verify references to policies and roles defined within this module. +1. The following template types will need checking for references to policies and roles as listed in the [resource changes](#resource-changes) section below: + 1. Archetype Definitions + 1. Policy Assignments + 1. Policy Set Definitions +1. The list of Policy Assignments deployed by the archetype definitions included with this module have been updated to reflect the Enterprise-scale reference architecture. Please review these before updating your environment to prevent unexpected issues. + +## Resource changes + +The following changes have been made within the module which may cause issues when using custom archetype definitions: + +- All policy and role names have been updated to reflect the names used within the reference [Azure/Enterprise-Scale][azure/enterprise-scale] repository. This means the `ES-` prefix has been removed, and some names have been changed (see lists below). +- All policies and roles are referenced by the `name` field. Previously we referenced the `properties.displayName` field. Please ensure any custom policy and role templates are updated to ensure the correct name is present in the `name` field. This change allows you to set a more user-friendly display name for these resources. +- The following archetype definitions have been updated (details in the [Archetype Definitions](#archetype-definitions-changes) section below): + - es_root + - es_landing_zones + - es_management + +> NOTE: All references to resource names are **_Case Sensitive_**. Failure to use the correct case will result in an `Invalid index` error when running `terraform plan`, such as the following example: + +```shell +Error: Invalid index + + on ../../modules/archetypes/locals.policy_definitions.tf line 82, in locals: + 82: template = local.archetype_policy_definitions_map[policy] + |---------------- + | local.archetype_policy_definitions_map is object with 100 attributes + +The given key does not identify an element in this collection value. +``` + +### Resource type: `azurerm_policy_assignment` + +| Policy Assignment Name (v0.0.8) | Policy Assignment Name (v0.1.0) | Notes | +| :------------------------------ | :------------------------------ | :---- | +| ES-Allowed-Locations | Deny-Resource-Locations | | +| ES-Allowed-RSG-Locations | Deny-RSG-Locations | | +| ES-Deny-AppGW-No-WAF | Deny-AppGW-Without-WAF | | +| | Deny-http-Ingress-AKS" | (new) | +| ES-Deny-VMIPForwarding | Deny-IP-Forwarding | | +| | Deny-Priv-Containers-AKS | (new) | +| | Deny-Priv-Escalation-AKS | (new) | +| ES-Deny-RDPFromInternet | Deny-RDP-From-Internet | | +| ES-Deny-ResourceTypes | Deny-Resource-Types | | +| | Deny-Storage-http | (new) | +| ES-Deny-SubnetWithoutNsg | Deny-Subnet-Without-Nsg | | +| | Deploy-AKS-Policy | (new) | +| ES-Deploy-ASC-Standard | Deploy-ASC-Defender | | +| ES-Deploy-ASC-Monitoring | Deploy-ASC-Monitoring | | +| | Deploy-AzActivity-Log | (new) | +| | Deploy-Log-Analytics | (new) | +| | Deploy-LX-Arc-Monitoring | (new) | +| | Deploy-Resource-Diag | (new) | +| | Deploy-SQL-DB-Auditing | (new) | +| | Deploy-SQL-Security | (new) | +| | Deploy-VM-Backup | (new) | +| | Deploy-VM-Monitoring | (new) | +| | Deploy-VMSS-Monitoring | (new) | +| | Deploy-WS-Arc-Monitoring | (new) | + +### Resource type: `azurerm_policy_definition` + +| Policy Definition Name (v0.0.8) | Policy Definition Name (v0.1.0) | Notes | +| :-------------------------------------------------- | :----------------------------------------------- | :------------------ | +| ES-Append-KV-SoftDelete | Append-KV-SoftDelete | | +| ES-Deny-AA-child-resources | Deny-AA-child-resources | | +| ES-Deny-AppGW-Without-WAF | Deny-AppGW-Without-WAF | | +| ES-Deny-ERPeering | | (moved to built-in) | +| ES-Deny-Private-DNS-Zones | Deny-Private-DNS-Zones | | +| ES-Deny-PublicEndpoint-Aks | Deny-PublicEndpoint-Aks | | +| ES-Deny-PublicEndpoint-CosmosDB | Deny-PublicEndpoint-CosmosDB | | +| ES-Deny-PublicEndpoint-KeyVault | Deny-PublicEndpoint-KeyVault | | +| ES-Deny-PublicEndpoint-MariaDB | Deny-PublicEndpoint-MariaDB | | +| ES-Deny-PublicEndpoint-MySQL | Deny-PublicEndpoint-MySQL | | +| ES-Deny-PublicEndpoint-PostgreSql | Deny-PublicEndpoint-PostgreSql | | +| ES-Deny-PublicEndpoint-Sql | Deny-PublicEndpoint-Sql | | +| ES-Deny-PublicEndpoint-Storage | Deny-PublicEndpoint-Storage | | +| ES-Deny-PublicIP | Deny-PublicIP | | +| | Deny-RDP-From-Internet | (new) | +| ES-Deny-Subnets-Without-NSG | Deny-Subnet-Without-Nsg | | +| ES-Deny-Subnets-Without-UDR | Deny-Subnet-Without-Udr | | +| | Deny-VNET-Peer-Cross-Sub | (new) | +| | Deny-VNet-Peering | (new) | +| ES-Deploy-ASC-ContinuousExportToWorkspace | | (moved to built-in) | +| ES-Deploy-ASC-Standard | Deploy-ASC-Standard | | +| | Deploy-Budget | (new) | +| ES-Deploy-AzureBackup-on-VMs | | (moved to built-in) | +| ES-Deploy-DDoSProtection | Deploy-DDoSProtection | | +| ES-Deploy-Diagnostics-AA | Deploy-Diagnostics-AA | | +| ES-Deploy-Diagnostics-ACI | Deploy-Diagnostics-ACI | | +| ES-Deploy-Diagnostics-ACR | Deploy-Diagnostics-ACR | | +| ES-Deploy-Diagnostics-ActivityLog | Deploy-Diagnostics-ActivityLog | | +| ES-Deploy-Diagnostics-AKS | Deploy-Diagnostics-AKS | | +| ES-Deploy-Diagnostics-AnalysisService | Deploy-Diagnostics-AnalysisService | | +| ES-Deploy-Diagnostics-APIMgmt | Deploy-Diagnostics-APIMgmt | | +| ES-Deploy-Diagnostics-ApplicationGateway | Deploy-Diagnostics-ApplicationGateway | | +| ES-Deploy-Diagnostics-Batch | Deploy-Diagnostics-Batch | | +| ES-Deploy-Diagnostics-CDNEndpoints | Deploy-Diagnostics-CDNEndpoints | | +| ES-Deploy-Diagnostics-CognitiveServices | Deploy-Diagnostics-CognitiveServices | | +| ES-Deploy-Diagnostics-CosmosDB | Deploy-Diagnostics-CosmosDB | | +| | Deploy-Diagnostics-Databricks | (new) | +| ES-Deploy-Diagnostics-DataFactory | Deploy-Diagnostics-DataFactory | | +| ES-Deploy-Diagnostics-DataLakeStore | Deploy-Diagnostics-DataLakeStore | | +| ES-Deploy-Diagnostics-DLAnalytics | Deploy-Diagnostics-DLAnalytics | | +| ES-Deploy-Diagnostics-EventGridSub | Deploy-Diagnostics-EventGridSub | | +| | Deploy-Diagnostics-EventGridSystemTopic | (new) | +| ES-Deploy-Diagnostics-EventGridTopic | Deploy-Diagnostics-EventGridTopic | | +| ES-Deploy-Diagnostics-EventHub | Deploy-Diagnostics-EventHub | | +| ES-Deploy-Diagnostics-ExpressRoute | Deploy-Diagnostics-ExpressRoute | | +| ES-Deploy-Diagnostics-Firewall | Deploy-Diagnostics-Firewall | | +| | Deploy-Diagnostics-FrontDoor | (new) | +| | Deploy-Diagnostics-Function | (new) | +| ES-Deploy-Diagnostics-HDInsight | Deploy-Diagnostics-HDInsight | | +| ES-Deploy-Diagnostics-iotHub | Deploy-Diagnostics-iotHub | | +| ES-Deploy-Diagnostics-KeyVault | Deploy-Diagnostics-KeyVault | | +| ES-Deploy-Diagnostics-LoadBalancer | Deploy-Diagnostics-LoadBalancer | | +| ES-Deploy-Diagnostics-LogicAppsISE | Deploy-Diagnostics-LogicAppsISE | | +| ES-Deploy-Diagnostics-LogicAppsWF | Deploy-Diagnostics-LogicAppsWF | | +| | Deploy-Diagnostics-MariaDB | (new) | +| ES-Deploy-Diagnostics-MlWorkspace | Deploy-Diagnostics-MlWorkspace | | +| ES-Deploy-Diagnostics-MySQL | Deploy-Diagnostics-MySQL | | +| ES-Deploy-Diagnostics-NetworkSecurityGroups | Deploy-Diagnostics-NetworkSecurityGroups | | +| ES-Deploy-Diagnostics-NIC | Deploy-Diagnostics-NIC | | +| ES-Deploy-Diagnostics-PostgreSQL | Deploy-Diagnostics-PostgreSQL | | +| ES-Deploy-Diagnostics-PowerBIEmbedded | Deploy-Diagnostics-PowerBIEmbedded | | +| ES-Deploy-Diagnostics-PublicIP | Deploy-Diagnostics-PublicIP | | +| ES-Deploy-Diagnostics-RecoveryVault | Deploy-Diagnostics-RecoveryVault | | +| ES-Deploy-Diagnostics-RedisCache | Deploy-Diagnostics-RedisCache | | +| ES-Deploy-Diagnostics-Relay | Deploy-Diagnostics-Relay | | +| ES-Deploy-Diagnostics-SearchServices | Deploy-Diagnostics-SearchServices | | +| ES-Deploy-Diagnostics-ServiceBus | Deploy-Diagnostics-ServiceBus | | +| ES-Deploy-Diagnostics-SignalR | Deploy-Diagnostics-SignalR | | +| ES-Deploy-Diagnostics-SQLDBs | Deploy-Diagnostics-SQLDBs | | +| ES-Deploy-Diagnostics-SQLElasticPools | Deploy-Diagnostics-SQLElasticPools | | +| ES-Deploy-Diagnostics-SQLMI | Deploy-Diagnostics-SQLMI | | +| ES-Deploy-Diagnostics-StreamAnalytics | Deploy-Diagnostics-StreamAnalytics | | +| ES-Deploy-Diagnostics-TimeSeriesInsights | Deploy-Diagnostics-TimeSeriesInsights | | +| ES-Deploy-Diagnostics-TrafficManager | Deploy-Diagnostics-TrafficManager | | +| ES-Deploy-Diagnostics-VirtualNetwork | Deploy-Diagnostics-VirtualNetwork | | +| ES-Deploy-Diagnostics-VM | Deploy-Diagnostics-VM | | +| ES-Deploy-Diagnostics-VMSS | Deploy-Diagnostics-VMSS | | +| ES-Deploy-Diagnostics-VNetGW | Deploy-Diagnostics-VNetGW | | +| ES-Deploy-Diagnostics-WebServerFarm | Deploy-Diagnostics-WebServerFarm | | +| ES-Deploy-Diagnostics-Website | Deploy-Diagnostics-Website | | +| | Deploy-Diagnostics-WVDAppGroup | (new) | +| | Deploy-Diagnostics-WVDHostPools | (new) | +| | Deploy-Diagnostics-WVDWorkspace | (new) | +| ES-Deploy-DNSZoneGroup-For-Blob-PrivateEndpoint | Deploy-DNSZoneGroup-For-Blob-PrivateEndpoint | | +| ES-Deploy-DNSZoneGroup-For-File-PrivateEndpoint | Deploy-DNSZoneGroup-For-File-PrivateEndpoint | | +| ES-Deploy-DNSZoneGroup-For-KeyVault-PrivateEndpoint | Deploy-DNSZoneGroup-For-KeyVault-PrivateEndpoint | | +| ES-Deploy-DNSZoneGroup-For-Queue-PrivateEndpoint | Deploy-DNSZoneGroup-For-Queue-PrivateEndpoint | | +| ES-Deploy-DNSZoneGroup-For-Sql-PrivateEndpoint | Deploy-DNSZoneGroup-For-Sql-PrivateEndpoint | | +| ES-Deploy-DNSZoneGroup-For-Table-PrivateEndpoint | Deploy-DNSZoneGroup-For-Table-PrivateEndpoint | | +| ES-Deploy-FirewallPolicy | Deploy-FirewallPolicy | | +| ES-Deploy-HUB | Deploy-HUB | | +| ES-Deploy-LA-Config | Deploy-LA-Config | | +| ES-Deploy-LogAnalytics | Deploy-Log-Analytics | | +| ES-Deploy-Nsg-FlowLogs | Deploy-Nsg-FlowLogs-to-LA | | +| ES-Deploy-Sql-AuditingSettings | Deploy-Sql-AuditingSettings | | +| ES-Deploy-Sql-SecurityAlertPolicies | Deploy-Sql-SecurityAlertPolicies | | +| ES-Deploy-Sql-Tde | Deploy-Sql-Tde | | +| ES-Deploy-Sql-VulnerabilityAssessments | Deploy-Sql-vulnerabilityAssessments | | +| ES-Deploy-vHUB | Deploy-vHUB | | +| | Deploy-VNET-HubSpoke | (new) | +| ES-Deploy-vNet | Deploy-vNet | | +| ES-Deploy-vWAN | Deploy-vWAN | | +| ES-Deploy-Windows-DomainJoin | Deploy-Windows-DomainJoin | | + +### Resource type: `azurerm_policy_set_definition` + +| Policy Set Definition Name (v0.0.8) | Policy Set Definition Name (v0.1.0) | Notes | +| :----------------------------------------- | :---------------------------------- | :---- | +| ES-Deny-Public-Endpoints-for-PaaS-Services | Deny-PublicEndpoints | | +| ES-Deploy-Diagnostics-LogAnalytics | Deploy-Diag-LogAnalytics | | +| ES-Deploy-Sql-Security | Deploy-Sql-Security | | + +### Resource type: `azurerm_role_definition` + +| Role Definition Name (v0.0.8) | Role Definition Name (v0.1.0) | Notes | +| :---------------------------- | :---------------------------- | :---- | +| ES-Network-Subnet-Contributor | Network-Subnet-Contributor | | + +## Archetype definitions changes + +To reflect the updated policies, and ensure policies are assigned according to the foundation implementation of Enterprise-scale, the following updates were made to the archetype definitions: + +### es_root + +In a default configuration, the `es_root` archetype definition is applied to the `${var.root_id}` Management Group. This is the default scope for all custom Policy Definitions, Policy Set Definitions (Initiatives), and Role Definitions defined by Enterprise-scale but is also where user-defined definitions should be created. +This ensures all definitions are available for assignment anywhere within the Enterprise-scale Management Group hierarchy. + +As such, this archetype definition contains references for ALL of the Policy Definitions, Policy Set Definitions (Initiatives), and Role Definitions listed in the previous sections. + +To bring this in alignment with the Enterprise-scale reference architecture, the following changes will be made to the Policy Assignments created by this archetype from v0.1.0 onwards: + + +| Policy Assignments (v0.0.8) | Policy Assignments (v0.1.0) | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ES-Allowed-Locations
ES-Allowed-RSG-Locations
ES-Deny-AppGW-No-WAF
ES-Deny-VMIPForwarding
ES-Deny-RDPFromInternet
ES-Deny-ResourceTypes
ES-Deny-SubnetWithoutNsg
ES-Deploy-ASC-Monitoring
ES-Deploy-ASC-Standard | Deploy-ASC-Monitoring
Deploy-ASC-Defender
Deploy-AzActivity-Log
Deploy-LX-Arc-Monitoring
Deploy-Resource-Diag
Deploy-VM-Monitoring
Deploy-VMSS-Monitoring
Deploy-WS-Arc-Monitoring

| + + +If you are using a copy of this archetype in your custom library (as specified using the `library_path` variable), please ensure you update all applicable resource names from the v0.0.8 format to v0.1.0. + +> The policy assignments for `ES-Allowed-Locations` and `ES-Allowed-RSG-Locations` do not form part of the official Enterprise-scale reference architecture foundation policy assignments so are no longer assigned by default, but are still available within the module using the new names `Deny-Resource-Locations` and `Deny-RSG-Locations`. + +### es_landing_zones + +In a default configuration, the `es_landing_zones` archetype definition is applied to the `${var.root_id}-landing-zones` Management Group. Previously this archetype contained no entries (equivalent to the `default_empty` archetype.) + +To bring this in alignment with the Enterprise-scale reference architecture, the following Policy Assignments will now be created by this archetype from v0.1.0 onwards: + +- Deny-IP-Forwarding +- Deny-RDP-From-Internet +- Deny-Storage-http +- Deny-Subnet-Without-Nsg +- Deploy-AKS-Policy +- Deploy-SQL-DB-Auditing +- Deploy-VM-Backup +- Deploy-SQL-Security +- Deny-Priv-Escalation-AKS +- Deny-Priv-Containers-AKS +- Deny-http-Ingress-AKS + +### es_management + +In a default configuration, the `es_management` archetype definition is applied to the `${var.root_id}-management` Management Group. Previously this archetype contained no entries (equivalent to the `default_empty` archetype.) + +To bring this in alignment with the Enterprise-scale reference architecture, the following Policy Assignments will now be created by this archetype from v0.1.0 onwards: + +- Deploy-Log-Analytics + +## Will this happen again? + +Unfortunately this question is hard to answer, but our intent is to keep future updates to policies in smaller increments so the impact will be smaller. + +To help with this, we have automated the process used to keep the policies in sync, allowing us to more quickly and easily manage future updates in smaller and more frequent increments. None should also be as dramatic as this update. + +## Next steps + +Take a look at the latest [User Guide](./User-Guide) documentation and our [Examples](./Examples) to understand the latest module configuration options, and review your implementation against the changes documented on this page. + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[terraform-registry-caf-enterprise-scale]: https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest "Terraform Registry: Terraform Module for Cloud Adoption Framework Enterprise-scale" +[azure/enterprise-scale]: https://github.com/Azure/Enterprise-Scale diff --git a/docs/wiki/[User-Guide]-Upgrade-from-v0.1.2-to-v0.2.0.md b/docs/wiki/[User-Guide]-Upgrade-from-v0.1.2-to-v0.2.0.md new file mode 100644 index 000000000..4bfea6231 --- /dev/null +++ b/docs/wiki/[User-Guide]-Upgrade-from-v0.1.2-to-v0.2.0.md @@ -0,0 +1,82 @@ +## Overview + +As part of upgrade from release 0.1.2 to 0.2.0, the [Terraform Module for Cloud Adoption Framework Enterprise-scale][terraform-registry-caf-enterprise-scale] has updates to the included `Policy Definitions` and `Policy Set Definitions`. + +This update helps to keep this module up to date with the latest reference architecture published in the [Azure/Enterprise-Scale][azure/enterprise-scale] repository. + +## Required actions + +Anyone using this module should be aware of the following when planning to upgrade from release 0.1.2 to 0.2.0: + +1. A select number of policies and roles provided as part of this module will be redeployed. Please carefully review the output of `terraform plan` to ensure there are no issues with any custom configuration within your root module. +1. If you are using custom templates, you will need to verify references to policies defined within this module. +1. The following template types will need checking for references to policies as listed in the [resource changes](#resource-changes) section below: + 1. Archetype Definitions + 1. Policy Assignments + 1. Policy Set Definitions +1. This update adds new functionality to enable deployment of [Management and monitoring][ESLZ-Management] resources into the current Subscription context. + +## Resource changes + +The following changes have been made within the module which may cause issues when using custom archetype definitions: + +- The `es_root` archetype definition has been updated to reflect the policy changes listed in the [resource changes](#resource-changes) section below. + +> NOTE: All references to resource names are **_Case Sensitive_**. Failure to use the correct case will result in an `Invalid index` error when running `terraform plan`, such as the following example: + +```shell +Error: Invalid index + + on ../../modules/archetypes/locals.policy_definitions.tf line 82, in locals: + 82: template = local.archetype_policy_definitions_map[policy] + |---------------- + | local.archetype_policy_definitions_map is object with 100 attributes + +The given key does not identify an element in this collection value. +``` + +### Resource type: `azurerm_policy_assignment` + +The `Deploy-ASC-Defender` Policy Assignment has been updated to use the new `Deploy-ASC-Config` Policy Set Definition, replacing the original `Deploy-ASC-Standard` Policy Definition. +This Policy Assignment now has the following additional parameters: + +- `emailSecurityContact` (required) +- `logAnalytics` (required) +- `pricingTierSqlServerVirtualMachines` (optional) + +### Resource type: `azurerm_policy_definition` + +| Policy Definition Name (v0.1.2) | Policy Definition Name (v0.2.0) | Notes | +| :------------------------------ | :------------------------------ | :-------- | +| Deploy-ASC-Standard | | (removed) | +| | Deploy-ASC-Defender-ACR | (new) | +| | Deploy-ASC-Defender-AKS | (new) | +| | Deploy-ASC-Defender-AKV | (new) | +| | Deploy-ASC-Defender-AppSrv | (new) | +| | Deploy-ASC-Defender-ARM | (new) | +| | Deploy-ASC-Defender-DNS | (new) | +| | Deploy-ASC-Defender-SA | (new) | +| | Deploy-ASC-Defender-Sql | (new) | +| | Deploy-ASC-Defender-SQLVM | (new) | +| | Deploy-ASC-Defender-VMs | (new) | +| | Deploy-ASC-SecurityContacts | (new) | +| Deploy-Diagnostics-PublicIP | | (removed) | + +### Resource type: `azurerm_policy_set_definition` + +| Policy Set Definition Name (v0.1.2) | Policy Set Definition Name (v0.2.0) | Notes | +| :---------------------------------- | :---------------------------------- | :---- | +| | Deploy-ASC-Config | (new) | + +## Next steps + +> **IMPORTANT** If you are using custom archetype definitions, please ensure you update this to reflect the above changes. + +Take a look at the latest [User Guide](./User-Guide) documentation and our [Examples](./Examples) to understand the latest module configuration options, and review your implementation against the changes documented on this page. + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[terraform-registry-caf-enterprise-scale]: https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest "Terraform Registry: Terraform Module for Cloud Adoption Framework Enterprise-scale" +[azure/enterprise-scale]: https://github.com/Azure/Enterprise-Scale +[ESLZ-Management]: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/enterprise-scale/management-and-monitoring diff --git a/docs/wiki/[Variables]-archetype_config_overrides.md b/docs/wiki/[Variables]-archetype_config_overrides.md new file mode 100644 index 000000000..a431bc9da --- /dev/null +++ b/docs/wiki/[Variables]-archetype_config_overrides.md @@ -0,0 +1,50 @@ +## Overview + +[**archetype_config_overrides**](#overview) `map` (optional) + +```hcl +map( + object({ + archetype_id = string + parameters = any + access_control = any + }) +) +``` + +If specified, will set custom Archetype configurations to the default Enterprise-scale Management Groups. + +## Default value + +`{}` + +## Validation + +None + +## Usage + +To override default configuration settings for the default Management Groups, update the `archetype_config_overrides` variable to contain a valid `archetype_config` object with the required settings for each Management Group to customize. + +Supported default Management Group IDs: + +**`root`**, **`decommissioned`**, **`sandboxes`**, **`landing-zones`**, **`platform`**, **`connectivity`**, **`management`**, **`identity`** + +```hcl + archetype_config_overrides = { + root = { + archetype_id = "" + parameters = {} + access_control = {} + } + } +``` + +The [`archetype_config`](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Archetype-Definitions) object must contain valid entries for the `archetype_id` `parameters`, and `access_control` attributes. + +> NOTE: This variable can also be used to customize the [demo Management Groups](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BVariables%5D-deploy_demo_landing_zones): `demo-corp`, `demo-online`, `demo-sap` + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-create_duration_delay.md b/docs/wiki/[Variables]-create_duration_delay.md new file mode 100644 index 000000000..6587170d5 --- /dev/null +++ b/docs/wiki/[Variables]-create_duration_delay.md @@ -0,0 +1,46 @@ +## Overview + +[**create_duration_delay**](#overview) `map(string)` (optional) + +Sets a custom delay period after creation of the specified resource type. Used to tune `terraform apply` when faced with errors caused by API caching or eventual consistency. + +## Default value + +```hcl +{ + azurerm_management_group = "30s" + azurerm_policy_assignment = "30s" + azurerm_policy_definition = "30s" + azurerm_policy_set_definition = "30s" + azurerm_role_assignment = "0s" + azurerm_role_definition = "60s" +} +``` + +## Validation + +Each `create_duration_delay` value must be a string containing the duration in numbers (1-6 digits) followed by the measure of time represented by s (seconds), m (minutes), or h (hours), matching the following RegEx: + +`^[0-9]{1,6}(s|m|h)$` + +## Usage + +Change the delay period of the specified resource type. + +```hcl +{ + azurerm_management_group = "30s" + azurerm_policy_assignment = "30s" + azurerm_policy_definition = "30s" + azurerm_policy_set_definition = "30s" + azurerm_role_assignment = "30s" + azurerm_role_definition = "90s" +} +``` + +> Important: Only supported for the resource type listed in the example above + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-custom_landing_zones.md b/docs/wiki/[Variables]-custom_landing_zones.md new file mode 100644 index 000000000..31d791597 --- /dev/null +++ b/docs/wiki/[Variables]-custom_landing_zones.md @@ -0,0 +1,64 @@ +## Overview + +[**custom_landing_zones**](#overview) `map` (optional) + +```hcl +variable "custom_landing_zones" { + type = map( + object({ + display_name = string + parent_management_group_id = string + subscription_ids = list(string) + archetype_config = object({ + archetype_id = string + parameters = any + access_control = any + }) + }) + ) +``` + +If specified, will deploy additional Management Groups alongside Enterprise-scale core Management Groups. + +## Default value + +`{}` + +## Validation + +The custom_landing_zones keys must be between 2 to 36 characters long and can only contain lowercase letters, numbers and hyphens, matching the following RegEx: + +`[a-z0-9-]{2,36}$` + +## Usage + +In a deployment when `custom_landing_zones` block is configured, will deploy additional Management Groups alongside core Management Groups. +The main block parameters are `display_name`, `parent_management_group_id`, `subscription_ids`and `archetype_config`. + +`display_name` is the name assigned to the Management Group. + +`parent_management_group_id` is the name of the parent Management Group and must be a valid Management Group ID. + +`subscription_ids` is an object containing a list of Subscription IDs to assign to the current Management Group. + +[`archetype_config`](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Archetype-Definitions) is used to configure archetype settings applied to each Management Group. This object must contain valid entries for the `archetype_id` `parameters`, and `access_control` attributes. + +```hcl + custom_landing_zones = { + myorg-1-customer-corp = { + display_name = "" + parent_management_group_id = "" + subscription_ids = [] + archetype_config = { + archetype_id = "" + parameters = {} + access_control = {} + } + } + } +``` + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-default_location.md b/docs/wiki/[Variables]-default_location.md new file mode 100644 index 000000000..07ca7ba72 --- /dev/null +++ b/docs/wiki/[Variables]-default_location.md @@ -0,0 +1,30 @@ +## Overview + +[**default_location**](#overview) `string` (optional) + +Set the Azure region in which region bound resources will be deployed. + +## Default value + +`"eastus"` + +## Validation + +None + +> Important: The default location must be a valid Azure region. + +## Usage + +Set the value to your [Azure region](https://azure.microsoft.com/en-gb/global-infrastructure/geographies/) of choice. + +```hcl + default_location = "uksouth" +``` + +> Tip: Changing this value will cause all location bound resources to be recreated + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-deploy_core_landing_zones.md b/docs/wiki/[Variables]-deploy_core_landing_zones.md new file mode 100644 index 000000000..4168cdba0 --- /dev/null +++ b/docs/wiki/[Variables]-deploy_core_landing_zones.md @@ -0,0 +1,35 @@ +## Overview + +[**deploy_core_landing_zones**](#overview) `bool` (optional) + +If set to true, will include the core Enterprise-scale Management Group hierarchy. + +## Default value + +`true` + +## Validation + +None + +## Usage + +Set the value to true or false. +If set to _false_ with all the other values as _default_, the module will deploy no resources. +This is for advanced scenarios such as: + +- Nested deployments (see [example](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Using-Module-Nesting)) +- Landing zone resources: + - Management (coming soon) + - Connectivity (coming soon) + +```hcl + deploy_core_landing_zones = false +``` + +> Important: If changed to _false_ after initial deployment, terraform will destroy all core Enterprise-scale Management Groups and Management Group scoped resources. + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-deploy_demo_landing_zones.md b/docs/wiki/[Variables]-deploy_demo_landing_zones.md new file mode 100644 index 000000000..9b4b734b0 --- /dev/null +++ b/docs/wiki/[Variables]-deploy_demo_landing_zones.md @@ -0,0 +1,30 @@ +## Overview + +[**deploy_demo_landing_zones**](#overview) `bool` (optional) + +If set to true, will include the demo "Landing Zone" Management Groups. + +## Default value + +`false` + +## Validation + +None + +## Usage + +Set the value to true or false. +If set to _true_, the module will deploy additional Management Groups used for demonstrating the Enterprise-scale Landing Zone archetypes. +This is for demonstration purposes mainly and should not be used for production workloads. + +```hcl + deploy_demo_landing_zones = true +``` + +To see the effect of this change, please refer to the [Demo landing zones example](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Demo-Landing-Zone-Archetypes). + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-destroy_duration_delay.md b/docs/wiki/[Variables]-destroy_duration_delay.md new file mode 100644 index 000000000..138fb2d29 --- /dev/null +++ b/docs/wiki/[Variables]-destroy_duration_delay.md @@ -0,0 +1,38 @@ +## Overview + +[**destroy_duration_delay**](#overview) `map(string)` (optional) + +Used to tune terraform deploy when faced with errors caused by API caching or eventual consistency. Sets a custom delay period after destruction of the specified resource type. + +## Default value + +```hcl +{} +``` + +## Validation + +The `destroy_duration_delay` values must be a string containing the duration in numbers (1-6 digits) followed by the measure of time represented by s (seconds), m (minutes), or h (hours), matching the following RegEx: + +`[0-9]{1,6}(s|m|h)$` + +## Usage + +To create a delay after the destruction of a supported resource type, change the value as per the example. +In the following, we set a 30s delay after the destruction of `azurerm_policy_assignment` resources. + +```hcl +{ + azurerm_management_group = "0s" + azurerm_policy_assignment = "30s" + azurerm_policy_definition = "0s" + azurerm_policy_set_definition = "0s" + azurerm_role_assignment = "0s" + azurerm_role_definition = "0s" +} +``` + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-library_path.md b/docs/wiki/[Variables]-library_path.md new file mode 100644 index 000000000..f24905da9 --- /dev/null +++ b/docs/wiki/[Variables]-library_path.md @@ -0,0 +1,28 @@ +## Overview + +[**library_path**](#overview) `string` (optional) + +If specified, sets the path to a custom library folder for archetype artifacts. + +## Default value + +`""` + +## Validation + +None + +## Usage + +Set the path to a custom directory within your root module. + +```hcl + library_path = "${path.root}/lib" +``` + +> Important: Please ensure you create the `/lib` directory first within your root module. You can use this custom directory to store all your custom archetype definition templates. + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-root_id.md b/docs/wiki/[Variables]-root_id.md new file mode 100644 index 000000000..d0e8e13bf --- /dev/null +++ b/docs/wiki/[Variables]-root_id.md @@ -0,0 +1,30 @@ +## Overview + +[**root_id**](#overview) `string` (optional) + +If specified, will set a custom Name (ID) value for the Enterprise-scale "root" Management Group, and append this to the ID for all core Enterprise-scale Management Groups. + +## Default value + +`"es"` + +## Validation + +The `root_id` must be a string between 2 to 10 characters long and can only contain alphanumeric characters and hyphens, matching the following RegEx: + +`[a-zA-Z0-9-]{2,10}$` + +## Usage + +To set a custom Name (ID) value for the Enterprise-scale "root" Management Group to `myorg-1`, set the value of `root_id` as below: + +```hcl + root_id = "myorg-1" +``` + +> WARNING: Changing this value will cause Terraform to re-create all resources managed by this module + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-root_name.md b/docs/wiki/[Variables]-root_name.md new file mode 100644 index 000000000..cc13581a9 --- /dev/null +++ b/docs/wiki/[Variables]-root_name.md @@ -0,0 +1,29 @@ +## Overview + +[**root_name**](#overview) `string` (optional) + +If specified, will set a custom Display Name value for the Enterprise-scale "root" Management Group. + +## Default value + +`"Enterprise-Scale"` + +## Validation + +The `root_name` value must be a string between 2 to 24 characters long, start with a letter, end with a letter or number, and can only contain space, hyphen, underscore or period characters, matching the following RegEx: + +`[A-Za-z][A-Za-z0-9- ._]{1,22}[A-Za-z0-9]?$` + +## Usage + +To set a custom Display Name value for the Enterprise-scale "root" Management Group to `My Organization 1`, set the value of `root_name` as below: + +```hcl + root_name = "My Organization 1" + +``` + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-root_parent_id.md b/docs/wiki/[Variables]-root_parent_id.md new file mode 100644 index 000000000..de3c21723 --- /dev/null +++ b/docs/wiki/[Variables]-root_parent_id.md @@ -0,0 +1,39 @@ +## Overview + +[**root_parent_id**](#overview) `string` (required) + +Represents an existing Management Group, under which the Enterprise-scale resource hierarchy will be deployed. +Usually this will be the Tenant Root Group, which is the default Management Group referenced by the Tenant ID. + +## Default value + +None + +## Validation + +The `root_parent_id` value must be a valid Management Group ID matching the following RegEx: + +`^[a-zA-Z0-9-_\(\)\.]{1,36}$` + +## Usage + +For a typical deployment, this will be the Tenant ID. + +```hcl + root_parent_id = "9dd91fa3-6367-43be-a321-27c56b855e88" +``` + +> In our examples we get the Tenant ID dynamically using [azurerm_client_config](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/client_config) data source. + +In some cases you may need to do nested deployments. In this scenario, you must set the `root_parent_id` to the ID of an existing Management Group. + +The following shows how you would configure the `root_parent_id` to the core "Landing Zones" Management Group, as per our nested deployments [example](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Using-Module-Nesting). + +```hcl + root_parent_id = "es-landing-zones" +``` + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-subscription_id_overrides.md b/docs/wiki/[Variables]-subscription_id_overrides.md new file mode 100644 index 000000000..79f992d53 --- /dev/null +++ b/docs/wiki/[Variables]-subscription_id_overrides.md @@ -0,0 +1,38 @@ +## Overview + +[**subscription_id_overrides**](#overview) `map(list(string))` (optional) + +If specified, will be used to assign subscription_ids to the default Enterprise-scale Management Groups. + +## Default value + +`{}` + +## Validation + +None + +## Usage + +To associate one or more Subscriptions with one of the default Management Groups, update the `subscription_id_overrides` variable to contain a map using the default Management Group ID as each key and a list of Subscription IDs as the value. + +A full list of default Management Groups: + +**`root`**, **`decommissioned`**, **`sandboxes`**, **`landing-zones`**, **`platform`**, **`connectivity`**, **`management`**, **`identity`** + +```hcl + subscription_id_overrides = { + sandboxes = [ + "00000000-0000-0000-0000-000000000000", + "11111111-1111-1111-1111-111111111111", + "22222222-2222-2222-2222-222222222222", + ] + } +``` + +> NOTE: You do not need to replace `root` with the actual root ID, or prefix the other Management Group IDs. The module will do this for you. + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/[Variables]-template_file_variables.md b/docs/wiki/[Variables]-template_file_variables.md new file mode 100644 index 000000000..7978b542e --- /dev/null +++ b/docs/wiki/[Variables]-template_file_variables.md @@ -0,0 +1,22 @@ +## Overview + +[**template_file_variables**](#overview) `map(any)` (optional) + +If specified, provides the ability to define custom template variables used when reading in template files from the built-in and custom library_path. + +## Default value + +`{}` + +## Validation + +None + +## Usage + +_coming soon_ + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[this_page]: # "Link for the current page." diff --git a/docs/wiki/_Footer.md b/docs/wiki/_Footer.md new file mode 100644 index 000000000..53b049c24 --- /dev/null +++ b/docs/wiki/_Footer.md @@ -0,0 +1,2 @@ +**This wiki is being actively developed** +If you discover any documentation bugs or would like to request new content, please raise them as an [issue](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/issues) or feel free to contribute to the wiki via a [pull request](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/pulls). The wiki docs are located in the repository in the `docs/wiki/` folder. \ No newline at end of file diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 000000000..65ea04043 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,52 @@ +![caf-enterprise-scale](media/azure.svg) + +## Terraform Module for Cloud Adoption Framework Enterprise-scale + +- [Home][wiki_home] +- [User Guide][wiki_user_guide] + - [Getting Started][wiki_getting_started] + - [Module Variables][wiki_module_variables] + - [Archetype Definitions][wiki_archetype_definitions] + - [Deploy Management Resources][wiki_deploy_management_resources] + - [Upgrade from v0.0.8 to v0.1.0][wiki_upgrade_from_v0_0_8_to_v0_1_0] + - [Upgrade from v0.1.2 to v0.2.0][wiki_upgrade_from_v0_1_2_to_v0_2_0] +- [Examples][wiki_examples] + - [Deploy Default Configuration][wiki_deploy_default_configuration] + - [Deploy Demo Landing Zone Archetypes][wiki_deploy_demo_landing_zone_archetypes] + - [Deploy Custom Landing Zone Archetypes][wiki_deploy_custom_landing_zone_archetypes] + - [Expand Built-in Archetype Definitions][wiki_expand_built_in_archetype_definitions] + - [Deploy Using Module Nesting][wiki_deploy_using_module_nesting] + - [Override Module Role Assignments][wiki_override_module_role_assignments] +- [Frequently Asked Questions][wiki_frequently_asked_questions] +- [Troubleshooting][wiki_troubleshooting] +- [Contributing][wiki_contributing] + - [Raising an Issue][wiki_raising_an_issue] + - [Feature Requests][wiki_feature_requests] + - [Contributing to Code][wiki_contributing_to_code] + - [Contributing to Documentation][wiki_contributing_to_documentation] + +[//]: # "************************" +[//]: # "INSERT LINK LABELS BELOW" +[//]: # "************************" +[wiki_home]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Home "Wiki - Home" +[wiki_user_guide]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/User-Guide "Wiki - User Guide" +[wiki_getting_started]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Getting-Started "Wiki - Getting Started" +[wiki_module_variables]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Module-Variables "Wiki - Module Variables" +[wiki_archetype_definitions]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Archetype-Definitions "Wiki - Archetype Definitions" +[wiki_upgrade_from_v0_0_8_to_v0_1_0]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Upgrade-from-v0.0.8-to-v0.1.0 "Wiki - Upgrade from v0.0.8 to v0.1.0" +[wiki_upgrade_from_v0_1_2_to_v0_2_0]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Upgrade-from-v0.1.2-to-v0.2.0 "Wiki - Upgrade from v0.1.2 to v0.2.0" +[wiki_deploy_management_resources]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BUser-Guide%5D-Deploy-Management-Resources "Wiki - Deploy Management Resources" +[wiki_examples]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Examples "Wiki - Examples" +[wiki_deploy_default_configuration]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Default-Configuration "Wiki - Deploy Default Configuration" +[wiki_deploy_demo_landing_zone_archetypes]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Demo-Landing-Zone-Archetypes "Wiki - Deploy Demo Landing Zone Archetypes" +[wiki_deploy_custom_landing_zone_archetypes]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Custom-Landing-Zone-Archetypes "Wiki - Deploy Custom Landing Zone Archetypes" +[wiki_deploy_using_module_nesting]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Deploy-Using-Module-Nesting "Wiki - Deploy Using Module Nesting" +[wiki_frequently_asked_questions]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Frequently-Asked-Questions "Wiki - Frequently Asked Questions" +[wiki_troubleshooting]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Troubleshooting "Wiki - Troubleshooting" +[wiki_contributing]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Contributing "Wiki - Contributing" +[wiki_raising_an_issue]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Raising-an-Issue "Wiki - Raising an Issue" +[wiki_feature_requests]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Feature-Requests "Wiki - Feature Requests" +[wiki_contributing_to_code]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Contributing-to-Code "Wiki - Contributing to Code" +[wiki_contributing_to_documentation]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Contributing-to-Documentation "Wiki - Contributing to Documentation" +[wiki_expand_built_in_archetype_definitions]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Expand-Built-in-Archetype-Definitions "Wiki - Expand Built-in Archetype Definitions" +[wiki_override_module_role_assignments]: https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/%5BExamples%5D-Override-Module-Role-Assignments "Wiki - Override Module Role Assignments" diff --git a/docs/wiki/media/azure.svg b/docs/wiki/media/azure.svg new file mode 100644 index 000000000..15eb30f3f --- /dev/null +++ b/docs/wiki/media/azure.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/wiki/media/examples-deploy-custom-demo-landing-zone-archetypes.png b/docs/wiki/media/examples-deploy-custom-demo-landing-zone-archetypes.png new file mode 100644 index 000000000..543db2a28 Binary files /dev/null and b/docs/wiki/media/examples-deploy-custom-demo-landing-zone-archetypes.png differ diff --git a/docs/wiki/media/examples-deploy-default-configuration.png b/docs/wiki/media/examples-deploy-default-configuration.png new file mode 100644 index 000000000..1d4c454ee Binary files /dev/null and b/docs/wiki/media/examples-deploy-default-configuration.png differ diff --git a/docs/wiki/media/examples-deploy-demo-landing-zone-archetypes.png b/docs/wiki/media/examples-deploy-demo-landing-zone-archetypes.png new file mode 100644 index 000000000..123ab2247 Binary files /dev/null and b/docs/wiki/media/examples-deploy-demo-landing-zone-archetypes.png differ diff --git a/docs/wiki/media/examples-deploy-using-module-nesting.png b/docs/wiki/media/examples-deploy-using-module-nesting.png new file mode 100644 index 000000000..967a2206c Binary files /dev/null and b/docs/wiki/media/examples-deploy-using-module-nesting.png differ diff --git a/docs/wiki/media/examples-expand-built-in-archetype-definitions-01.png b/docs/wiki/media/examples-expand-built-in-archetype-definitions-01.png new file mode 100644 index 000000000..358254ad5 Binary files /dev/null and b/docs/wiki/media/examples-expand-built-in-archetype-definitions-01.png differ diff --git a/docs/wiki/media/examples-expand-built-in-archetype-definitions-02.png b/docs/wiki/media/examples-expand-built-in-archetype-definitions-02.png new file mode 100644 index 000000000..a6444528d Binary files /dev/null and b/docs/wiki/media/examples-expand-built-in-archetype-definitions-02.png differ diff --git a/docs/wiki/media/examples-expand-built-in-archetype-definitions.png b/docs/wiki/media/examples-expand-built-in-archetype-definitions.png new file mode 100644 index 000000000..6bf123f22 Binary files /dev/null and b/docs/wiki/media/examples-expand-built-in-archetype-definitions.png differ diff --git a/docs/wiki/media/examples-override-module-role-assignments-01.png b/docs/wiki/media/examples-override-module-role-assignments-01.png new file mode 100644 index 000000000..82ea37b54 Binary files /dev/null and b/docs/wiki/media/examples-override-module-role-assignments-01.png differ diff --git a/docs/wiki/media/examples-override-module-role-assignments-02.png b/docs/wiki/media/examples-override-module-role-assignments-02.png new file mode 100644 index 000000000..a3f56fb1b Binary files /dev/null and b/docs/wiki/media/examples-override-module-role-assignments-02.png differ diff --git a/docs/wiki/media/examples-override-module-role-assignments-03.png b/docs/wiki/media/examples-override-module-role-assignments-03.png new file mode 100644 index 000000000..9e67c43ab Binary files /dev/null and b/docs/wiki/media/examples-override-module-role-assignments-03.png differ diff --git a/docs/wiki/media/examples-override-module-role-assignments-04.png b/docs/wiki/media/examples-override-module-role-assignments-04.png new file mode 100644 index 000000000..debeb6034 Binary files /dev/null and b/docs/wiki/media/examples-override-module-role-assignments-04.png differ diff --git a/docs/wiki/media/examples-override-module-role-assignments.png b/docs/wiki/media/examples-override-module-role-assignments.png new file mode 100644 index 000000000..8956f270d Binary files /dev/null and b/docs/wiki/media/examples-override-module-role-assignments.png differ diff --git a/docs/wiki/media/terraform-caf-enterprise-scale-management.png b/docs/wiki/media/terraform-caf-enterprise-scale-management.png new file mode 100644 index 000000000..9c7d92938 Binary files /dev/null and b/docs/wiki/media/terraform-caf-enterprise-scale-management.png differ diff --git a/docs/wiki/media/terraform-caf-enterprise-scale-overview.png b/docs/wiki/media/terraform-caf-enterprise-scale-overview.png new file mode 100644 index 000000000..90c766561 Binary files /dev/null and b/docs/wiki/media/terraform-caf-enterprise-scale-overview.png differ