### Role Assignment Configuration Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/types.md

Provides examples of configuring role assignments for users and service principals, including optional properties like description and conditions.

```hcl
role_assignments = {
  "reader_access" = {
    role_definition_id_or_name = "Reader"
    principal_id               = "12345678-1234-1234-1234-123456789012"
    principal_type             = "User"
    description                = "Grant reader access to team member"
  }
  "blob_contributor" = {
    role_definition_id_or_name = "Storage Blob Data Contributor"
    principal_id               = "87654321-4321-4321-4321-210987654321"
    principal_type             = "ServicePrincipal"
    skip_service_principal_aad_check = true
    condition_version = "2.0"
    condition = "(!(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete'}))"
  }
}
```

--------------------------------

### Resource Group Full Output Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Example of the full output for a created resource group, including its ID, name, location, type, tags, properties, and managed_by status.

```json
{
  "id": "/subscriptions/abc-123/resourceGroups/my-rg",
  "name": "my-rg",
  "location": "eastus",
  "type": "Microsoft.Resources/resourceGroups",
  "tags": {
    "Environment": "Production"
  },
  "properties": {},
  "managed_by": null
}
```

--------------------------------

### Integration Example: Passing Lock Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Demonstrates the flow of configuration from user variables to the interfaces module, specifically for lock settings.

```hcl
# 1. User provides configuration
variable "lock" {
  type = object({
    kind = string
    name = optional(string, null)
  })
  default = null
}

# 2. Configuration is passed to interfaces module
module "interfaces" {
  source = "Azure/avm-utl-interfaces/azure"
  version = "0.6.0"
  
  lock = var.lock
  # ... other inputs
}
```

--------------------------------

### Example Output of azapi_client_config

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Illustrates the structure and content of the output from the `azapi_client_config` data source.

```json
{
  "subscription_id": "12345678-1234-1234-1234-123456789012",
  "tenant_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "object_id": "11111111-1111-1111-1111-111111111111"
}
```

--------------------------------

### Example Timeout Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/types.md

Illustrates how to configure timeout values for different API operations using the `timeout` object. This example sets specific durations for create, delete, read, and update operations.

```hcl
timeouts = {
  create = "15m"
  delete = "10m"
  read   = "5m"
  update = "15m"
}
```

--------------------------------

### Example Role Assignments Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/README.md

Demonstrates how to configure role assignments for a resource group, including basic assignments and assignments with conditions.

```hcl
role_assignments = {
  "role_assignment1" = {
    role_definition_id_or_name = "Reader"
    principal_id = "4179302c-702e-4de7-a061-beacd0a1be09"

  },
"role_assignment2" = {
  role_definition_id_or_name = "2a2b9908-6ea1-4ae2-8e65-a410df84e7d1" // Storage Blob Data Reader Role Guid
  principal_id = "4179302c-702e-4de7-a061-beacd0a1be09"
  skip_service_principal_aad_check = false
  condition_version = "2.0"
  condition = <<-EOT
(
  (
    !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
  )
OR
  (
  @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId]
  ForAnyOfAnyValues:GuidEquals {4179302c-702e-4de7-a061-beacd0a1be09}
  )
)
AND
(
  (
    !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
  )
  OR
  (
    @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId]
    ForAnyOfAnyValues:GuidEquals {dc887ae1-fe50-4307-be53-213ff08f3c0b}
  )
)
EOT
  }
}
```

--------------------------------

### Construct Resource ID with Subscription

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Example of using the `azapi_client_config` data source to get the subscription ID for constructing a parent resource ID.

```hcl
resource "azapi_resource" "this" {
  parent_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
  # ... rest of configuration
}
```

--------------------------------

### Example Generated Role Assignment Names

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Provides examples of names that the module might generate for role assignments when a name is not supplied by the user.

```plaintext
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
- 12345678-1234-1234-1234-123456789012
```

--------------------------------

### Complete Production Resource Group Setup

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

This snippet demonstrates a comprehensive production-ready Azure Resource Group setup. It includes essential configurations like locks for preventing accidental deletion, role assignments for access control, and detailed tagging for governance. It also features proper retry and timeout configurations for robust deployment.

```hcl
terraform {
  required_version = ">= 1.9, < 2.0"
  
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.4"
    }
  }
}

provider "azapi" {}

variable "environment" {
  type        = string
  default     = "production"
  description = "Deployment environment"
}

variable "team_owner_id" {
  type        = string
  description = "Azure AD group ID of team owners"
}

variable "operations_sp_id" {
  type        = string
  description = "Service principal ID for operations automation"
}

locals {
  resource_group_name = "prod-applications-rg"
  location            = "eastus"
  
  tags = {
    Environment     = "Production"
    Owner           = "Platform-Team"
    CostCenter      = "Engineering"
    DataClassification = "Internal"
    BackupPolicy    = "Daily"
    ChangeControl   = "Required"
  }
}

module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = local.location
  name     = local.resource_group_name
  
  # Prevent accidental deletion
  lock = {
    kind = "CanNotDelete"
    name = "${local.resource_group_name}-deletion-lock"
  }
  
  # RBAC assignments
  role_assignments = {
    owners = {
      role_definition_id_or_name = "Owner"
      principal_id               = var.team_owner_id
      principal_type             = "Group"
      description                = "Team owner access for resource management"
    }
    
    operations = {
      role_definition_id_or_name = "Contributor"
      principal_id               = var.operations_sp_id
      principal_type             = "ServicePrincipal"
      skip_service_principal_aad_check = true
      description                = "Operations automation service principal"
    }
  }
  
  # Resource optimization
  retry = {
    error_message_regex  = ["409 Conflict", "429 Too Many Requests"]
    interval_seconds     = 10
    max_interval_seconds = 120
  }
  
  timeouts = {
    create = "15m"
    delete = "10m"
    read   = "5m"
    update = "15m"
  }
  
  # Tags for governance
  tags = local.tags
  
  # Disable telemetry in restricted environments
  enable_telemetry = true
}

# Outputs for downstream modules
output "resource_group_id" {
  value       = module.resource_group.resource_id
  description = "The resource ID of the created resource group"
}

output "resource_group_name" {
  value       = module.resource_group.name
  description = "The name of the created resource group"
}

output "resource_group_location" {
  value       = module.resource_group.location
  description = "The location of the created resource group"
}

```

--------------------------------

### Example Output Value for role_assignments_azapi

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

An example of the processed role assignment configuration for use with azapi_resource. It shows a map of assignment names to their respective AzAPI resource details.

```hcl
{
  "role_assignment_1" = {
    name = "dfd0b1f9-3f46-32ba-e9e1-4b5591aa8337"
    type = "Microsoft.Authorization/roleAssignments@2022-04-01"
    body = {
      properties = {
        principalId           = "12345678-1234-1234-1234-123456789012"
        roleDefinitionId      = "/subscriptions/abc123/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7"
        description           = "Reader role assignment"
        # Additional properties based on input
      }
    }
  }
}
```

--------------------------------

### Create a Resource Group with Default Settings

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/module.md

Example of creating a resource group with minimal required parameters: location and name. Outputs the resource ID.

```hcl
module "rg" {
  source   = "Azure/avm-res-resources-resourcegroup/azurerm"
  location = "eastus"
  name     = "my-rg"
}

output "rg_id" {
  value = module.rg.resource_id
}
```

--------------------------------

### Telemetry Headers for Forked Modules

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Example of User-Agent header format for telemetry when using a forked AVM module.

```text
User-Agent: fork_avm=true random_id=<uuid>
```

--------------------------------

### Lock Creation Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Example of how to define a lock configuration within Terraform variables. This specifies the lock kind and an optional custom name.

```hcl
lock = {
  kind = "CanNotDelete"
  name = "my-lock"  # Optional; auto-generated if omitted
}

```

--------------------------------

### Enable Telemetry Input Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Shows how to pass the 'enable_telemetry' boolean input to the interfaces module, controlling telemetry processing.

```hcl
enable_telemetry = var.enable_telemetry
```

--------------------------------

### Example Output Value for lock_azapi

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

An example of the processed lock configuration for use with azapi_resource. It includes the generated name, AzAPI resource type, and the request body.

```hcl
{
  name = "lock-CanNotDelete"
  type = "Microsoft.Authorization/locks@2020-05-01"
  body = {
    properties = {
      level = "CanNotDelete"
    }
  }
}
```

--------------------------------

### Telemetry Headers for AVM Modules

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Example of User-Agent header format for telemetry when using an AVM module with telemetry enabled.

```text
User-Agent: avm=true random_id=<uuid> avm_module_source=<source> avm_module_version=<version>
```

--------------------------------

### Lock Input Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Illustrates how to provide the 'lock' input, specifying the kind and an optional name for resource locks. This configuration is transformed by the interfaces module.

```hcl
lock = var.lock  # e.g., { kind = "CanNotDelete", name = "my-lock" }
```

--------------------------------

### Example Role Assignment Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Demonstrates how to configure role assignments using the 'role_assignments' variable. The module validates role definition IDs, generates assignment names, and transforms the configuration for AzAPI.

```hcl
role_assignments = var.role_assignments  # e.g., {
  # "role1" = {
  #   role_definition_id_or_name = "Reader"
  #   principal_id = "12345678-1234-1234-1234-123456789012"
  # }
}
```

--------------------------------

### Valid and Invalid GUID for Role Assignment Name

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

Demonstrates the correct format for role assignment names when using a GUID. A proper GUID format is required, or the name can be omitted to auto-generate.

```hcl
# ❌ INVALID - not a valid GUID format
name = "my-assignment-name"

# ✅ VALID - proper GUID format
name = "12345678-1234-1234-1234-123456789012"

# ✅ VALID - omit to auto-generate
# name = null (or omit entirely)
```

--------------------------------

### Resource Body Structure Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Illustrates the JSON structure for the resource group's body, showing the `properties` object (empty for direct creation) and the optional `managedBy` property.

```json
{
  "properties": {},
  "managedBy": "/subscriptions/sub-id/resourceGroups/manager-rg"
}
```

--------------------------------

### Consume Resource Group Module

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Shows a basic example of consuming the resource group module and accessing its outputs, including the resource ID.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = "eastus"
  name     = "my-rg"
}

# Use module output for resource group ID
output "resource_group_id" {
  value = module.resource_group.resource_id
}
```

--------------------------------

### Generated GUID Format for Role Assignment Names

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Illustrates the format of GUIDs generated by the module when a role assignment name is not explicitly provided. This ensures unique names for each assignment.

```plaintext
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
```

--------------------------------

### Complete Resource Group Deployment Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/examples/complete/README.md

This HCL code demonstrates a full deployment of an Azure Resource Group using the AVM module. It includes provider configurations, naming conventions, region selection, user-assigned identity creation, and multiple role assignments with conditions.

```hcl
terraform {
  required_version = ">= 1.9, < 2.0"

  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.4"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.5.0, < 4.0.0"
    }
  }
}

provider "azapi" {}

/*
# NOTE: The azurerm provider block is required only when upgrading from a previous version of the module that used the azurerm provider. It can be removed in new implementations of the module or after upgrading.
provider "azurerm" {
  features {}
}
*/

data "azapi_client_config" "current" {}

# Importing the Azure naming module to ensure resources have unique CAF compliant names.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.4.2"
}

module "regions" {
  source  = "Azure/avm-utl-regions/azurerm"
  version = "0.12.0"

  is_recommended = true
}

# This allows us to randomize the region for the resource group.
resource "random_integer" "region_index" {
  max = length(module.regions.regions) - 1
  min = 0
}

resource "azapi_resource" "dep" {
  location  = module.regions.regions[random_integer.region_index.result].name
  name      = "${module.naming.resource_group.name_unique}-dep"
  parent_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
  type      = "Microsoft.Resources/resourceGroups@2025-04-01"
  body = {
    properties = {}
  }
}

resource "azapi_resource" "dep_uai" {
  location               = azapi_resource.dep.location
  name                   = module.naming.user_assigned_identity.name_unique
  parent_id              = azapi_resource.dep.id
  type                   = "Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31"
  body                   = {}
  response_export_values = ["properties.principalId"]
}

module "resource_group" {
  source = "../../"

  location = module.regions.regions[random_integer.region_index.result].name
  name     = module.naming.resource_group.name_unique
  lock = {
    kind = "CanNotDelete"
    name = "myCustomLockName"
  }
  role_assignments = {
    "roleassignment1" = {
      name                       = "dfd0b1f9-3f46-32ba-e9e1-4b5591aa8337"
      principal_id               = azapi_resource.dep_uai.output.properties.principalId
      role_definition_id_or_name = "Reader"
      principal_type             = "ServicePrincipal"
      description                = "Reader role assignment for the user assigned identity"
    },
    "role_assignment2" = {
      name                             = "bd83f8d6-f0a2-1584-9e3c-f31c185847ea"
      role_definition_id_or_name       = "Storage Blob Data Reader"
      principal_id                     = azapi_resource.dep_uai.output.properties.principalId
      skip_service_principal_aad_check = false
      principal_type                   = "ServicePrincipal"
      description                      = "Storage Blob Data Reader role assignment with conditional access on blob list operations"
      condition_version                = "2.0"
      condition                        = <<-EOT
( 
 ( 
 !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})
 )
 OR
 ( 
 @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container'
 )
)
EOT
    },
    "role_assignment3" = {
      role_definition_id_or_name = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor
      principal_id               = azapi_resource.dep_uai.output.properties.principalId
      principal_type             = "ServicePrincipal"
      description                = "Storage Blob Data Contributor role assignment using a role definition resource ID"
    }
  }
  tags = {
    "hidden-title" = "This is visible in the resource name"
    Environment    = "Non-Prod"
    Role           = "DeploymentValidation"
  }
}

```

--------------------------------

### Terraform Configuration for Role Assignments

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Example of how to define a role assignment within Terraform configuration, specifying role, principal, and description.

```hcl
role_assignments = {
  "reader_access" = {
    role_definition_id_or_name = "Reader"
    principal_id               = "12345678-1234-1234-1234-123456789012"
    principal_type             = "User"
    description                = "Grant read-only access"
  }
}
```

--------------------------------

### Outputting Full Resource Group Object

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/outputs.md

Provides an example of outputting the complete resource object for the resource group. This object contains all properties and attributes of the resource group.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"
  location = "eastus"
  name     = "my-rg"
}

output "rg_full_object" {
  value = module.resource_group.resource
}

# Access specific properties
output "rg_id" {
  value = module.resource_group.resource.id
}

output "rg_properties" {
  value = module.resource_group.resource.properties
}
```

--------------------------------

### Increase Timeouts for Slow Operations

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Adjusts timeout settings for resource creation and updates to accommodate slow API operations. Example sets both create and update timeouts to 30 minutes.

```hcl
timeouts = {
  create = "30m"
  update = "30m"
}
```

--------------------------------

### ABAC Condition Syntax Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/types.md

Illustrates the use of attribute-based access control (ABAC) for scoping role assignments. Ensure `condition_version` is set to "2.0" when using conditions.

```hcl
condition = <<-EOT
(
  (
    !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})
  )
  OR
  (
    @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'allowed-container'
  )
)
EOT
```

--------------------------------

### Role Assignment Definition Scope Input Example

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Demonstrates setting the 'role_assignment_definition_scope' input, which is used to resolve role definition names to IDs within a specific Azure subscription scope.

```hcl
role_assignment_definition_scope = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
```

--------------------------------

### Get Module Source and Version for Telemetry

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Retrieves information about the module's source and version, used for telemetry. This data source is conditionally created when telemetry is enabled.

```hcl
data "modtm_module_source" "telemetry" {
  count       = var.enable_telemetry ? 1 : 0
  module_path = path.module
}
```

--------------------------------

### Update AVM Utility Module Version

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

This example demonstrates how to update the version of the AVM utility module in your Terraform configuration. Ensure to test updates before deploying to production.

```hcl
module "interfaces" {
  source  = "Azure/avm-utl-interfaces/azure"
  version = "0.6.1"  # Update version
  
  # ... rest of configuration
}
```

--------------------------------

### Disable Telemetry in Module Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Illustrates how to disable telemetry for a specific module instance by setting the 'enable_telemetry' argument to false. This is a solution for 'Failed to get module source information' errors.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"
  
  enable_telemetry = false
  # ... rest of configuration
}
```

--------------------------------

### Deploy Multiple Resource Groups with a Loop

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/INDEX.md

Shows how to deploy multiple resource groups using the 'for_each' meta-argument based on a map of environment configurations.

```hcl
module "resource_groups" {
  for_each = var.environments
  
  source = "Azure/avm-res-resources-resourcegroup/azurerm"
  
  location = each.value.location
  name     = "app-${each.key}-rg"
}
```

--------------------------------

### Configuring Module for Multi-Subscription Deployments

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Illustrates how to configure the resource group module to manage resources across multiple subscriptions by defining separate 'azapi' provider aliases. Each alias is associated with a specific subscription ID.

```hcl
provider "azapi" {
  alias           = "prod"
  subscription_id = var.prod_subscription_id
}

provider "azapi" {
  alias           = "dev"
  subscription_id = var.dev_subscription_id
}

module "prod_rg" {
  source   = "Azure/avm-res-resources-resourcegroup/azurerm"
  providers = {
    azapi = azapi.prod
  }
  
  location = "eastus"
  name     = "prod-rg"
}

module "dev_rg" {
  source   = "Azure/avm-res-resources-resourcegroup/azurerm"
  providers = {
    azapi = azapi.dev
  }
  
  location = "westus"
  name     = "dev-rg"
}
```

--------------------------------

### Using Module Location Output

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Demonstrates how to use the location output from the resource group module in downstream resource configurations. Ensure the module is defined before referencing its outputs.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = "eastus"
  name     = "my-rg"
}

# Use location from module output
resource "azapi_resource" "storage" {
  location = module.resource_group.location
  name     = "mystorageaccount"
  parent_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/resourceGroups/${module.resource_group.name}"
  type     = "Microsoft.Storage/storageAccounts@2023-01-01"
  # ... rest of configuration
}
```

--------------------------------

### Get Telemetry Azure Context

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Retrieves subscription and tenant information specifically for telemetry collection. This data source is conditionally created when telemetry is enabled.

```hcl
data "azapi_client_config" "telemetry" {
  count = var.enable_telemetry ? 1 : 0
}
```

--------------------------------

### Get Current Azure Context

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Retrieves authentication and subscription information for the current Azure context. This is used internally by the module to construct resource IDs.

```hcl
data "azapi_client_config" "current" {}
```

--------------------------------

### Module File Organization

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/README.md

This snippet shows the directory structure for the module's documentation files.

```text
output/
├── README.md                       ← This file
├── INDEX.md                        ← Master index and navigation
├── configuration.md                ← Input variables (9 vars)
├── outputs.md                      ← Output values (4 outputs)
├── types.md                        ← Type definitions (4 types)
├── examples.md                     ← Usage examples (8 scenarios)
└── api-reference/
    ├── module.md                   ← Module signature and API
    ├── resources.md                ← Azure resources (3 types)
    ├── interfaces.md               ← Utility module
    └── data-sources.md            ← Data sources (3 sources)
```

--------------------------------

### Usage of role_assignments_azapi in Main Module

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Demonstrates how the 'role_assignments_azapi' output is used to configure multiple 'azapi_resource' blocks for creating role assignments. It utilizes 'for_each' to iterate over the map of assignments.

```hcl
resource "azapi_resource" "role_assignments" {
  for_each = module.interfaces.role_assignments_azapi

  name                   = each.value.name
  parent_id              = azapi_resource.this.id
  type                   = each.value.type
  body                   = each.value.body
  # ... additional configuration
}
```

--------------------------------

### Usage of lock_azapi in Main Module

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Demonstrates how the 'lock_azapi' output is used to configure an 'azapi_resource' block for creating resource locks. It shows the mapping of output properties to the resource arguments.

```hcl
resource "azapi_resource" "lock" {
  count = var.lock != null ? 1 : 0

  name                   = module.interfaces.lock_azapi.name
  parent_id              = azapi_resource.this.id
  type                   = module.interfaces.lock_azapi.type
  body                   = module.interfaces.lock_azapi.body
  # ... additional configuration
}
```

--------------------------------

### Reference Resource Group in Other Modules

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/module.md

Demonstrates how to use the resource group's ID as a parent for other resources, such as storage accounts. Requires 'location' and 'name'.

```hcl
module "rg" {
  source   = "Azure/avm-res-resources-resourcegroup/azurerm"
  location = "eastus"
  name     = "storage-rg"
}

# Use the resource group as parent for other resources
resource "azapi_resource" "storage" {
  parent_id = module.rg.resource_id
  # ... additional configuration
}
```

--------------------------------

### Basic Resource Group Deployment

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

Creates a resource group using only the required location and name parameters. The module utilizes the AzAPI provider for direct API interaction, and the output provides the resource group ID.

```hcl
terraform {
  required_version = ">= 1.9, < 2.0"
  
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.4"
    }
  }
}

provider "azapi" {}

module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = "eastus"
  name     = "example-rg"
}

output "resource_group_id" {
  value = module.resource_group.resource_id
}
```

--------------------------------

### Basic Resource Group Creation

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/module.md

Creates a simple Azure Resource Group with a specified location and name. This is the most basic configuration for the module.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = "eastus"
  name     = "example-rg"
}
```

--------------------------------

### Reference Resource Group in Downstream Modules

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/INDEX.md

Demonstrates how to reference the resource group module and use its outputs like resource_id and location in other resources.

```hcl
module "resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"
  # ...
}

# Use outputs in other resources
resource "azapi_resource" "storage" {
  parent_id = module.resource_group.resource_id
  location  = module.resource_group.location
  # ...
}
```

--------------------------------

### Multiple Resource Groups with Dynamic Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

This snippet shows how to create multiple Azure Resource Groups with varying configurations using Terraform's `for_each` meta-argument. It leverages a map input to dynamically define locations, locks, and tags for each resource group, making it ideal for multi-environment deployments.

```hcl
variable "resource_groups" {
  type = map(object({
    location = string
    lock     = optional(bool, false)
    tags     = optional(map(string), {})
  }))
  default = {
    "dev" = {
      location = "eastus"
      lock     = false
      tags = {
        Environment = "Development"
      }
    }
    "staging" = {
      location = "eastus2"
      lock     = true
      tags = {
        Environment = "Staging"
      }
    }
    "prod" = {
      location = "westus"
      lock     = true
      tags = {
        Environment = "Production"
      }
    }
  }
}

module "resource_groups" {
  for_each = var.resource_groups

  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location = each.value.location
  name     = "app-${each.key}-rg"
  
  lock = each.value.lock ? {
    kind = "CanNotDelete"
    name = "app-${each.key}-lock"
  } : null
  
  tags = merge(
    each.value.tags,
    {
      Workspace = each.key
      CreatedBy = "Terraform"
    }
  )
}

output "resource_groups" {
  value = {
    for k, rg in module.resource_groups : k => {
      id       = rg.resource_id
      name     = rg.name
      location = rg.location
    }
  }
  description = "Details of created resource groups"
}

```

--------------------------------

### Accessing and Displaying Module Outputs

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/outputs.md

Illustrates how to access various outputs from the resource group module using locals and display them in a structured output. This is a common pattern for consuming module outputs.

```hcl
module "my_rg" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"
  
  location = "eastus"
  name     = "example-rg"
  tags = {
    Environment = "test"
  }
}

# Access outputs
locals {
  rg_id       = module.my_rg.resource_id
  rg_name     = module.my_rg.name
  rg_location = module.my_rg.location
  rg_object   = module.my_rg.resource
}

# Display outputs
output "deployment_info" {
  value = {
    resource_id = module.my_rg.resource_id
    name        = module.my_rg.name
    location    = module.my_rg.location
  }
}
```

--------------------------------

### Dependency on Utility Module

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/interfaces.md

Shows how the main resource group module declares its dependency on the 'interfaces' utility module, including source and version.

```hcl
module "interfaces" {
  source  = "Azure/avm-utl-interfaces/azure"
  version = "0.6.0"

  enable_telemetry                 = var.enable_telemetry
  lock                             = var.lock
  role_assignment_definition_scope = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
  role_assignments                 = var.role_assignments
}
```

--------------------------------

### Telemetry Tags with Azure Context

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Shows how subscription and tenant IDs from `azapi_client_config` are used to generate telemetry tags.

```hcl
tags = {
  subscription_id = one(data.azapi_client_config.telemetry).subscription_id
  tenant_id       = one(data.azapi_client_config.telemetry).tenant_id
  module_source   = one(data.modtm_module_source.telemetry).module_source
  module_version  = one(data.modtm_module_source.telemetry).module_version
  random_id       = one(random_uuid.telemetry).result
  location        = var.location
}
```

--------------------------------

### Accessing Current Subscription ID

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Demonstrates how to use the 'azapi_client_config' data source to retrieve the current subscription ID and output it. This is useful for dynamic resource placement or referencing.

```hcl
data "azapi_client_config" "current" {}

output "my_subscription" {
  value = data.azapi_client_config.current.subscription_id
}
```

--------------------------------

### Access Subscription ID in Consumer Code

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Demonstrates how to access the `subscription_id` output from the `azapi_client_config` data source in consumer code.

```hcl
output "subscription_id" {
  value = data.azapi_client_config.current.subscription_id
}
```

--------------------------------

### Construct Telemetry Headers

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Generates telemetry headers, including information about whether the module is a fork and its source/version if it's an official AVM module.

```hcl
locals {
  avm_azapi_headers = !var.enable_telemetry ? {} : (local.fork_avm ? {
    fork_avm  = "true"
    random_id = one(random_uuid.telemetry).result
  } : {
    avm                = "true"
    random_id          = one(random_uuid.telemetry).result
    avm_module_source  = one(data.modtm_module_source.telemetry).module_source
    avm_module_version = one(data.modtm_module_source.telemetry).module_version
  })
}
```

--------------------------------

### Set Azure Subscription Command

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Shows the command to set the active Azure subscription context using the Azure CLI. This is necessary if Terraform cannot infer the correct subscription ID.

```bash
az account set --subscription "12345678-1234-1234-1234-123456789012"
```

--------------------------------

### Multiple Role Assignments in Terraform

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Demonstrates how to define multiple role assignments using a map in Terraform, each processed individually.

```hcl
role_assignments = {
  "assignment1" = { ... }
  "assignment2" = { ... }
  "assignment3" = { ... }
}
```

--------------------------------

### Valid and Invalid Role Definition Identifiers

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

Shows correct ways to specify role definitions for role assignments. Use standard role names or full definition IDs; invalid names will cause errors.

```hcl
# ❌ INVALID - role name doesn't exist
role_definition_id_or_name = "InvalidRole"

# ✅ VALID - use standard role names
role_definition_id_or_name = "Reader"
role_definition_id_or_name = "Contributor"
role_definition_id_or_name = "Storage Blob Data Reader"

# ✅ VALID - use role definition ID
role_definition_id_or_name = "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7"
```

--------------------------------

### Configure Operation Timeouts

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/configuration.md

Set custom timeout durations for create, delete, read, and update operations. Uses AzAPI provider defaults when null. Values must be parsable as Go duration strings.

```hcl
timeouts = {
  create = "10m"
  delete = "5m"
  read   = "2m"
  update = "10m"
}
```

--------------------------------

### Remove Lock to Enable Deletion

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Demonstrates how to remove a 'CanNotDelete' lock to allow deletion of a resource group. The lock must be set to null before applying changes to delete the resource group.

```hcl
# Remove lock first
lock = null  # Then apply
# Now the resource group can be deleted
```

--------------------------------

### Module Output Mapping for Resource Group

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Maps the outputs of the `azapi_resource.this` resource to module outputs, providing access to the full resource, its ID, name, and location.

```hcl
output "resource" {
  description = "This is the full output for the resource group."
  value       = azapi_resource.this
}

output "resource_id" {
  description = "The resource Id of the resource group"
  value       = azapi_resource.this.id
}

output "name" {
  description = "The name of the resource group"
  value       = azapi_resource.this.name
}

output "location" {
  description = "The location of the resource group"
  value       = azapi_resource.this.location
}
```

--------------------------------

### Azure CLI Login Command

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/data-sources.md

Provides the command to log in to Azure using the Azure CLI, a prerequisite for Terraform to authenticate when using environment variables or Azure CLI authentication.

```bash
az login
```

--------------------------------

### Terraform Configuration for ABAC Conditions

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Illustrates defining a complex ABAC condition using Terraform's heredoc syntax for granular access control.

```hcl
condition = <<-EOT
(
  (
    !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})
  )
  OR
  (
    @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'allowed-container'
  )
)
EOT
condition_version = "2.0"
```

--------------------------------

### Resource Group with Managed By

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/examples.md

Create a resource group that is managed by another service, such as Managed Applications or Databricks. The `managed_by` property indicates ownership by another service and is read-only after creation.

```hcl
data "azapi_client_config" "current" {}

# First, create the managing resource
resource "azapi_resource" "managing_app" {
  location  = "eastus"
  name      = "managed-app-rg"
  parent_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
  type      = "Microsoft.Resources/resourceGroups@2025-04-01"
  body = {
    properties = {}
  }
}

# Create a managed resource group
module "managed_resource_group" {
  source = "Azure/avm-res-resources-resourcegroup/azurerm"

  location   = "eastus"
  name       = "application-managed-rg"
  managed_by = azapi_resource.managing_app.id
  
  tags = {
    ManagedBy = "ManagedApplication"
  }
}

output "managed_rg_id" {
  value = module.managed_resource_group.resource_id
}

output "manager_rg_id" {
  value = azapi_resource.managing_app.id
}
```

--------------------------------

### Resource Group Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Defines the main resource group resource using the `azapi_resource` type. It includes essential properties like location, name, type, and optional configurations for managedBy, telemetry headers, tags, retry settings, and timeouts.

```hcl
resource "azapi_resource" "this" {
  location  = var.location
  name      = var.name
  parent_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}"
  type      = "Microsoft.Resources/resourceGroups@2025-04-01"
  
  body = {
    properties = {}
    managedBy  = var.managed_by
  }
  
  # Telemetry headers (optional)
  create_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  read_headers   = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  update_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  delete_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  
  response_export_values = ["id", "name", "location"]
  
  tags   = var.tags
  retry  = var.retry
  
  timeouts {
    create = var.timeouts.create
    delete = var.timeouts.delete
    read   = var.timeouts.read
    update = var.timeouts.update
  }
}
```

--------------------------------

### Resource Group Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-resources-resourcegroup/blob/main/_autodocs/api-reference/resources.md

Configures the main resource group using the azapi_resource provider. Includes settings for name, parent ID, type, and body, with optional telemetry and retry configurations.

```hcl
resource "azapi_resource" "lock" {
  count = var.lock != null ? 1 : 0

  name                   = coalesce(module.interfaces.lock_azapi.name, "lock-${var.lock.kind}")
  parent_id              = azapi_resource.this.id
  type                   = module.interfaces.lock_azapi.type
  body                   = module.interfaces.lock_azapi.body
  
  create_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  read_headers   = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  update_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  delete_headers = var.enable_telemetry ? { "User-Agent" : local.avm_azapi_header } : null
  
  response_export_values = []
  
  retry = var.retry
  
  timeouts {
    create = var.timeouts.create
    delete = var.timeouts.delete
    read   = var.timeouts.read
    update = var.timeouts.update
  }
}

```