apim-terraform

---
name: apim-terraform
description: Guide for creating Terraform files for Azure API Management (APIM) and related Azure services. Use when users want to create, modify, or understand Terraform configurations for APIM instances, APIs, backends, subscriptions, policies, products, loggers, diagnostics, and supporting infrastructure using the azurerm provider. This skill provides HCL syntax, resource definitions, and patterns from the Terraform Registry and this repository.
---

# APIM Terraform Skill

Guide for creating Terraform files for Azure API Management and related Azure services.

## Quick Start

### Minimum Viable APIM Deployment

```hcl
terraform {
  required_version = ">=1.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~>4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "rg" {
  name     = "example-resources"
  location = "westeurope"
}

resource "azurerm_api_management" "apim" {
  name                = "example-apim"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  publisher_name      = "My Company"
  publisher_email     = "company@example.com"
  sku_name            = "Developer_1"
}
```

## Resource Types

### Core APIM Resources

| Resource | Description |
|----------|-------------|
| `azurerm_api_management` | APIM service instance |
| `azurerm_api_management_api` | API definition |
| `azurerm_api_management_api_operation` | API operation |
| `azurerm_api_management_backend` | Backend service |
| `azurerm_api_management_subscription` | Subscription for API access |
| `azurerm_api_management_product` | Product grouping APIs |
| `azurerm_api_management_product_api` | Link product to API |

### Policy Resources

| Resource | Description |
|----------|-------------|
| `azurerm_api_management_policy` | Global policy |
| `azurerm_api_management_api_policy` | API-level policy |
| `azurerm_api_management_api_operation_policy` | Operation-level policy |
| `azurerm_api_management_product_policy` | Product-level policy |
| `azurerm_api_management_policy_fragment` | Reusable policy fragment |

### Monitoring Resources

| Resource | Description |
|----------|-------------|
| `azurerm_api_management_logger` | Logger (App Insights/Event Hub) |
| `azurerm_api_management_diagnostic` | Service-level diagnostics |
| `azurerm_api_management_api_diagnostic` | API-level diagnostics |

### Configuration Resources

| Resource | Description |
|----------|-------------|
| `azurerm_api_management_named_value` | Named value (property) |
| `azurerm_api_management_certificate` | Certificate |
| `azurerm_api_management_authorization_server` | OAuth server |
| `azurerm_api_management_openid_connect_provider` | OpenID provider |

For complete resource reference, see [references/apim-resources.md](references/apim-resources.md).

## Essential Patterns

### APIM Service with Managed Identity

```hcl
resource "azurerm_api_management" "apim" {
  name                          = "example-apim"
  location                      = azurerm_resource_group.rg.location
  resource_group_name           = azurerm_resource_group.rg.name
  publisher_name                = "My Company"
  publisher_email               = "noreply@example.com"
  sku_name                      = "BasicV2_1"
  virtual_network_type          = "None"
  public_network_access_enabled = true

  identity {
    type = "SystemAssigned"
  }
}
```

### API with OpenAPI Import

```hcl
resource "azurerm_api_management_api" "api" {
  name                  = "example-api"
  resource_group_name   = azurerm_resource_group.rg.name
  api_management_name   = azurerm_api_management.apim.name
  revision              = "1"
  display_name          = "Example API"
  path                  = "api"
  protocols             = ["https"]
  subscription_required = false
  api_type              = "http"

  import {
    content_format = "openapi-link"
    content_value  = "https://example.com/openapi.json"
  }

  subscription_key_parameter_names {
    header = "api-key"
    query  = "api-key"
  }
}
```

### Backend with Circuit Breaker (azapi)

For advanced backend features like circuit breakers, use the azapi provider:

```hcl
resource "azapi_resource" "backend" {
  type      = "Microsoft.ApiManagement/service/backends@2024-06-01-preview"
  parent_id = azurerm_api_management.apim.id
  name      = "example-backend"

  body = {
    properties = {
      url         = "https://backend.example.com/api"
      protocol    = "http"
      description = "Backend service"

      circuitBreaker = {
        rules = [
          {
            failureCondition = {
              count            = 1
              errorReasons     = ["Server errors"]
              interval         = "PT5M"
              statusCodeRanges = [{ min = 429, max = 429 }]
            }
            name             = "BreakerRule"
            tripDuration     = "PT1M"
            acceptRetryAfter = true
          }
        ]
      }
    }
  }
}
```

### Backend Pool for Load Balancing (azapi)

```hcl
resource "azapi_resource" "backend_pool" {
  type                      = "Microsoft.ApiManagement/service/backends@2024-06-01-preview"
  name                      = "backend-pool"
  parent_id                 = azurerm_api_management.apim.id
  schema_validation_enabled = false

  body = {
    properties = {
      description = "Load balancer for multiple backends"
      type        = "Pool"

      pool = {
        services = [
          { id = azapi_resource.backend1.id, priority = 1, weight = 100 },
          { id = azapi_resource.backend2.id, priority = 2, weight = 50 }
        ]
      }
    }
  }
}
```

### API Policy with XML

```hcl
resource "azurerm_api_management_api_policy" "policy" {
  api_name            = azurerm_api_management_api.api.name
  api_management_name = azurerm_api_management.apim.name
  resource_group_name = azurerm_resource_group.rg.name

  xml_content = <<XML
<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="backend-pool" />
    <authentication-managed-identity resource="https://cognitiveservices.azure.com" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>
XML
}
```

### Policy from File with Variable Substitution

```hcl
resource "azurerm_api_management_api_policy" "policy" {
  api_name            = azurerm_api_management_api.api.name
  api_management_name = azurerm_api_management.apim.name
  resource_group_name = azurerm_resource_group.rg.name

  xml_content = replace(file("policy.xml"), "{backend-id}", azapi_resource.backend_pool.name)
}
```

### Subscription

```hcl
resource "azurerm_api_management_subscription" "subscription" {
  display_name        = "example-subscription"
  api_management_name = azurerm_api_management.apim.name
  resource_group_name = azurerm_resource_group.rg.name
  api_id              = replace(azurerm_api_management_api.api.id, "/;rev=.*/", "")
  allow_tracing       = true
  state               = "active"
}
```

### Product

```hcl
resource "azurerm_api_management_product" "product" {
  product_id            = "example-product"
  api_management_name   = azurerm_api_management.apim.name
  resource_group_name   = azurerm_resource_group.rg.name
  display_name          = "Example Product"
  subscription_required = true
  approval_required     = true
  published             = true
}

resource "azurerm_api_management_product_api" "product_api" {
  api_name            = azurerm_api_management_api.api.name
  product_id          = azurerm_api_management_product.product.product_id
  api_management_name = azurerm_api_management.apim.name
  resource_group_name = azurerm_resource_group.rg.name
}
```

### Logging with Application Insights

```hcl
resource "azurerm_application_insights" "appinsights" {
  name                = "example-appinsights"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  application_type    = "web"
}

resource "azurerm_api_management_logger" "logger" {
  name                = "appinsights-logger"
  api_management_name = azurerm_api_management.apim.name
  resource_group_name = azurerm_resource_group.rg.name
  resource_id         = azurerm_application_insights.appinsights.id

  application_insights {
    instrumentation_key = azurerm_application_insights.appinsights.instrumentation_key
  }
}

resource "azurerm_api_management_diagnostic" "diagnostic" {
  identifier               = "applicationinsights"
  resource_group_name      = azurerm_resource_group.rg.name
  api_management_name      = azurerm_api_management.apim.name
  api_management_logger_id = azurerm_api_management_logger.logger.id

  sampling_percentage       = 5.0
  always_log_errors         = true
  log_client_ip             = true
  verbosity                 = "verbose"
  http_correlation_protocol = "W3C"

  frontend_request {
    body_bytes     = 32
    headers_to_log = ["content-type", "accept", "origin"]
  }

  frontend_response {
    body_bytes     = 32
    headers_to_log = ["content-type", "content-length", "origin"]
  }

  backend_request {
    body_bytes     = 32
    headers_to_log = ["content-type", "accept", "origin"]
  }

  backend_response {
    body_bytes     = 32
    headers_to_log = ["content-type", "content-length", "origin"]
  }
}
```

### Named Values

```hcl
resource "azurerm_api_management_named_value" "value" {
  name                = "example-property"
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.apim.name
  display_name        = "ExampleProperty"
  value               = "Example Value"
  secret              = false
}
```

### Role Assignment for Cognitive Services

```hcl
resource "azurerm_role_assignment" "cognitive_services_user" {
  scope                = azurerm_cognitive_account.ai_services.id
  role_definition_name = "Cognitive Services User"
  principal_id         = azurerm_api_management.apim.identity[0].principal_id
}
```

## SKU Reference

| SKU | Format | Notes |
|-----|--------|-------|
| Consumption | `Consumption_0` | Auto-scaling, capacity always 0 |
| Developer | `Developer_1` | Development/testing |
| Basic | `Basic_1` or `Basic_2` | Entry-level production |
| BasicV2 | `BasicV2_1` | New v2 tier |
| Standard | `Standard_1` to `Standard_4` | Production workloads |
| StandardV2 | `StandardV2_1` | New v2 tier |
| Premium | `Premium_1` to `Premium_12` | Enterprise features |
| PremiumV2 | `PremiumV2_1` | New v2 tier |

## Best Practices

1. **Use managed identity** for secure access to backend services
2. **Use azapi provider** for features not yet in azurerm (circuit breakers, backend pools)
3. **Store policies in separate files** and use `file()` function
4. **Use variables** for configurable values like locations, SKUs, and names
5. **Use `for_each`** for multiple similar resources (backends, deployments)
6. **Strip revision suffix** from API ID for subscriptions: `replace(api.id, "/;rev=.*/", "")`
7. **Add random suffix** to globally unique names using `random_string`

## Provider Requirements

```hcl
terraform {
  required_version = ">=1.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~>4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~>2.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~>3.0"
    }
  }
}

provider "azurerm" {
  features {}
}
```

## References

- [references/apim-resources.md](references/apim-resources.md) - Complete APIM resource definitions
- [references/ai-gateway-patterns.md](references/ai-gateway-patterns.md) - AI Gateway patterns from this repository

More agent context in Azure-Samples/AI-Gateway

7 other files this repository gives its agents.