diff --git a/modules/azure-policy-assignments/.terraform-docs.yml b/modules/azure-policy-assignments/.terraform-docs.yml
new file mode 100644
index 000000000..7159f428f
--- /dev/null
+++ b/modules/azure-policy-assignments/.terraform-docs.yml
@@ -0,0 +1,48 @@
+formatter: "markdown"
+
+version: ""
+
+header-from: docs/header.md
+footer-from: docs/footer.md
+
+recursive:
+ enabled: false
+ path: modules
+ include-main: true
+
+sections:
+ hide: []
+ show: []
+
+content: ""
+
+output:
+ file: "README.MD"
+ mode: inject
+ template: |-
+
+ {{ .Content }}
+
+
+output-values:
+ enabled: false
+ from: ""
+
+sort:
+ enabled: true
+ by: name
+
+settings:
+ anchor: true
+ color: true
+ default: true
+ description: false
+ escape: true
+ hide-empty: false
+ html: true
+ indent: 2
+ lockfile: true
+ read-comments: true
+ required: true
+ sensitive: true
+ type: true
\ No newline at end of file
diff --git a/modules/azure-policy-assignments/README.MD b/modules/azure-policy-assignments/README.MD
index a2e68f3bf..b617f8e5d 100644
--- a/modules/azure-policy-assignments/README.MD
+++ b/modules/azure-policy-assignments/README.MD
@@ -133,3 +133,187 @@ assignments = [
}
]
```
+
+
+# Azure Policy Assignments Terraform Module
+
+## Overview
+
+This Terraform module allows you to assign Azure policies at the management group, subscription, resource group, or resource level, supporting both built-in and custom policies.
+
+## Main features
+- Assign policies to management groups, subscriptions, resource groups, or resources.
+- Support for both built-in and custom policy definitions.
+- Flexible assignment configuration with metadata, parameters, and non-compliance messages.
+- Realistic configuration example.
+
+## Complete usage example
+
+### YAML
+```yaml
+values:
+ assignments:
+ - name: "example-assignment-3"
+ policy_type: "custom"
+ policy_name: "Example Policy"
+ resource_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"
+ scope: "resource"
+ - name: "example-assignment-2"
+ policy_type: "builtin"
+ policy_name: "Allowed virtual machine size SKUs"
+ resource_group_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
+ scope: "resource group"
+ - name: "example-assignment-2"
+ policy_type: "builtin"
+ policy_name: "Allowed virtual machine size SKUs"
+ resource_group_name: "test"
+ scope: "resource group"
+ - name: "example-assignment-1"
+ policy_type: "builtin"
+ policy_name: "Allowed locations"
+ scope: "subscription"
+ - name: "example-assignment-4"
+ policy_type: "custom"
+ policy_name: "Example Policy"
+ management_group_name: "example"
+ scope: "management group"
+```
+
+### HCL
+```hcl
+assignments = [
+ {
+ name = "example-assignment-3"
+ policy_type = "custom"
+ policy_name = "Example Policy"
+ resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/-test"
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "resource"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-2"
+ policy_type = "builtin"
+ policy_name = "Allowed virtual machine size SKUs"
+ resource_id = ""
+ resource_group_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
+ resource_group_name = ""
+ scope = "resource group"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-2"
+ policy_type = "builtin"
+ policy_name = "Allowed virtual machine size SKUs"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = "test"
+ scope = "resource group"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-1"
+ policy_type = "builtin"
+ policy_name = "Allowed locations"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "subscription"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-4"
+ policy_type = "custom"
+ policy_name = "Example Policy"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "management group"
+ management_group_name = "example"
+ }
+]
+```
+
+## Notes
+- You can assign policies at any scope: management group, subscription, resource group, or resource.
+- Both built-in and custom policies are supported.
+- Use the `assignments` variable to define all assignment details.
+
+## File structure
+
+```
+.
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── README.MD
+├── CHANGELOG.md
+└── docs/
+ ├── header.md
+ └── footer.md
+```
+
+## Requirements
+
+| Name | Version |
+|------|---------|
+| [terraform](#requirement\_terraform) | >= 1.7.0 |
+| [azurerm](#requirement\_azurerm) | >= 4.22.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| [azurerm](#provider\_azurerm) | >= 4.22.0 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [azurerm_management_group_policy_assignment.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/management_group_policy_assignment) | resource |
+| [azurerm_resource_group_policy_assignment.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group_policy_assignment) | resource |
+| [azurerm_resource_policy_assignment.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_policy_assignment) | resource |
+| [azurerm_subscription_policy_assignment.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/subscription_policy_assignment) | resource |
+| [azurerm_management_group.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/management_group) | data source |
+| [azurerm_policy_definition.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/policy_definition) | data source |
+| [azurerm_resource_group.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/resource_group) | data source |
+| [azurerm_subscription.current](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/subscription) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| [assignments](#input\_assignments) | List of objects containing all the variables for the policy assignments. | list(object({
name = string
policy_type = optional(string, "builtin")
policy_name = optional(string)
policy_definition_id = optional(string)
resource_id = optional(string)
resource_group_id = optional(string)
management_group_id = optional(string)
resource_group_name = optional(string)
management_group_name = optional(string)
scope = string
description = optional(string)
display_name = optional(string)
enforce = optional(bool, true)
identity = optional(object({
type = string
identity_ids = optional(list(string))
}))
location = optional(string)
metadata = optional(string)
non_compliance_message = optional(list(object({
content = string
policy_definition_reference_id = optional(string)
})))
not_scopes = optional(list(string))
parameters = optional(map(any))
overrides = optional(list(object({
value = string
selectors = optional(list(object({
in = optional(list(string))
not_in = optional(list(string))
})))
})))
resource_selectors = optional(list(object({
name = optional(string)
selectors = list(object({
kind = string
in = optional(list(string))
not_in = optional(list(string))
}))
})))
})) | `[]` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| [management\_group\_policy\_assignment\_ids](#output\_management\_group\_policy\_assignment\_ids) | List of all Azure management group policy assignment IDs |
+| [resource\_group\_policy\_assignment\_ids](#output\_resource\_group\_policy\_assignment\_ids) | List of all Azure resource group policy assignment IDs |
+| [resource\_policy\_assignment\_ids](#output\_resource\_policy\_assignment\_ids) | List of all Azure resource policy assignment IDs |
+| [subscription\_policy\_assignment\_ids](#output\_subscription\_policy\_assignment\_ids) | List of all Azure subscription policy assignment IDs |
+
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples):
+
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples/basic) - Policy assignments at subscription, resource group and management group scopes.
+
+## Resources and support
+
+- [Official Azure Policy documentation](https://learn.microsoft.com/en-us/azure/governance/policy/overview)
+- [Terraform reference for azurerm\_management\_group\_policy\_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/management_group_policy_assignment)
+- [Terraform reference for azurerm\_resource\_group\_policy\_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group_policy_assignment)
+- [Terraform reference for azurerm\_resource\_policy\_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_policy_assignment)
+- [Terraform reference for azurerm\_subscription\_policy\_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/subscription_policy_assignment)
+
+## Support
+
+For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues).
+
\ No newline at end of file
diff --git a/modules/azure-policy-assignments/_examples/basic/main.tf b/modules/azure-policy-assignments/_examples/basic/main.tf
new file mode 100644
index 000000000..7bced7d61
--- /dev/null
+++ b/modules/azure-policy-assignments/_examples/basic/main.tf
@@ -0,0 +1,19 @@
+module "azure_policy_assignments" {
+ source = "../../"
+
+ assignments = [
+ {
+ name = "example-assignment-subscription"
+ policy_type = "builtin"
+ policy_name = "Allowed locations"
+ scope = "subscription"
+ },
+ {
+ name = "example-assignment-rg"
+ policy_type = "builtin"
+ policy_name = "Allowed virtual machine size SKUs"
+ resource_group_name = "test"
+ scope = "resource group"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/modules/azure-policy-assignments/_examples/basic/values.yaml b/modules/azure-policy-assignments/_examples/basic/values.yaml
new file mode 100644
index 000000000..ed3ff16d3
--- /dev/null
+++ b/modules/azure-policy-assignments/_examples/basic/values.yaml
@@ -0,0 +1,10 @@
+assignments:
+ - name: example-assignment-subscription
+ policy_type: builtin
+ policy_name: Allowed locations
+ scope: subscription
+ - name: example-assignment-rg
+ policy_type: builtin
+ policy_name: Allowed virtual machine size SKUs
+ resource_group_name: test
+ scope: resource group
\ No newline at end of file
diff --git a/modules/azure-policy-assignments/docs/footer.md b/modules/azure-policy-assignments/docs/footer.md
new file mode 100644
index 000000000..349bc2dde
--- /dev/null
+++ b/modules/azure-policy-assignments/docs/footer.md
@@ -0,0 +1,17 @@
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples):
+
+- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples/basic) - Policy assignments at subscription, resource group and management group scopes.
+
+## Resources and support
+
+- [Official Azure Policy documentation](https://learn.microsoft.com/en-us/azure/governance/policy/overview)
+- [Terraform reference for azurerm_management_group_policy_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/management_group_policy_assignment)
+- [Terraform reference for azurerm_resource_group_policy_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group_policy_assignment)
+- [Terraform reference for azurerm_resource_policy_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_policy_assignment)
+- [Terraform reference for azurerm_subscription_policy_assignment](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/subscription_policy_assignment)
+
+## Support
+
+For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues).
\ No newline at end of file
diff --git a/modules/azure-policy-assignments/docs/header.md b/modules/azure-policy-assignments/docs/header.md
new file mode 100644
index 000000000..f05356445
--- /dev/null
+++ b/modules/azure-policy-assignments/docs/header.md
@@ -0,0 +1,118 @@
+# Azure Policy Assignments Terraform Module
+
+## Overview
+
+This Terraform module allows you to assign Azure policies at the management group, subscription, resource group, or resource level, supporting both built-in and custom policies.
+
+## Main features
+- Assign policies to management groups, subscriptions, resource groups, or resources.
+- Support for both built-in and custom policy definitions.
+- Flexible assignment configuration with metadata, parameters, and non-compliance messages.
+- Realistic configuration example.
+
+## Complete usage example
+
+### YAML
+```yaml
+values:
+ assignments:
+ - name: "example-assignment-3"
+ policy_type: "custom"
+ policy_name: "Example Policy"
+ resource_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"
+ scope: "resource"
+ - name: "example-assignment-2"
+ policy_type: "builtin"
+ policy_name: "Allowed virtual machine size SKUs"
+ resource_group_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
+ scope: "resource group"
+ - name: "example-assignment-2"
+ policy_type: "builtin"
+ policy_name: "Allowed virtual machine size SKUs"
+ resource_group_name: "test"
+ scope: "resource group"
+ - name: "example-assignment-1"
+ policy_type: "builtin"
+ policy_name: "Allowed locations"
+ scope: "subscription"
+ - name: "example-assignment-4"
+ policy_type: "custom"
+ policy_name: "Example Policy"
+ management_group_name: "example"
+ scope: "management group"
+```
+
+### HCL
+```hcl
+assignments = [
+ {
+ name = "example-assignment-3"
+ policy_type = "custom"
+ policy_name = "Example Policy"
+ resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/-test"
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "resource"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-2"
+ policy_type = "builtin"
+ policy_name = "Allowed virtual machine size SKUs"
+ resource_id = ""
+ resource_group_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
+ resource_group_name = ""
+ scope = "resource group"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-2"
+ policy_type = "builtin"
+ policy_name = "Allowed virtual machine size SKUs"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = "test"
+ scope = "resource group"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-1"
+ policy_type = "builtin"
+ policy_name = "Allowed locations"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "subscription"
+ management_group_name = ""
+ },
+ {
+ name = "example-assignment-4"
+ policy_type = "custom"
+ policy_name = "Example Policy"
+ resource_id = ""
+ resource_group_id = ""
+ resource_group_name = ""
+ scope = "management group"
+ management_group_name = "example"
+ }
+]
+```
+
+## Notes
+- You can assign policies at any scope: management group, subscription, resource group, or resource.
+- Both built-in and custom policies are supported.
+- Use the `assignments` variable to define all assignment details.
+
+## File structure
+
+```
+.
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── README.MD
+├── CHANGELOG.md
+└── docs/
+ ├── header.md
+ └── footer.md
+```
\ No newline at end of file