add zone creation details to readme and inline explanation

README.md

@@ -4,10 +4,62 @@ This terraform module is used to create Dynatrace environment specific resources
 
 ## Metrics to monitor
 
-By default, services defined in the [default\_metrics.yaml](default_metrics.yaml) will be monitored on all the aws connections specified in the input (from the terragrunt repo). 
+By default, services defined in the [default\_metrics.yaml](default_metrics.yaml) will be monitored on all the aws connections specified in the input (from the terragrunt repo).
 
 This set of services can be _topped up_ or _completely replaced_ by including/altering relavant sections as specified in the https://github.com/UKHomeOffice/core-cloud-dynatrace-terragrunt documentation.
 
+## Management Zones
+
+Management Zones are maintained by the [dynatrace_management_zones module](https://github.com/UKHomeOffice/core-cloud-dynatrace-environment-terraform/blob/main/dynatrace_management_zones) in the core-cloud-dynatrace-environment-terraform repo.
+Zones can be created per-Dynatrace instance by adding a block to the corresponding environment section of the [config.yaml](config.yaml) file.
+For example, in order to configure a Management Zone for the "Core Cloud Test" Dynatrace:
+
+```
+corecloud_dynatracetest:
+  management_zones:
+  YourZoneName:
+    rules:
+      some_rule_name:
+        type: "ME"
+        enabled: true
+        attribute_rule:
+          entity_type: "AWS_ACCOUNT"
+          attribute_conditions:
+            condition:
+              key: "AWS_ACCOUNT_ID"
+              operator: "NOT_EQUALS"
+              string_value: "992382599151"
+              case_sensitive: true
+```
+
+In the example above, the first entry "YourZoneName" will be used as the literal name for the Zone within the Dynatrace UI.
+Inside the 'rules' block, descriptive rule names are recommended for readability of the config file (to explain the intended purpose of the underlying rule).
+The rule name provided (in this case "some_rule_name") will not actually be used/visible in the actual Dynatrace Console
+Further parameters, such as the type of rule (in this case 'attribute_rule') and the relevant conditions, will map to the possible dropdown/field inputs in the Dynatrace UI.
+
+Similarly to the above attribute_rule example, a dimension rule can be created by setting a "dimension_rule" block inside a rule definition. The dimension-specific parameters are then entered (such as whether it applies to logs, metrics or both) and the conditions (structured similarly to the attribute rule):
+
+```
+corecloud_dynatracetest:
+  management_zones:
+  YourZoneName:
+    rules:
+      additional_rule:
+        type: "DIMENSION"
+        enabled: true
+        dimension_rule:
+          applies_to: "METRIC"
+          dimension_conditions:
+            condition:
+              condition_type: "METRIC_KEY"
+              rule_matcher: "BEGINS_WITH"
+              value: "cloud.gcp."
+```
+
+Setting any 'Rules' for a Management Zone is entirely optional, but opening a "Rules" block will require at least one contained rule to be created, or else the pipeline will fail.
+
+For information on further options and attributes for the Zone and the Rules (whether 'attribute' or 'dimension') contained therein, please refer to the [Dynatrace Documentation](https://docs.dynatrace.com/docs/manage/identity-access-management/permission-management/management-zones) and the base [Terraform for the v2 resource](https://registry.terraform.io/providers/dynatrace-oss/dynatrace/latest/docs/resources/management_zone_v2) to clarify required/optional arguments.
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -34,4 +86,4 @@ No modules.
 ## Outputs
 
 No outputs.
-<!-- END_TF_DOCS -->
+<!-- END_TF_DOCS -->

dynatrace_management_zones/main.tf

@@ -8,22 +8,27 @@ terraform {
 }
 
 resource "dynatrace_management_zone_v2" "management_zone" {
+# Corresponds to the object structure defined in the variables.tf
+# One zone enitty, consisting of 0 or 1 'rules' blocks - which in turn consist of 1 or more individual 'rule' definitions
 
   name = var.zone_name
   description = var.zone_vars.description
   legacy_id = var.zone_vars.legacy_id
   dynamic "rules" {
     for_each = var.zone_vars.rules != null ? var.zone_vars.rules[*] : []
+    # Create a 'rules' block if defined in the config.yaml, else skips all following dynamic blocks
     content {
       dynamic "rule" {
         for_each = var.zone_vars.rules
+        # Creates one rule definition per entry inside the 'rules' section of the MZ config (name not used)
         content {
             type = rule.value.type
             enabled = rule.value.enabled
             entity_selector = ""
 
           dynamic "attribute_rule" {
             for_each = rule.value.attribute_rule[*]
+            # Creates an attribute rule block with conditions as defined - either this or dimension_rule
             content {
               azure_to_pgpropagation = attribute_rule.value.azure_to_pgpropagation
               azure_to_service_propagation = attribute_rule.value.azure_to_service_propagation
@@ -53,6 +58,7 @@ resource "dynatrace_management_zone_v2" "management_zone" {
 
           dynamic "dimension_rule" {
             for_each = rule.value.dimension_rule[*]
+            # Creates a dimension rule block with conditions as defined - either this or attribute_rule
             content {
               applies_to = dimension_rule.value.applies_to
               dimension_conditions {

dynatrace_management_zones/variables.tf

@@ -1,57 +1,58 @@
 variable "zone_name" {
+# The name of the management zone - retrieved as the identifying key within the 'management_zones' block of the config.yaml
   type = string
 }
 
-#variable "zone_vars" {
-#  type = any
-#}
-
-
 variable "zone_vars" {
+#This variable consists of the content of the per-named Management Zone key from the config.yaml
+#The provided values are structured into an object, containing further nested objects, as below
   type = object({
     description = optional(string)
     legacy_id = optional(string)
 
     rules = optional(map(object({
-        enabled = bool
-        type = string
-        entity_selector = optional(string, "")
-        attribute_rule = optional(object({
-          azure_to_pgpropagation = optional(bool)
-          azure_to_service_propagation = optional(bool)
-          custom_device_group_to_custom_device_propagation = optional(bool)
-          host_to_pgpropagation = optional(bool)
-          pg_to_host_propagation = optional(bool)
-          pg_to_service_propagation = optional(bool)
-          service_to_host_propagation = optional(bool)
-          service_to_pgpropagation = optional(bool)
-          entity_type = string
-          attribute_conditions = object({
-            condition = object({
-              key = string
-              operator = string
-              case_sensitive = optional(bool)
-              dynamic_key = optional(string)
-              dynamic_key_source = optional(string)
-              entity_id = optional(string)
-              enum_value = optional(string)
-              integer_value = optional(number)
-              string_value = optional(string)
-              tag = optional(string)
-            })
+    # The below attributes are contained in an individual 'rule' block created by the main TF file
+    # The 'rule' itself is dynamic and not defined as an object here, for cases where 'rules' are not defined
+    # ('Rules' are optional, but when set must contain at least one 'rule' block)
+      enabled = bool
+      type = string
+      entity_selector = optional(string, "")
+      attribute_rule = optional(object({
+        azure_to_pgpropagation = optional(bool)
+        azure_to_service_propagation = optional(bool)
+        custom_device_group_to_custom_device_propagation = optional(bool)
+        host_to_pgpropagation = optional(bool)
+        pg_to_host_propagation = optional(bool)
+        pg_to_service_propagation = optional(bool)
+        service_to_host_propagation = optional(bool)
+        service_to_pgpropagation = optional(bool)
+        entity_type = string
+        attribute_conditions = object({
+          condition = object({
+            key = string
+            operator = string
+            case_sensitive = optional(bool)
+            dynamic_key = optional(string)
+            dynamic_key_source = optional(string)
+            entity_id = optional(string)
+            enum_value = optional(string)
+            integer_value = optional(number)
+            string_value = optional(string)
+            tag = optional(string)
+          })
+        })
+      }))
+      dimension_rule = optional(object({
+        applies_to = string
+        dimension_conditions = optional(object({
+          condition = object({
+            condition_type = string
+            rule_matcher = string
+            value = string
+            key = optional(string)
           })
         }))
-        dimension_rule = optional(object({
-          applies_to = string
-          dimension_conditions = optional(object({
-            condition = object({
-              condition_type = string
-              rule_matcher = string
-              value = string
-              key = optional(string)
-            })
-          }))
-        }))
-      })))
-    })
+      }))
+    })))
+  })
 }

main.tf

@@ -15,6 +15,9 @@ module "dynatrace_management_zones" {
   source = "./dynatrace_management_zones"
 
   for_each = var.tenant_vars.management_zones
+  # Create one management zone per named entry under the "management_zones" block of the config.yaml
   zone_vars = each.value
+  # Value is the attribute/parameter content of each named entry
   zone_name = each.key
+  # Name reference for the zone within config yaml is used as the literal name of the MZ to be created
 }