feat!: architcture support (#69)

* wip: architecture support

* wip: kinda working

* feat: alzreference example working

* feat: basic functionality

* feat: make architecture a variable

* chore: pre-commit

* feat: only create mgs if exists flag is false

* feat: add role defs

* wip example

* feat: role definitions and other example

* feat!: architectures

* fix: lint errors

* style: avmfix

* docs: make docs

.gitignore

@@ -49,3 +49,6 @@ avm.tflint_example.merged.hcl
 .alzlib
 avm.tflint_module.hcl
 avm.tflint_module.merged.hcl
+
+*.tfrc
+

.tflint.override.hcl

@@ -0,0 +1,3 @@
+rule "required_output_rmfr7" {
+  enabled = false
+}

.vscode/extensions.json

@@ -1,6 +1,7 @@
 {
   "recommendations": [
     "hashicorp.terraform",
-    "EditorConfig.EditorConfig"
+    "EditorConfig.EditorConfig",
+    "redhat.vscode-yaml"
   ]
 }

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-    "editor.bracketPairColorization.enabled": true
+  "editor.bracketPairColorization.enabled": true
 }

_header.md

@@ -2,8 +2,57 @@
 
 # ALZ Terraform Module
 
-> ⚠️ ***Warning*** ⚠️ This module is still in development but is ready for initial testing and feedback via [GitHub Issues](https://github.com/Azure/terraform-azurerm-avm-ptn-alz/issues).
+> [!WARNING]
+> This module is still in development but is ready for initial testing and feedback via [GitHub Issues](https://github.com/Azure/terraform-azurerm-avm-ptn-alz/issues).
 
 - This repository contains a Terraform module for deploying Azure Landing Zones (ALZs).
 - Make sure to review the examples.
 
+> [!IMPORTANT]
+> Do not pass unknown (computed) values into the properties of the module. Instead use string interpolation and other means to pass the values. Seem below for details.
+
+## Unknown Values
+
+This module uses the ALZ Terraform provider. This uses a data source which **must** be read prior to creating the plan.
+If you pass an unknown/computed value into the module, it will not be able to read the data source until the plan is being applied.
+This may cause resources to be unnecessarily recreated.
+
+Such unknown values include resource ids. For example, if you are creating a resource and passing the id of the resource group to the module, this will cause the issue.
+
+Instead, use string interpolation to pass the values. For example:
+
+### Recommended
+
+This is the recommended way to use this module:
+
+> [!NOTE]
+> We assume that all variable inputs are literals.
+
+```terraform
+
+locals {
+  foo_resource_id = "/subscriptions/${data.azurerm_client_config.current.subscription_id}/resourceGroups/${var.resource_group_name}/providers/Microsoft.FooResourceProvider/${var.foo_resource_name}"
+}
+
+
+module "example" {
+  source = "Azure/terraform-azurerm-avm-ptn-alz/azurerm"
+
+  policy_assignments_to_modify = {
+    alzroot = {
+      policy_assignments = {
+        mypolicy = {
+          parameters = jsonencode({
+            parameterName = local.foo_resource_id
+          })
+        }
+      }
+    }
+  }
+}
+```
+
+### Deferred Actions
+
+We are awaiting the results of the upstream Terraform language experiment *deferred actions*. This may provide a solution to this issue.
+See the release notes [here](https://github.com/hashicorp/terraform/releases/tag/v1.10.0-alpha20240619) for more information.