Robertjam954/multimodal_rag_application / .claude/skills/azure-prepare
azure-prepare
FlaggedPrepare Azure apps for deployment (infra Bicep/Terraform, azure.yaml, Dockerfiles). Use for create/modernize or create+deploy; not cross-cloud migration (use azure-cloud-migrate). DO NOT USE FOR: copilot-sdk apps (use azure-hosted-copilot-sdk), or Python code-only App Service deploys (use python-appservice-deploy). WHEN: "create app", "build web app", "create API", "modernize application", "host on Azure", "deploy to Azure", "deploy to Azure using Terraform", "deploy to Azure App Service", "deploy to Azure App Service using Terraform", "deploy to Azure Container Apps", "generate Terraform", "generate Bicep", "function app", "timer trigger", "service bus trigger", "event-driven function", "managed identity".
references/recipes/azd/terraform.md
View on GitHub# AZD with Terraform
Use Azure Developer CLI (azd) with Terraform as the infrastructure provider.
## When to Use
Choose azd+Terraform when you want:
- **Terraform's multi-cloud capabilities** with **azd's deployment simplicity**
- Existing Terraform expertise but want `azd up` convenience
- Team familiar with Terraform but needs environment management
- Multi-cloud IaC with Azure-first deployment experience
## Benefits
| Feature | Pure Terraform | AZD + Terraform |
|---------|---------------|-----------------|
| Deploy command | `terraform apply` | `azd up` |
| Environment management | Manual workspaces | Built-in `azd env` |
| CI/CD generation | Manual setup | Auto-generated pipelines |
| Service deployment | Manual scripts | Automatic from azure.yaml |
| State management | Manual backend setup | Configurable |
| Multi-cloud | ✅ Yes | ✅ Yes |
## Configuration
### 1. azure.yaml Structure
Create `azure.yaml` in project root:
```yaml
name: myapp
metadata:
template: azd-init
# Specify Terraform as IaC provider
infra:
provider: terraform
path: ./infra
# Define services as usual
services:
api:
project: ./src/api
language: python
host: containerapp
docker:
path: ./src/api/Dockerfile
web:
project: ./src/web
language: js
host: staticwebapp
dist: dist
```
### 2. Terraform File Structure
Place Terraform files in `./infra/`:
```
infra/
├── main.tf # Main resources
├── variables.tf # Variable definitions
├── outputs.tf # Output values
├── provider.tf # Provider configuration
└── modules/
├── api/
│ └── main.tf
└── web/
└── main.tf
```
### 3. Provider Configuration
**provider.tf:**
```hcl
terraform {
required_version = ">= 1.5.0"
required_providers {
azurerm = {
source = "hashicorp/azurerm"
version = "~> 4.2"
}
azurecaf = {
source = "aztfmod/azurecaf"
version = "~> 1.2"
}
}
# Optional: Remote state for team collaboration
backend "azurerm" {
resource_group_name = "rg-terraform-state"
storage_account_name = "tfstate${var.state_suffix}"
container_name = "tfstate"
key = "app.terraform.tfstate"
}
}
provider "azurerm" {
features {}
}
```
> **⚠️ IMPORTANT**: For **Azure Functions Flex Consumption**, use azurerm provider **v4.2 or later**:
> ```hcl
> terraform {
> required_providers {
> azurerm = {
> source = "hashicorp/azurerm"
> version = "~> 4.2"
> }
> }
> }
> ```
> See [Terraform Functions patterns](../../services/functions/terraform.md) for Flex Consumption examples.
### 4. Variables and Outputs
> ⚠️ **WARNING: Use `${VAR}` syntax in `main.tfvars.json`, NOT Go-style `{{ .Env.* }}`**
>
> azd's template engine processes `azure.yaml` and service manifests — it does **NOT** interpolate
> Go-style `{{ .Env.* }}` template variables in `.tfvars.json` or any Terraform variable files.
> Literal strings like `{{ .Env.AZURE_ENV_NAME }}` will be passed directly to Terraform, causing
> deployment failures.
>
> azd reads `infra/main.tfvars.json`, substitutes `${VAR}` references using its built-in envsubst,
> and passes the resolved file to Terraform via `-var-file=`. Use this pattern:
>
> ```json
> {
> "environment_name": "${AZURE_ENV_NAME}",
> "location": "${AZURE_LOCATION}",
> "subscription_id": "${AZURE_SUBSCRIPTION_ID}"
> }
> ```
>
> For additional variables not in `main.tfvars.json`, use **`TF_VAR_*` environment variables**:
> `azd env set TF_VAR_myvar value`
**variables.tf:**
```hcl
variable "environment_name" {
type = string
description = "Environment name from azd"
}
variable "location" {
type = string
description = "Azure region"
default = "eastus2"
}
variable "principal_id" {
type = string
description = "User principal ID from azd auth"
default = ""
}
```
**outputs.tf:**
```hcl
# Required: Resource group name
output "AZURE_RESOURCE_GROUP" {
value = azurerm_resource_group.main.name
}
# Service-specific outputs
output "API_URL" {
value = azurerm_container_app.api.latest_revision_fqdn
}
output "WEB_URL" {
value = azurerm_static_web_app.web.default_host_name
}
```
> 💡 **Tip:** Output names in UPPERCASE are automatically set as azd environment variables.
### 5. Required Tags for azd
**CRITICAL:** Tag hosting resources with service names from azure.yaml:
```hcl
resource "azurerm_container_app" "api" {
name = "ca-${var.environment_name}-api"
resource_group_name = azurerm_resource_group.main.name
# Required for azd deploy to find this resource
tags = merge(var.tags, {
"azd-service-name" = "api" # Matches service name in azure.yaml
})
# ... rest of configuration
}
resource "azurerm_static_web_app" "web" {
name = "swa-${var.environment_name}-web"
resource_group_name = azurerm_resource_group.main.name
# Required for azd deploy to find this resource
tags = merge(var.tags, {
"azd-service-name" = "web" # Matches service name in azure.yaml
})
# ... rest of configuration
}
```
> ⚠️ **WARNING:** Without `azd-service-name` tags, `azd deploy` will fail to find deployment targets.
### 6. Resource Group Tags
Tag the resource group with environment name:
```hcl
resource "azurerm_resource_group" "main" {
name = "rg-${var.environment_name}"
location = var.location
tags = {
"azd-env-name" = var.environment_name
}
}
```
## Deployment Workflow
### Initial Setup
```bash
# 1. Create azd environment
azd env new dev --no-prompt
# 2. Set required variables
azd env set AZURE_LOCATION eastus2
# 3. Provision infrastructure (runs terraform init, plan, apply)
azd provision
# 4. Deploy services
azd deploy
# Or do both with single command
azd up
```
### Variables and State
**azd environment variables** → **Terraform variables**
azd passes variables to Terraform through `main.tfvars.json` (with `${VAR}` substitution) or
explicit `TF_VAR_*` environment variables. Define the variable in `variables.tf` and reference
it in `main.tfvars.json`.
infra/main.tfvars.json — azd substitutes ${VAR} references via envsubst:
```json
{
"environment_name": "${AZURE_ENV_NAME}",
"location": "${AZURE_LOCATION}",
"database_name": "${DATABASE_NAME}"
}
```
variables.tf — value provided via main.tfvars.json or TF_VAR_database_name:
```hcl
variable "database_name" {
type = string
}
```
For variables not in `main.tfvars.json`, use `TF_VAR_*` environment variables:
```bash
azd env set TF_VAR_custom_setting "my-value"
```
> ⚠️ **Use `${VAR}` syntax in `main.tfvars.json`, NOT Go-style `{{ .Env.* }}`.** azd substitutes
> `${VAR}` references using its built-in envsubst. Go-style template variables are only processed
> in `azure.yaml` and service manifests. See [Variables and Outputs](#4-variables-and-outputs) for details.
**Remote state setup:**
```bash
# Create state storage (one-time setup)
az group create --name rg-terraform-state --location eastus2
az storage account create \
--name tfstate<unique> \
--resource-group rg-terraform-state \
--sku Standard_LRS
az storage container create \
--name tfstate \
--account-name tfstate<unique>
# Set backend variables for azd
azd env set TF_STATE_RESOURCE_GROUP rg-terraform-state
azd env set TF_STATE_STORAGE_ACCOUNT tfstate<unique>
```
## Generation Steps
When preparing a new azd+Terraform project:
1. **Generate azure.yaml** with `infra.provider: terraform`
2. **Create Terraform files** in `./infra/`:
- `main.tf` - Core resources and resource group
- `variables.tf` - environment_name, location, tags
- `outputs.tf` - Service URLs and resource names (UPPERCASE)
- `provider.tf` - azurerm provider + backend config
3. **Add required tags**:
- Resource group: `azd-env-name`
- Hosting resources: `azd-service-name` (matches azure.yaml services)
4. **Research best practices** - Call `mcp_azure_mcp_azureterraformbestpractices`
## AVM Terraform Module Priority
For Terraform module selection, enforce this order:
1. AVM Terraform Pattern Modules
2. AVM Terraform Resource Modules
3. AVM Terraform Utility Modules
Use `mcp_azure_mcp_documentation` (`azure-documentation`) for current guidance and AVM context first, then use Context7 only as supplemental examples if required. If Context7 is not available, instruct the user to install it:
```bash
npx @upstash/context7-mcp@latest
```
## Migration from Pure Terraform
Converting existing Terraform project to use azd:
1. Create `azure.yaml` with services and `infra.provider: terraform`
2. Move `.tf` files to `./infra/` directory
3. Add `azd-service-name` tags to hosting resources
4. Ensure outputs include service URLs in UPPERCASE
5. Test with `azd provision` and `azd deploy`
## CI/CD Integration
azd can auto-generate pipelines for Terraform:
```bash
# Generate GitHub Actions workflow
azd pipeline config
# Generate Azure DevOps pipeline
azd pipeline config --provider azdo
```
Generated pipelines will:
- Install Terraform
- Run `terraform init`, `plan`, `apply`
- Use azd authentication
- Deploy services with `azd deploy`
## Comparison: azd+Terraform vs Pure Terraform
| Aspect | Pure Terraform | azd + Terraform |
|--------|---------------|-----------------|
| **IaC** | Terraform | Terraform |
| **Provision** | `terraform apply` | `azd provision` (wraps terraform) |
| **Deploy apps** | Manual scripts | `azd deploy` (automatic) |
| **Environment mgmt** | Workspaces | `azd env` |
| **Auth** | Manual az login | `azd auth login` |
| **CI/CD** | Manual setup | `azd pipeline config` |
| **Multi-service** | Manual orchestration | Automatic from azure.yaml |
| **Learning curve** | Medium | Low |
## When NOT to Use azd+Terraform
Use pure Terraform (without azd) when:
- Multi-cloud deployment (not Azure-first)
- Complex Terraform modules/workspaces that conflict with azd conventions
- Existing complex Terraform CI/CD that's hard to migrate
- Team has strong Terraform expertise but no bandwidth for azd learning
## Azure Policy Compliance
Enterprise Azure subscriptions typically enforce security policies. Your Terraform must comply:
### Storage Account (Required for Functions)
```hcl
resource "azurerm_storage_account" "storage" {
name = "stmyapp${random_string.suffix.result}"
resource_group_name = azurerm_resource_group.rg.name
location = azurerm_resource_group.rg.location
account_tier = "Standard"
account_replication_type = "LRS"
# Azure policy requirements
allow_nested_items_to_be_public = false # Disable anonymous blob access
local_user_enabled = false # Disable local users
shared_access_key_enabled = false # RBAC-only, no access keys
}
```
### Function App with Managed Identity Storage
```hcl
provider "azurerm" {
features {}
storage_use_azuread = true # Required when shared_access_key_enabled = false
}
resource "azurerm_linux_function_app" "function" {
name = "func-myapp"
resource_group_name = azurerm_resource_group.rg.name
location = azurerm_resource_group.rg.location
service_plan_id = azurerm_service_plan.plan.id
storage_account_name = azurerm_storage_account.storage.name
storage_uses_managed_identity = true # Use MI instead of access key
identity {
type = "SystemAssigned"
}
tags = {
"azd-service-name" = "api" # REQUIRED for azd deploy
}
depends_on = [azurerm_role_assignment.deployer_storage]
}
# RBAC for deploying user (create function with MI storage)
resource "azurerm_role_assignment" "deployer_storage" {
scope = azurerm_storage_account.storage.id
role_definition_name = "Storage Blob Data Owner"
principal_id = data.azurerm_client_config.current.object_id
}
# RBAC for function app after creation
resource "azurerm_role_assignment" "function_storage" {
scope = azurerm_storage_account.storage.id
role_definition_name = "Storage Blob Data Owner"
principal_id = azurerm_linux_function_app.function.identity[0].principal_id
}
```
### Services with Disabled Local Auth
```hcl
# Service Bus
resource "azurerm_servicebus_namespace" "sb" {
local_auth_enabled = false # RBAC-only
}
# Event Hubs
resource "azurerm_eventhub_namespace" "eh" {
local_authentication_enabled = false # RBAC-only
}
# Cosmos DB
resource "azurerm_cosmosdb_account" "cosmos" {
local_authentication_disabled = true # RBAC-only
}
```
## Troubleshooting
| Issue | Solution |
|-------|----------|
| `resource not found: unable to find a resource tagged with 'azd-service-name'` | Add `azd-service-name` tag to hosting resource in Terraform |
| `RequestDisallowedByPolicy: shared key access` | Set `shared_access_key_enabled = false` on storage |
| `RequestDisallowedByPolicy: local auth disabled` | Set `local_auth_enabled = false` on Service Bus |
| `RequestDisallowedByPolicy: anonymous blob access` | Set `allow_nested_items_to_be_public = false` on storage |
| `terraform command not found` | Install Terraform CLI: `brew install terraform` or download from terraform.io |
| State conflicts | Configure remote backend in provider.tf |
| Variable not passed to Terraform | Ensure variable is set with `azd env set` and defined in variables.tf |
| Literal `{{ .Env.* }}` in Terraform errors | Use `${VAR}` syntax in `main.tfvars.json`, not Go-style `{{ .Env.* }}`. azd substitutes `${VAR}` references via envsubst |
| `main.tfvars.json` interpolation failure | Ensure `main.tfvars.json` uses `${VAR}` syntax (e.g., `${AZURE_ENV_NAME}`), not Go-style `{{ .Env.* }}` templates |
## References
- [Microsoft Docs: Use Terraform with azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/use-terraform-for-azd)
- [azd-starter-terraform template](https://github.com/Azure-Samples/azd-starter-terraform)
- [Terraform Azure Provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
- [Azure CAF Naming](https://registry.terraform.io/providers/aztfmod/azurecaf/latest/docs)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |