feat: avmtf v1

docs/content/specs-defs/includes/terraform/shared/functional/TFFR3.md

@@ -23,30 +23,30 @@ priority: 20030
 
 Authors **MUST** only use the following Azure providers, and versions, in their modules:
 
-| provider | min version | max version |
-|----------|-------------|-------------|
-| azapi    | >= 2.0      | < 3.0       |
-| azurerm  | >= 4.0      | < 5.0       |
-
-{{% notice style="note" %}}
-Authors **MAY** select either Azurerm, Azapi, or both providers in their module.
-{{% /notice %}}
+| provider              | min version | max version |
+|-----------------------|-------------|-------------|
+| Azure/azapi           | >= 2.0      | < 3.0       |
+
+> The AzureRM provider is permitted for module versions prior to v1.0.0, but **MUST NOT** be used in module versions v1.0.0 and later.
+> Should your module use the AzureRM provider, you **MUST** use version 4.x of the provider, i.e., `~> 4.0`. You MAY also create an exclusion for the TFLint rule:
+>
+> ```hcl
+> rule "provider_azurerm_disallowed" {
+>   enabled = false
+> }
+> ```
 
 Authors **MUST** use the `required_providers` block in their module to enforce the provider versions.
 
 The following is an example.
 
 - In it we use the [pessimistic version constraint operator](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#operators) `~>`.
-- That is to say that `~> 4.0` is equivalent to `>= 4.0, < 5.0`.
+- That is to say that `~> 2.0` is equivalent to `>= 2.0, < 3.0`.
 
 ```terraform
 terraform {
   required_providers {
     # Include one or both providers, as needed
-    azurerm = {
-      source  = "hashicorp/azurerm"
-      version = "~> 4.0"
-    }
     azapi = {
       source  = "Azure/azapi"
       version = "~> 2.0"

docs/content/specs-defs/includes/terraform/shared/functional/TFFR4.md

@@ -0,0 +1,65 @@
+---
+title: TFFR4 - AzAPI - response_export_values
+description: Module Specification for the Azure Verified Modules (AVM) program
+url: /spec/TFFR4
+type: default
+tags: [
+  Class-Resource, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Class-Pattern, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Class-Utility, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Type-Functional, # SINGLE VALUE: this can be "Type-Functional" OR "Type-NonFunctional"
+  Category-Naming/Composition, # SINGLE VALUE: this can be "Category-Testing" OR "Category-Telemetry" OR "Category-Contribution/Support" OR "Category-Documentation" OR "Category-CodeStyle" OR "Category-Naming/Composition" OR "Category-Inputs/Outputs" OR "Category-Release/Publishing"
+  Language-Terraform, # MULTIPLE VALUES: this can be "Language-Bicep" AND/OR "Language-Terraform"
+  Severity-MUST, # SINGLE VALUE: this can be "Severity-MUST" OR "Severity-SHOULD" OR "Severity-MAY"
+  Persona-Owner, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Persona-Contributor, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Lifecycle-BAU, # SINGLE VALUE: this can be "Lifecycle-Initial" OR "Lifecycle-BAU" OR "Lifecycle-EOL"
+  Validation-TF/CI/Enforced # SINGLE VALUE: this can be "Validation-TF/Manual" OR "Validation-TF/CI/Informational" OR "Validation-TF/CI/Enforced"
+]
+priority: 20040
+---
+
+## ID: TFFR4 - Category: Composition - AzAPI - response_export_values
+
+Authors **MUST** specify the `response_export_values` argument when using the AzAPI provider:
+
+```terraform
+resource "azapi_resource" "example" {
+  type      = "Microsoft.Example/resourceType@2021-01-01"
+  name      = "example-resource"
+  location  = "West US"
+  response_export_values = [] # must be specified, even if empty
+  body = {
+    properties = {
+      exampleProperty = "exampleValue"
+    }
+  }
+}
+
+If you require read-only properties to be returned from the resource, you SHOULD include them as follows:
+
+```terraform
+resource "azapi_resource" "example" {
+  type      = "Microsoft.Example/resourceType@2021-01-01"
+  name      = "example-resource"
+  location  = "West US"
+  # Example as a list:
+  response_export_values = ["properties.readOnlyProperty"]
+  # Example as a map:
+  # response_export_values = {
+  #   read_only_property = "properties.readOnlyProperty"
+  # }
+  body = {
+    properties = {
+      exampleProperty = "exampleValue"
+    }
+  }
+}
+
+output "read_only_property" {
+  # Example if response_export_values is a list:
+  value = azapi_resource.example.output.properties.readOnlyProperty
+  # Example if response_export_values is a map:
+  # value = azapi_resource.example.output.read_only_property
+}
+```

docs/content/specs-defs/includes/terraform/shared/functional/TFFR5.md

@@ -0,0 +1,41 @@
+---
+title: TFFR5 - AzAPI - replace_triggers_refs
+description: Module Specification for the Azure Verified Modules (AVM) program
+url: /spec/TFFR5
+type: default
+tags: [
+  Class-Resource, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Class-Pattern, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Class-Utility, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Type-Functional, # SINGLE VALUE: this can be "Type-Functional" OR "Type-NonFunctional"
+  Category-Naming/Composition, # SINGLE VALUE: this can be "Category-Testing" OR "Category-Telemetry" OR "Category-Contribution/Support" OR "Category-Documentation" OR "Category-CodeStyle" OR "Category-Naming/Composition" OR "Category-Inputs/Outputs" OR "Category-Release/Publishing"
+  Language-Terraform, # MULTIPLE VALUES: this can be "Language-Bicep" AND/OR "Language-Terraform"
+  Severity-MUST, # SINGLE VALUE: this can be "Severity-MUST" OR "Severity-SHOULD" OR "Severity-MAY"
+  Persona-Owner, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Persona-Contributor, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Lifecycle-BAU, # SINGLE VALUE: this can be "Lifecycle-Initial" OR "Lifecycle-BAU" OR "Lifecycle-EOL"
+  Validation-TF/CI/Enforced # SINGLE VALUE: this can be "Validation-TF/Manual" OR "Validation-TF/CI/Informational" OR "Validation-TF/CI/Enforced"
+]
+priority: 20050
+---
+
+## ID: TFFR5 - Category: Composition - AzAPI - replace_triggers_refs
+
+Authors **MUST** specify the `replace_triggers_refs` argument when using the AzAPI provider. The values should contain the body paths that would cause the resource to be replaced when they change.
+
+This is to ensure that changes to properties that require replacement of the resource are handled correctly by Terraform.
+
+```terraform
+resource "azapi_resource" "example" {
+  type      = "Microsoft.Example/resourceType@2021-01-01"
+  name      = "example-resource"
+  location  = "West US"
+  replace_triggers_refs = [
+    "properties.exampleProperty"
+  ] # must be specified, even if empty
+  body = {
+    properties = {
+      exampleProperty = "exampleValue"
+    }
+  }
+}

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR17.md

@@ -33,9 +33,9 @@ variable "kubernetes_cluster_key_management_service" {
     key_vault_network_access = optional(string)
   })
   default     = null
-  description = <<-EOT
+  description = <<-DESCRIPTION
   - `key_vault_key_id` - (Required) Identifier of Azure Key Vault key. See [key identifier format](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name) for more details. When Azure Key Vault key management service is enabled, this field is required and must be a valid key identifier. When `enabled` is `false`, leave the field empty.
   - `key_vault_network_access` - (Optional) Network access of the key vault Network access of key vault. The possible values are `Public` and `Private`. `Public` means the key vault allows public access from all networks. `Private` means the key vault disables public access and enables private link. Defaults to `Public`.
-EOT
+DESCRIPTION
 }
 ```

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR18.md

@@ -20,7 +20,7 @@ priority: 21180
 
 ## ID: TFNFR18 - Category: Code Style - Variables with Types
 
-`type` **MUST** be defined for every `variable`. `type` **SHOULD** be as precise as possible, `any` **MAY** only be defined with adequate reasons.
+`type` **MUST** be defined for every `variable`. `type` **SHOULD** be as precise as possible. Authors **SHOULD NOT** use `any`.
 
 - Use `bool` instead of `string` or `number` for `true/false`
 - Use `string` for text

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR23.md

@@ -20,4 +20,26 @@ priority: 21230
 
 ## ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions
 
-A default value **MUST NOT** be set for a sensitive input - e.g., a default password.
+A default value **MUST NOT** be set for a sensitive input, unless it is an empty collection value.
+
+Good example:
+
+```hcl
+variable "example_map" {
+  type        = map(string)
+  default     = {}
+  description = "An example map variable with an empty default value."
+  sensitive   = true
+}
+```
+
+Bad example:
+
+```hcl
+variable "example_string" {
+  type        = string
+  default     = "sensitive_value"
+  description = "An example string variable with a sensitive default value."
+  sensitive   = true
+}
+```

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR25.md

@@ -39,8 +39,8 @@ terraform {
   required_version = "~> 1.6"
   required_providers {
     azurerm = {
-      source  = "hashicorp/azurerm"
-      version = "~> 3.11"
+      source  = "Azure/azapi"
+      version = "~> 2.5"
     }
   }
 }

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR36.md

@@ -18,7 +18,7 @@ tags: [
 priority: 21360
 ---
 
-## ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources
+## ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources (AzureRM only)
 
 From Terraform AzureRM 3.0, the default value of `prevent_deletion_if_contains_resources` in `provider` block is `true`. This will lead to an unstable test because the test subscription has some policies applied, and they will add some extra resources during the run, which can cause failures during destroy of resource groups.
 

docs/content/specs-defs/includes/terraform/shared/non-functional/TFNFR5.md

@@ -20,12 +20,6 @@ priority: 21050
 
 ## ID: TFNFR5 - Category: Testing - Test Tooling
 
-Module owners **MUST** use the below tooling for unit/linting/static/security analysis tests. These are also used in the AVM Compliance Tests.
+Module owners **MUST** use the below test script for unit/linting/static/security analysis tests.
 
-- [Terraform](https://www.terraform.io/)
-  - `terraform <validate/fmt/test>`
-- [terrafmt](https://github.com/katbyte/terrafmt)
-- [Checkov](https://www.checkov.io/)
-- [tflint (with azurerm ruleset)](https://github.com/terraform-linters/tflint-ruleset-azurerm)
-- [Go](https://go.dev/)
-  - Some tests are provided as part of the AVM Compliance Tests, but you are free to also use Go for your own tests.
+- `./avm pr-check`

docs/static/includes/interfaces/tf/int.diag.schema.tf

@@ -4,7 +4,7 @@ variable "diagnostic_settings" {
     log_categories                           = optional(set(string), [])
     log_groups                               = optional(set(string), ["allLogs"])
     metric_categories                        = optional(set(string), ["AllMetrics"])
-    log_analytics_destination_type           = optional(string, "Dedicated")
+    log_analytics_destination_type           = optional(string)
     workspace_resource_id                    = optional(string, null)
     storage_account_resource_id              = optional(string, null)
     event_hub_authorization_rule_resource_id = optional(string, null)
@@ -28,7 +28,7 @@ variable "diagnostic_settings" {
     error_message = "At least one of `workspace_resource_id`, `storage_account_resource_id`, `marketplace_partner_resource_id`, or `event_hub_authorization_rule_resource_id`, must be set."
   }
   description = <<DESCRIPTION
-A map of diagnostic settings to create on the Key Vault. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
+A map of diagnostic settings to create on the resource. The map key is deliberately arbitrary to avoid issues where map keys maybe unknown at plan time.
 
 - `name` - (Optional) The name of the diagnostic setting. One will be generated if not set, however this will not be unique if you want to create multiple diagnostic setting resources.
 - `log_categories` - (Optional) A set of log categories to send to the log analytics workspace. Defaults to `[]`.