Enable unidirectional sync from docs/wiki to wiki (#91)

* add action * add docs/wiki folder with latest wiki content * amend footer * remove '/' * add action 'if' * Fixes for MD042 linting rule * MD042 further fixes * MD009, MD028, MD034, MD040 - fixes * another MD028 fix * further linting fixes * remove trailing spaces Co-authored-by: Kevin Rowlandson <[email protected]>
Azure · May 10, 2021 · 6327afa · 6327afa
1 parent e8ab7f7
commit 6327afa
Show file tree

Hide file tree

Showing 53 changed files with 2,607 additions and 0 deletions.
diff --git a/.github/workflows/wiki-sync.yml 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: "[email protected]"
+  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://[email protected]/$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
@@ -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)
+
+<!--Reference links in article-->
+
+[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"
diff --git a/docs/wiki/Contributing-to-Documentation.md 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_
diff --git a/docs/wiki/Contributing.md 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 [email protected] 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)
+
+<!--Reference links in article-->
+
+[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
@@ -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
@@ -0,0 +1 @@
+_Coming soon_
diff --git a/docs/wiki/Frequently-Asked-Questions.md b/docs/wiki/Frequently-Asked-Questions.md
@@ -0,0 +1 @@
+_Coming soon_
diff --git a/docs/wiki/Home.md 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
@@ -0,0 +1 @@
+_Coming soon_
diff --git a/docs/wiki/Troubleshooting.md 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
+
+<details>
+  <summary><samp>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 '&#60;redacted&#62;' does not exist."
+</samp></summary>
+  <dl>
+    <dd><strong>Description:</strong></dd>
+    <dd>
+      <p>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.</p>
+    </dd>
+    <dd><strong>Solution:</strong></dd>
+    <dd>
+      <p>If the Role Definition has been successfully created in Azure but has not been committed to the <code>terraform state</code> you will need to run <code>terraform import</code> 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.</p>
+      <p>This problem has been identified and logged on GitHub against the AzureRM Provider: <a href="https://github.com/terraform-providers/terraform-provider-azurerm/issues/10442">#10442</a></p>
+    </dd>
+  </dl>
+</details>
+
+<details>
+  <summary><samp>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 '&#60;redacted&#62;' is not found."</samp></summary>
+  <dl>
+    <dd><h5>Description:</h5></dd>
+    <dd>Coming soon</dd>
+  </dl>
+</details>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Please ensure you have read our [Contributing](./Contributing) page before going any further.

		_More information coming soon_