### Configure API Management Products

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

Example of how to define products for an API Management service, including display name, description, and associated APIs.

```terraform
products = {
  "starter" = {
    display_name          = "Starter"
    description           = "Starter product for new developers"
    subscription_required = true
    approval_required     = false
    state                 = "published"
    api_names             = ["petstore-api", "weather-api"]
    group_names           = ["developers"]
  }
}
```

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

### API Management Service API Version Set Example

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

An example of how to configure API Version Sets for an API Management service. This snippet demonstrates setting up a version set that uses a header for versioning.

```terraform
api_version_sets = {
  "my-api-versions" = {
    display_name        = "My API Versions"
    versioning_scheme   = "Header"
    version_header_name = "api-version"
    description         = "Version set for My API"
  }
}
```

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

### API Configuration Example

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

Defines an API for the API Management service, including its display name, path, protocols, and operations. Use this to configure a new API.

```terraform
apis = {
  "petstore-api" = {
    display_name = "Petstore API"
    path         = "petstore"
    protocols    = ["https"]
    service_url  = "https://petstore.swagger.io/v2"

    operations = {
      "get-pets" = {
        display_name = "Get all pets"
        method       = "GET"
        url_template = "/pets"
      }
    }
  }
}
```

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

### Configure API Management Backends

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

Example of defining HTTP backends for an API Management service. Includes configurations for a test backend and an Azure AI Foundry backend with resource ID.

```terraform
backends = {
  "httpbin-backend" = {
    protocol    = "http"
    url         = "https://httpbin.org"
    description = "HTTPBin test backend"
    tls = {
      validate_certificate_chain = true
      validate_certificate_name  = true
    }
  }
  "ai-foundry-backend" = {
    protocol    = "http"
    url         = "https://my-ai-service.cognitiveservices.azure.com/openai"
    description = "Azure AI Foundry backend"
    resource_id = "/subscriptions/.../providers/Microsoft.CognitiveServices/accounts/my-ai-service"
  }
}
```

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

### Terraform Configuration for AI Foundry Backend Example

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

This Terraform configuration sets up the necessary Azure resources for an AI Foundry backend with API Management. It includes provider configurations, naming conventions, resource group, Key Vault, Storage Account, AI Services, AI Foundry hub, and AI Foundry project.

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

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {
  storage_use_azuread = true

  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = false
    }
  }
}

data "azurerm_client_config" "current" {}

# This ensures we have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.3.0"
}

# =================================================================
# Resource Group
# =================================================================
resource "azurerm_resource_group" "this" {
  location = var.location
  name     = module.naming.resource_group.name_unique
}

# =================================================================
# AI Foundry Prerequisites: Key Vault, Storage Account, AI Services
# =================================================================

resource "azurerm_key_vault" "this" {
  location                 = azurerm_resource_group.this.location
  name                     = module.naming.key_vault.name_unique
  resource_group_name      = azurerm_resource_group.this.name
  sku_name                 = "standard"
  tenant_id                = data.azurerm_client_config.current.tenant_id
  purge_protection_enabled = true
}

resource "azurerm_key_vault_access_policy" "deployer" {
  key_vault_id = azurerm_key_vault.this.id
  object_id    = data.azurerm_client_config.current.object_id
  tenant_id    = data.azurerm_client_config.current.tenant_id
  key_permissions = [
    "Create",
    "Get",
    "Delete",
    "Purge",
    "GetRotationPolicy",
  ]
}

resource "azurerm_storage_account" "this" {
  account_replication_type        = "ZRS"
  account_tier                    = "Standard"
  location                        = azurerm_resource_group.this.location
  name                            = module.naming.storage_account.name_unique
  resource_group_name             = azurerm_resource_group.this.name
  allow_nested_items_to_be_public = false
  shared_access_key_enabled       = false
}

resource "azurerm_ai_services" "this" {
  location            = azurerm_resource_group.this.location
  name                = "${module.naming.cognitive_account.name_unique}-ais"
  resource_group_name = azurerm_resource_group.this.name
  sku_name            = "S0"
}

# =================================================================
# AI Foundry Hub
# =================================================================
resource "azurerm_ai_foundry" "this" {
  key_vault_id        = azurerm_key_vault.this.id
  location            = azurerm_resource_group.this.location
  name                = "${module.naming.cognitive_account.name_unique}-hub"
  resource_group_name = azurerm_resource_group.this.name
  storage_account_id  = azurerm_storage_account.this.id

  identity {
    type = "SystemAssigned"
  }
}

# =================================================================
# AI Foundry Project
# =================================================================
resource "azurerm_ai_foundry_project" "this" {
  ai_services_hub_id = azurerm_ai_foundry.this.id
  location           = azurerm_ai_foundry.this.location
  name               = "${module.naming.cognitive_account.name_unique}-project"

  identity {
    type = "SystemAssigned"
  }
}

# =================================================================
# Grant APIM managed identity "Cognitive Services OpenAI User" role
# on the AI Services account for managed identity authentication
# =================================================================
resource "azurerm_role_assignment" "apim_cognitive_services" {
  principal_id         = module.apim.workspace_identity.principal_id
  scope                = azurerm_ai_services.this.id
  role_definition_name = "Cognitive Services OpenAI User"
}

# =================================================================
# API Management Module with AI Foundry Backend

```

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

### Terraform Configuration and Provider Setup

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/vnet_private_endpoint/README.md

Defines the required Terraform version, providers (Azurerm), and feature configurations for Azure resources. Ensure your Terraform version meets the specified requirements.

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

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {

  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = false
    }

  }
}
```

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

### API Management Service Module Call

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

Example of how to call the API Management service module, defining subscription details and network zones. Ensure correct subscription scope and state are set.

```terraform
module "apim" {
  source = "git::https://github.com/Azure/terraform-azurerm-avm-res-apimanagement-service.git"

  # Resource specific variables
  environment = "global"
  location    = "eastus"
  name        = "my-apim-service"
  resource_group_name = "my-resource-group"
  publisher_name      = "My Company"
  publisher_email     = "myemail@example.com"

  # Optional variables
  sku_name = "Developer_1"

  # Example of subscriptions
  subscriptions = {
    "starter-subscription" = {
      display_name     = "Starter Subscription"
      scope_type       = "product"
      scope_identifier = "starter"
      state            = "active"
      allow_tracing    = true
    }

    "premium-subscription" = {
      display_name     = "Premium Subscription"
      scope_type       = "product"
      scope_identifier = "premium"
      state            = "submitted" # Awaiting approval (because premium requires approval)
      allow_tracing    = true
    }
  }
  zones = ["1", "2", "3"]
}
```

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

### API Management Role Assignment Configuration

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

Example of configuring role assignments for an API Management service, specifying role definition, principal ID, and optional conditions.

```hcl
map(object({
    role_definition_id_or_name             = string
    principal_id                           = string
    description                            = optional(string, null)
    skip_service_principal_aad_check       = optional(bool, false)
    condition                              = optional(string, null)
    condition_version                      = optional(string, null)
    delegated_managed_identity_resource_id = optional(string, null)
    principal_type                         = optional(string, null)
  }))
```

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

### Configure Subscription for AI Product

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Sets up an active subscription for the 'ai-product' named 'ai-subscription'. This subscription allows tracing and is scoped to the product.

```hcl
subscriptions = {
    "ai-subscription" = {
      display_name     = "AI Services Subscription"
      scope_type       = "product"
      scope_identifier = "ai-product"
      state            = "active"
      allow_tracing    = true
    }
  }
```

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

### Configure API Management Service with APIs, Backends, and Products

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

This snippet shows a complete module call for setting up an API Management service. It includes defining APIs with policies and operations, configuring backends, setting named values (including secrets), and creating products to package APIs.

```terraform
module "apim" {
  source = "../../"

  location            = azurerm_resource_group.this.location
  name                = module.naming.api_management.name_unique
  publisher_email     = "admin@contoso.com"
  resource_group_name = azurerm_resource_group.this.name
  
  apis = {
    "echo-api" = {
      display_name          = "Echo API"
      path                  = "echo"
      protocols             = ["https"]
      revision              = "1"
      description           = "Simple echo API for testing - returns request information"
      subscription_required = true
      service_url           = "http://echoapi.cloudapp.net/api"

      policy = {
        xml_content = <<-XML
<policies>
  <inbound>
    <base />
    <rate-limit calls="100" renewal-period="60" />
    <set-header name="X-API-Name" exists-action="override">
      <value>Echo API</value>
    </set-header>
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-header name="X-Powered-By" exists-action="delete" />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>
XML
      }

      operations = {
        "get-resource" = {
          display_name = "Get Resource"
          method       = "GET"
          url_template = "/resource"
          description  = "Echo back request information"

          responses = [
            {
              status_code = 200
              description = "Success - returns request echo"
              representations = [
                {
                  content_type = "application/json"
                }
              ]
            }
          ]
        }
      }
    }
  }
  
  backends = {
    "echo-backend" = {
      protocol    = "http"
      url         = "https://echoapi.cloudapp.net/api"
      description = "Echo API backend service"
      title       = "Echo Backend"
      tls = {
        validate_certificate_chain = true
        validate_certificate_name  = true
      }
    }
  }
  enable_telemetry = var.enable_telemetry
  
  managed_identities = {
    system_assigned = true
  }
  
  named_values = {
    "backend-url" = {
      display_name = "Backend-URL"
      value        = "https://echoapi.cloudapp.net/api"
      tags         = ["configuration", "url"]
    }

    "api-key" = {
      display_name = "API-Key"
      value        = "secret-key-value-12345"
      secret       = true
      tags         = ["secret", "api"]
    }

    "environment" = {
      display_name = "Environment"
      value        = "development"
      tags         = ["environment"]
    }
  }
  
  products = {
    "starter" = {
      display_name          = "Starter"
      description           = "Basic API access for developers"
      subscription_required = true
      approval_required     = false
      state                 = "published"
      terms                 = "By subscribing to this product, you agree to our terms of service."
      api_names             = ["echo-api"]
      group_names           = ["developers"]
    }

    "premium" = {
      display_name          = "Premium"
      description           = "Premium access with higher rate limits - requires approval"
      subscription_required = true
      approval_required     = true
      subscriptions_limit   = 10
      state                 = "published"
      api_names             = ["echo-api"]
      group_names           = ["developers", "guests"]
    }
  }
  publisher_name = "Contoso"
  sku_name       = "Premium_3"
}
```

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

### Completions

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Creates a completion for the given deployment. This endpoint is compatible with the Azure OpenAI Completions API.

```APIDOC
## POST /deployments/{deployment-id}/completions

### Description
Creates a completion for the given deployment.

### Method
POST

### Endpoint
/deployments/{deployment-id}/completions

### Parameters
#### Path Parameters
- **deployment-id** (string) - Required - The deployment name of the model

#### Request Body
- **description**: Completion request body
- **representations**: 
  - content_type: application/json

### Response
#### Success Response (200)
- **description**: Successful completion response
- **representations**: 
  - content_type: application/json
```

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

### Terraform Configuration for API Management Service

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/system_assigned_identity/README.md

This HCL code block defines the Terraform configuration, including required providers and a default example for deploying an API Management service with system-assigned managed identity.

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

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {

  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = false
    }

  }
}

# This ensures we have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.3.0"
}

# This is required for resource modules
resource "azurerm_resource_group" "this" {
  location = var.location
  name     = module.naming.resource_group.name_unique
}

# This is the module call
# Leaving location as `null` will cause the module to use the resource group location
# with a data source.
module "test" {
  source = "../../"

  location            = azurerm_resource_group.this.location
  name                = module.naming.api_management.name_unique
  publisher_email     = var.publisher_email
  resource_group_name = azurerm_resource_group.this.name
  enable_telemetry    = var.enable_telemetry
  managed_identities = {
    system_assigned = true
  }
  publisher_name = "Apim Example Publisher"
  sku_name       = "Premium_3"
  tags = {
    environment = "test"
    cost_center = "test"
  }
  zones = ["1", "2", "3"] # For compliance with WAF
}
```

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

### Chat Completions

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Creates a chat completion for the given deployment. This endpoint is compatible with the Azure OpenAI Chat Completions API.

```APIDOC
## POST /deployments/{deployment-id}/chat/completions

### Description
Creates a chat completion for the given deployment.

### Method
POST

### Endpoint
/deployments/{deployment-id}/chat/completions

### Parameters
#### Path Parameters
- **deployment-id** (string) - Required - The deployment name of the model

#### Request Body
- **description**: Chat completion request body
- **representations**: 
  - content_type: application/json

### Response
#### Success Response (200)
- **description**: Successful chat completion response
- **representations**: 
  - content_type: application/json
```

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

### API Management Sign-Up Settings

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

Configure user sign-up settings for the API Management service, including whether sign-up is enabled and if user consent is required for terms of service.

```hcl
object({
    enabled = bool
    terms_of_service = object({
      consent_required = bool
      enabled          = bool
      text             = optional(string, null)
    })
  })
```

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

### Virtual Network and Subnet Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/vnet_private_endpoint/README.md

Creates a virtual network with specified address space and subnets for testing purposes. The subnet configuration includes details like name, address prefixes, and service endpoints.

```hcl
# Create a virtual network for testing if needed
module "virtual_network" {
  source  = "Azure/avm-res-network-virtualnetwork/azurerm"
  version = "0.9.2"

  address_space       = ["10.0.0.0/16"]
  location            = azurerm_resource_group.this.location
  resource_group_name = azurerm_resource_group.this.name
  name                = module.naming.virtual_network.name_unique
  subnets = {
    default_subnet = {
      name             = "default_subnet"
      address_prefixes = ["10.0.1.0/24"]
      # delegations       = {}
    }
    pe_subnet = {
      name              = "pe_subnet"
      address_prefixes  = ["10.0.2.0/24"]
      service_endpoints = []
      # delegations       = {}
    }
  }
}
```

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

### API Management Service Module Call

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/preprovisioned_virtual_network_private_endpoints_with_permissions/README.md

This is the main module call for deploying the API Management service. Leaving the location as `null` will default to the resource group's location. Ensure all required variables are provided.

```hcl
# This is the module call
# Leaving location as `null` will cause the module to use the resource group location

```

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

### Default Terraform Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/default/README.md

This configuration deploys the Azure API Management module in its simplest form. It sets up the Terraform version, required providers, and a basic resource group. The module call includes essential parameters like location, name, publisher email, resource group name, telemetry enablement, publisher name, SKU, tags, and zones.

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

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {

  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = false
    }

  }
}

# This ensures we have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.3.0"
}

# This is required for resource modules
resource "azurerm_resource_group" "this" {
  location = var.location
  name     = module.naming.resource_group.name_unique
}

# This is the module call
# Leaving location as `null` will cause the module to use the resource group location
# with a data source.
module "test" {
  source = "../../"

  location            = azurerm_resource_group.this.location
  name                = module.naming.api_management.name_unique
  publisher_email     = var.publisher_email
  resource_group_name = azurerm_resource_group.this.name
  enable_telemetry    = var.enable_telemetry
  publisher_name      = "Apim Example Publisher"
  sku_name            = "Premium_3"
  tags = {
    environment = "test"
    cost_center = "test"
  }
  zones = ["1", "2", "3"] # For compliance with WAF
}
```

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

### Terraform Configuration for Azure API Management Module

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

Sets up the Terraform version, required providers (azurerm, random), and provider configuration. Includes a module for random region selection and naming conventions.

```hcl
terraform {
  required_version = ">= 1.9"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0, < 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.6.0, < 4.0.0"
    }
  }
}

provider "azurerm" {
  features {}
}

## Section to provide a random Azure region for the resource group
# This allows us to randomize the region for the resource group, or use a specified region.
module "regions" {
  source  = "Azure/regions/azurerm"
  version = "0.8.1"
}

# Use specified region or random one if not provided
locals {
  azure_region = var.azure_region != null ? var.azure_region : module.regions.regions[random_integer.region_index.result].name
}

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

# This ensures we have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.4.2"
}

# This is required for resource modules
resource "azurerm_resource_group" "this" {
  location = local.azure_region
  name     = module.naming.resource_group.name_unique
}

```

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

### Define API Product for AI Foundry

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Configures a product named 'ai-product' for AI Foundry API access. This product requires subscription, is published, and grants access to the 'ai-foundry-api' API for 'developers' group.

```hcl
products = {
    "ai-product" = {
      display_name          = "AI Services"
      description           = "AI Foundry API access"
      subscription_required = true
      approval_required     = false
      state                 = "published"
      api_names             = ["ai-foundry-api"]
      group_names           = ["developers"]
    }
  }
```

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

### Terraform Configuration with Azure Provider

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/preprovisioned_virtual_network_private_endpoints_with_permissions/README.md

Sets up the Terraform version and required providers, including the Azure provider with specific features enabled. Ensure the Azure provider version is compatible.

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

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0"
    }
  }
}

provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = false
    }

  }
}
```

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

### API Management Security Settings

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

Configure various security protocols like SSL 3.0, TLS 1.0, 1.1, and 1.3 for both backend and frontend connections. Also includes options for enabling specific cipher suites and disabling older protocols like triple DES.

```hcl
object({
    enable_backend_ssl30                                = optional(bool, false)
    enable_backend_tls10                                = optional(bool, false)
    enable_backend_tls11                                = optional(bool, false)
    enable_backend_tls13                                = optional(bool)
    enable_frontend_ssl30                               = optional(bool, false)
    enable_frontend_tls10                               = optional(bool, false)
    enable_frontend_tls11                               = optional(bool, false)
    enable_frontend_tls13                               = optional(bool)
    tls_ecdhe_ecdsa_with_aes128_cbc_sha_ciphers_enabled = optional(bool, false)
    tls_ecdhe_ecdsa_with_aes256_cbc_sha_ciphers_enabled = optional(bool, false)
    tls_ecdhe_rsa_with_aes128_cbc_sha_ciphers_enabled   = optional(bool, false)
    tls_ecdhe_rsa_with_aes256_cbc_sha_ciphers_enabled   = optional(bool, false)
    tls_rsa_with_aes128_cbc_sha256_ciphers_enabled      = optional(bool, false)
    tls_rsa_with_aes128_cbc_sha_ciphers_enabled         = optional(bool, false)
    tls_rsa_with_aes128_gcm_sha256_ciphers_enabled      = optional(bool, false)
    tls_rsa_with_aes256_gcm_sha384_ciphers_enabled      = optional(bool, false)
    tls_rsa_with_aes256_cbc_sha256_ciphers_enabled      = optional(bool, false)
    tls_rsa_with_aes256_cbc_sha_ciphers_enabled         = optional(bool, false)
    triple_des_ciphers_enabled                          = optional(bool, false)
  })
```

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

### APIM Service Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Defines the APIM service configuration, including enabling telemetry, setting the publisher name, SKU, and availability zones.

```hcl
enable_telemetry = var.enable_telemetry
  # Enable system-assigned managed identity for backend authentication
  managed_identities = {
    system_assigned = true
  }
  # =================================================================
  # Products Configuration
  # =================================================================
  products = {
    "ai-product" = {
      display_name          = "AI Services"
      description           = "AI Foundry API access"
      subscription_required = true
      approval_required     = false
      state                 = "published"
      api_names             = ["ai-foundry-api"]
      group_names           = ["developers"]
    }
  }
  publisher_name = "Contoso"
  sku_name       = "Premium_3"
  # =================================================================
  # Subscriptions Configuration
  # =================================================================
  subscriptions = {
    "ai-subscription" = {
      display_name     = "AI Services Subscription"
      scope_type       = "product"
      scope_identifier = "ai-product"
      state            = "active"
      allow_tracing    = true
    }
  }
  zones = ["1", "2", "3"]
}
```

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

### Virtual Network and Subnet Configuration

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/preprovisioned_virtual_network_private_endpoints_with_permissions/README.md

Defines a virtual network with a specified address space and creates multiple subnets for different purposes, including private endpoints, APIM, and a default subnet. Ensure address spaces do not overlap.

```hcl
# Create Virtual Network and Subnets
resource "azurerm_virtual_network" "this" {
  location            = azurerm_resource_group.this.location
  name                = module.naming.virtual_network.name_unique
  resource_group_name = azurerm_resource_group.this.name
  address_space       = ["10.0.0.0/16"]
  tags = {
    environment = "test"
    cost_center = "test"
  }
}

resource "azurerm_subnet" "private_endpoints" {
  address_prefixes     = ["10.0.1.0/24"]
  name                 = "private_endpoints"
  resource_group_name  = azurerm_resource_group.this.name
  virtual_network_name = azurerm_virtual_network.this.name
}

resource "azurerm_subnet" "apim_subnet" {
  address_prefixes     = ["10.0.2.0/24"]
  name                 = "apim_subnet"
  resource_group_name  = azurerm_resource_group.this.name
  virtual_network_name = azurerm_virtual_network.this.name
}

resource "azurerm_subnet" "default" {
  address_prefixes     = ["10.0.3.0/24"]
  name                 = "default"
  resource_group_name  = azurerm_resource_group.this.name
  virtual_network_name = azurerm_virtual_network.this.name
}
```

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

### API Management Delegation Settings

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

Defines delegation settings for the API Management service, including subscription and user registration enablement, and URLs for delegation.

```hcl
object({
    subscriptions_enabled     = optional(bool, false)
    user_registration_enabled = optional(bool, false)
    url                       = optional(string, null)
    validation_key            = optional(string, null)
  })
```

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

### Configure Azure API Management Service with Private Endpoints and Role Assignments

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/preprovisioned_virtual_network_private_endpoints_with_permissions/README.md

This snippet demonstrates the configuration of an Azure API Management service using a Terraform module. It includes setting the location, name, publisher details, private endpoint configurations with DNS zone linking, and various role assignments for different principals. Ensure the necessary data sources and resources (like azurerm_resource_group, azurerm_subnet, module.private_dns_apim, data.azurerm_client_config, azurerm_user_assigned_identity) are defined elsewhere in your Terraform configuration.

```hcl
module "test" {
  source = "../../"

  # Remove the hardcoded location and use the resource group location
  location            = azurerm_resource_group.this.location
  name                = module.naming.api_management.name_unique
  publisher_email     = var.publisher_email
  resource_group_name = azurerm_resource_group.this.name
  enable_telemetry    = var.enable_telemetry
  # Add private endpoint configuration
  private_endpoints = {
    endpoint1 = {
      name               = "pe-${module.naming.api_management.name_unique}"
      subnet_resource_id = azurerm_subnet.private_endpoints.id

      # Link to the private DNS zone we created
      private_dns_zone_resource_ids = [
        module.private_dns_apim.resource.id
      ]

      tags = {
        environment = "test"
        service     = "apim"
      }
    }
  }
  publisher_name = "Apim Example Publisher"
  role_assignments = {
    deployment_user_secrets = {
      role_definition_id_or_name = "Key Vault Administrator"
      principal_id               = data.azurerm_client_config.current.object_id
    }

    cosmos_db = {
      role_definition_id_or_name       = "Key Vault Crypto Service Encryption User"
      principal_id                     = "a232010e-820c-4083-83bb-3ace5fc29d0b"
      skip_service_principal_aad_check = true # because it isn't a traditional SP
    }

    uai = {
      role_definition_id_or_name = "Key Vault Crypto Officer" # Key Vault Crypto Officer
      principal_id               = azurerm_user_assigned_identity.cmk.principal_id
    }
  }
  sku_name = "Premium_3"
  tags = {
    environment = "test"
    cost_center = "test"
  }
  zones = ["1", "2", "3"] # For compliance with WAF
}

```

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

### API Management Sign-In Settings

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

Configure whether user sign-in is enabled for the API Management service. When enabled, anonymous users are redirected to the sign-in page.

```hcl
object({
    enabled = bool
  })
```

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

### Naming Module for Resource Naming

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/vnet_private_endpoint/README.md

Utilizes the Azure naming module to generate CAF compliant unique names for resources. This is essential for maintaining consistency and avoiding naming conflicts.

```hcl
# This ensures we have unique CAF compliant names for our resources.
module "naming" {
  source  = "Azure/naming/azurerm"
  version = "0.3.0"
}
```

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

### Embeddings

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Creates embeddings for the given deployment. This endpoint is compatible with the Azure OpenAI Embeddings API.

```APIDOC
## POST /deployments/{deployment-id}/embeddings

### Description
Creates embeddings for the given deployment.

### Method
POST

### Endpoint
/deployments/{deployment-id}/embeddings

### Parameters
#### Path Parameters
- **deployment-id** (string) - Required - The deployment name of the model

#### Request Body
- **description**: Embeddings request body
- **representations**: 
  - content_type: application/json

### Response
#### Success Response (200)
- **description**: Successful embeddings response
- **representations**: 
  - content_type: application/json
```

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

### Configure APIM Backend for AI Foundry

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

Defines the backend configuration for AI Foundry, routing traffic to the AI Services endpoint. It specifies the URL, description, title, and resource ID for the backend. The resource_id is the Cognitive Services audience URL used for APIM managed identity authentication.

```hcl
backend {
      url         = "${azurerm_ai_services.this.endpoint}openai"
      description = "Azure AI Foundry backend via AI Services"
      title       = "AI Foundry"
      # Routes through the AI Services endpoint;
      # resource_id is the Cognitive Services audience URL
      # used by APIM managed identity authentication (not an ARM resource ID in this case).
      resource_id = "https://management.azure.com${azurerm_ai_services.this.id}"
    }
```

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

### API Management Backend Configuration Type

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

Defines the structure and types for backend configurations in API Management, including credentials, proxy, and TLS settings.

```hcl
map(object({
    protocol    = string
    url         = string
    description = optional(string)
    resource_id = optional(string)
    title       = optional(string)

    credentials = optional(object({
      authorization = optional(object({
        parameter = optional(string)
        scheme    = optional(string)
      }))
      certificate = optional(list(string), [])
      header      = optional(map(string), {})
      query       = optional(map(string), {})
    }))

    proxy = optional(object({
      url      = string
      username = string
      password = optional(string)
    }))

    service_fabric_cluster = optional(object({
      client_certificate_thumbprint    = optional(string)
      client_certificate_id            = optional(string)
      management_endpoints             = list(string)
      max_partition_resolution_retries = number
      server_certificate_thumbprints   = optional(list(string), [])
      server_x509_name = optional(list(object({
        issuer_certificate_thumbprint = string
        name                          = string
      })), [])
    }))

    tls = optional(object({
      validate_certificate_chain = optional(bool)
      validate_certificate_name  = optional(bool)
    }))
  }))
```

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

### Configure API Management Subscriptions

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

Define subscriptions for the API Management service, specifying display name, scope type, and optional parameters like state and tracing.

```terraform
subscriptions = {
  "developer-sub" = {
    display_name     = "Developer Subscription"
    scope_type       = "product"
    scope_identifier = "starter"
    state            = "active"
    allow_tracing    = true
  }
  "api-specific-sub" = {
    display_name     = "Petstore API Subscription"
    scope_type       = "api"
    scope_identifier = "petstore-api"
    state            = "active"
  }
}
```

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

### Configure AI Foundry API in API Management

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/ai-foundry/README.md

This snippet defines an API in Azure API Management that proxies to the AI Foundry backend. It specifies the API's path, protocols, and includes a policy to authenticate using managed identity.

```terraform
module "apim" {
  source = "../../"

  location            = azurerm_resource_group.this.location
  name                = module.naming.api_management.name_unique
  publisher_email     = var.publisher_email
  resource_group_name = azurerm_resource_group.this.name
  apis = {
    "ai-foundry-api" = {
      display_name          = "AI Foundry API"
      path                  = "ai"
      protocols             = ["https"]
      revision              = "1"
      description           = "Azure AI Foundry API with managed identity authentication"
      subscription_required = true
      policy = {
        xml_content = <<-XML
<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="ai-foundry-backend" />
    <authentication-managed-identity resource="https://cognitiveservices.azure.com/" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>
XML
      }

      operations = {
        "chat-completions" = {
          display_name = "Chat Completions"
          method       = "POST"
          url_template = "/deployments/{deployment-id}/chat/completions"
          description  = "Creates a chat completion for the given deployment"

          template_parameters = [
            {
              name        = "deployment-id"
              required    = true
              type        = "string"
              description = "The deployment name of the model"
            }
          ]

          request = {
            description = "Chat completion request body"
            representations = [
              {
                content_type = "application/json"
              }
            ]
          }

          responses = [
            {
              status_code = 200
              description = "Successful chat completion response"
              representations = [
                {
                  content_type = "application/json"
                }
              ]
            }
          ]
        }

        "completions" = {
          display_name = "Completions"
          method       = "POST"
          url_template = "/deployments/{deployment-id}/completions"
          description  = "Creates a completion for the given deployment"

          template_parameters = [
            {
              name        = "deployment-id"
              required    = true
              type        = "string"
              description = "The deployment name of the model"
            }
          ]

          request = {
            description = "Completion request body"
            representations = [
              {
                content_type = "application/json"
              }
            ]
          }

          responses = [
            {
              status_code = 200
              description = "Successful completion response"
              representations = [
                {
                  content_type = "application/json"
                }
              ]
            }
          ]
        }

        "embeddings" = {
          display_name = "Embeddings"
          method       = "POST"
          url_template = "/deployments/{deployment-id}/embeddings"
          description  = "Creates embeddings for the given deployment"

          template_parameters = [
            {
              name        = "deployment-id"
              required    = true
              type        = "string"
              description = "The deployment name of the model"
            }
          ]

          request = {
            description = "Embeddings request body"
            representations = [
              {
                content_type = "application/json"
              }
            ]
          }

          responses = [
            {
              status_code = 200
              description = "Successful embeddings response"
              representations = [
                {
                  content_type = "application/json"
                }
              ]
            }
          ]
        }
      }
    }
  }
  backends = {
    "ai-foundry-backend" = {
      protocol    = "http"

```

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

### Azure Resource Group Creation

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/preprovisioned_virtual_network_private_endpoints_with_permissions/README.md

Creates an Azure resource group using the location and a unique name generated by the naming module. This resource group will contain all deployed resources.

```hcl
resource "azurerm_resource_group" "this" {
  location = var.location
  name     = module.naming.resource_group.name_unique
}
```

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

### Resource Group Creation

Source: https://github.com/azure/terraform-azurerm-avm-res-apimanagement-service/blob/main/examples/vnet_private_endpoint/README.md

Defines the Azure resource group where all resources will be deployed. It uses a unique name generated by the naming module.

```hcl
# This is required for resource modules
resource "azurerm_resource_group" "this" {
  location = var.location
  name     = module.naming.resource_group.name_unique
}
```

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

### API Management Service Protocol Settings

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

Defines the protocol settings for the API Management service, specifically enabling HTTP/2.

```hcl
object({
    enable_http2 = optional(bool, false)
  })
```

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

### API Management Service Zones Configuration

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

Define Availability Zones for the API Management service. This is only supported in the Premium tier.

```hcl
list(string)
```

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

### API Management Certificate Configuration Type

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

Defines the structure for certificate configurations, including encoded certificate, store name, and optional password.

```hcl
list(object({
    encoded_certificate  = string
    store_name           = string
    certificate_password = optional(string, null)
  }))
```

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

### API Management Resource Lock Configuration

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

Configures resource locks for the API Management service. Specify the lock 'kind' (CanNotDelete or ReadOnly) and optionally a 'name'. Changing the lock kind forces resource recreation.

```hcl
object({
    kind = string
    name = optional(string, null)
  })
```

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

### Define Global Policies for API Management

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

Configure service-level policies that apply to all APIs. This includes inbound, backend, outbound, and error handling rules.

```terraform
policy = {
  xml_content = <<XML
<policies>
  <inbound>
    <base />
    <cors allow-credentials="true">
      <allowed-origins>
        <origin>https://example.com</origin>
      </allowed-origins>
      <allowed-methods>
        <method>GET</method>
        <method>POST</method>
      </allowed-methods>
    </cors>
    <rate-limit-by-key calls="100" renewal-period="60" counter-key="@(context.Subscription.Id)" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-header name="X-Powered-By" exists-action="delete" />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>
XML
}
```

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

### API Management Diagnostic Settings Configuration

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

Configures diagnostic settings for the API Management service, allowing logs and metrics to be sent to various destinations like Log Analytics, Storage Accounts, or Event Hubs.

```hcl
map(object({
    name                                     = optional(string, null)
    log_categories                           = optional(set(string), [])
    log_groups                               = optional(set(string), ["allLogs"])
    metric_categories                        = optional(set(string), ["AllMetrics"])
    log_analytics_destination_type           = optional(string, "Dedicated")
    workspace_resource_id                    = optional(string, null)
    storage_account_resource_id              = optional(string, null)
    event_hub_authorization_rule_resource_id = optional(string, null)
    event_hub_name                           = optional(string, null)
    marketplace_partner_resource_id          = optional(string, null)
  }))
```

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

### API Management Hostname Configuration

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

Defines the hostname configurations for various API Management service endpoints like management, portal, developer portal, proxy, and SCM. Supports custom hostnames and SSL certificate binding, including Key Vault integration.

```hcl
object({
    management = optional(list(object({
      host_name                       = string
      key_vault_id                    = optional(string, null)
      certificate                     = optional(string, null)
      certificate_password            = optional(string, null)
      negotiate_client_certificate    = optional(bool, false)
      ssl_keyvault_identity_client_id = optional(string, null)
    })), [])
    portal = optional(list(object({
      host_name                       = string
      key_vault_id                    = optional(string, null)
      certificate                     = optional(string, null)
      certificate_password            = optional(string, null)
      negotiate_client_certificate    = optional(bool, false)
      ssl_keyvault_identity_client_id = optional(string, null)
    })), [])
    developer_portal = optional(list(object({
      host_name                       = string
      key_vault_id                    = optional(string, null)
      certificate                     = optional(string, null)
      certificate_password            = optional(string, null)
      negotiate_client_certificate    = optional(bool, false)
      ssl_keyvault_identity_client_id = optional(string, null)
    })), [])
    proxy = optional(list(object({
      host_name                       = string
      default_ssl_binding             = optional(bool, false)
      key_vault_id                    = optional(string, null)
      certificate                     = optional(string, null)
      certificate_password            = optional(string, null)
      negotiate_client_certificate    = optional(bool, false)
      ssl_keyvault_identity_client_id = optional(string, null)
    })), [])
    scm = optional(list(object({
      host_name                       = string
      key_vault_id                    = optional(string, null)
      certificate                     = optional(string, null)
      certificate_password            = optional(string, null)
      negotiate_client_certificate    = optional(bool, false)
      ssl_keyvault_identity_client_id = optional(string, null)
    })), [])
  })
```