# Azure CLI Commands

Common az commands for deployment workflows.

## Resource Group

```bash
# Create
az group create --name <rg-name> --location <location>

# Delete
az group delete --name <rg-name> --yes --no-wait
```

## Container Registry

```bash
# Create
az acr create --name <acr-name> --resource-group <rg-name> --sku Basic

# Login
az acr login --name <acr-name>

# Build and push
az acr build --registry <acr-name> --image <image:tag> .
```

## Container Apps

```bash
# Create environment
az containerapp env create \
  --name <env-name> \
  --resource-group <rg-name> \
  --location <location>

# Deploy app
az containerapp create \
  --name <app-name> \
  --resource-group <rg-name> \
  --environment <env-name> \
  --image <acr-name>.azurecr.io/<image:tag> \
  --target-port 8080 \
  --ingress external
```

## App Service

```bash
# Create plan
az appservice plan create \
  --name <plan-name> \
  --resource-group <rg-name> \
  --sku B1 --is-linux

# Create web app
az webapp create \
  --name <app-name> \
  --resource-group <rg-name> \
  --plan <plan-name> \
  --runtime "NODE:22-lts"
```

## Functions

```bash
# Create function app
az functionapp create \
  --name <func-name> \
  --resource-group <rg-name> \
  --storage-account <storage-name> \
  --consumption-plan-location <location> \
  --runtime node \
  --functions-version 4
```

## Key Vault

```bash
# Create
az keyvault create \
  --name <kv-name> \
  --resource-group <rg-name> \
  --location <location>

# Set secret
az keyvault secret set \
  --vault-name <kv-name> \
  --name <secret-name> \
  --value <secret-value>
```

# AZCLI Recipe

Azure CLI workflow for imperative Azure deployments.

## When to Use

- Existing az scripts in project
- Need imperative control over deployment
- Custom deployment pipelines
- AKS deployments
- Direct resource manipulation

## Before Generation

**REQUIRED: Research best practices before generating any files.**

| Artifact | Research Action |
|----------|-----------------|
| Bicep files | Call `mcp_bicep_get_bicep_best_practices` |
| Bicep modules | Call `mcp_bicep_list_avm_metadata` and follow [AVM module order](../azd/iac-rules.md#avm-module-selection-order-mandatory) |
| Azure CLI commands | Call `activate_azure_cli_management_tools` |
| Azure best practices | Call `mcp_azure_mcp_get_azure_bestpractices` |

## Generation Steps

### 1. Generate Infrastructure (Bicep)

Create Bicep templates in `./infra/`.

**Structure:**
```
infra/
├── main.bicep
├── main.parameters.json
└── modules/
    └── *.bicep
```

### 2. Generate Deployment Scripts

Create deployment scripts for provisioning.

→ [scripts.md](scripts.md)

### 3. Generate Dockerfiles (if containerized)

Manual Dockerfile creation required.

## Output Checklist

| Artifact | Path |
|----------|------|
| Main Bicep | `./infra/main.bicep` |
| Parameters | `./infra/main.parameters.json` |
| Modules | `./infra/modules/*.bicep` |
| Deploy script | `./scripts/deploy.sh` or `deploy.ps1` |
| Dockerfiles | `src/<service>/Dockerfile` |

## Deployment Commands

See [commands.md](commands.md) for common patterns.

## Naming Convention

Resources: `{prefix}{token}{instance}`
- Alphanumeric only, no special characters
- Prefix ≤3 chars (e.g., `kv` for Key Vault)
- Token = 5 char random string
- Total ≤32 characters

## References

- [Deployment Commands](commands.md)
- [Deployment Scripts](scripts.md)

## Next

→ Update `.azure/deployment-plan.md` → **azure-validate**

# Deployment Scripts

Script templates for AZCLI deployments.

## Bash Script

```bash
#!/bin/bash
set -euo pipefail

# Configuration
RESOURCE_GROUP="${RESOURCE_GROUP:-rg-myapp}"
LOCATION="${LOCATION:-eastus2}"
ENVIRONMENT="${ENVIRONMENT:-dev}"

echo "Deploying to $ENVIRONMENT environment..."

# Create resource group
az group create \
  --name "$RESOURCE_GROUP" \
  --location "$LOCATION" \
  --tags environment="$ENVIRONMENT"

# Deploy infrastructure
az deployment group create \
  --resource-group "$RESOURCE_GROUP" \
  --template-file ./infra/main.bicep \
  --parameters ./infra/main.parameters.json \
  --parameters environmentName="$ENVIRONMENT"

# Get outputs
ACR_NAME=$(az deployment group show \
  --resource-group "$RESOURCE_GROUP" \
  --name main \
  --query properties.outputs.acrName.value -o tsv)

# Build and push containers
az acr login --name "$ACR_NAME"
az acr build --registry "$ACR_NAME" --image api:latest ./src/api

echo "Deployment complete!"
```

## PowerShell Script

```powershell
#Requires -Version 7.0
$ErrorActionPreference = "Stop"

# Configuration
$ResourceGroup = $env:RESOURCE_GROUP ?? "rg-myapp"
$Location = $env:LOCATION ?? "eastus2"
$Environment = $env:ENVIRONMENT ?? "dev"

Write-Host "Deploying to $Environment environment..."

# Create resource group
az group create `
  --name $ResourceGroup `
  --location $Location `
  --tags environment=$Environment

# Deploy infrastructure
az deployment group create `
  --resource-group $ResourceGroup `
  --template-file ./infra/main.bicep `
  --parameters ./infra/main.parameters.json `
  --parameters environmentName=$Environment

# Get outputs
$AcrName = az deployment group show `
  --resource-group $ResourceGroup `
  --name main `
  --query properties.outputs.acrName.value -o tsv

# Build and push containers
az acr login --name $AcrName
az acr build --registry $AcrName --image api:latest ./src/api

Write-Host "Deployment complete!"
```

## Script Best Practices

| Practice | Description |
|----------|-------------|
| Fail fast | `set -euo pipefail` (bash) or `$ErrorActionPreference = "Stop"` (pwsh) |
| Use variables | Environment-based configuration |
| Idempotent | Safe to run multiple times |
| Output logging | Clear progress messages |
| Error handling | Capture and report failures |

# .NET Aspire Projects with AZD

**⛔ MANDATORY: For .NET Aspire projects, NEVER manually create azure.yaml. Use `azd init --from-code` instead.**

## Detection

| Indicator | How to Detect |
|-----------|---------------|
| `*.AppHost.csproj` | `find . -name "*.AppHost.csproj"` |
| `Aspire.Hosting` package | `grep -r "Aspire\.Hosting" . --include="*.csproj"` |
| `Aspire.AppHost.Sdk` | `grep -r "Aspire\.AppHost\.Sdk" . --include="*.csproj"` |

## Workflow

### ⛔ DO NOT (Wrong Approach)

```yaml
# ❌ WRONG - Missing services section
name: aspire-app
metadata:
  template: azd-init
# Results in: "Could not find infra\main.bicep" error
```

### ✅ DO (Correct Approach)

```bash
# Generate environment name
ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"

# Use azd init with auto-detection
azd init --from-code -e "$ENV_NAME"
```

**Generated azure.yaml:**
```yaml
name: aspire-app
metadata:
  template: azd-init
services:
  app:
    language: dotnet
    project: ./MyApp.AppHost/MyApp.AppHost.csproj
    host: containerapp
```

> 💡 **AddDockerfile services:** If the AppHost uses `AddDockerfile()` (e.g., `builder.AddDockerfile("ginapp", "./ginapp")`), do NOT add separate service entries for those resources. Aspire handles container builds for `AddDockerfile` resources at runtime through the AppHost. The `azure.yaml` should contain only the single `app` service pointing to the AppHost.

> ⛔ **BEFORE continuing:** Complete the mandatory [AddParameter + WithBuildArg scan](#after-azd-init-fix-addparameter-used-with-withbuildarg-before-builddeploy) below. Skipping this step is the #1 cause of failed Aspire container-build deployments.

## Command Flags

| Flag | Required | Purpose |
|------|----------|---------|
| `--from-code` | ✅ | Auto-detect AppHost, no prompts |
| `-e <name>` | ✅ | Environment name (non-interactive) |
| `--no-prompt` | Optional | Skip all confirmations |

**Why `--from-code` is critical:**
- Without: Prompts "How do you want to initialize?" (needs TTY)
- With: Auto-detects AppHost, no interaction needed
- Essential for agents and CI/CD

## ⛔ After `azd init`: Fix AddParameter Used with WithBuildArg Before Build/Deploy

> **MANDATORY** — After running `azd init --from-code`, but before `azd package`, `azd up`, or any Docker image build/deploy step, scan the AppHost source for `AddParameter` calls that are passed to `WithBuildArg` or `WithBuildSecret`. This pattern triggers an azd bug that causes Docker builds to fail.

.NET Aspire [external parameters](https://aspire.dev/fundamentals/external-parameters/) let apps request values from the deployment environment. Each `AddParameter()` call generates a Bicep parameter in the deployment manifest. However, azd cannot resolve these Bicep parameters during the Docker image build phase, producing the error `parameter infra.parameters.<name> not found`. This bug has been present across all azd versions tested (including 1.24.0).

### Scan for the pattern

**Bash:**
```bash
grep -RIn --include="*.cs" -E "AddParameter|WithBuildArg|WithBuildSecret" <path/to/AppHost>
```

**PowerShell:**
```powershell
Get-ChildItem -Path "<path/to/AppHost>" -Recurse -Filter "*.cs" |
  Select-String -Pattern "AddParameter|WithBuildArg|WithBuildSecret"
```

**Problematic pattern:**
```csharp
// ❌ azd cannot resolve AddParameter values during Docker builds
var goVersion = builder.AddParameter("goversion", "1.25.4", publishValueAsDefault: true);
builder.AddDockerfile("ginapp", "./ginapp")
    .WithBuildArg("GO_VERSION", goVersion);
```

### Fix Option A: Replace AddParameter with a constant (preferred)

For every `AddParameter(name, defaultValue, ...)` whose result is used **only** as a `WithBuildArg` argument, replace it with a `const string` (or `string`) constant:

```csharp
// ✅ Use a constant instead
const string goVersion = "1.25.4";
builder.AddDockerfile("ginapp", "./ginapp")
    .WithBuildArg("GO_VERSION", goVersion);
```

**Why:** This eliminates the parameter from Bicep output entirely, so azd never attempts to resolve it during Docker builds. Use this when the build arg value does not need to vary per deployment environment.

### Fix Option B: Pre-set parameter in azd environment config

If the value must remain an [external parameter](https://aspire.dev/fundamentals/external-parameters/) (e.g., it varies per environment), pre-set it in the azd environment config immediately after `azd init`:

```bash
azd env config set infra.parameters.<name> <value>
```

**Example:**
```bash
azd env config set infra.parameters.goversion 1.25.4
```

**Why:** This writes the parameter value into `.azure/<env>/config.json` so azd can find it during Docker builds without modifying AppHost source code. Use this when the build arg value must be configurable per environment.

> ⚠️ **Do NOT skip this step for container-build projects.** If the AppHost passes an `AddParameter` result to `WithBuildArg`, apply one of these fixes before running `azd up`.

---

## Troubleshooting

### Error: "Could not find infra\main.bicep"

**Cause:** Manual azure.yaml without services section

**Fix:**
1. Delete manual azure.yaml
2. Run `azd init --from-code -e <env-name>`
3. Verify services section exists

### Error: "no default response for prompt"

**Cause:** Missing `--from-code` flag

**Fix:** Always use `--from-code` for Aspire:
```bash
azd init --from-code -e "$ENV_NAME"
```

### Error: "parameter infra.parameters.<name> not found"

**Cause:** The AppHost uses `AddParameter()` as a `WithBuildArg` argument. azd cannot resolve Aspire [external parameters](https://aspire.dev/fundamentals/external-parameters/) during Docker builds, regardless of azd version.

**Example error:**
```
ERROR: building service 'ginapp': parameter infra.parameters.goversion not found
```

**Fix (Option A — preferred):** In the AppHost source, replace the `AddParameter(...)` call with a constant:

```csharp
// ❌ Before (causes the error)
var goVersion = builder.AddParameter("goversion", "1.25.4", publishValueAsDefault: true);
builder.AddDockerfile("ginapp", "./ginapp")
    .WithBuildArg("GO_VERSION", goVersion);

// ✅ After (fix)
const string goVersion = "1.25.4";
builder.AddDockerfile("ginapp", "./ginapp")
    .WithBuildArg("GO_VERSION", goVersion);
```

**Fix (Option B):** Pre-set the parameter in azd environment config:
```bash
azd env config set infra.parameters.goversion 1.25.4
```

### AppHost Not Detected

**Solutions:**
1. Verify: `find . -name "*.AppHost.csproj"`
2. Build: `dotnet build`
3. Check package references in .csproj
4. Run from solution root

### Error: "unsupported resource type" — Custom Aspire Resources

**Symptoms:** `azd init --from-code` fails with `unsupported resource type` for one or more resources in the AppHost (e.g., custom child resources, ClockHand, or other custom Aspire integration types).

**Cause:** The AppHost contains custom Aspire resource types designed for local development tooling only. These resources have no Azure equivalent and are not deployable.

**Resolution:**

1. ⛔ **Stop — do NOT fix this error by modifying source code.** Do not add `.ExcludeFromManifest()` to suppress the error.
2. ⛔ **Do NOT proceed with deployment.**
3. ✅ Inform the user: the application uses custom Aspire resource authoring patterns intended for local tooling, not cloud deployment.
4. ✅ Record a deployment blocker: "AppHost contains custom Aspire resource types (`unsupported resource type`) with no Azure deployment target."

> ⚠️ Adding `.ExcludeFromManifest()` to work around this error violates the application's design intent and may produce an incomplete or incorrect deployment.

## Infrastructure Auto-Generation

| Traditional | Aspire |
|------------|--------|
| Manual infra/main.bicep | Auto-gen from AppHost |
| Define in IaC | Define in C# code |
| Update IaC per service | Add to AppHost |

**How it works:**
1. AppHost defines services in C#
2. `azd provision` analyzes AppHost
3. Generates Bicep automatically
4. Deploys to Azure Container Apps

## Validation Steps

1. **⛔ Fix `AddParameter` used with `WithBuildArg`** — see [Post-Init: Fix AddParameter Used with WithBuildArg](#after-azd-init-fix-addparameter-used-with-withbuildarg-before-builddeploy)
2. Verify azure.yaml has a non-empty services section
3. Do NOT add separate service entries for `AddDockerfile()` resources — Aspire handles container builds at runtime through the AppHost
4. Run `azd package` to validate Docker build succeeds
5. Review generated infra/ (don't modify)

## Next Steps

1. Set subscription: `azd env set AZURE_SUBSCRIPTION_ID <id>`
2. Proceed to **azure-validate**
3. Deploy with **azure-deploy** (`azd up`)

## References

- [.NET Aspire External Parameters](https://aspire.dev/fundamentals/external-parameters/)
- [.NET Aspire Docs](https://learn.microsoft.com/dotnet/aspire/)
- [azd + Aspire](https://learn.microsoft.com/dotnet/aspire/deployment/azure/aca-deployment-azd-in-depth)
- [Samples](https://github.com/dotnet/aspire-samples)
- [Main Guide](../../aspire.md)
- [azure.yaml Schema](azure-yaml.md)
- [Docker Guide](docker.md)

# azure.yaml Generation

> ⛔ **CRITICAL: Check for .NET Aspire projects FIRST**
>
> **DO NOT manually create azure.yaml for .NET Aspire projects.** If you detect:
> - Files ending with `*.AppHost.csproj` (e.g., `MyApp.AppHost.csproj`)
> - `Aspire.Hosting` or `Aspire.AppHost.Sdk` in `.csproj` files
>
> **STOP and use `azd init --from-code` instead.** See [aspire.md](aspire.md) for details.

Create `azure.yaml` in project root for AZD.

## Structure

### Basic (Bicep - default)

```yaml
name: <project-name>
metadata:
  template: azd-init

services:
  <service-name>:
    project: <path-to-source>
    language: <python|js|ts|java|dotnet|go>
    host: <containerapp|appservice|function|staticwebapp|aks>
```

### With Terraform Provider

```yaml
name: <project-name>
metadata:
  template: azd-init

# Specify Terraform as IaC provider
infra:
  provider: terraform
  path: ./infra

services:
  <service-name>:
    project: <path-to-source>
    language: <python|js|ts|java|dotnet|go>
    host: <containerapp|appservice|function|staticwebapp|aks>
```

> 💡 **Tip:** Omit `infra` section to use Bicep (default). Add `infra.provider: terraform` to use Terraform. See [terraform.md](terraform.md) for details.

## Host Types

| Host | Azure Service | Use For |
|------|---------------|---------|
| `containerapp` | Container Apps | APIs, microservices, workers |
| `appservice` | App Service | Traditional web apps |
| `function` | Azure Functions | Serverless functions |
| `staticwebapp` | Static Web Apps | SPAs, static sites |
| `aks` | AKS | Kubernetes workloads |

## Examples

### Container App with Bicep (default)

```yaml
name: myapp

services:
  api:
    project: ./src/api
    language: python
    host: containerapp
    docker:
      path: ./src/api/Dockerfile
```

### Container App with Terraform

```yaml
name: myapp

infra:
  provider: terraform
  path: ./infra

services:
  api:
    project: ./src/api
    language: python
    host: containerapp
    docker:
      path: ./src/api/Dockerfile
```

### Container App with Custom Docker Context

When a **non-Aspire** project has a Dockerfile that expects files relative to a specific directory:

```yaml
name: myapp

services:
  ginapp:
    project: .
    host: containerapp
    image: ginapp
    docker:
      path: ginapp/Dockerfile
      context: ginapp
```

> 💡 **Tip:** The `context` field specifies the Docker build context directory. This is crucial for:
> - Dockerfiles with `COPY` commands expecting files relative to a subdirectory
> - Multi-service repos where each service has its own context

> ⚠️ **Aspire projects:** Do NOT manually add per-service entries with `docker.context` for Aspire `AddDockerfile()` resources. Aspire handles container builds at runtime through the AppHost. The generated `azure.yaml` should contain only a single `app` service pointing to the AppHost. See [aspire.md](aspire.md) for details.

> ⚠️ **Language Field:** When using the `docker` section, the `language` field should be **omitted** or set to the language that azd will use for framework-specific behaviors. For containerized apps with custom Dockerfiles, the language is not used by azd since the build is handled by Docker. Only include `language` if you need azd to perform additional framework-specific actions beyond Docker build.

### Azure Functions

```yaml
services:
  functions:
    project: ./src/functions
    language: js
    host: function
```

### Static Web App (with framework build)

For React, Vue, Angular, Next.js, etc. that require `npm run build`:

```yaml
services:
  web:
    project: ./src/web     # folder containing package.json
    language: js           # triggers: npm install && npm run build
    host: staticwebapp
    dist: dist             # build output folder (e.g., dist, build, out)
```

### Static Web App (pure HTML/CSS - no build)

For pure HTML sites without a framework build step:

**Static files in subfolder (recommended):**
```yaml
services:
  web:
    project: ./src/web     # folder containing index.html
    host: staticwebapp
    dist: .                # works when project != root
```

**Static files in root - requires build script:**

> ⚠️ **SWA CLI Limitation:** When `project: .`, you cannot use `dist: .`. Files must be copied to a separate output folder.

Add a minimal `package.json` with a build script:
```json
{
  "scripts": {
    "build": "node -e \"require('fs').mkdirSync('public',{recursive:true});require('fs').readdirSync('.').filter(f=>/\\.(html|css|js|png|jpe?g|gif|svg|ico|json|xml|txt|webmanifest|map)$/i.test(f)).forEach(f=>require('fs').copyFileSync(f,'public/'+f))\""
  }
}
```

Then configure azure.yaml with `language: js` to trigger the build:
```yaml
services:
  web:
    project: .
    language: js           # triggers npm install && npm run build
    host: staticwebapp
    dist: public
```

### SWA Project Structure Detection

| Layout | Configuration |
|--------|---------------|
| Static in root | `project: .`, `language: js`, `dist: public` + package.json build script |
| Framework in root | `project: .`, `language: js`, `dist: <output>` |
| Static in subfolder | `project: ./path`, `dist: .` |
| Framework in subfolder | `project: ./path`, `language: js`, `dist: <output>` |

> **Key rules:**
> - `dist` is **relative to `project`** path
> - **SWA CLI limitation**: When `project: .`, cannot use `dist: .` - must use a distinct folder
> - For static files in root, add `package.json` with build script to copy files to dist folder
> - Use `language: js` to trigger npm build even for pure static sites in root
> - `language: html` and `language: static` are **NOT valid** - will fail

### SWA Bicep Requirement

Bicep must include the `azd-service-name` tag:
```bicep
resource staticWebApp 'Microsoft.Web/staticSites@2022-09-01' = {
  name: name
  location: location
  tags: union(tags, { 'azd-service-name': 'web' })}
```
}
```

### App Service

```yaml
services:
  api:
    project: ./src/api
    language: dotnet
    host: appservice
```

## Hooks (Optional)

```yaml
hooks:
  preprovision:
    shell: sh
    run: ./scripts/setup.sh
  postprovision:
    shell: sh
    run: ./scripts/seed-data.sh
```

## Valid Values

| Field | Options |
|-------|---------|
| `language` | python, js, ts, java, dotnet, go (omit for staticwebapp without build) |
| `host` | containerapp, appservice, function, staticwebapp, aks |
| `docker.path` | Path to Dockerfile (relative to project root) |
| `docker.context` | Docker build context directory (optional, defaults to directory containing Dockerfile) |

> 💡 **Docker Context:** When `docker.context` is omitted, azd uses the directory containing the Dockerfile as the build context. Specify `context` explicitly when the Dockerfile expects files from a different directory.

## Output

- `./azure.yaml`

# Dockerfile Generation

Create Dockerfiles for containerized services.

## When to Containerize

| Include | Exclude |
|---------|---------|
| APIs, microservices | Static websites (use Static Web Apps) |
| Web apps (SSR) | Azure Functions (native deploy) |
| Background workers | Database services |
| Message processors | Logic Apps |

## Templates by Language

### Node.js

```dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]
```

### Python

```dockerfile
FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### .NET

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["*.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "App.dll"]
```

### Java

```dockerfile
FROM eclipse-temurin:21-jdk-alpine AS build
WORKDIR /app
COPY . .
RUN ./mvnw package -DskipTests

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

### Go

```dockerfile
FROM golang:1.22-alpine AS build
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o main .

FROM alpine:latest
WORKDIR /app
COPY --from=build /app/main .
EXPOSE 8080
CMD ["./main"]
```

## .dockerignore

```
.git
node_modules
__pycache__
*.pyc
.env
.azure
```

## Best Practices

- Use slim/alpine base images
- Multi-stage builds for compiled languages
- Non-root user when possible
- Include health check endpoint in app

## Runtime-Specific Configuration

For production settings specific to each runtime:

| Runtime | Reference |
|---------|-----------| 
| Node.js/Express | [runtimes/nodejs.md](../../runtimes/nodejs.md) |

# AZD IAC Rules

IaC rules for AZD projects. **Additive** — for Bicep, apply `mcp_bicep_get_bicep_best_practices`, `mcp_bicep_list_avm_metadata`, and `mcp_bicep_get_az_resource_type_schema` first; for Terraform, apply `mcp_azure_mcp_azureterraformbestpractices` first; then apply these azd-specific rules.

## AVM Module Selection Order (MANDATORY)

Always prefer modules in provider-specific order:

For **Bicep**:
1. AVM Bicep Pattern Modules (AVM+AZD first when available)
2. AVM Bicep Resource Modules
3. AVM Bicep Utility Modules

For **Terraform**:
1. AVM Terraform Pattern Modules
2. AVM Terraform Resource Modules
3. AVM Terraform Utility Modules

If no pattern module exists for the active provider, default immediately to AVM modules in the same provider order (resource, then utility) instead of using non-AVM modules.

## Retrieval Strategy (azure-documentation MCP primary + optional Context7)

- **Primary (authoritative):** Use `mcp_azure_mcp_documentation` (`azure-documentation`) for current Azure guidance and AVM integration documentation.
- **Primary (module catalog):** Use `mcp_bicep_list_avm_metadata` plus official AVM indexes to select concrete modules.
- **Secondary (supplemental):** Use Context7 only for implementation examples when `mcp_azure_mcp_documentation` does not provide enough detail. If Context7 is not available, instruct the user to install it: `npx -y @upstash/context7-mcp@latest`.

## Validation Plan

Before finalizing generated guidance:

1. Verify the selected module path uses the required AVM order above.
2. Verify AVM+AZD pattern modules were checked first, and fallback moved to AVM resource/utility modules when no pattern module exists.
3. Verify Terraform guidance follows pattern -> resource -> utility ordering.
4. Include selected module names and source links in the plan/output for traceability.

## File Structure

| Requirement | Details |
|-------------|---------|
| Location | `./infra/` folder |
| Entry point | `main.bicep` with `targetScope = 'subscription'` |
| Parameters | `main.parameters.json` (ARM JSON — see format below) |
| Modules | `./infra/modules/*.bicep` with `targetScope = 'resourceGroup'` |

## Parameter File Format

`main.parameters.json` uses ARM JSON syntax. Do **not** use `.bicepparam` syntax (`using`, `param`, `readEnvironmentVariable()`) in this file — `azd` will fail with a JSON parse error.

```json
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}
```

Use `azd env set` to supply values. During `azd provision`, azd substitutes `${VAR}` placeholders with values from the environment.

## Naming Convention

> ⚠️ **Before generating any resource name in Bicep, check [Resource naming rules](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-name-rules) for that resource type's valid characters, length limits, and uniqueness scope.** Some resources forbid dashes or special characters, require globally unique names, or have short length limits. Adapt the pattern below accordingly.

**Default pattern:** `{resourceAbbreviation}-{name}-{uniqueHash}`

For resources that disallow dashes, omit separators: `{resourceAbbreviation}{name}{uniqueHash}`

- [Resource abbreviations](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations) — recommended prefixes per resource type

```bicep
var resourceSuffix = take(uniqueString(subscription().id, environmentName, location), 6)
// Adapt separator/format per resource naming rules
var defaultName = '${name}-${resourceSuffix}'
var alphanumericName = replace('${name}${resourceSuffix}', '-', '')
```

**Forbidden:** Hard-coded tenant IDs, subscription IDs, resource group names

## Required Tags

| Tag | Apply To | Value |
|-----|----------|-------|
| `azd-env-name` | Resource group | `{environmentName}` |
| `azd-service-name` | Hosting resources | Service name from azure.yaml |

## Module Parameters

All modules must accept: `name` (string), `location` (string), `tags` (object)

## Security

| Rule | Details |
|------|---------|
| No secrets | Use Key Vault references |
| Managed Identity | Least privilege |
| Diagnostics | Enable logging |
| API versions | Use latest |

## Recommended Outputs

`azd` reads `output` values from `main.bicep` and stores UPPERCASE names as environment variables (accessible via `azd env get-values`).

| Output | When |
|--------|------|
| `AZURE_RESOURCE_GROUP` | Always (required) |
| `AZURE_CONTAINER_REGISTRY_ENDPOINT` | If using containers |
| `AZURE_KEY_VAULT_NAME` | If using secrets |
| `AZURE_LOG_ANALYTICS_WORKSPACE_ID` | If using monitoring |
| `API_URL`, `WEB_URL`, etc. | One per service endpoint |

## Templates

**main.bicep:**

```bicep
targetScope = 'subscription'

param environmentName string
param location string

var resourceSuffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }

resource rg 'Microsoft.Resources/resourceGroups@2023-07-01' = {
  name: 'rg-${environmentName}'
  location: location
  tags: tags
}

module resources './modules/resources.bicep' = {
  name: 'resources'
  scope: rg
  params: { location: location, tags: tags }
}

// Outputs — UPPERCASE names become azd env vars
output AZURE_RESOURCE_GROUP string = rg.name
output API_URL string = resources.outputs.apiUrl
```

**Child module:**

```bicep
targetScope = 'resourceGroup'

param name string
param location string = resourceGroup().location
param tags object = {}

var resourceSuffix = take(uniqueString(subscription().id, resourceGroup().name, name), 6)
```

> ⚠️ **Container resources:** CPU must use `json()` wrapper: `cpu: json('0.5')`, memory as string: `memory: '1Gi'`

# AZD Recipe

Azure Developer CLI workflow for preparing Azure deployments.

## When to Use

- New projects, multi-service apps, want `azd up`
- Need environment management, auto-generated CI/CD
- Team prefers simplified deployment workflow

> 💡 **Tip:** azd supports both Bicep and Terraform as IaC providers. Choose based on your team's expertise and requirements.

## IaC Provider Options

| Provider | Use When |
|----------|----------|
| **Bicep** (default) | Azure-only, no existing IaC, want simplest setup |
| **Terraform** | Multi-cloud IaC, existing TF expertise, want azd simplicity |

**For Terraform with azd:** See [terraform.md](terraform.md)

## Before Generation

**REQUIRED: Research best practices before generating any files.**

### Check for Existing Codebase Patterns

**⚠️ CRITICAL: For existing codebases with special patterns, use `azd init --from-code -e <environment-name>` instead of manual generation.**

| Pattern | Detection | Action |
|---------|-----------|--------|
| **.NET Aspire** | `*.AppHost.csproj` or `Aspire.Hosting` package | Use `azd init --from-code -e <environment-name>` → [aspire.md](../../aspire.md) |
| **Existing azure.yaml** | `azure.yaml` present | MODIFY mode - update existing config |
| **New project** | No azure.yaml, no special patterns | Manual generation (steps below) |

> 💡 **Note:** The `-e <environment-name>` flag is **required** when running `azd init --from-code` in non-interactive environments (agents, CI/CD pipelines). Without it, the command will fail with a prompt error.

### References for Manual Generation

| Artifact | Reference |
|----------|-----------|
| azure.yaml | [Schema Guide](azure-yaml.md) |
| .NET Aspire projects | [Aspire Guide](../../aspire.md) |
| Terraform with azd | [Terraform Guide](terraform.md) |
| AZD IAC rules | [IAC Rules](iac-rules.md) |
| Azure Functions templates | [Templates](../../services/functions/templates/README.md) |
| Bicep best practices | `mcp_bicep_get_bicep_best_practices` |
| Bicep resource schema | `mcp_bicep_get_az_resource_type_schema` |
| Azure Verified Modules | `mcp_bicep_list_avm_metadata` + [AVM module order](iac-rules.md#avm-module-selection-order-mandatory) |
| Terraform best practices | `mcp_azure_mcp_azureterraformbestpractices` |
| Dockerfiles | [Docker Guide](docker.md) |

## Generation Steps

### For Bicep (default)

| # | Artifact | Reference |
|---|----------|-----------|
| 1 | azure.yaml | [Schema Guide](azure-yaml.md) |
| 2 | Application code | Entry points, health endpoints, config |
| 3 | Dockerfiles | [Docker Guide](docker.md) (if containerized) |
| 4 | Infrastructure | `./infra/main.bicep` + modules per [IAC Rules](iac-rules.md) |

### For Terraform

| # | Artifact | Reference |
|---|----------|-----------|
| 1 | azure.yaml with `infra.provider: terraform` | [Terraform Guide](terraform.md) |
| 2 | Application code | Entry points, health endpoints, config |
| 3 | Dockerfiles | [Docker Guide](docker.md) (if containerized) |
| 4 | Terraform files | `./infra/*.tf` per [Terraform Guide](terraform.md) |

## Outputs

### For Bicep

| Artifact | Path |
|----------|------|
| azure.yaml | `./azure.yaml` |
| App Code | `src/<service>/*` |
| Dockerfiles | `src/<service>/Dockerfile` (if containerized) |
| Infrastructure | `./infra/` (Bicep files) |

### For Terraform

| Artifact | Path |
|----------|------|
| azure.yaml | `./azure.yaml` (with `infra.provider: terraform`) |
| App Code | `src/<service>/*` |
| Dockerfiles | `src/<service>/Dockerfile` (if containerized) |
| Infrastructure | `./infra/` (Terraform files) |

## References

- [.NET Aspire Projects](../../aspire.md)
- [azure.yaml Schema](azure-yaml.md)
- [.NET Aspire Apps](aspire.md)
- [Terraform with AZD](terraform.md)
- [Docker Configuration](docker.md)
- [IAC Rules](iac-rules.md)

## Next

→ Update `.azure/deployment-plan.md` → **azure-validate**

# 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)

# Bicep Patterns

Common patterns for Bicep infrastructure templates.

## File Structure

```
infra/
├── main.bicep              # Entry point (subscription scope)
├── main.parameters.json    # Parameter values
└── modules/
    ├── resources.bicep     # Base resources
    ├── container-app.bicep # Container App module
    └── ...
```

## main.bicep Template

```bicep
targetScope = 'subscription'

@minLength(1)
@maxLength(64)
param environmentName string

@minLength(1)
param location string

var tags = { environment: environmentName }

resource rg 'Microsoft.Resources/resourceGroups@2023-07-01' = {
  name: 'rg-${environmentName}'
  location: location
  tags: tags
}

module resources './modules/resources.bicep' = {
  name: 'resources'
  scope: rg
  params: {
    location: location
    environmentName: environmentName
    tags: tags
  }
}

output resourceGroupName string = rg.name
```

## main.parameters.json

> ⚠️ **Warning:** This file uses ARM JSON syntax. Do **not** use `.bicepparam` syntax (`using`, `param`, `readEnvironmentVariable()`) in this file — `azd` will fail with a JSON parse error.

```json
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}
```

Use `azd env set` to supply values at deploy time:

```bash
azd env set AZURE_ENV_NAME myapp-1234
azd env set AZURE_LOCATION eastus2
```

## Naming Convention

```bicep
var resourceToken = uniqueString(subscription().id, resourceGroup().id, location)

// Pattern: {prefix}{name}{token}
// Total ≤32 chars, alphanumeric only
var kvName = 'kv${environmentName}${resourceToken}'
var storName = 'stor${resourceToken}'

// Container Registry: alphanumeric only (5-50 chars)
var acrName = replace('cr${environmentName}${resourceToken}', '-', '')
```

## Security Requirements

| Requirement | Pattern |
|-------------|---------|
| No hardcoded secrets | Use Key Vault references |
| Managed Identity | `identity: { type: 'UserAssigned' }` |
| HTTPS only | `httpsOnly: true` |
| TLS 1.2+ | `minTlsVersion: '1.2'` |
| No public blob access | `allowBlobPublicAccess: false` |

## Common Modules

### Log Analytics

```bicep
resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
  name: 'log-${resourceToken}'
  location: location
  properties: {
    sku: { name: 'PerGB2018' }
    retentionInDays: 30
  }
}
```

### Application Insights

```bicep
resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: 'appi-${resourceToken}'
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
    WorkspaceResourceId: logAnalytics.id
  }
}
```

### Key Vault

```bicep
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: 'kv-${resourceToken}'
  location: location
  properties: {
    sku: { family: 'A', name: 'standard' }
    tenantId: subscription().tenantId
    enableRbacAuthorization: true
  }
}
```

# Bicep Recipe

Standalone Bicep workflow (without AZD).

## When to Use

- IaC-first approach
- No CLI wrapper needed
- Direct ARM deployment control
- Existing Bicep modules to reuse
- Custom deployment orchestration

## Before Generation

**REQUIRED: Research best practices before generating any files.**

| Artifact | Research Action |
|----------|-----------------|
| Bicep files | Call `mcp_bicep_get_bicep_best_practices` |
| Bicep modules | Call `mcp_bicep_list_avm_metadata` and follow [AVM module order](../azd/iac-rules.md#avm-module-selection-order-mandatory) |
| Resource schemas | Use `activate_azure_resource_schema_tools` if needed |

## Generation Steps

### 1. Generate Infrastructure

Create Bicep templates in `./infra/`.

→ [patterns.md](patterns.md)

**Structure:**
```
infra/
├── main.bicep
├── main.parameters.json
└── modules/
    ├── container-app.bicep
    ├── storage.bicep
    └── ...
```

### 2. Generate Dockerfiles (if containerized)

Manual Dockerfile creation required.

## Output Checklist

| Artifact | Path |
|----------|------|
| Main Bicep | `./infra/main.bicep` |
| Parameters | `./infra/main.parameters.json` |
| Modules | `./infra/modules/*.bicep` |
| Dockerfiles | `src/<service>/Dockerfile` |

## References

- [Bicep Patterns](patterns.md)

## Next

→ Update `.azure/deployment-plan.md` → **azure-validate**

# Terraform Patterns

Common patterns for Terraform Azure deployments.

## File Structure

```
infra/
├── main.tf             # Main resources
├── variables.tf        # Variable definitions
├── outputs.tf          # Output values
├── terraform.tfvars    # Variable values
├── backend.tf          # State backend
└── modules/
    └── ...
```

## Provider Configuration

```hcl
# backend.tf
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
    azurecaf = {
      source  = "aztfmod/azurecaf"
      version = "~> 1.2"
    }
  }

  backend "azurerm" {
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "tfstate<unique>"
    container_name       = "tfstate"
    key                  = "app.terraform.tfstate"
  }
}

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

## Variables

```hcl
# variables.tf
variable "environment" {
  type        = string
  description = "Environment name"
}

variable "location" {
  type        = string
  description = "Azure region"
  default     = "eastus2"
}
```

## Main Configuration

```hcl
# main.tf
resource "azurerm_resource_group" "main" {
  name     = "rg-${var.environment}"
  location = var.location
  tags     = { environment = var.environment }
}

module "app" {
  source              = "./modules/app"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location
  environment         = var.environment
}
```

## Outputs

```hcl
# outputs.tf
output "resource_group_name" {
  value = azurerm_resource_group.main.name
}

output "app_url" {
  value = module.app.url
}
```

## Naming with Azure CAF

```hcl
resource "azurecaf_name" "storage" {
  name          = var.environment
  resource_type = "azurerm_storage_account"
  random_length = 5
}

resource "azurerm_storage_account" "main" {
  name = azurecaf_name.storage.result
  # ...
}
```

## State Backend Setup

```bash
# Create state storage
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>
```

## Security Requirements

| Requirement | Pattern |
|-------------|---------|
| No hardcoded secrets | Use Key Vault data sources |
| Managed Identity | `identity { type = "UserAssigned" }` |
| State encryption | Azure Storage encryption |
| State locking | Azure Blob lease |

## Container Apps with ACR

> **⚠️ Two-Phase Deployment Required.** See [Container Apps Terraform Patterns](../../services/container-apps/terraform.md) for full details.

Use a **public placeholder image** during initial provisioning. Never reference an ACR image that hasn't been built yet. Do **not** use `admin_enabled` on the ACR or add a `registry` block with `username`/`password_secret_name` — use managed identity instead.

```hcl
resource "azurerm_container_app" "api" {
  # ...
  template {
    container {
      name   = "api"
      image  = "mcr.microsoft.com/azuredocs/containerapps-helloworld:latest"
      # ...
    }
  }

  # Prevent Terraform from reverting post-apply image and registry updates
  lifecycle {
    ignore_changes = [
      template[0].container[0].image,
      registry,
    ]
  }
}
```

After `terraform apply`, build the real image and update the Container App via CLI — see the **azure-deploy** skill's `references/recipes/terraform/README.md` (Container Apps Two-Phase Deployment section).

# Terraform Recipe

Terraform workflow for Azure deployments.

> **⚠️ IMPORTANT: Consider azd+Terraform First**
>
> If you're deploying to Azure, you should **default to [azd with Terraform](../azd/terraform.md)** instead of pure Terraform. azd+Terraform gives you:
> - Terraform's IaC capabilities
> - Simple `azd up` deployment workflow
> - Built-in environment management
> - Automatic CI/CD pipeline generation
> - Service orchestration from azure.yaml
>
> → **See [azd+Terraform documentation](../azd/terraform.md)** ←

## When to Use Pure Terraform (Without azd)

Only use pure Terraform workflow when you have specific requirements that prevent using azd:

- **Multi-cloud deployments** where Azure is not the primary target
- **Complex Terraform modules/workspaces** that are incompatible with azd conventions
- **Existing Terraform CI/CD** pipelines that are hard to migrate
- **Organization mandate** for pure Terraform workflow without any wrapper tools
- **Explicitly requested** by the user to use Terraform without azd

## When to Use azd+Terraform Instead

Use azd+Terraform (the default) when:

- **Azure-first deployment** (even if you want multi-cloud IaC)
- Want **`azd up` simplicity** with Terraform IaC
- **Multi-service apps** needing orchestration
- Team wants to learn Terraform with a simpler workflow

→ See [azd+Terraform documentation](../azd/terraform.md)

## Before Generation

**REQUIRED: Research best practices before generating any files.**

| Artifact | Research Action |
|----------|-----------------|
| Terraform patterns | Call `mcp_azure_mcp_azureterraformbestpractices` |
| Azure best practices | Call `mcp_azure_mcp_get_azure_bestpractices` |

## Generation Steps

### 1. Generate Infrastructure

Create Terraform files in `./infra/`.

→ [patterns.md](patterns.md)

**Structure:**
```
infra/
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars
├── backend.tf
└── modules/
    └── ...
```

### 2. Set Up State Backend

Azure Storage for remote state.

### 3. Generate Dockerfiles (if containerized)

Manual Dockerfile creation required.

## Output Checklist

| Artifact | Path |
|----------|------|
| Main config | `./infra/main.tf` |
| Variables | `./infra/variables.tf` |
| Outputs | `./infra/outputs.tf` |
| Values | `./infra/terraform.tfvars` |
| Backend | `./infra/backend.tf` |
| Modules | `./infra/modules/` |
| Dockerfiles | `src/<service>/Dockerfile` |

## References

- [Terraform Patterns](patterns.md)

## Next

→ Update `.azure/deployment-plan.md` → **azure-validate**

# AKS - Add-ons

## Container Monitoring

```bicep
addonProfiles: {
  omsagent: {
    enabled: true
    config: {
      logAnalyticsWorkspaceResourceID: logAnalytics.id
    }
  }
}
```

## Azure CNI Networking

```bicep
networkProfile: {
  networkPlugin: 'azure'
  networkPolicy: 'calico'
}
```

## Azure Key Vault Provider

```bicep
addonProfiles: {
  azureKeyvaultSecretsProvider: {
    enabled: true
    config: {
      enableSecretRotation: 'true'
    }
  }
}
```

## Application Gateway Ingress Controller

```bicep
addonProfiles: {
  ingressApplicationGateway: {
    enabled: true
    config: {
      applicationGatewayId: appGateway.id
    }
  }
}
```

## Add-ons Summary

| Add-on | Purpose |
|--------|---------|
| omsagent | Container Insights monitoring |
| azureKeyvaultSecretsProvider | Mount Key Vault secrets as volumes |
| ingressApplicationGateway | Application Gateway as ingress controller |
| azurepolicy | Azure Policy for Kubernetes |

# AKS - Bicep Patterns

## Cluster Resource

```bicep
resource aks 'Microsoft.ContainerService/managedClusters@2023-07-01' = {
  name: '${resourcePrefix}-aks-${uniqueHash}'
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    dnsPrefix: '${resourcePrefix}-aks'
    kubernetesVersion: '1.28'
    agentPoolProfiles: [
      {
        name: 'default'
        count: 3
        vmSize: 'Standard_DS2_v2'
        mode: 'System'
        osType: 'Linux'
        enableAutoScaling: true
        minCount: 1
        maxCount: 5
      }
    ]
    networkProfile: {
      networkPlugin: 'azure'
      serviceCidr: '10.0.0.0/16'
      dnsServiceIP: '10.0.0.10'
    }
  }
}
```

## ACR Pull Role Assignment

```bicep
resource acrPullRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(aks.id, containerRegistry.id, 'acrpull')
  scope: containerRegistry
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d')
    principalId: aks.properties.identityProfile.kubeletidentity.objectId
    principalType: 'ServicePrincipal'
  }
}
```

## Node Pool Configuration

### System Pool (Required)

```bicep
{
  name: 'system'
  count: 3
  vmSize: 'Standard_DS2_v2'
  mode: 'System'
  osType: 'Linux'
}
```

### User Pool (Workloads)

```bicep
{
  name: 'workload'
  count: 2
  vmSize: 'Standard_DS4_v2'
  mode: 'User'
  osType: 'Linux'
  enableAutoScaling: true
  minCount: 1
  maxCount: 10
}
```

## Workload Identity

```bicep
properties: {
  oidcIssuerProfile: {
    enabled: true
  }
  securityProfile: {
    workloadIdentity: {
      enabled: true
    }
  }
}
```

# AKS - Kubernetes Manifests

## Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-service
  template:
    metadata:
      labels:
        app: my-service
    spec:
      containers:
      - name: my-service
        image: myacr.azurecr.io/my-service:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
```

## Service

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-service
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP
```

## Ingress

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
spec:
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80
```

# Azure Kubernetes Service (AKS)

Full Kubernetes orchestration for complex containerized workloads.

## When to Use

- Complex microservices requiring Kubernetes orchestration
- Teams with Kubernetes expertise
- Workloads needing fine-grained infrastructure control
- Multi-container pods with sidecars
- Custom networking requirements
- Hybrid/multi-cloud Kubernetes strategies

## Service Type in azure.yaml

```yaml
services:
  my-service:
    host: aks
    project: ./src/my-service
    docker:
      path: ./Dockerfile
    k8s:
      deploymentPath: ./k8s
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Container Registry | Image storage |
| Log Analytics Workspace | Monitoring |
| Virtual Network | Network isolation (optional) |
| Key Vault | Secrets management |

## Node Pool Types

| Pool | Purpose |
|------|---------|
| System | Cluster infrastructure, 3 nodes minimum |
| User | Application workloads, auto-scaling |

## References

- [Bicep Patterns](bicep.md)
- [K8s Manifests](manifests.md)
- [Add-ons](addons.md)

# App Insights

Azure Application Insights for telemetry, monitoring, and APM.

## When to Add

- User wants observability/monitoring
- User mentions telemetry, tracing, or logging
- Production apps needing health visibility

## Implementation

> **→ Invoke the `appinsights-instrumentation` skill**
>
> This skill has detailed guides for:
> - Auto-instrumentation (ASP.NET Core on App Service)
> - Manual instrumentation (Node.js, Python, C#)
> - Bicep templates and CLI scripts

## Quick Reference

| Aspect | Value |
|--------|-------|
| Resource | `Microsoft.Insights/components` |
| Depends on | Log Analytics Workspace |
| SKU | PerGB2018 (consumption-based) |

## Architecture Notes

- Create in same resource group as the app
- Connect to centralized Log Analytics Workspace
- Use connection string (not instrumentation key) for new apps

# App Service Bicep Patterns

## Linux vs Windows

> ⚠️ **Warning:** `linuxFxVersion` and `reserved: true` are **Linux-only** properties. Setting `linuxFxVersion` on a Windows App Service Plan causes a deployment error: `LinuxFxVersion cannot be set for non-Linux App Service plans`. Omit both for Windows plans.

| Property | Linux | Windows |
|----------|-------|---------|
| Plan `reserved` | `true` | omit (defaults to `false`) |
| Site `kind` | `'app,linux'` | `'app'` |
| Site `linuxFxVersion` | e.g. `'NODE\|20-lts'` | omit |
| Site `WEBSITE_NODE_DEFAULT_VERSION` | omit | e.g. `'~20'` |

> 💡 **Tip:** When both frontend and API use Node.js, prefer a **single Linux App Service Plan** for both. This avoids mixed-platform complexity and keeps all services on one plan.

## Linux App Service (Recommended for Node.js)

> ⚠️ **REQUIRED: `azd-service-name` tag** — The `tags` property MUST include `union(tags, { 'azd-service-name': serviceName })` so that `azd deploy` can locate the resource. Without this tag, `azd deploy` fails with `resource not found: unable to find a resource tagged with 'azd-service-name: web'`.

```bicep
resource appServicePlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-plan-${uniqueHash}'
  location: location
  kind: 'linux'
  sku: {
    name: 'B1'
    tier: 'Basic'
  }
  properties: {
    reserved: true  // Required for Linux
  }
}

resource webApp 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'app,linux'
  tags: union(tags, { 'azd-service-name': serviceName })  // REQUIRED for azd deploy
  properties: {
    serverFarmId: appServicePlan.id
    siteConfig: {
      linuxFxVersion: 'NODE|24-lts'
      alwaysOn: true
      healthCheckPath: '/health'
      appSettings: [
        {
          name: 'SCM_DO_BUILD_DURING_DEPLOYMENT'
          value: 'true'  // Required for source-based Node.js deploys (azd deploy)
        }
        {
          name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
          value: applicationInsights.properties.ConnectionString
        }
        {
          name: 'ApplicationInsightsAgent_EXTENSION_VERSION'
          value: '~3'
        }
      ]
    }
    httpsOnly: true
  }
  identity: {
    type: 'SystemAssigned'
  }
}
```

## Windows App Service

Use when the runtime requires Windows (e.g. .NET Framework) or when explicitly requested.

```bicep
resource appServicePlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-plan-${uniqueHash}'
  location: location
  sku: {
    name: 'B1'
    tier: 'Basic'
  }
  // Do NOT set reserved: true for Windows
}

resource webApp 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'app'
  tags: union(tags, { 'azd-service-name': serviceName })  // REQUIRED for azd deploy
  properties: {
    serverFarmId: appServicePlan.id
    siteConfig: {
      // Do NOT set linuxFxVersion for Windows plans
      alwaysOn: true
      healthCheckPath: '/health'
      appSettings: [
        {
          name: 'SCM_DO_BUILD_DURING_DEPLOYMENT'
          value: 'true'  // Required for source-based Node.js deploys (azd deploy)
        }
        {
          name: 'WEBSITE_NODE_DEFAULT_VERSION'
          value: '~20'
        }
        {
          name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
          value: applicationInsights.properties.ConnectionString
        }
        {
          name: 'ApplicationInsightsAgent_EXTENSION_VERSION'
          value: '~3'
        }
      ]
    }
    httpsOnly: true
  }
  identity: {
    type: 'SystemAssigned'
  }
}
```

## Node.js Build Configuration

> ⚠️ **Warning:** For source-based Node.js deployments to App Service (e.g. `azd deploy`), you **must** set `SCM_DO_BUILD_DURING_DEPLOYMENT=true` so App Service runs `npm install` during deployment. Without this, the app fails at runtime with `Cannot find module` errors.

This setting is already included in both the Linux and Windows examples above.

## Key Vault Integration

Reference secrets from Key Vault:

```bicep
appSettings: [
  {
    name: 'DATABASE_URL'
    value: '@Microsoft.KeyVault(VaultName=${keyVault.name};SecretName=database-url)'
  }
]
```

# App Service Custom Domains and Managed TLS

## Prerequisites

| Requirement | Details |
|------------|---------|
| SKU tier | Basic (B1) or higher |
| DNS access | Ability to create CNAME, A, and TXT records |
| Domain ownership | Verified via TXT record |

## DNS Configuration

### Subdomain (CNAME)

| Record Type | Name | Value |
|------------|------|-------|
| CNAME | `www` | `<app-name>.azurewebsites.net` |
| TXT | `asuid.www` | `<verification-id>` |

### Apex / Root Domain (A Record)

| Record Type | Name | Value |
|------------|------|-------|
| A | `@` | `<app-ip-address>` |
| TXT | `asuid` | `<verification-id>` |

Get the verification ID and IP address:

```bash
# Get verification ID
az webapp show -n $APP -g $RG --query "customDomainVerificationId" -o tsv

# Get IP address (for A records)
az webapp show -n $APP -g $RG --query "inboundIpAddress" -o tsv
```

> 💡 **Tip:** Prefer CNAME records for subdomains. For apex domains, consider using an Azure DNS alias record to avoid hardcoding IP addresses that may change.

## Bind Custom Domain via CLI

```bash
# Add custom domain
az webapp config hostname add -n $APP -g $RG --hostname www.contoso.com

# Create managed certificate (free)
az webapp config ssl create -n $APP -g $RG --hostname www.contoso.com

# Capture certificate thumbprint
THUMBPRINT=$(az webapp config ssl list -n $APP -g $RG \
  --query "[?contains(hostNames, 'www.contoso.com')].thumbprint | [0]" -o tsv)

# Bind the certificate
az webapp config ssl bind -n $APP -g $RG \
  --certificate-thumbprint $THUMBPRINT --ssl-type SNI
```

## Bicep — Custom Domain with Managed Certificate

```bicep
resource customDomain 'Microsoft.Web/sites/hostNameBindings@2022-09-01' = {
  parent: webApp
  name: 'www.contoso.com'
  properties: {
    siteName: webApp.name
    hostNameType: 'Verified'
    sslState: 'Disabled' // enable after cert is created
  }
}

resource managedCert 'Microsoft.Web/certificates@2022-09-01' = {
  name: 'www.contoso.com'
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    canonicalName: 'www.contoso.com'
  }
  dependsOn: [customDomain]
}
```

Then run a follow-up Bicep deployment to enable SNI and bind the managed certificate to the hostname:

```bicep
resource managedCert 'Microsoft.Web/certificates@2022-09-01' existing = {
  name: 'www.contoso.com'
}

resource customDomainTlsBinding 'Microsoft.Web/sites/hostNameBindings@2022-09-01' = {
  parent: webApp
  name: 'www.contoso.com'
  properties: {
    siteName: webApp.name
    hostNameType: 'Verified'
    sslState: 'SniEnabled'
    thumbprint: managedCert.properties.thumbprint
  }
}
```

> ⚠️ **Warning:** Managed certificate creation requires the DNS records to be in place first. The hostname binding must exist before requesting the certificate.

## Terraform — Custom Domain with Managed Certificate

```hcl
resource "azurerm_app_service_custom_hostname_binding" "domain" {
  hostname            = "www.contoso.com"
  app_service_name    = azurerm_linux_web_app.app.name
  resource_group_name = azurerm_resource_group.rg.name
}

resource "azurerm_app_service_managed_certificate" "cert" {
  custom_hostname_binding_id = azurerm_app_service_custom_hostname_binding.domain.id
}

resource "azurerm_app_service_certificate_binding" "binding" {
  hostname_binding_id = azurerm_app_service_custom_hostname_binding.domain.id
  certificate_id      = azurerm_app_service_managed_certificate.cert.id
  ssl_state           = "SniEnabled"
}
```

## TLS Options

| Option | Cost | Renewal | Use Case |
|--------|------|---------|----------|
| App Service Managed Certificate | Free | Auto-renewed | Standard custom domains |
| App Service Certificate (purchased) | ~$70/yr | Auto-renewed | Extended validation, wildcard |
| Bring your own certificate | Varies | Manual | Enterprise PKI, specific CA |

### Enforce HTTPS Only

```bicep
resource webApp 'Microsoft.Web/sites@2022-09-01' = {
  name: appName
  location: location
  properties: {
    httpsOnly: true
    // ...
  }
}
```

```hcl
resource "azurerm_linux_web_app" "app" {
  name                = var.app_name
  # ...
  https_only          = true
}
```

## Minimum TLS Version

```bash
# Set minimum TLS version to 1.2
az webapp config set -n $APP -g $RG --min-tls-version 1.2
```

```bicep
siteConfig: {
  minTlsVersion: '1.2'
}
```

> ⚠️ **Warning:** TLS 1.0 and 1.1 are deprecated. Always set minimum TLS version to 1.2 for production workloads.

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| Domain verification fails | Missing TXT record | Add `asuid` TXT record and wait for DNS propagation |
| Certificate creation fails | DNS not yet propagated | Wait 5-15 min for propagation; verify with `nslookup` |
| SSL binding error | SKU too low | Upgrade to Basic (B1) or higher |
| Managed cert not renewing | DNS record changed | Verify CNAME/A record still points to the app |

# App Service Deployment Slots

Zero-downtime deployments using staging slots.

## Basic Staging Slot

```bicep
resource stagingSlot 'Microsoft.Web/sites/slots@2022-09-01' = {
  parent: webApp
  name: 'staging'
  location: location
  properties: {
    serverFarmId: appServicePlan.id
  }
}
```

## Slot Requirements — App Service

| SKU Tier | Slots Supported |
|----------|-----------------|
| Free/Shared | 0 |
| Basic | 0 |
| Standard | 5 |
| Premium | 20 |

## Slot Requirements — Azure Functions

> ⚠️ Slot support for Azure Functions varies by OS and hosting plan.

| Hosting Plan | OS | Slots Supported |
|---|---|---|
| Flex Consumption (FC1) | Linux | ❌ 0 |
| Consumption (Y1) | **Windows** | ✅ 1 staging slot |
| Consumption (Y1) | Linux | ❌ 0 |
| Elastic Premium (EP1-EP3) | Windows or Linux | ✅ 20 slots |
| Dedicated (Standard+) | Windows or Linux | ✅ 5–20 slots |

> 💡 **For Azure Functions requiring deployment slots:**
> - **Windows Consumption (Y1) supports 1 staging slot** — this is a supported platform capability.
>   If you need it, use it. See the Bicep example below.
> - Recommendation for new projects: prefer **Elastic Premium (EP1+)** (no cold starts, VNet integration)
>   or a **Dedicated plan (Standard+)**. Y1 cold starts can affect slot swap warm-up reliability.
> - **Linux Consumption and Flex Consumption do not support deployment slots.**

### Windows Consumption Function App with Staging Slot (Bicep)

```bicep
resource functionAppPlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-funcplan-${uniqueHash}'
  location: location
  sku: { name: 'Y1', tier: 'Dynamic' }
  // No 'reserved: true' — Windows Consumption
}

resource functionApp 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'functionapp'  // Windows (no 'linux' suffix)
  identity: { type: 'SystemAssigned' }
  properties: {
    serverFarmId: functionAppPlan.id
    httpsOnly: true
    siteConfig: {
      appSettings: [
        { name: 'WEBSITE_NODE_DEFAULT_VERSION', value: '~20' }
        { name: 'FUNCTIONS_EXTENSION_VERSION', value: '~4' }
        { name: 'FUNCTIONS_WORKER_RUNTIME', value: 'node' }
        { name: 'WEBSITE_CONTENTAZUREFILECONNECTIONSTRING', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'WEBSITE_CONTENTSHARE', value: '${toLower(serviceName)}-prod' }
        { name: 'AzureWebJobsStorage', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: applicationInsights.properties.ConnectionString }
      ]
    }
  }
}

// Staging slot — only 1 staging slot supported on Consumption
resource stagingSlot 'Microsoft.Web/sites/slots@2022-09-01' = {
  parent: functionApp
  name: 'staging'
  location: location
  kind: 'functionapp'
  properties: {
    serverFarmId: functionAppPlan.id
    siteConfig: {
      appSettings: [
        { name: 'WEBSITE_NODE_DEFAULT_VERSION', value: '~20' }
        { name: 'FUNCTIONS_EXTENSION_VERSION', value: '~4' }
        { name: 'FUNCTIONS_WORKER_RUNTIME', value: 'node' }
        { name: 'WEBSITE_CONTENTAZUREFILECONNECTIONSTRING', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'WEBSITE_CONTENTSHARE', value: '${toLower(serviceName)}-staging' }  // MUST differ from production
        { name: 'AzureWebJobsStorage', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: applicationInsights.properties.ConnectionString }
      ]
    }
  }
}
```

> ⚠️ `WEBSITE_CONTENTSHARE` **must be unique per slot** on Windows Consumption — each slot needs its own file share.
> Use slot-sticky settings (via `slotConfigNames`) for `WEBSITE_CONTENTSHARE` and `WEBSITE_CONTENTAZUREFILECONNECTIONSTRING`
> so these values do not swap with production.

## Deployment Flow

1. Deploy to staging slot
2. Warm up and test staging
3. Swap staging with production
4. Rollback by swapping again if needed

## Slot Settings

Configure settings that should not swap:

```bicep
resource slotConfigNames 'Microsoft.Web/sites/config@2022-09-01' = {
  parent: webApp
  name: 'slotConfigNames'
  properties: {
    appSettingNames: [
      'APPLICATIONINSIGHTS_CONNECTION_STRING'
    ]
  }
}
```

# App Service Networking

VNet integration, Private Endpoints, Access Restrictions, and Hybrid Connections.

## Feature Availability by SKU

| Feature | Free | Basic | Standard | Premium | Isolated |
|---------|:-:|:-:|:-:|:-:|:-:|
| VNet integration (outbound) | ❌ | ✅ | ✅ | ✅ | ✅ (native) |
| Private Endpoints (inbound) | ❌ | ✅ | ✅ | ✅ | ✅ |
| Access Restrictions | ✅ | ✅ | ✅ | ✅ | ✅ |
| Hybrid Connections | ❌ | 5 | 25 | 200 | 200 |
| Access to service-endpoint-protected resources | ❌ | ✅ | ✅ | ✅ | ✅ |
> Note: Service endpoints are configured on VNets/subnets and downstream services (e.g., Storage, SQL). App Service accesses them via VNet integration rather than enabling service endpoints directly on the app.

## VNet Integration (Outbound)

Routes outbound traffic from the app through a VNet subnet, enabling access to private resources (databases, storage, VMs).

### Subnet Requirements

| Requirement | Value |
|------------|-------|
| Minimum subnet size | `/26` (64 addresses) recommended |
| Delegation | `Microsoft.Web/serverFarms` |
| Dedicated | One subnet per App Service plan |

### Bicep — VNet Integration

```bicep
resource subnet 'Microsoft.Network/virtualNetworks/subnets@2023-11-01' = {
  parent: vnet
  name: 'app-service-subnet'
  properties: {
    addressPrefix: '10.0.1.0/26'
    delegations: [
      {
        name: 'Microsoft.Web.serverFarms'
        properties: { serviceName: 'Microsoft.Web/serverFarms' }
      }
    ]
  }
}

resource webApp 'Microsoft.Web/sites@2024-11-01' = {
  name: appName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    virtualNetworkSubnetId: subnet.id
    outboundVnetRouting: {
      allTraffic: true // route all outbound through VNet
    }
  }
}
```

### CLI - VNet Integration

```bash
# Configure virtual network integration 
az webapp vnet-integration add --resource-group RG --name APP --vnet VNET --subnet SUBNET

# Update app configuration to route all outbound traffic through the virtual network integration
az resource update --resource-group RG --name APP --resource-type "Microsoft.Web/sites" --set properties.outboundVnetRouting.allTraffic=true
```


> 💡 **Tip:** Set `outboundVnetRouting.allTraffic: true` to route ALL outbound traffic through the VNet. Without this, only RFC1918 traffic is routed through the VNet.

## Private Endpoints (Inbound)

Expose the app on a private IP address within your VNet. Public access can be disabled entirely.

### Bicep — Private Endpoint

```bicep
resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = {
  name: '${appName}-pe'
  location: location
  properties: {
    subnet: { id: privateEndpointSubnet.id }
    privateLinkServiceConnections: [
      {
        name: '${appName}-connection'
        properties: {
          privateLinkServiceId: webApp.id
          groupIds: ['sites']
        }
      }
    ]
  }
}

resource privateDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = {
  name: 'privatelink.azurewebsites.net'
  location: 'global'
}

resource dnsLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = {
  parent: privateDnsZone
  name: '${vnet.name}-link'
  location: 'global'
  properties: {
    virtualNetwork: { id: vnet.id }
    registrationEnabled: false
  }
}

resource privateDnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = {
  parent: privateEndpoint
  name: 'default'
  properties: {
    privateDnsZoneConfigs: [
      {
        name: 'webapp-dns-zone'
        properties: {
          privateDnsZoneId: privateDnsZone.id
        }
      }
    ]
  }
}
```

### CLI - Private Endpoint

```bash
# Retrieve web app resource id
id=$(az webapp show --name APP --resource-group RG --query id --output tsv)

# Create Private Endpoint
az network private-endpoint create --connection-name CONNECTIONNAME --name private-endpoint --private-connection-resource-id $id --resource-group RG --subnet SUBNET --group-id sites --vnet-name VNET

# Create Private DNS Zone
az network private-dns zone create --resource-group RG --name "privatelink.azurewebsites.net"

# Link the DNS Zone to virtual network
az network private-dns link vnet create --resource-group RG --zone-name "privatelink.azurewebsites.net" --name dns-link --virtual-network VNET --registration-enabled false

```

> ⚠️ **Warning:** Private Endpoints require Basic (B1+) or higher tier. The private DNS zone `privatelink.azurewebsites.net` must be linked to the VNet for name resolution.

## Access Restrictions

Control inbound access with IP-based or service-tag rules. Available on all SKUs.

### Bicep — Access Restrictions

```bicep
siteConfig: {
  ipSecurityRestrictions: [
    {
      name: 'allow-office'
      priority: 100
      action: 'Allow'
      ipAddress: '203.0.113.0/24'
    }
    {
      name: 'deny-all'
      priority: 2147483647
      action: 'Deny'
      ipAddress: 'Any'
    }
  ]
  scmIpSecurityRestrictionsUseMain: true
}
```

### CLI - Access Restrictions

```bash
# Add restriction to allow traffic from set range used by the office
az webapp config access-restriction add --resource-group RG --name APP --rule-name 'allow-office' --action Allow --ip-address 203.0.113.0/24 --priority 100

# Add restriction to deny access from any other address range
az webapp config access-restriction add --resource-group RG --name APP --rule-name 'deny-all' --action Deny --ip-address Any --priority 2147483647

# Set SCM Site (Kudu) to use same access restrictions as main site
az webapp config access-restriction set -g RG -n APP --use-same-restrictions-for-scm-site true
```

> 💡 **Tip:** Always restrict the SCM/Kudu site too. Use `scmIpSecurityRestrictionsUseMain: true` to inherit main site rules, or define separate SCM rules.

## Hybrid Connections

Connect to on-premises resources without VPN. Requires Basic tier or higher. Uses Hybrid Connection Manager (HCM) agent on-premises relaying through Azure Relay.

> ⚠️ **Warning:** Each Hybrid Connection maps to a single host:port endpoint. Basic tier supports 5; Standard tier supports 25; Premium/Isolated support 200.

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| Cannot reach private DB | VNet integration not enabled | Enable VNet integration; check `outboundVnetRouting.allTraffic` |
| DNS resolution fails | Private DNS zone not linked | Link `privatelink.*` DNS zone to VNet |
| Access restriction not working | Priority ordering wrong | Lower numbers = higher priority; check rule order |
| Hybrid Connection timeout | HCM not running | Verify HCM service status on-premises |
| Outbound traffic blocked | NSG rules on subnet | Allow outbound to required services in NSG |

# Azure App Service

Hosting patterns and best practices for Azure App Service.

## When to Use

- Traditional web applications
- REST APIs without containerization
- .NET, Node.js, Python, Java, PHP applications
- When Docker is not required/desired
- When built-in deployment slots are needed

## Service Type in azure.yaml

```yaml
services:
  my-web:
    host: appservice
    project: ./src/my-web
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| App Service Plan | Compute hosting |
| Application Insights | Monitoring |
| Key Vault | Secrets (optional) |

## Runtime Stacks

> 💡 **Tip:** Prefer Linux App Service Plans for Node.js, Python, and Java. Use Windows only when explicitly required (e.g. .NET Framework). See [Bicep Patterns](bicep.md) for Linux vs Windows configuration.

### Linux (recommended)

| Language | linuxFxVersion |
|----------|----------------|
| Node.js 24 | `NODE\|24-lts` |
| Node.js 22 | `NODE\|22-lts` |
| Python 3.14 | `PYTHON\|3.14` |
| .NET 10 | `DOTNETCORE\|10.0` |
| Java 21 | `JAVA\|21-java21` |

### Windows

| Language | Setting |
|----------|---------|
| Node.js | `WEBSITE_NODE_DEFAULT_VERSION: '~24'` (app setting) |
| .NET 10 | Built-in (no extra config) |

## SKU Selection

| SKU | Use Case |
|-----|----------|
| F1/D1 | Development/testing (free/shared) |
| B1-B3 | Small production, basic features |
| S1-S3 | Production with auto-scale, slots |
| P1v3-P3v3 | High-performance production |

## Health Checks

Always configure health check path:

```bicep
siteConfig: {
  healthCheckPath: '/health'
}
```

Endpoint should return 200 OK when healthy.

## Templates

For App Service templates with composable recipes (SQL, Cosmos DB, Auth, Redis), see [Template Selection](templates/selection.md).

## Common Data Backends

When pairing App Service with a data layer, load the corresponding service references:

| Data Service | Reference                                 |
| ------------ | ----------------------------------------- |
| Azure SQL    | [SQL Database](../sql-database/README.md) |
| Cosmos DB    | [Cosmos DB](../cosmos-db/README.md)       |

## References

- [Bicep Patterns](bicep.md)
- [Deployment Slots](deployment-slots.md)
- [Auto-Scaling](scaling.md)
- [Networking](networking.md)
- [SKU Selection](sku-selection.md)
- [Custom Domains](custom-domains.md)

# App Service Auto-scaling

## Basic Auto-scale Configuration

```bicep
resource autoScale 'Microsoft.Insights/autoscalesettings@2022-10-01' = {
  name: '${webApp.name}-autoscale'
  location: location
  properties: {
    targetResourceUri: appServicePlan.id
    enabled: true
    profiles: [
      {
        name: 'Auto scale'
        capacity: {
          minimum: '1'
          maximum: '10'
          default: '1'
        }
        rules: [
          {
            metricTrigger: {
              metricName: 'CpuPercentage'
              metricResourceUri: appServicePlan.id
              timeGrain: 'PT1M'
              statistic: 'Average'
              timeWindow: 'PT5M'
              timeAggregation: 'Average'
              operator: 'GreaterThan'
              threshold: 70
            }
            scaleAction: {
              direction: 'Increase'
              type: 'ChangeCount'
              value: '1'
              cooldown: 'PT5M'
            }
          }
        ]
      }
    ]
  }
}
```

## Common Metrics

| Metric | Use Case |
|--------|----------|
| CpuPercentage | CPU-bound workloads |
| MemoryPercentage | Memory-intensive apps |
| HttpQueueLength | Request queue depth |
| Requests | Request volume |

## Recommendations

| Workload | Min | Max | Metric |
|----------|-----|-----|--------|
| Production API | 2 | 10 | CPU + Requests |
| Dev/Test | 1 | 3 | CPU |
| High-traffic | 3 | 20 | HTTP Queue |

## SKU Requirements

Auto-scaling requires **Standard (S1+)** or **Premium** tier.

# App Service SKU Selection

## SKU Comparison Matrix

| Feature | Free (F1) | Basic (B1-B3) | Standard (S1-S3) | Premium (P0v3-P3v3 and P1Mv3-P5Mv3;P0v4-P3v4 and P1Mv4-P5Mv4) | Isolated (I1v2-I6v2) |
|---------|:-:|:-:|:-:|:-:|:-:|
| **Custom domains** | ❌ | ✅ | ✅ | ✅ | ✅ |
| **TLS/SSL bindings** | ❌ | ✅ (SNI) | ✅ (SNI + IP) | ✅ (SNI + IP) | ✅ (SNI + IP) |
| **Deployment slots** | ❌ | ❌ | 5 | 20 | 20 |
| **Auto-scale** | ❌ | ❌ | ✅ (10 inst.) | ✅ (30 inst.) | ✅ (100 inst.) |
| **VNet integration** | ❌ | ✅ | ✅ | ✅ | ✅ (ASE is in VNet) |
| **Private endpoints** | ❌ | ✅ | ✅ | ✅ | ✅ |
| **Always On** | ❌ | ✅ | ✅ | ✅ | ✅ |
| **Backup/Restore** | ❌ | ❌ | ✅ | ✅ | ✅ |
| **Hybrid Connections** | ❌ | 5 | 25 | 200 | 200 |
| **Traffic Manager** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **SLA** | None | None | 99.95% | 99.95% | 99.95% |

## Pricing Overview

| SKU | vCPU | RAM | Storage | Approx. Monthly Cost |
|-----|------|-----|---------|---------------------|
| F1 | Shared | 1 GB | 1 GB | Free |
| B1 | 1 | 1.75 GB | 10 GB | ~$55 |
| B2 | 2 | 3.5 GB | 10 GB | ~$110 |
| S1 | 1 | 1.75 GB | 50 GB | ~$73 |
| S2 | 2 | 3.5 GB | 50 GB | ~$146 |
| P1v3 | 2 | 8 GB | 250 GB | ~$138 |
| P2v3 | 4 | 16 GB | 250 GB | ~$276 |
| P3v3 | 8 | 32 GB | 250 GB | ~$552 |
| I1v2 | 2 | 8 GB | 1 TB | ~$460 |

> 💡 **Tip:** Figures are representative for **Windows OS** in **Central US**, **as of 2026-04**. Prices vary by region, OS, and offer. Use the [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/) for exact figures.

### Save by using Reserved Instances and Savings Plans

Cost savings can be made on Premium V3, Premium V4 and Isolated V2 plans by committing to reserved instances for 1 or 3 year terms, details can found at [https://learn.microsoft.com/azure/cost-management-billing/reservations/prepay-app-service](https://learn.microsoft.com/azure/cost-management-billing/reservations/prepay-app-service).

Alternatively cost savings can be made using [Azure Savings plans](https://learn.microsoft.com/en-us/azure/cost-management-billing/savings-plan/).

## Decision Criteria

```
Production workload?
├─ No → Free (F1) or Basic (B1) for dev/test
└─ Yes
   Need deployment slots, auto-scale, or backups?
   ├─ No → Basic (B1-B3) if budget-constrained (supports VNet integration and Private Endpoints)
   └─ Yes
          Need network isolation (dedicated ASE)?
          ├─ Yes → Isolated (I1v2+)
          └─ No
             Need more than 5 deployment slots or more than 10 instances?
             ├─ Yes → Premium (P1v3+)
             └─ No → Standard (S1-S3) with Private Endpoints and VNet integration
```

## Feature Unlock Summary

Key features unlocked at each tier:

| Upgrade Path | Features Gained |
|-------------|-----------------|
| Free → Basic | Custom domains, TLS/SSL, Always On, VNet Integration, Private Endpoints, Hybrid Connections (5) |
| Basic → Standard | Deployment slots, auto-scale, backups |
| Standard → Premium | More slots (20), higher scale (30 inst.) |
| Premium → Isolated | Full network isolation (ASE), dedicated infrastructure |

## Bicep — App Service Plan with SKU

```bicep
resource appServicePlan 'Microsoft.Web/serverfarms@2025-03-01' = {
  name: planName
  location: location
  sku: {
    name: 'P1v3'
    tier: 'PremiumV3'
    capacity: 2 // number of instances
  }
  kind: 'linux'
  properties: {
    reserved: true // required for Linux
  }
}
```

## Terraform — App Service Plan with SKU

```hcl
resource "azurerm_service_plan" "plan" {
  name                = var.plan_name
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  os_type             = "Linux"
  sku_name            = "P1v3"
}
```

## Scaling Within a Tier

Scale up (change SKU) vs scale out (add instances):

| Strategy | When to Use | How |
|----------|-------------|-----|
| Scale up | App needs more CPU/RAM | Change SKU (e.g., S1 → S2) |
| Scale out | Handle more concurrent load | Increase instance count or enable auto-scale |

> ⚠️ **Warning:** Scaling from one tier family to another (e.g., Standard to Premium) may cause a brief restart. Schedule changes during low-traffic windows.

## Recommendations by Workload

| Workload | Recommended SKU | Reason |
|----------|----------------|--------|
| Personal blog / prototype | F1 or B1 | Minimal cost, no SLA needed |
| Team dev/test | B1-B2 | Always On, custom domain |
| Production API | S1-S3 (P0v3/P0v4+ for higher scale/perf) | Auto-scale, slots, VNet |
| Enterprise with compliance | P1v3+/P1v4+ | Private endpoints, 20 slots, 30 instances |
| Regulated / multi-tenant SaaS | I1v2+ | Full network isolation |

# Container Apps Bicep Patterns

> **⚠️ Container Registry Naming:** If using Azure Container Registry, names must be alphanumeric only (5-50 characters). Use `replace()` to remove hyphens: `replace('cr${environmentName}${resourceSuffix}', '-', '')`

> **⚠️ Two-Phase Deployment (Mandatory):** To avoid a circular dependency when scoping the AcrPull role assignment to a Bicep module, use the two-phase pattern below:
> - **Phase 1:** Deploy ACR and Container App with a public placeholder image and **no** `registries` block.
> - **Phase 2:** Deploy the AcrPull role assignment as a **separate module** using outputs from Phase 1.
>
> The Bicep template does **not** need a `registries` block. `azd deploy` handles the registry/identity link by calling `az containerapp registry set --server <acr-server> --identity system` via the Azure API before updating the container image. If you are not using AZD, you must run this command manually before switching the image to an ACR-hosted image; otherwise the app will hit image pull failures.

## Phase 1: Container App Module (No Registry Link)

```bicep
// Placeholder image allows provisioning before app image exists in ACR.
// No registries block in Bicep — azd deploy configures the registry/identity link
// (az containerapp registry set --identity system) and updates the image via the Azure API.
// If not using AZD, run that command manually before switching to an ACR-hosted image.
param containerImageName string = 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  name: appName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    environmentId: containerAppsEnvironment.id
    configuration: {
      ingress: {
        external: true
        targetPort: 8080
        transport: 'auto'
      }
      // No registries block in Bicep. azd deploy sets the registry/identity link via
      // 'az containerapp registry set --identity system' before pushing the real image.
      // Without this step (or its manual equivalent), the app will fail to pull from ACR.
    }
    template: {
      containers: [
        {
          name: serviceName
          image: containerImageName
          resources: {
            cpu: json('0.5')
            memory: '1Gi'
          }
        }
      ]
    }
  }
}

output systemAssignedMIPrincipalId string = containerApp.identity.principalId
```

## Phase 2: AcrPull Role Assignment Module (acr-pull-role.bicep)

Place this in a **separate module file** so neither the ACR module nor the Container App module depends on it, eliminating the circular dependency.

```bicep
// acr-pull-role.bicep
param acrName string
param principalId string

resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
  name: acrName
}

resource acrPullRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(containerRegistry.id, principalId, 'acrpull')
  scope: containerRegistry
  properties: {
    roleDefinitionId: subscriptionResourceId(
      'Microsoft.Authorization/roleDefinitions',
      '7f951dda-4ed3-4680-a7ca-43fe172d538d'
    )
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

> 💡 **Tip:** Always set `principalType: 'ServicePrincipal'` for managed identities. This avoids a Graph API lookup and speeds up role assignment propagation.

## Wiring Phase 1 and Phase 2 in main.bicep

```bicep
// Phase 1: ACR and Container App — neither module depends on the role assignment
module containerRegistry './modules/container-registry.bicep' = {
  name: 'containerRegistry'
  scope: rg
  params: { /* ... */ }
}

module api './modules/container-app.bicep' = {
  name: 'api'
  scope: rg
  params: {
    containerImageName: 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'
    // No registries param in Bicep — azd deploy configures the registry/identity link
    // and updates the image via the Azure API after provisioning.
    /* ... */
  }
}

// Phase 2: Role assignment depends on outputs of both Phase 1 modules,
// but neither Phase 1 module depends on this — no circular dependency.
module acrPullRole './modules/acr-pull-role.bicep' = {
  name: 'acrPullRole'
  scope: rg
  params: {
    acrName: containerRegistry.outputs.name
    principalId: api.outputs.systemAssignedMIPrincipalId
  }
}
```

## Container Apps Environment

```bicep
resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2023-05-01' = {
  name: '${resourcePrefix}-env'
  location: location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: logAnalyticsWorkspace.properties.customerId
        sharedKey: logAnalyticsWorkspace.listKeys().primarySharedKey
      }
    }
  }
}
```

# Container Apps Day-2 Operations

Operational tasks for running Container Apps in production: restart, exec, logs, environment updates, and secret rotation.

## Restart and Lifecycle

| Action | Command |
|--------|---------|
| Restart active revision | `az containerapp revision restart -n $APP -g $RG --revision $REV` |
| Scale to zero (stop) | `az containerapp update -n $APP -g $RG --min-replicas 0 --max-replicas <current-max>` |
| Resume (restore scaling) | `az containerapp update -n $APP -g $RG --min-replicas <previous-min> --max-replicas <current-max>` |
| List replicas | `az containerapp replica list -n $APP -g $RG --revision $REV` |

> 💡 **Tip:** Restarting a revision replaces all running replicas gracefully. No new revision is created.

## Exec into a Container

Open a shell inside a running replica for debugging:

```bash
# Interactive shell
az containerapp exec -n $APP -g $RG --command /bin/sh

# Target a specific replica and container
az containerapp exec -n $APP -g $RG \
  --replica $REPLICA_NAME \
  --container $CONTAINER_NAME \
  --command /bin/sh
```

> ⚠️ **Warning:** Exec sessions are for debugging only. Changes to the container filesystem are lost on restart.

## Log Streaming

### Real-time Logs

```bash
# Stream system logs
az containerapp logs show -n $APP -g $RG --type system --follow

# Stream application (console) logs
az containerapp logs show -n $APP -g $RG --type console --follow

# Filter to a specific revision or replica
az containerapp logs show -n $APP -g $RG \
  --type console --revision $REV --follow
```

### Log Analytics (KQL)

Query historical logs via the Container Apps environment's Log Analytics workspace:

```kql
// Azure Monitor destination (new environments — default)
ContainerAppConsoleLogs
| where ContainerAppName == "my-app"
| where TimeGenerated > ago(1h)
| project TimeGenerated, Log, RevisionName
| order by TimeGenerated desc

// Log Analytics destination (legacy environments)
// ContainerAppConsoleLogs_CL
// | where ContainerAppName_s == "my-app"
// | project TimeGenerated, Log_s, RevisionName_s
```

## Environment Variable Updates

Updating environment variables creates a new revision:

```bash
# Set or update env vars
az containerapp update -n $APP -g $RG \
  --set-env-vars "DB_HOST=newhost.postgres.database.azure.com" \
                 "CACHE_TTL=300"

# Remove an env var
az containerapp update -n $APP -g $RG \
  --remove-env-vars "OLD_SETTING"
```

### Bicep — Env Vars with Secret References

```bicep
configuration: {
  secrets: [
    { name: 'db-password', value: dbPassword }  // or use keyVaultUrl + identity
  ]
}
template: {
  containers: [
    {
      name: 'api'
      image: '${acrName}.azurecr.io/api:latest'
      env: [
        { name: 'DB_HOST', value: dbHost }
        { name: 'DB_PASSWORD', secretRef: 'db-password' }
      ]
    }
  ]
}
```

## Secret Management

### Create and Update Secrets

```bash
# Add a secret (use Key Vault references in production — avoid plaintext secrets)
az containerapp secret set -n $APP -g $RG \
  --secrets "db-password=<secret-value>"

# Reference a Key Vault secret (managed identity required)
az containerapp secret set -n $APP -g $RG \
  --secrets "db-password=keyvaultref:https://myvault.vault.azure.net/secrets/db-pwd,identityref:/subscriptions/.../userAssignedIdentities/my-id"
```

> ⚠️ **Warning:** Avoid passing plaintext secrets on the command line — they may appear in shell history and process listings. Prefer Key Vault references. If you must use plaintext, use shell substitution like `--secrets "key=$(cat secret.txt)"` to avoid literals on the command line.

> 💡 **Tip:** Use Key Vault references instead of plain-text secrets. The Container App pulls the latest value on each new revision or replica start.

### Secret Rotation Workflow

1. Update the secret value in Key Vault
2. Create a new revision to pick up the updated value:
   ```bash
   az containerapp revision copy -n $APP -g $RG
   ```
3. Verify the new revision is healthy
4. Shift traffic to the new revision

> ⚠️ **Warning:** Existing replicas do NOT hot-reload Key Vault references. A new revision or replica restart is required.

## Health Monitoring

| Check | How |
|-------|-----|
| Revision health | `az containerapp revision list -n $APP -g $RG -o table` |
| Replica status | `az containerapp replica list -n $APP -g $RG --revision $REV` |
| System logs | `az containerapp logs show -n $APP -g $RG --type system` |
| Metrics | Azure Monitor → Container Apps → Requests, Replicas, CPU, Memory |

## Common Troubleshooting

| Symptom | Likely Cause | Remediation |
|---------|-------------|-------------|
| Replica crash loop | App startup failure | Check console logs; exec into container |
| 0 replicas running | Scale-to-zero + no traffic | Set `minReplicas: 1` or send a request |
| Env var not updating | Old revision still serving traffic | Verify the latest revision exists, then update ingress traffic weights or route to `latestRevision` |
| Secret value stale | Key Vault ref not refreshed | Create or verify the refreshed revision, then shift traffic to that revision |
| High memory/CPU | Resource limits too low | Update `resources.cpu` / `resources.memory` |

# Container Apps Environment Variables

## Standard Environment Variables

```bicep
env: [
  {
    name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
    value: applicationInsights.properties.ConnectionString
  }
  {
    name: 'AZURE_CLIENT_ID'
    value: managedIdentity.properties.clientId
  }
]
```

## Secret References (Key Vault)

Use secrets for sensitive values:

```bicep
configuration: {
  secrets: [
    {
      name: 'database-url'
      keyVaultUrl: 'https://myvault.vault.azure.net/secrets/database-url'
      identity: managedIdentity.id
    }
  ]
}

template: {
  containers: [
    {
      env: [
        {
          name: 'DATABASE_URL'
          secretRef: 'database-url'
        }
      ]
    }
  ]
}
```

## Common Variables

| Variable | Source | Notes |
|----------|--------|-------|
| `APPLICATIONINSIGHTS_CONNECTION_STRING` | App Insights | Telemetry |
| `AZURE_CLIENT_ID` | Managed Identity | SDK auth |
| `DATABASE_URL` | Key Vault secret | Connection string |
| `REDIS_URL` | Key Vault secret | Cache connection |

## Best Practices

- Never hardcode secrets in Bicep
- Use Key Vault references for all sensitive values
- Use Managed Identity for authentication
- Set `AZURE_CLIENT_ID` for SDK-based auth

# Container Apps Health Probes

Always configure health probes for production workloads.

## Liveness Probe

Detects if container is alive. Failure triggers restart.

```bicep
probes: [
  {
    type: 'liveness'
    httpGet: {
      path: '/health'
      port: 8080
    }
    initialDelaySeconds: 10
    periodSeconds: 30
    failureThreshold: 3
  }
]
```

## Readiness Probe

Detects if container is ready to receive traffic.

```bicep
probes: [
  {
    type: 'readiness'
    httpGet: {
      path: '/ready'
      port: 8080
    }
    initialDelaySeconds: 5
    periodSeconds: 10
    failureThreshold: 3
  }
]
```

## Startup Probe

For slow-starting containers. Delays other probes until startup succeeds.

```bicep
probes: [
  {
    type: 'startup'
    httpGet: {
      path: '/health'
      port: 8080
    }
    initialDelaySeconds: 0
    periodSeconds: 10
    failureThreshold: 30  // 30 * 10s = 5 min max startup
  }
]
```

## Recommendations

| Probe | Path | Initial Delay | Period |
|-------|------|---------------|--------|
| Liveness | `/health` | 10s | 30s |
| Readiness | `/ready` | 5s | 10s |
| Startup | `/health` | 0s | 10s |

# Container Apps Networking

VNet integration, ingress configuration, custom domains, and TLS for Container Apps.

## Ingress Modes

| Mode | Visibility | Use Case |
|------|-----------|----------|
| External | Internet-accessible | Public APIs, web apps |
| Internal | Not internet-accessible; reachable within the environment and VNet (if VNet-injected) | Microservices, back-end APIs |
| Disabled | No HTTP ingress | Background workers, queue processors |

### Bicep — External Ingress

```bicep
configuration: {
  ingress: {
    external: true
    targetPort: 8080
    transport: 'auto'
    allowInsecure: false
  }
}
```

### Bicep — Internal Ingress

```bicep
configuration: {
  ingress: {
    external: false
    targetPort: 8080
  }
}
```

> 💡 **Tip:** Internal apps get a `*.internal.<env-default-domain>` FQDN. This is accessible from within the Container Apps environment and, when the environment is VNet-injected, also from the VNet.

## VNet Integration

Container Apps run inside an environment that can be injected into a VNet subnet.

### Subnet Requirements

| Requirement | Workload Profiles (default) | Consumption-only (legacy) |
|------------|---------------------------|--------------------------|
| Minimum subnet size | `/27` (32 addresses) | `/23` (512 addresses) |
| Delegation | `Microsoft.App/environments` | `Microsoft.App/environments` |
| Dedicated | Subnet must be exclusive to the Container Apps environment | Same |

### Bicep — VNet-Integrated Environment

```bicep
resource subnet 'Microsoft.Network/virtualNetworks/subnets@2023-11-01' = {
  parent: vnet
  name: 'container-apps-subnet'
  properties: {
    addressPrefix: '10.0.16.0/27'
    delegations: [
      {
        name: 'Microsoft.App.environments'
        properties: { serviceName: 'Microsoft.App/environments' }
      }
    ]
  }
}

resource env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: envName
  location: location
  properties: {
    vnetConfiguration: {
      infrastructureSubnetId: subnet.id
      internal: false // true for internal-only environment
    }
  }
}
```

> ⚠️ **Warning:** VNet configuration is set at environment creation and cannot be changed afterward. Plan your network topology before creating the environment.

## Custom Domains

### Steps

1. Add a CNAME or A record pointing to the Container App's FQDN or static IP
2. Bind the custom domain to the Container App
3. Configure a managed or custom TLS certificate

```bash
# Register custom domain (hostname only — no cert provisioned yet)
az containerapp hostname add -n $APP -g $RG --hostname app.contoso.com

# Bind managed certificate (provisions and attaches TLS cert)
az containerapp hostname bind -n $APP -g $RG \
  --hostname app.contoso.com \
  --environment $ENV_NAME \
  --validation-method CNAME
```

### DNS Configuration

| Record Type | Name | Value |
|------------|------|-------|
| CNAME | `app.contoso.com` | `<app-name>.<region>.azurecontainerapps.io` |
| TXT (verification) | `asuid.app.contoso.com` | `<verification-id>` |
| A (apex domain) | `contoso.com` | Environment static IP |

> 💡 **Tip:** Use `az containerapp show -n $APP -g $RG --query properties.configuration.ingress.fqdn` to get the target FQDN for DNS records.

## TLS Configuration

### Managed Certificates

Azure automatically provisions and renews TLS certificates for custom domains — no manual cert management required.

> ⚠️ **Prerequisites:** Managed certificates require the app to be externally reachable with valid **public** DNS (CNAME or HTTP validation). They do **not** work for internal environments or apps behind private DNS. For private/internal scenarios, bring your own certificate via `az containerapp ssl upload`.

## IP Restrictions

> ⚠️ **Warning:** IP restriction rules are evaluated in **array order** (first match wins). The `priority` field does not exist in the Container Apps API — order your rules carefully in the array.

Allow-only rules implicitly deny all traffic not matching any rule. Deny-only rules implicitly allow all other traffic.

```bicep
configuration: {
  ingress: {
    external: true
    targetPort: 8080
    ipSecurityRestrictions: [
      {
        name: 'allow-office'
        action: 'Allow'
        ipAddressRange: '203.0.113.0/24'
        description: 'Office network'
      }
      {
        name: 'allow-vpn'
        action: 'Allow'
        ipAddressRange: '198.51.100.0/24'
        description: 'VPN gateway'
      }
    ]
  }
}
```

## Network Topology Summary

| Topology | Environment `internal` | Ingress `external` | Access |
|----------|----------------------|-------------------|--------|
| Public app | `false` | `true` | Internet + VNet |
| Internal microservice | `false` | `false` | Same environment; VNet if environment is VNet-injected |
| Fully private (VNet-wide) | `true` | `true` | VNet only (no public IP); accessible from anywhere in the VNet |
| Fully private (env-only) | `true` | `false` | VNet only (no public IP); accessible only within the Container Apps environment |

> ⚠️ **Warning:** An internal environment has no public IP. You need VPN, ExpressRoute, or a jump box to reach apps in an internal environment.

# Azure Container Apps

Serverless container hosting for microservices, APIs, and background workers.

## When to Use

- Microservices and APIs
- Background processing workers
- Event-driven applications
- Web applications (server-rendered)
- Any containerized workload that doesn't need full Kubernetes

## Service Type in azure.yaml

```yaml
services:
  my-api:
    host: containerapp
    project: ./src/my-api
    docker:
      path: ./Dockerfile
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Container Apps Environment | Hosting environment |
| Container Registry | Image storage |
| Log Analytics Workspace | Logging |
| Application Insights | Monitoring |

## Common Configurations

| Workload Type | Ingress | Min Replicas | Scaling |
|---------------|---------|--------------|---------|
| API Service | External | 1 (avoid cold starts) | HTTP-based |
| Background Worker | None | 0 (scale to zero) | Queue-based |
| Web Application | External | 1 | HTTP-based |

## References

- [Bicep Patterns](bicep.md)
- [Terraform Patterns](terraform.md)
- [Scaling Patterns](scaling.md)
- [Health Probes](health-probes.md)
- [Environment Variables](environment.md)
- [Day-2 Operations](day2-operations.md)
- [Networking & Ingress](networking.md)
- [Revisions & Traffic Splitting](revisions.md)

# Container Apps Revision Management

Revisions are immutable snapshots of a Container App version. Use them for blue/green deployments, canary releases, and instant rollback.

## Revision Modes

| Mode | Behavior | Use Case |
|------|----------|----------|
| `Single` | New revision replaces old immediately | Simple apps, dev/test |
| `Multiple` | Multiple revisions run simultaneously with traffic splitting | Production blue/green, canary |

## Setting Revision Mode (Bicep)

```bicep
resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  name: appName
  location: location
  properties: {
    configuration: {
      activeRevisionsMode: 'Multiple'
      ingress: {
        external: true
        targetPort: 8080
        traffic: [
          { latestRevision: true, weight: 100 }
        ]
      }
    }
  }
}
```

> 💡 **Tip:** In Bicep/ARM deployments, you typically can't predictably target a specific new revision name. Use `latestRevision: true` in Bicep for initial deployment, then configure traffic splitting or labels via CLI after the new revision is created.

> ⚠️ **Warning:** For blue/green workflows, you must first pin traffic to a named revision before deploying a new one. With `latestRevision: true, weight: 100`, new revisions automatically receive all traffic — there is no validation window.

## Traffic Splitting Patterns

### Blue/Green Deployment

Pin traffic to the current revision, deploy a new one, validate, then switch:

```bash
# Deploy new revision and capture its name from the update output
NEW_REV=$(az containerapp update -n $APP -g $RG --image $NEW_IMAGE \
  --query properties.latestRevisionName -o tsv)

# Test the new revision directly via its revision-specific URL
az containerapp revision list -n $APP -g $RG -o table

# Switch 100% traffic to the new revision
az containerapp ingress traffic set -n $APP -g $RG \
  --revision-weight "$NEW_REV=100"
```

### Canary Release

Gradually shift traffic to validate the new revision under load:

| Phase | Current | Canary | Duration |
|-------|---------|--------|----------|
| 1 | 90% | 10% | 15 min |
| 2 | 50% | 50% | 30 min |
| 3 | 0% | 100% | — |

```bash
# List revisions to identify current stable and new canary
az containerapp revision list -n $APP -g $RG -o table

STABLE_REV=<stable-revision-name>
CANARY_REV=<canary-revision-name>

az containerapp ingress traffic set -n $APP -g $RG \
  --revision-weight "$STABLE_REV=90" "$CANARY_REV=10"
```

### Label-Based Routing

Use labels instead of revision names for stable references:

```bash
# Assign labels
az containerapp revision label add -n $APP -g $RG \
  --label stable --revision "$APP--v1"
az containerapp revision label add -n $APP -g $RG \
  --label canary --revision "$APP--v2"

# Route by label
az containerapp ingress traffic set -n $APP -g $RG \
  --label-weight stable=80 canary=20
```

> 💡 **Tip:** Label-based routing lets you swap revision targets without changing traffic rules.

## Rollback

Revert instantly by redirecting all traffic to a known-good revision (e.g., one labeled `stable`):

```bash
# List active revisions and identify the known-good one
az containerapp revision list -n $APP -g $RG -o table

# Roll back using label-based routing (preferred)
az containerapp ingress traffic set -n $APP -g $RG \
  --label-weight stable=100

# Or roll back to a specific revision by name
az containerapp ingress traffic set -n $APP -g $RG \
  --revision-weight "<known-good-revision-name>=100"
```

## Revision Lifecycle

| Action | Command |
|--------|---------|
| List revisions | `az containerapp revision list -n $APP -g $RG` |
| Show revision details | `az containerapp revision show -n $APP -g $RG --revision $REV` |
| Activate a revision | `az containerapp revision activate -n $APP -g $RG --revision $REV` |
| Deactivate a revision | `az containerapp revision deactivate -n $APP -g $RG --revision $REV` |
| Restart a revision | `az containerapp revision restart -n $APP -g $RG --revision $REV` |

> ⚠️ **Warning:** Deactivated revisions cannot receive traffic. Reactivate before routing traffic to them.

## Terraform Traffic Config

```hcl
resource "azurerm_container_app" "app" {
  name                         = var.app_name
  container_app_environment_id = azurerm_container_app_environment.env.id
  resource_group_name          = azurerm_resource_group.rg.name
  revision_mode                = "Multiple"

  ingress {
    external_enabled = true
    target_port      = 8080
    traffic_weight {
      label           = "stable"
      revision_suffix = "v1"
      percentage      = 80
    }
    traffic_weight {
      label           = "canary"
      revision_suffix = "v2"
      percentage      = 20
    }
  }
}
```

## Recommendations

| Scenario | Revision Mode | Traffic Strategy |
|----------|---------------|------------------|
| Dev/Test | Single | N/A — auto-replace |
| Prod API | Multiple | Blue/green with instant swap |
| High-risk change | Multiple | Canary (10% → 50% → 100%) |
| Feature flags | Multiple | Label-based routing |

# Container Apps Scaling Patterns

## HTTP-based Scaling

Best for APIs and web applications:

```bicep
scale: {
  minReplicas: 1
  maxReplicas: 10
  rules: [
    {
      name: 'http-scaling'
      http: {
        metadata: {
          concurrentRequests: '100'
        }
      }
    }
  ]
}
```

## Queue-based Scaling

Best for background workers:

```bicep
scale: {
  minReplicas: 0
  maxReplicas: 30
  rules: [
    {
      name: 'queue-scaling'
      azureQueue: {
        queueName: 'orders'
        queueLength: 10
        auth: [
          {
            secretRef: 'storage-connection'
            triggerParameter: 'connection'
          }
        ]
      }
    }
  ]
}
```

## Service Bus Scaling

```bicep
scale: {
  minReplicas: 0
  maxReplicas: 20
  rules: [
    {
      name: 'servicebus-scaling'
      custom: {
        type: 'azure-servicebus'
        metadata: {
          queueName: 'myqueue'
          messageCount: '5'
        }
        auth: [
          {
            secretRef: 'servicebus-connection'
            triggerParameter: 'connection'
          }
        ]
      }
    }
  ]
}
```

## Recommendations

| Workload | Min Replicas | Max Replicas | Rule Type |
|----------|--------------|--------------|-----------|
| Production API | 1 | 10-20 | HTTP |
| Dev/Test API | 0 | 5 | HTTP |
| Background Worker | 0 | 30+ | Queue/Event |
| Scheduled Job | 0 | 1 | KEDA cron |

# Container Apps Terraform Patterns

> **⚠️ Container Registry Naming:** ACR names must be alphanumeric only (5-50 characters). Use Terraform's `replace()` function when constructing the value passed to `azurecaf_name`, or otherwise strip hyphens manually.

> **⚠️ Two-Phase Deployment (Mandatory):** To avoid the chicken-and-egg problem where Terraform tries to create a Container App referencing an ACR image that doesn't exist yet:
> - **Phase 1 (`terraform apply`):** Deploy ACR and Container App with a **public placeholder image** and **no `registry` block**.
> - **Phase 2 (post-apply CLI):** Build/push the app image to ACR, configure the registry/identity link, then update the Container App image.
>
> This mirrors the [Bicep two-phase pattern](bicep.md). Without it, `terraform apply` fails with `ContainerAppOperationError` because the image doesn't exist in ACR yet.

> **⚠️ ACR Authentication — Managed Identity Only:** Do **not** use `admin_enabled = true` on `azurerm_container_registry` or add a `registry` block with `username`/`password_secret_name` to the Container App. Admin credentials are a security risk and leak secrets into Terraform state. Always use **managed identity** with an `AcrPull` role assignment, and configure the registry link via `az containerapp registry set --identity system` in Phase 2.

## Phase 1: Container App Resource (No Registry Block)

```hcl
# Placeholder image allows provisioning before the app image exists in ACR.
# No registry block in Terraform during Phase 1 — the registry/identity link is
# configured via CLI after provisioning (see Phase 2 below).
# Do NOT add a registry block with username/password_secret_name — use managed identity.
resource "azurerm_container_app" "api" {
  name                         = azurecaf_name.container_app.result
  container_app_environment_id = azurerm_container_app_environment.env.id
  resource_group_name          = azurerm_resource_group.rg.name
  revision_mode                = "Single"

  identity {
    type = "SystemAssigned"
  }

  tags = merge(var.tags, {
    "azd-service-name" = "api"
  })

  template {
    min_replicas = 1
    max_replicas = 3

    container {
      name   = "api"
      image  = "mcr.microsoft.com/azuredocs/containerapps-helloworld:latest"
      cpu    = 0.25
      memory = "0.5Gi"
    }
  }

  ingress {
    external_enabled = true
    target_port      = 8080

    traffic_weight {
      latest_revision = true
      percentage      = 100
    }
  }

  # Phase 2 updates the image and configures the registry/identity link via CLI.
  # Prevent Terraform from reverting those changes on subsequent applies.
  # Do NOT add a registry block here — use `az containerapp registry set --identity system`.
  lifecycle {
    ignore_changes = [
      template[0].container[0].image,
      registry,
    ]
  }
}
```

## AcrPull Role Assignment

Deploy the `AcrPull` role assignment as a **separate resource** that depends on the Container App (to read its system-assigned identity principal ID). Neither the ACR nor the Container App depends on this resource, so there is no circular dependency.

```hcl
resource "azurerm_role_assignment" "api_acr_pull" {
  scope                = azurerm_container_registry.acr.id
  role_definition_name = "AcrPull"
  principal_id         = azurerm_container_app.api.identity[0].principal_id
  principal_type       = "ServicePrincipal"
}
```

> 💡 **Tip:** Always set `principal_type = "ServicePrincipal"` for managed identities. This skips the Graph API lookup and speeds up role assignment propagation.

## Phase 2: Post-Apply Deployment (CLI)

After `terraform apply` succeeds, run these commands to build the real image and switch the Container App to it:

```bash
ACR_NAME=$(terraform output -raw acr_name)
ACR_SERVER=$(terraform output -raw acr_login_server)
APP_NAME=$(terraform output -raw container_app_name)
RG_NAME=$(terraform output -raw resource_group_name)

# 1. Build and push the application image to ACR
az acr build --registry $ACR_NAME --image myapp:latest ./src/api

# 2. Configure the registry/identity link (managed identity, no passwords)
az containerapp registry set \
  --name $APP_NAME \
  --resource-group $RG_NAME \
  --server $ACR_SERVER \
  --identity system

# 3. Update the Container App to use the real image
az containerapp update \
  --name $APP_NAME \
  --resource-group $RG_NAME \
  --image $ACR_SERVER/myapp:latest
```

**PowerShell:**
```powershell
$AcrName = terraform output -raw acr_name
$AcrServer = terraform output -raw acr_login_server
$AppName = terraform output -raw container_app_name
$RgName = terraform output -raw resource_group_name

# 1. Build and push the application image to ACR
az acr build --registry $AcrName --image myapp:latest ./src/api

# 2. Configure the registry/identity link (managed identity, no passwords)
az containerapp registry set `
  --name $AppName `
  --resource-group $RgName `
  --server $AcrServer `
  --identity system

# 3. Update the Container App to use the real image
az containerapp update `
  --name $AppName `
  --resource-group $RgName `
  --image "$AcrServer/myapp:latest"
```

> ⚠️ **Warning:** Step 2 requires the `AcrPull` role assignment to have propagated (1–5 minutes after `terraform apply`). If the image pull fails, wait and retry. See the **azure-deploy** skill's `references/pre-deploy-checklist.md` (Container Apps + ACR pre-deploy RBAC health check).

## Terraform Outputs

Export the values needed by Phase 2:

```hcl
output "acr_name" {
  value = azurerm_container_registry.acr.name
}

output "acr_login_server" {
  value = azurerm_container_registry.acr.login_server
}

output "container_app_name" {
  value = azurerm_container_app.api.name
}

output "resource_group_name" {
  value = azurerm_resource_group.rg.name
}

output "api_url" {
  value = "https://${azurerm_container_app.api.ingress[0].fqdn}"
}
```

## Container Apps Environment

```hcl
resource "azurerm_container_app_environment" "env" {
  name                       = azurecaf_name.container_app_env.result
  location                   = azurerm_resource_group.rg.location
  resource_group_name        = azurerm_resource_group.rg.name
  log_analytics_workspace_id = azurerm_log_analytics_workspace.logs.id
}
```

# Cosmos DB Bicep Patterns

## Account

```bicep
resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
  name: '${resourcePrefix}-cosmos-${uniqueHash}'
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
        failoverPriority: 0
        isZoneRedundant: false
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    capabilities: [
      {
        name: 'EnableServerless'
      }
    ]
  }
}
```

## Database

```bicep
resource cosmosDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2023-04-15' = {
  parent: cosmosAccount
  name: 'appdb'
  properties: {
    resource: {
      id: 'appdb'
    }
  }
}
```

## Container

```bicep
resource cosmosContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2023-04-15' = {
  parent: cosmosDatabase
  name: 'items'
  properties: {
    resource: {
      id: 'items'
      partitionKey: {
        paths: ['/partitionKey']
        kind: 'Hash'
      }
      indexingPolicy: {
        indexingMode: 'consistent'
        includedPaths: [
          { path: '/*' }
        ]
      }
    }
  }
}
```

## Autoscale Container

```bicep
resource cosmosContainer 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2023-04-15' = {
  parent: cosmosDatabase
  name: 'items'
  properties: {
    resource: {
      id: 'items'
      partitionKey: {
        paths: ['/partitionKey']
        kind: 'Hash'
      }
    }
    options: {
      autoscaleSettings: {
        maxThroughput: 4000
      }
    }
  }
}
```

## Global Distribution

```bicep
properties: {
  locations: [
    {
      locationName: 'East US'
      failoverPriority: 0
    }
    {
      locationName: 'West US'
      failoverPriority: 1
    }
  ]
  enableMultipleWriteLocations: true
}
```

# Cosmos DB Partition Key Selection

## Good Partition Keys

A good partition key should have:

- **High cardinality** - Many distinct values
- **Even data distribution** - No hot partitions
- **Even request distribution** - Balanced workload
- **Used in most queries** - Enables efficient routing

## Examples by Scenario

| Scenario | Partition Key | Reason |
|----------|---------------|--------|
| User-centric data | `/userId` | Queries typically filter by user |
| Multi-tenant apps | `/tenantId` | Isolates tenant data |
| E-commerce orders | `/customerId` | Orders queried by customer |
| IoT telemetry | `/deviceId` | High cardinality, even distribution |

## Hierarchical Partition Keys

For complex scenarios, use hierarchical keys:

```bicep
partitionKey: {
  paths: ['/tenantId', '/userId']
  kind: 'MultiHash'
}
```

## Anti-Patterns

Avoid these partition key choices:

| Bad Choice | Problem |
|------------|---------|
| Timestamp | Creates hot partitions |
| Boolean values | Only 2 partitions |
| Low cardinality enums | Uneven distribution |
| Random GUID | Can't query efficiently |

# Azure Cosmos DB

Globally distributed, multi-model database for low-latency data at scale.

## When to Use

- Global distribution requirements
- Multi-model data (document, graph, key-value)
- Variable and unpredictable throughput
- Low-latency reads/writes at scale
- Flexible schema requirements

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Cosmos DB is fully managed |
| Key Vault | Store connection strings (recommended) |

## Capacity Modes

| Mode | Use Case | Billing |
|------|----------|---------|
| **Serverless** | Variable/low traffic, dev/test | Per request |
| **Provisioned** | Predictable workloads | Per RU/s |
| **Autoscale** | Variable but predictable peaks | Per max RU/s |

## Consistency Levels

| Level | Latency | Consistency |
|-------|---------|-------------|
| Strong | Highest | Linearizable |
| Bounded Staleness | High | Bounded |
| Session | Medium | Session-scoped |
| Consistent Prefix | Low | Prefix ordering |
| Eventual | Lowest | Eventually consistent |

Recommendation: Use **Session** for most applications.

## Environment Variables

| Variable | Value |
|----------|-------|
| `COSMOS_CONNECTION_STRING` | Primary connection string (Key Vault reference) |
| `COSMOS_ENDPOINT` | Account endpoint URL |
| `COSMOS_DATABASE` | Database name |

## References

- [Bicep Patterns](bicep.md)
- [Partition Key Selection](partitioning.md)
- [SDK Connection Patterns](sdk.md)

# Cosmos DB SDK Connection Patterns

## Node.js

```javascript
const { CosmosClient } = require("@azure/cosmos");

const client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);
const database = client.database("appdb");
const container = database.container("items");

// Query example
const { resources } = await container.items
  .query("SELECT * FROM c WHERE c.userId = @userId", {
    parameters: [{ name: "@userId", value: userId }]
  })
  .fetchAll();
```

## Python

```python
from azure.cosmos import CosmosClient
import os

client = CosmosClient.from_connection_string(os.environ["COSMOS_CONNECTION_STRING"])
database = client.get_database_client("appdb")
container = database.get_container_client("items")

# Query example
items = container.query_items(
    query="SELECT * FROM c WHERE c.userId = @userId",
    parameters=[{"name": "@userId", "value": user_id}]
)
```

## .NET

```csharp
using Microsoft.Azure.Cosmos;

var client = new CosmosClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
var database = client.GetDatabase("appdb");
var container = database.GetContainer("items");

// Query example
var query = new QueryDefinition("SELECT * FROM c WHERE c.userId = @userId")
    .WithParameter("@userId", userId);
var iterator = container.GetItemQueryIterator<dynamic>(query);
```

## Best Practices

| Practice | Reason |
|----------|--------|
| Reuse client instances | Connection pooling |
| Use parameterized queries | SQL injection prevention |
| Set appropriate timeouts | Handle transient failures |
| Enable diagnostics in dev | Debug RU consumption |

# Durable Task Scheduler — Bicep Patterns

Bicep templates for provisioning the Durable Task Scheduler, task hubs, and RBAC role assignments.

## Scheduler + Task Hub

```bicep
// Parameters — define these at file level or pass from a parent module
param schedulerName string
param location string = resourceGroup().location

@allowed(['Consumption', 'Dedicated'])
@description('Use Consumption for quickstarts/variable workloads, Dedicated for high-demand/predictable throughput')
param skuName string = 'Consumption'

resource scheduler 'Microsoft.DurableTask/schedulers@2025-11-01' = {
  name: schedulerName
  location: location
  properties: {
    sku: { name: skuName }
    ipAllowlist: ['0.0.0.0/0'] // Required: empty list denies all traffic
  }
}

resource taskHub 'Microsoft.DurableTask/schedulers/taskHubs@2025-11-01' = {
  parent: scheduler
  name: 'default'
}
```

## SKU Selection

| SKU | Best For |
|-----|----------|
| **Consumption** | quickstarts, variable or bursty workloads, pay-per-use |
| **Dedicated** | High-demand workloads, predictable throughput requirements |

> **💡 TIP**: Start with `Consumption` for development and variable workloads. Switch to `Dedicated` when you need consistent, high-throughput performance.

> **⚠️ WARNING**: The scheduler's `ipAllowlist` **must** include at least one entry (e.g., `['0.0.0.0/0']` for allow-all). An empty array `[]` denies **all** traffic, causing 403 errors on gRPC calls even with correct RBAC.

## RBAC — Durable Task Data Contributor

The Function App's managed identity **must** have the `Durable Task Data Contributor` role on the scheduler resource. Without it, the app receives **403 PermissionDenied** on gRPC calls.

```bicep
// Assumes the UAMI principal ID is passed from the base template's identity module
param functionAppPrincipalId string

var durableTaskDataContributorRoleId = '0ad04412-c4d5-4796-b79c-f76d14c8d402'

resource durableTaskRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(scheduler.id, functionAppPrincipalId, durableTaskDataContributorRoleId)
  scope: scheduler
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', durableTaskDataContributorRoleId)
    principalId: functionAppPrincipalId
    principalType: 'ServicePrincipal'
  }
}
```

## RBAC — Dashboard Access for Developers

To allow developers to view orchestration status and history in the [DTS dashboard](https://portal.azure.com), assign the same `Durable Task Data Contributor` role to the deploying user's identity. Without this, the dashboard returns **403 Forbidden**.

```bicep
// Accept the deploying user's principal ID (azd auto-populates this from AZURE_PRINCIPAL_ID)
param principalId string = ''

resource dashboardRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (!empty(principalId)) {
  name: guid(scheduler.id, principalId, durableTaskDataContributorRoleId)
  scope: scheduler
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', durableTaskDataContributorRoleId)
    principalId: principalId
    principalType: 'User'
  }
}
```

> **💡 TIP**: This is the same role used for the Function App's managed identity, but assigned with `principalType: 'User'` to the developer. See the [sample repo](https://github.com/Azure-Samples/Durable-Task-Scheduler/blob/main/samples/infra/main.bicep) for a full example.

## Connection String App Setting

Include these entries in the Function App resource's `siteConfig.appSettings` array:

```bicep
// UAMI client ID from base template identity module - REQUIRED for UAMI auth
param uamiClientId string

{
  name: 'DURABLE_TASK_SCHEDULER_CONNECTION_STRING'
  value: 'Endpoint=${scheduler.properties.endpoint};TaskHub=${taskHub.name};Authentication=ManagedIdentity;ClientID=${uamiClientId}'
}
```

> **⚠️ IMPORTANT**: The base templates use User Assigned Managed Identity (UAMI). You **must** include `ClientID=<uami-client-id>` in the connection string. Without it, the Durable Task SDK cannot resolve the correct identity.

> **⚠️ WARNING**: Always use `scheduler.properties.endpoint` to get the scheduler URL. Do **not** construct it manually — the endpoint includes a hash suffix and region (e.g., `https://myscheduler-abc123.westus2.durabletask.io`).

## Provision via CLI

> **💡 TIP**: When hosting Durable Functions, use a **Flex Consumption** plan (`FC1` SKU) rather than the legacy Consumption plan (`Y1`). Flex Consumption supports identity-based storage connections natively and handles deployment artifacts correctly.

```bash
# Install the durabletask CLI extension (if not already installed)
az extension add --name durabletask

# Create scheduler (consumption SKU for getting started)
az durabletask scheduler create \
    --resource-group myResourceGroup \
    --name my-scheduler \
    --location eastus \
    --sku consumption
```

# Durable Task Scheduler — .NET

## Learn More

- [Durable Task Scheduler documentation](https://learn.microsoft.com/azure/durable-task-scheduler/)
- [Durable Functions .NET isolated worker guide](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-dotnet-isolated-overview)

## Durable Functions Setup

### Required NuGet Packages

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.14.1" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.4.0" />
  <PackageReference Include="Azure.Identity" Version="1.17.1" />
</ItemGroup>
```

> **💡 Finding latest versions**: Search [nuget.org](https://www.nuget.org/) for each package name to find the current stable version. Look for the `Microsoft.Azure.Functions.Worker.Extensions.DurableTask` and `Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged` packages.

### host.json

```json
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      },
      "hubName": "default"
    }
  }
}
```

> **💡 NOTE**: .NET isolated uses the `DurableTask.AzureManaged` NuGet package, which registers the `azureManaged` storage provider type. Other runtimes (Python, Java, JavaScript) use extension bundles and require `durabletask-scheduler` instead — see the respective language files. All runtimes use the same `DURABLE_TASK_SCHEDULER_CONNECTION_STRING` environment variable.

### local.settings.json

```json
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}
```

## Minimal Example

```csharp
using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;
using Microsoft.DurableTask.Client;

public static class DurableFunctionsApp
{
    [Function("HttpStart")]
    public static async Task<HttpResponseData> HttpStart(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req,
        [DurableClient] DurableTaskClient client)
    {
        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(nameof(MyOrchestration));
        return await client.CreateCheckStatusResponseAsync(req, instanceId);
    }

    [Function(nameof(MyOrchestration))]
    public static async Task<string> MyOrchestration([OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var result1 = await context.CallActivityAsync<string>(nameof(SayHello), "Tokyo");
        var result2 = await context.CallActivityAsync<string>(nameof(SayHello), "Seattle");
        return $"{result1}, {result2}";
    }

    [Function(nameof(SayHello))]
    public static string SayHello([ActivityTrigger] string name) => $"Hello {name}!";
}
```

## Workflow Patterns

### Fan-Out/Fan-In

```csharp
[Function(nameof(FanOutFanIn))]
public static async Task<string[]> FanOutFanIn([OrchestrationTrigger] TaskOrchestrationContext context)
{
    string[] cities = { "Tokyo", "Seattle", "London", "Paris", "Berlin" };

    // Fan-out: schedule all in parallel
    var tasks = cities.Select(city => context.CallActivityAsync<string>(nameof(SayHello), city));

    // Fan-in: wait for all
    return await Task.WhenAll(tasks);
}
```

### Human Interaction

```csharp
[Function(nameof(ApprovalWorkflow))]
public static async Task<string> ApprovalWorkflow([OrchestrationTrigger] TaskOrchestrationContext context)
{
    await context.CallActivityAsync(nameof(SendApprovalRequest), context.GetInput<string>());
    
    // Wait for approval event with timeout
    using var cts = new CancellationTokenSource();
    var approvalTask = context.WaitForExternalEvent<bool>("ApprovalEvent");
    var timeoutTask = context.CreateTimer(context.CurrentUtcDateTime.AddDays(3), cts.Token);
    
    var winner = await Task.WhenAny(approvalTask, timeoutTask);
    
    if (winner == approvalTask)
    {
        cts.Cancel();
        return await approvalTask ? "Approved" : "Rejected";
    }
    return "Timed out";
}
```

## Orchestration Determinism

| ❌ NEVER | ✅ ALWAYS USE |
|----------|--------------|
| `DateTime.Now` | `context.CurrentUtcDateTime` |
| `Guid.NewGuid()` | `context.NewGuid()` |
| `Random` | Pass random values from activities |
| `Task.Delay()`, `Thread.Sleep()` | `context.CreateTimer()` |
| Direct I/O, HTTP, database | `context.CallActivityAsync()` |

### Replay-Safe Logging

```csharp
[Function(nameof(MyOrchestration))]
public static async Task<string> MyOrchestration([OrchestrationTrigger] TaskOrchestrationContext context)
{
    ILogger logger = context.CreateReplaySafeLogger(nameof(MyOrchestration));
    logger.LogInformation("Started");  // Only logs once, not on replay
    return await context.CallActivityAsync<string>(nameof(MyActivity), "input");
}
```

## Error Handling & Retry

```csharp
var retryOptions = new TaskOptions
{
    Retry = new RetryPolicy(
        maxNumberOfAttempts: 3,
        firstRetryInterval: TimeSpan.FromSeconds(5),
        backoffCoefficient: 2.0,
        maxRetryInterval: TimeSpan.FromMinutes(1))
};

var input = context.GetInput<string>();

try
{
    await context.CallActivityAsync<string>(nameof(UnreliableService), input, retryOptions);
}
catch (TaskFailedException ex)
{
    context.SetCustomStatus(new { Error = ex.Message });
    await context.CallActivityAsync(nameof(CompensationActivity), input);
}
```

## Durable Task SDK (Non-Functions)

For applications running outside Azure Functions (containers, VMs, Azure Container Apps, Azure Kubernetes Service):

```csharp
var connectionString = "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";

// Worker
builder.Services.AddDurableTaskWorker()
    .AddTasks(registry => registry.AddAllGeneratedTasks())
    .UseDurableTaskScheduler(connectionString);

// Client
var client = DurableTaskClientBuilder.UseDurableTaskScheduler(connectionString).Build();
string instanceId = await client.ScheduleNewOrchestrationInstanceAsync("MyOrchestration", input);
```

# Durable Task Scheduler — Java

## Learn More

- [Durable Task Scheduler documentation](https://learn.microsoft.com/azure/durable-task-scheduler/)
- [Durable Functions Java guide](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=java)

## Durable Functions Setup

### Required Maven Dependencies

```xml
<dependencies>
  <dependency>
    <groupId>com.microsoft.azure.functions</groupId>
    <artifactId>azure-functions-java-library</artifactId>
    <version>3.2.3</version>
  </dependency>
  <dependency>
    <groupId>com.microsoft</groupId>
    <artifactId>durabletask-azure-functions</artifactId>
    <version>1.7.0</version>
  </dependency>
</dependencies>
```

> **💡 Finding latest versions**: Search [Maven Central](https://central.sonatype.com/) for `durabletask-azure-functions` (group: `com.microsoft`) to find the current stable version.

### host.json

```json
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "durabletask-scheduler",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}
```

### local.settings.json

```json
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "java",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}
```

## Minimal Example

```java
import com.microsoft.azure.functions.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.durabletask.*;
import com.microsoft.durabletask.azurefunctions.*;

public class DurableFunctionsApp {

    @FunctionName("HttpStart")
    public HttpResponseMessage httpStart(
            @HttpTrigger(name = "req", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION)
            HttpRequestMessage<Void> request,
            @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
        DurableTaskClient client = durableContext.getClient();
        String instanceId = client.scheduleNewOrchestrationInstance("MyOrchestration");
        return durableContext.createCheckStatusResponse(request, instanceId);
    }

    @FunctionName("MyOrchestration")
    public String myOrchestration(
            @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
        String result1 = ctx.callActivity("SayHello", "Tokyo", String.class).await();
        String result2 = ctx.callActivity("SayHello", "Seattle", String.class).await();
        return result1 + ", " + result2;
    }

    @FunctionName("SayHello")
    public String sayHello(@DurableActivityTrigger(name = "name") String name) {
        return "Hello " + name + "!";
    }
}
```

## Workflow Patterns

### Fan-Out/Fan-In

```java
@FunctionName("FanOutFanIn")
public List<String> fanOutFanIn(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String[] cities = {"Tokyo", "Seattle", "London", "Paris", "Berlin"};
    List<Task<String>> parallelTasks = new ArrayList<>();

    // Fan-out: schedule all activities in parallel
    for (String city : cities) {
        parallelTasks.add(ctx.callActivity("SayHello", city, String.class));
    }

    // Fan-in: wait for all to complete
    List<String> results = new ArrayList<>();
    for (Task<String> task : parallelTasks) {
        results.add(task.await());
    }

    return results;
}
```

### Human Interaction

```java
@FunctionName("ApprovalWorkflow")
public String approvalWorkflow(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    ctx.callActivity("SendApprovalRequest", ctx.getInput(String.class)).await();

    // Wait for approval event with timeout
    Task<Boolean> approvalTask = ctx.waitForExternalEvent("ApprovalEvent", Boolean.class);
    Task<Void> timeoutTask = ctx.createTimer(Duration.ofDays(3));

    Task<?> winner = ctx.anyOf(approvalTask, timeoutTask).await();

    if (winner == approvalTask) {
        return approvalTask.await() ? "Approved" : "Rejected";
    }
    return "Timed out";
}
```

## Orchestration Determinism

| ❌ NEVER | ✅ ALWAYS USE |
|----------|--------------|
| `System.currentTimeMillis()` | `ctx.getCurrentInstant()` |
| `UUID.randomUUID()` | Pass random values from activities |
| `Thread.sleep()` | `ctx.createTimer()` |
| Direct I/O, HTTP, database | `ctx.callActivity()` |

### Replay-Safe Logging

```java
private static final java.util.logging.Logger logger =
    java.util.logging.Logger.getLogger("MyOrchestration");

@FunctionName("MyOrchestration")
public String myOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    // Use isReplaying to avoid duplicate logs
    if (!ctx.getIsReplaying()) {
        logger.info("Started");  // Only logs once, not on replay
    }
    return ctx.callActivity("MyActivity", "input", String.class).await();
}
```

## Error Handling & Retry

```java
@FunctionName("WorkflowWithRetry")
public String workflowWithRetry(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    TaskOptions retryOptions = new TaskOptions(new RetryPolicy(
        3,  // maxNumberOfAttempts
        Duration.ofSeconds(5)  // firstRetryInterval
    ));

    try {
        return ctx.callActivity("UnreliableService", ctx.getInput(String.class),
                retryOptions, String.class).await();
    } catch (TaskFailedException ex) {
        ctx.setCustomStatus(Map.of("Error", ex.getMessage()));
        ctx.callActivity("CompensationActivity", ctx.getInput(String.class)).await();
        return "Compensated";
    }
}
```

## Durable Task SDK (Non-Functions)

For applications running outside Azure Functions (containers, VMs, Azure Container Apps, Azure Kubernetes Service):

```java
import com.microsoft.durabletask.*;
import com.microsoft.durabletask.azuremanaged.DurableTaskSchedulerWorkerExtensions;
import com.microsoft.durabletask.azuremanaged.DurableTaskSchedulerClientExtensions;

import java.time.Duration;

public class App {
    public static void main(String[] args) throws Exception {
        String connectionString = "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";

        // Worker
        DurableTaskGrpcWorker worker = DurableTaskSchedulerWorkerExtensions
            .createWorkerBuilder(connectionString)
            .addOrchestration(new TaskOrchestrationFactory() {
                @Override public String getName() { return "MyOrchestration"; }
                @Override public TaskOrchestration create() {
                    return ctx -> {
                        String result = ctx.callActivity("SayHello",
                                ctx.getInput(String.class), String.class).await();
                        ctx.complete(result);
                    };
                }
            })
            .addActivity(new TaskActivityFactory() {
                @Override public String getName() { return "SayHello"; }
                @Override public TaskActivity create() {
                    return ctx -> "Hello " + ctx.getInput(String.class) + "!";
                }
            })
            .build();

        worker.start();

        // Client
        DurableTaskClient client = DurableTaskSchedulerClientExtensions
            .createClientBuilder(connectionString).build();
        String instanceId = client.scheduleNewOrchestrationInstance("MyOrchestration", "World");
        OrchestrationMetadata result = client.waitForInstanceCompletion(
                instanceId, Duration.ofSeconds(30), true);
        System.out.println("Output: " + result.readOutputAs(String.class));

        worker.stop();
    }
}
```

# Durable Task Scheduler — JavaScript

## Learn More

- [Durable Task Scheduler documentation](https://learn.microsoft.com/azure/durable-task-scheduler/)
- [Durable Functions JavaScript guide](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=javascript)

## Durable Functions Setup

### Required npm Packages

```json
{
  "dependencies": {
    "@azure/functions": "^4.0.0",
    "durable-functions": "^3.0.0"
  }
}
```

> **💡 Finding latest versions**: Run `npm view durable-functions version` or check [npmjs.com/package/durable-functions](https://www.npmjs.com/package/durable-functions) for the latest stable release.

### host.json

```json
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "durabletask-scheduler",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}
```

### local.settings.json

```json
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}
```

## Minimal Example

```javascript
const { app } = require("@azure/functions");
const df = require("durable-functions");

// Activity
df.app.activity("sayHello", {
  handler: (city) => `Hello ${city}!`,
});

// Orchestrator
df.app.orchestration("myOrchestration", function* (context) {
  const result1 = yield context.df.callActivity("sayHello", "Tokyo");
  const result2 = yield context.df.callActivity("sayHello", "Seattle");
  return `${result1}, ${result2}`;
});

// HTTP Starter
app.http("HttpStart", {
  route: "orchestrators/{orchestrationName}",
  methods: ["POST"],
  authLevel: "function",
  extraInputs: [df.input.durableClient()],
  handler: async (request, context) => {
    const client = df.getClient(context);
    const instanceId = await client.startNew(request.params.orchestrationName);
    return client.createCheckStatusResponse(request, instanceId);
  },
});
```

## Workflow Patterns

### Fan-Out/Fan-In

```javascript
df.app.orchestration("fanOutFanIn", function* (context) {
  const cities = ["Tokyo", "Seattle", "London", "Paris", "Berlin"];

  // Fan-out: schedule all activities in parallel
  const tasks = cities.map((city) => context.df.callActivity("sayHello", city));

  // Fan-in: wait for all to complete
  const results = yield context.df.Task.all(tasks);
  return results;
});
```

### Human Interaction

```javascript
df.app.orchestration("approvalWorkflow", function* (context) {
  yield context.df.callActivity("sendApprovalRequest", context.df.getInput());

  // Wait for approval event with timeout
  const expiration = new Date(context.df.currentUtcDateTime);
  expiration.setDate(expiration.getDate() + 3);

  const approvalTask = context.df.waitForExternalEvent("ApprovalEvent");
  const timeoutTask = context.df.createTimer(expiration);

  const winner = yield context.df.Task.any([approvalTask, timeoutTask]);

  if (winner === approvalTask) {
    return approvalTask.result ? "Approved" : "Rejected";
  }
  return "Timed out";
});
```

## Orchestration Determinism

| ❌ NEVER | ✅ ALWAYS USE |
|----------|--------------|
| `new Date()` | `context.df.currentUtcDateTime` |
| `Math.random()` | Pass random values from activities |
| `setTimeout()` | `context.df.createTimer()` |
| Direct I/O, HTTP, database | `context.df.callActivity()` |

### Replay-Safe Logging

```javascript
df.app.orchestration("myOrchestration", function* (context) {
  if (!context.df.isReplaying) {
    console.log("Started");  // Only logs once, not on replay
  }
  const result = yield context.df.callActivity("myActivity", "input");
  return result;
});
```

## Error Handling & Retry

```javascript
df.app.orchestration("workflowWithRetry", function* (context) {
  const retryOptions = new df.RetryOptions(5000, 3); // firstRetryInterval, maxAttempts
  retryOptions.backoffCoefficient = 2.0;
  retryOptions.maxRetryIntervalInMilliseconds = 60000;

  try {
    const result = yield context.df.callActivityWithRetry(
      "unreliableService",
      retryOptions,
      context.df.getInput()
    );
    return result;
  } catch (ex) {
    context.df.setCustomStatus({ error: ex.message });
    yield context.df.callActivity("compensationActivity", context.df.getInput());
    return "Compensated";
  }
});
```

## Durable Task SDK (Non-Functions)

For applications running outside Azure Functions (containers, VMs, Azure Container Apps, Azure Kubernetes Service):

```javascript
const { createAzureManagedWorkerBuilder, createAzureManagedClient } = require("@microsoft/durabletask-js-azuremanaged");

const connectionString = "Endpoint=http://localhost:8080;Authentication=None;TaskHub=default";

// Activity
const sayHello = async (_ctx, name) => `Hello ${name}!`;

// Orchestrator
const myOrchestration = async function* (ctx, name) {
  const result = yield ctx.callActivity(sayHello, name);
  return result;
};

async function main() {
  // Worker
  const worker = createAzureManagedWorkerBuilder(connectionString)
    .addOrchestrator(myOrchestration)
    .addActivity(sayHello)
    .build();

  await worker.start();

  // Client
  const client = createAzureManagedClient(connectionString);
  const instanceId = await client.scheduleNewOrchestration("myOrchestration", "World");
  const state = await client.waitForOrchestrationCompletion(instanceId, true, 30);
  console.log("Output:", state.serializedOutput);

  await client.stop();
  await worker.stop();
}

main().catch(console.error);
```

# Durable Task Scheduler — Python

## Learn More

- [Durable Task Scheduler documentation](https://learn.microsoft.com/azure/durable-task-scheduler/)
- [Durable Functions Python guide](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview?tabs=python)

## Durable Functions Setup

### Required Packages

```txt
# requirements.txt
azure-functions
azure-functions-durable
azure-identity
```

> **💡 Finding latest versions**: Run `pip index versions azure-functions-durable` or check [pypi.org/project/azure-functions-durable](https://pypi.org/project/azure-functions-durable/) for the latest stable release.

### host.json

```json
{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "hubName": "default",
      "storageProvider": {
        "type": "durabletask-scheduler",
        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}
```

> **💡 NOTE**: Python uses extension bundles, so the storage provider type is `durabletask-scheduler`. .NET isolated uses the NuGet package directly and requires `azureManaged` instead — see [dotnet.md](dotnet.md).

### local.settings.json

```json
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
  }
}
```

## Minimal Example

```python
import azure.functions as func
import azure.durable_functions as df

my_app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

# HTTP Starter
@my_app.route(route="orchestrators/{function_name}", methods=["POST"])
@my_app.durable_client_input(client_name="client")
async def http_start(req: func.HttpRequest, client):
    function_name = req.route_params.get('function_name')
    instance_id = await client.start_new(function_name)
    return client.create_check_status_response(req, instance_id)

# Orchestrator
@my_app.orchestration_trigger(context_name="context")
def my_orchestration(context: df.DurableOrchestrationContext):
    result1 = yield context.call_activity("say_hello", "Tokyo")
    result2 = yield context.call_activity("say_hello", "Seattle")
    return f"{result1}, {result2}"

# Activity
@my_app.activity_trigger(input_name="name")
def say_hello(name: str) -> str:
    return f"Hello {name}!"
```

## Workflow Patterns

### Fan-Out/Fan-In

```python
@my_app.orchestration_trigger(context_name="context")
def fan_out_fan_in(context: df.DurableOrchestrationContext):
    cities = ["Tokyo", "Seattle", "London", "Paris", "Berlin"]
    
    # Fan-out: schedule all in parallel
    parallel_tasks = []
    for city in cities:
        task = context.call_activity("say_hello", city)
        parallel_tasks.append(task)
    
    # Fan-in: wait for all
    results = yield context.task_all(parallel_tasks)
    return results
```

### Human Interaction

```python
import datetime

@my_app.orchestration_trigger(context_name="context")
def approval_workflow(context: df.DurableOrchestrationContext):
    yield context.call_activity("send_approval_request", context.get_input())
    
    # Wait for approval event with timeout
    timeout = context.current_utc_datetime + datetime.timedelta(days=3)
    approval_task = context.wait_for_external_event("ApprovalEvent")
    timeout_task = context.create_timer(timeout)
    
    winner = yield context.task_any([approval_task, timeout_task])
    
    if winner == approval_task:
        approved = approval_task.result
        return "Approved" if approved else "Rejected"
    return "Timed out"
```

## Orchestration Determinism

| ❌ NEVER | ✅ ALWAYS USE |
|----------|--------------|
| `datetime.now()` | `context.current_utc_datetime` |
| `uuid.uuid4()` | `context.new_uuid()` |
| `random.random()` | Pass random values from activities |
| `time.sleep()` | `context.create_timer()` |
| Direct I/O, HTTP, database | `context.call_activity()` |

### Replay-Safe Logging

```python
import logging

@my_app.orchestration_trigger(context_name="context")
def my_orchestration(context: df.DurableOrchestrationContext):
    # Check if replaying to avoid duplicate logs
    if not context.is_replaying:
        logging.info("Started")  # Only logs once, not on replay
    result = yield context.call_activity("my_activity", "input")
    return result
```

## Error Handling & Retry

```python
retry_options = df.RetryOptions(
    first_retry_interval_in_milliseconds=5000,
    max_number_of_attempts=3,
    backoff_coefficient=2.0,
    max_retry_interval_in_milliseconds=60000
)

@my_app.orchestration_trigger(context_name="context")
def workflow_with_retry(context: df.DurableOrchestrationContext):
    try:
        result = yield context.call_activity_with_retry(
            "unreliable_service", 
            retry_options, 
            context.get_input()
        )
        return result
    except Exception as ex:
        context.set_custom_status({"error": str(ex)})
        yield context.call_activity("compensation_activity", context.get_input())
        return "Compensated"
```

## Durable Task SDK (Non-Functions)

For applications running outside Azure Functions (containers, VMs, Azure Container Apps, Azure Kubernetes Service):

```python
import asyncio
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker

# Activity function
def say_hello(ctx, name: str) -> str:
    return f"Hello {name}!"

# Orchestrator function
def my_orchestration(ctx, name: str) -> str:
    result = yield ctx.call_activity('say_hello', input=name)
    return result

async def main():
    with DurableTaskSchedulerWorker(
        host_address="http://localhost:8080",
        secure_channel=False,
        taskhub="default"
    ) as worker:
        worker.add_activity(say_hello)
        worker.add_orchestrator(my_orchestration)
        worker.start()

        # Client
        from durabletask.azuremanaged.client import DurableTaskSchedulerClient
        client = DurableTaskSchedulerClient(
            host_address="http://localhost:8080",
            taskhub="default",
            token_credential=None,
            secure_channel=False
        )
        instance_id = client.schedule_new_orchestration("my_orchestration", input="World")
        result = client.wait_for_orchestration_completion(instance_id, timeout=30)
        print(f"Output: {result.serialized_output}")

if __name__ == "__main__":
    asyncio.run(main())
```

# Durable Task Scheduler

Build reliable, fault-tolerant workflows using durable execution with Azure Durable Task Scheduler.

## When to Use

- Long-running workflows requiring state persistence
- Distributed transactions with compensating actions (saga pattern)
- Multi-step orchestrations with checkpointing
- Fan-out/fan-in parallel processing
- Workflows requiring human interaction or external events
- Stateful entities (aggregators, counters, state machines)
- Multi-agent AI orchestration
- Data processing pipelines

## Framework Selection

| Framework | Best For | Hosting |
|-----------|----------|---------|
| **Durable Functions** | Serverless event-driven apps | Azure Functions |
| **Durable Task SDKs** | Any compute (containers, VMs) | Azure Container Apps, Azure Kubernetes Service, App Service, VMs |

> **💡 TIP**: Use Durable Functions for serverless with built-in triggers. Use Durable Task SDKs for hosting flexibility.

## Quick Start - Local Emulator

```bash
# Start the emulator (see https://mcr.microsoft.com/v2/dts/dts-emulator/tags/list for available versions)
docker pull mcr.microsoft.com/dts/dts-emulator:latest
docker run -d -p 8080:8080 -p 8082:8082 --name dts-emulator mcr.microsoft.com/dts/dts-emulator:latest

# Dashboard available at http://localhost:8082
```

## Workflow Patterns

| Pattern | Use When |
|---------|----------|
| **Function Chaining** | Sequential steps, each depends on previous |
| **Fan-Out/Fan-In** | Parallel processing with aggregated results |
| **Async HTTP APIs** | Long-running operations with HTTP polling |
| **Monitor** | Periodic polling with configurable timeouts |
| **Human Interaction** | Workflow pauses for external input/approval |
| **Saga** | Distributed transactions with compensation |
| **Durable Entities** | Stateful objects (counters, accounts) |

## Connection & Authentication

| Environment | Connection String |
|-------------|-------------------|
| Local Development (Emulator) | `Endpoint=http://localhost:8080;Authentication=None;TaskHub=default` |
| Azure (System-Assigned MI) | `Endpoint=https://<scheduler>.durabletask.io;Authentication=ManagedIdentity;TaskHub=default` |
| Azure (User-Assigned MI) | `Endpoint=https://<scheduler>.durabletask.io;Authentication=ManagedIdentity;ClientID=<uami-client-id>;TaskHub=default` |

> **⚠️ NOTE**: Durable Task Scheduler uses identity-based authentication only — no connection strings with keys. When using a User-Assigned Managed Identity (UAMI), you must include the `ClientID` in the connection string.

## Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| **403 PermissionDenied** on gRPC call (e.g., `client.start_new()`) | Function App managed identity lacks RBAC on the Durable Task Scheduler resource, or IP allowlist blocks traffic | 1. Assign `Durable Task Data Contributor` role (`0ad04412-c4d5-4796-b79c-f76d14c8d402`) to the identity (SAMI or UAMI) scoped to the Durable Task Scheduler resource. For UAMI, also ensure the connection string includes `ClientID=<uami-client-id>`. 2. Ensure the scheduler's `ipAllowlist` includes `0.0.0.0/0` (an empty list denies all traffic). 3. RBAC propagation can take up to 10 minutes — restart the Function App after assigning roles. |
| **Connection refused** to emulator | Emulator container not running or wrong port | Verify container is running: `docker ps` and confirm port 8080 is mapped |
| **403 despite correct RBAC** | Scheduler IP allowlist is empty (denies all) | Set `ipAllowlist: ['0.0.0.0/0']` in Bicep or update via CLI: `az durabletask scheduler update --ip-allowlist '0.0.0.0/0'` |
| **TaskHub not found** | Task hub not provisioned or name mismatch | Ensure the `TaskHub` parameter in the `DURABLE_TASK_SCHEDULER_CONNECTION_STRING` matches the provisioned task hub name |
| **403 Forbidden** on DTS dashboard | Deploying user lacks RBAC on the scheduler | Assign `Durable Task Data Contributor` role to your own user identity (not just the Function App MI) scoped to the scheduler resource — see [Bicep Patterns](bicep.md) for the dashboard role assignment snippet |

## References

- [.NET](dotnet.md) — packages, setup, examples, determinism, retry, SDK
- [Python](python.md) — packages, setup, examples, determinism, retry, SDK
- [Java](java.md) — dependencies, setup, examples, determinism, retry, SDK
- [JavaScript](javascript.md) — packages, setup, examples, determinism, retry, SDK
- [Bicep Patterns](bicep.md) — scheduler, task hub, RBAC, CLI provisioning
- [Official Documentation](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler)
- [Durable Functions Overview](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview)
- [Sample Repository](https://github.com/Azure-Samples/Durable-Task-Scheduler)
- [Choosing an Orchestration Framework](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/choose-orchestration-framework)

# Event Grid - Bicep Patterns

## Custom Topic

```bicep
resource eventGridTopic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: '${resourcePrefix}-egt-${uniqueHash}'
  location: location
  properties: {
    inputSchema: 'EventGridSchema'
    publicNetworkAccess: 'Enabled'
  }
}
```

## System Topic (Azure Resource Events)

```bicep
resource storageSystemTopic 'Microsoft.EventGrid/systemTopics@2023-12-15-preview' = {
  name: '${resourcePrefix}-storage-topic'
  location: location
  properties: {
    source: storageAccount.id
    topicType: 'Microsoft.Storage.StorageAccounts'
  }
}
```

## Event Domain

```bicep
resource eventDomain 'Microsoft.EventGrid/domains@2023-12-15-preview' = {
  name: '${resourcePrefix}-domain'
  location: location
  properties: {
    inputSchema: 'EventGridSchema'
  }
}
```

## Publishing Events

### Node.js

```javascript
const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  process.env.EVENTGRID_TOPIC_ENDPOINT,
  "EventGrid",
  new AzureKeyCredential(process.env.EVENTGRID_TOPIC_KEY)
);

await client.send([{
  eventType: "Order.Created",
  subject: "/orders/12345",
  dataVersion: "1.0",
  data: { orderId: "12345" }
}]);
```

### Python

```python
from azure.eventgrid import EventGridPublisherClient, EventGridEvent
from azure.core.credentials import AzureKeyCredential

client = EventGridPublisherClient(
    os.environ["EVENTGRID_TOPIC_ENDPOINT"],
    AzureKeyCredential(os.environ["EVENTGRID_TOPIC_KEY"])
)

client.send([EventGridEvent(
    event_type="Order.Created",
    subject="/orders/12345",
    data={"orderId": "12345"},
    data_version="1.0"
)])
```

# Azure Event Grid

Serverless event routing for event-driven architectures.

## When to Use

- Event-driven architectures
- Reactive programming patterns
- Decoupled event routing
- Near real-time event delivery
- Fan-out to multiple subscribers

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Event Grid is serverless |
| Key Vault | Store topic keys |

## Event Sources

| Type | Description |
|------|-------------|
| System Topics | Azure resource events (Storage, Key Vault, etc.) |
| Custom Topics | Your application events |
| Event Domains | Multi-tenant event management |

## Event Schemas

| Schema | Use Case |
|--------|----------|
| Event Grid Schema | Azure native format |
| CloudEvents 1.0 | CNCF standard, cross-platform |

## Environment Variables

| Variable | Value |
|----------|-------|
| `EVENTGRID_TOPIC_ENDPOINT` | Topic endpoint URL |
| `EVENTGRID_TOPIC_KEY` | Topic access key (Key Vault) |

## References

- [Bicep Patterns](bicep.md)
- [Subscriptions](subscriptions.md)

# Event Grid - Subscriptions

## Event Subscription

```bicep
resource eventGridSubscription 'Microsoft.EventGrid/topics/eventSubscriptions@2023-12-15-preview' = {
  parent: eventGridTopic
  name: 'order-processor-subscription'
  properties: {
    destination: {
      endpointType: 'WebHook'
      properties: {
        endpointUrl: 'https://my-api.azurecontainerapps.io/webhooks/orders'
      }
    }
    filter: {
      includedEventTypes: [
        'Order.Created'
        'Order.Updated'
      ]
    }
    retryPolicy: {
      maxDeliveryAttempts: 30
      eventTimeToLiveInMinutes: 1440
    }
  }
}
```

## Destination Types

### Webhook

```bicep
destination: {
  endpointType: 'WebHook'
  properties: {
    endpointUrl: 'https://my-api.example.com/events'
  }
}
```

### Azure Function

```bicep
destination: {
  endpointType: 'AzureFunction'
  properties: {
    resourceId: functionApp.id
  }
}
```

### Service Bus Queue

```bicep
destination: {
  endpointType: 'ServiceBusQueue'
  properties: {
    resourceId: '${serviceBus.id}/queues/events'
  }
}
```

### Event Hub

```bicep
destination: {
  endpointType: 'EventHub'
  properties: {
    resourceId: eventHub.id
  }
}
```

## Filtering

### Event Type Filter

```bicep
filter: {
  includedEventTypes: [
    'Order.Created'
    'Order.Shipped'
  ]
}
```

### Subject Filter

```bicep
filter: {
  subjectBeginsWith: '/orders/priority'
  subjectEndsWith: '.json'
}
```

### Advanced Filter

```bicep
filter: {
  advancedFilters: [
    {
      operatorType: 'NumberGreaterThan'
      key: 'data.amount'
      value: 100
    }
  ]
}
```

# Azure AI Foundry

Azure AI Foundry (formerly Azure OpenAI) for building AI-powered applications with models like GPT-4o, GPT-4, and embeddings.

> **💡 For detailed AI guidance**, invoke the **`microsoft-foundry`** skill. It provides model catalog access, RAG patterns, agent creation, and evaluation workflows.

## When to Use

- Chat and conversational AI applications
- Text generation and completion
- Code generation assistants
- Document analysis and summarization
- Embeddings for search and RAG
- Multi-modal applications (vision + text)

## Service Type in azure.yaml

```yaml
services:
  my-ai-service:
    host: containerapp  # AI services typically deployed via Container Apps
    project: ./src/ai-service
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Azure AI Foundry account | Model hosting |
| Model deployment | Specific model (GPT-4o, GPT-4, etc.) |
| Key Vault | Store API keys securely |
| Application Insights | Monitor usage and costs |

## Model Selection

| Model | Best For | Context Window |
|-------|----------|----------------|
| GPT-4o | General purpose, vision, latest | 128K |
| GPT-4 | Complex reasoning | 32K |
| GPT-3.5-Turbo | Cost-effective, simple tasks | 16K |
| text-embedding-ada-002 | Embeddings for RAG/search | 8K |

## References

- [Region Availability](region-availability.md)

# Foundry Region Availability

⚠️ **Very limited — varies by model**

| Region | GPT-4o | GPT-4 | GPT-3.5 | Embeddings |
|--------|:------:|:-----:|:-------:|:----------:|
| `eastus` | ✅ | ✅ | ✅ | ✅ |
| `eastus2` | ✅ | ✅ | ✅ | ✅ |
| `westus` | ⚠️ | ⚠️ | ✅ | ✅ |
| `westus3` | ✅ | ⚠️ | ✅ | ✅ |
| `southcentralus` | ✅ | ✅ | ✅ | ✅ |
| `swedencentral` | ✅ | ✅ | ✅ | ✅ |
| `westeurope` | ⚠️ | ✅ | ✅ | ✅ |

> Check https://learn.microsoft.com/azure/ai-services/openai/concepts/models for current model availability.

## Recommended Regions

| Need | Recommended Region |
|------|--------------------|
| Full model availability | `eastus`, `eastus2`, `swedencentral` |
| Europe compliance | `swedencentral`, `westeurope` |
| With SWA | `eastus2` (only overlap) |

# Azure Functions on Azure Container Apps (Aspire)

When .NET Aspire deploys Azure Functions via `azd`, Functions run as containerized workloads on Azure Container Apps. **File-based secret storage is required** when using identity-based storage access.

> ⚠️ **Critical:** When Azure Functions use identity-based storage (e.g., `AzureWebJobsStorage__blobServiceUri`), you **must** set `AzureWebJobsSecretStorageType=Files`.

## Proactive Configuration in AppHost

**Best Practice:** Add this setting in your AppHost BEFORE running `azd up`:

```csharp
var functions = builder.AddAzureFunctionsProject<Projects.Functions>("functions")
    .WithHostStorage(storage)
    .WithEnvironment("AzureWebJobsSecretStorageType", "Files")  // Required for Container Apps
    // ... other configuration
```

This ensures the environment variable is automatically included in the generated infrastructure.

## Container Apps Bicep Configuration

When Aspire generates infrastructure, the Functions container app should include this environment variable. If you need to customize the generated Bicep or create it manually, the configuration looks like this:

> **Note:** This example shows partial configuration. Assumes `containerAppEnv`, `storageAccount`, and `appInsights` resources are defined elsewhere in your Bicep templates.

```bicep
resource functionsContainerApp 'Microsoft.App/containerApps@2024-03-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    environmentId: containerAppEnv.id
    configuration: {
      ingress: {
        external: true
        targetPort: 8080
      }
    }
    template: {
      containers: [
        {
          name: 'functions-app'
          image: containerImage
          env: [
            {
              name: 'AzureWebJobsStorage__blobServiceUri'
              value: storageAccount.properties.primaryEndpoints.blob
            }
            {
              name: 'AzureWebJobsSecretStorageType'
              value: 'Files'  // Required for Container Apps with identity-based storage
            }
            {
              name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
              value: appInsights.properties.ConnectionString
            }
            {
              name: 'FUNCTIONS_EXTENSION_VERSION'
              value: '~4'
            }
            {
              name: 'FUNCTIONS_WORKER_RUNTIME'
              value: 'dotnet-isolated'
            }
          ]
        }
      ]
    }
  }
}
```

## Why This Is Required

- Identity-based storage URIs (e.g., `AzureWebJobsStorage__blobServiceUri`) work for runtime operations
- However, Functions' internal secret/key management does not support these identity-based URIs
- File-based secret storage is mandatory for Container Apps deployments with identity-based storage

## Common Error Without This Setting

```
System.InvalidOperationException: Secret initialization from Blob storage failed due to missing both
an Azure Storage connection string and a SAS connection uri.
```

## When to Use This Configuration

- Deploying Azure Functions to Container Apps via .NET Aspire
- Using `AddAzureFunctionsProject` with `WithHostStorage` in your AppHost
- Using identity-based storage access (no connection strings)
- Setting environment variables like `AzureWebJobsStorage__blobServiceUri`

# Functions Bicep Patterns — REFERENCE ONLY

> ⛔ **DO NOT COPY THIS CODE DIRECTLY**
>
> This file contains **reference patterns** for understanding Azure Functions Bicep structure.
> **You MUST use the composition algorithm** to generate infrastructure:
>
> 1. Load `templates/selection.md` to choose the correct base template
> 2. Follow `templates/recipes/composition.md` for the exact algorithm
> 3. Use `functions_template_get` MCP tool to list and fetch templates and write `functionFiles[]` + `projectFiles[]` directly — NEVER hand-write Bicep/Terraform and use `azd init -t <template>`/`func init`/`func new` as fallback when composing multiple recipes and required templates are not found
>
> Hand-writing Bicep from these patterns will result in missing RBAC, incorrect managed identity configuration, and security vulnerabilities.

## Flex Consumption (Recommended)

**Use Flex Consumption for new deployments with managed identity (no connection strings).**

```bicep
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: '${resourcePrefix}func${uniqueHash}'
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
  properties: {
    minimumTlsVersion: 'TLS1_2'
    allowBlobPublicAccess: false
    allowSharedKeyAccess: false  // Enforce managed identity
  }
}

resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-01-01' = {
  parent: storageAccount
  name: 'default'
}

resource deploymentContainer 'Microsoft.Storage/storageAccounts/blobServices/containers@2023-01-01' = {
  parent: blobService
  name: 'deploymentpackage'
}

resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: 'appi-${uniqueHash}'
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
  }
}

resource functionAppPlan 'Microsoft.Web/serverfarms@2024-04-01' = {
  name: 'plan-${uniqueHash}'
  location: location
  sku: {
    name: 'FC1'
    tier: 'FlexConsumption'
  }
  properties: {
    reserved: true
  }
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'functionapp,linux'
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    serverFarmId: functionAppPlan.id
    httpsOnly: true
    functionAppConfig: {
      deployment: {
        storage: {
          type: 'blobContainer'
          value: '${storageAccount.properties.primaryEndpoints.blob}deploymentpackage'
          authentication: {
            type: 'SystemAssignedIdentity'
          }
        }
      }
      scaleAndConcurrency: {
        maximumInstanceCount: 100
        instanceMemoryMB: 2048
      }
      runtime: {
        name: 'python'  // or 'node', 'dotnet-isolated'
        version: '<version>'  // Query latest GA: https://learn.microsoft.com/en-us/azure/azure-functions/supported-languages
      }
    }
    siteConfig: {
      appSettings: [
        {
          name: 'AzureWebJobsStorage__blobServiceUri'
          value: storageAccount.properties.primaryEndpoints.blob
        }
        {
          name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
          value: appInsights.properties.ConnectionString
        }
        {
          name: 'FUNCTIONS_EXTENSION_VERSION'
          value: '~4'
        }
        {
          name: 'FUNCTIONS_WORKER_RUNTIME'
          value: 'python'
        }
      ]
    }
  }
}

// Grant Function App access to Storage for runtime
resource storageRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storageAccount.id, functionApp.id, 'Storage Blob Data Owner')
  scope: storageAccount
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b7e6dc6d-f1e8-4753-8033-0f276bb0955b')
    principalId: functionApp.identity.principalId
    principalType: 'ServicePrincipal'
  }
}
```

> 💡 **Key Points:**
>
> - Use `AzureWebJobsStorage__blobServiceUri` instead of connection string
> - Set `allowSharedKeyAccess: false` for enhanced security
> - Use `SystemAssignedIdentity` for deployment authentication
> - Grant `Storage Blob Data Owner` role for full access to blobs, queues, and tables

## Consumption Plan (Legacy)

> ⛔ **DO NOT USE** — Y1/Dynamic SKU is deprecated for new deployments.
> **ALWAYS use Flex Consumption (FC1)** for all new Azure Functions.
> The Y1 example below is only for reference when migrating legacy apps.

**⚠️ Not recommended for new deployments. Use Flex Consumption instead.**

> 💡 **OS and Slots Matter for Consumption:**
>
> - **Linux Consumption** (`kind: 'functionapp,linux'`, `reserved: true`): Does **not** support deployment slots.
> - **Windows Consumption** (`kind: 'functionapp'`, no `reserved`): Supports **1 staging slot** (2 total including production).
>   If a user specifically needs Windows Consumption with a slot, that is supported — use the Windows pattern below.
>   For new apps needing slots, prefer **Elastic Premium (EP1)** for better performance and no cold-start issues.

### Linux Consumption (no slot support)

```bicep
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: '${resourcePrefix}func${uniqueHash}'
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

resource functionAppPlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-funcplan-${uniqueHash}'
  location: location
  sku: { name: 'Y1', tier: 'Dynamic' }
  properties: { reserved: true }
}

resource functionApp 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'functionapp,linux'
  identity: { type: 'SystemAssigned' }
  properties: {
    serverFarmId: functionAppPlan.id
    httpsOnly: true
    siteConfig: {
      linuxFxVersion: 'Node|24'
      appSettings: [
        { name: 'AzureWebJobsStorage', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'FUNCTIONS_EXTENSION_VERSION', value: '~4' }
        { name: 'FUNCTIONS_WORKER_RUNTIME', value: 'node' }
        { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: appInsights.properties.ConnectionString }
      ]
    }
  }
}
```

### Windows Consumption (supports 1 staging slot)

> ⚠️ **Windows Consumption is not recommended for new projects** — consider Flex Consumption or Elastic Premium.
> Use this pattern only for existing Windows apps or when Windows-specific features are required.

```bicep
resource functionAppPlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-funcplan-${uniqueHash}'
  location: location
  sku: { name: 'Y1', tier: 'Dynamic' }
  // No 'reserved: true' for Windows
}

resource functionApp 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  kind: 'functionapp'  // Windows (no 'linux' suffix)
  identity: { type: 'SystemAssigned' }
  properties: {
    serverFarmId: functionAppPlan.id
    httpsOnly: true
    siteConfig: {
      appSettings: [
        { name: 'WEBSITE_NODE_DEFAULT_VERSION', value: '~20' }
        { name: 'FUNCTIONS_EXTENSION_VERSION', value: '~4' }
        { name: 'FUNCTIONS_WORKER_RUNTIME', value: 'node' }
        { name: 'WEBSITE_CONTENTAZUREFILECONNECTIONSTRING', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'WEBSITE_CONTENTSHARE', value: '${toLower(serviceName)}-prod' }
        { name: 'AzureWebJobsStorage', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: applicationInsights.properties.ConnectionString }
      ]
    }
  }
}

// 1 staging slot is supported on Windows Consumption
resource stagingSlot 'Microsoft.Web/sites/slots@2022-09-01' = {
  parent: functionApp
  name: 'staging'
  location: location
  kind: 'functionapp'
  properties: {
    serverFarmId: functionAppPlan.id
    siteConfig: {
      appSettings: [
        { name: 'WEBSITE_NODE_DEFAULT_VERSION', value: '~20' }
        { name: 'FUNCTIONS_EXTENSION_VERSION', value: '~4' }
        { name: 'FUNCTIONS_WORKER_RUNTIME', value: 'node' }
        { name: 'WEBSITE_CONTENTAZUREFILECONNECTIONSTRING', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'WEBSITE_CONTENTSHARE', value: '${toLower(serviceName)}-staging' }  // MUST differ from production
        { name: 'AzureWebJobsStorage', value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};AccountKey=${storageAccount.listKeys().keys[0].value}' }
        { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: applicationInsights.properties.ConnectionString }
      ]
    }
  }
}

// Sticky settings — do not swap WEBSITE_CONTENTSHARE between slots
resource slotConfigNames 'Microsoft.Web/sites/config@2022-09-01' = {
  parent: functionApp
  name: 'slotConfigNames'
  properties: {
    appSettingNames: [
      'WEBSITE_CONTENTSHARE'
      'WEBSITE_CONTENTAZUREFILECONNECTIONSTRING'
    ]
  }
}
```

## Service Bus Integration (Managed Identity)

```bicep
resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' existing = {
  name: serviceBusNamespaceName
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  // ... (Function App definition from above)
  properties: {
    // ... (other properties)
    siteConfig: {
      appSettings: [
        // Storage with managed identity
        {
          name: 'AzureWebJobsStorage__blobServiceUri'
          value: storageAccount.properties.primaryEndpoints.blob
        }
        // Service Bus with managed identity
        {
          name: 'SERVICEBUS__fullyQualifiedNamespace'
          value: '${serviceBusNamespace.name}.servicebus.windows.net'
        }
        {
          name: 'SERVICEBUS_QUEUE_NAME'
          value: serviceBusQueueName
        }
        // Other settings...
      ]
    }
  }
}

// Grant Service Bus Data Receiver role for triggers
resource serviceBusReceiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBusNamespace.id, functionApp.id, 'Azure Service Bus Data Receiver')
  scope: serviceBusNamespace
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0')
    principalId: functionApp.identity.principalId
    principalType: 'ServicePrincipal'
  }
}

// Grant Service Bus Data Sender role (if function sends messages)
resource serviceBusSenderRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBusNamespace.id, functionApp.id, 'Azure Service Bus Data Sender')
  scope: serviceBusNamespace
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '69a216fc-b8fb-44d8-bc22-1f3c2cd27a39')
    principalId: functionApp.identity.principalId
    principalType: 'ServicePrincipal'
  }
}
```

> 💡 **Key Points:**
>
> - Use `SERVICEBUS__fullyQualifiedNamespace` (double underscore) for managed identity
> - Grant `Service Bus Data Receiver` role for reading messages
> - Grant `Service Bus Data Sender` role for sending messages (if needed)
> - Role assignments automatically enable connection via managed identity

## Premium Plan (No Cold Starts)

```bicep
resource functionAppPlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-funcplan-${uniqueHash}'
  location: location
  sku: { name: 'EP1', tier: 'ElasticPremium' }
  properties: {
    reserved: true
    minimumElasticInstanceCount: 1
  }
}
```

## Functions on Azure Container Apps (Aspire)

> ⚠️ **Important for .NET Aspire:** When deploying Azure Functions to Azure Container Apps with identity-based storage, you must configure `AzureWebJobsSecretStorageType=Files`.

See [aspire-containerapps.md](aspire-containerapps.md) for complete guidance on Functions running on Azure Container Apps and configuration examples.

# Azure Functions Cold Start Mitigation

Cold starts occur when a function app must allocate infrastructure, load the runtime, and initialize your code before handling a request. Impact and mitigation options differ significantly by hosting plan.

## Cold Start Behavior by Plan

Cold-start duration depends on the runtime, dependencies, package size, and initialization work. Measure the latency of the deployed app instead of relying on a fixed estimate.

| Plan | Platform behavior | Primary mitigation |
|------|-------------------|--------------------|
| Consumption (Y1) | Scales to zero; cold starts are expected | Reduce dependencies and startup work, or move to another plan |
| Flex Consumption (FC1) | Improved scale-from-zero behavior | Configure always-ready instances per function or trigger group |
| Premium (EP1-EP3) | Keeps app-level always-ready instances and an HTTP prewarmed buffer | Configure the app's always-ready instance count |
| Dedicated | Host runs continuously when `Always On` is enabled | Enable `Always On` |
| Container Apps (Functions-on-ACA) | Scales to zero when `minReplicas` is `0` | Set `minReplicas` to `1` or higher |

## Mitigation Strategies

### Consumption Plan

Consumption has no built-in always-ready setting. Reduce the work required to specialize a new instance:

| Strategy | How | Trade-off |
|----------|-----|-----------|
| Reduce package size | Trim unused dependencies; use tree-shaking/bundling | Development effort |
| Optimize startup code | Lazy-load heavy modules; defer non-critical connections | Code changes required |

> 💡 **Tip:** A timer-based keep-alive isn't a cold-start guarantee and creates extra executions. If cold starts are a consistent problem, move to Flex Consumption or Premium. See [hosting-plans.md](hosting-plans.md) for the comparison.

### Flex Consumption Plan

Configure always-ready instances for a function group with the dedicated CLI command (do not hand-edit the `functionAppConfig` ARM array — indexing into it by position can silently overwrite other always-ready groups):

```bash
# Set 1 always-ready instance for the "http" function group
az functionapp scale config always-ready set \
  -g $RG -n $APP \
  --settings http=1
```

#### Bicep — Always-Ready Configuration

```bicep
resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: appName
  location: location
  kind: 'functionapp,linux'
  properties: {
    serverFarmId: flexPlan.id
    functionAppConfig: {
      runtime: {
        name: 'node'
        version: '<supported-major-version>'
      }
      scaleAndConcurrency: {
        alwaysReady: [
          { name: 'http', instanceCount: 1 }
        ]
        instanceMemoryMB: 2048
        maximumInstanceCount: 100
      }
    }
  }
}
```

> ⚠️ **Warning:** Always-ready instances are billed continuously, separate from and in addition to on-demand instances (they don't count toward `maximumInstanceCount`). Start with 1 instance per group and scale based on observed traffic.

### Premium Plan

Set the app-level always-ready count so this function app stays loaded. The HTTP prewarmed buffer defaults to one instance and usually shouldn't be changed:

```bash
az functionapp update -g $RG -n $APP \
  --set siteConfig.minimumElasticInstanceCount=2
```

If you need to reserve plan capacity ahead of scale-out or change its burst ceiling, configure the plan separately:

```bash
az functionapp plan update -g $RG -n $PLAN --min-instances 2
az functionapp plan update -g $RG -n $PLAN --max-burst 20
```

> `--min-instances` reserves plan capacity. It doesn't replace the app-level `minimumElasticInstanceCount` setting that keeps a specific app always ready. `--min-elastic-worker-count` isn't a valid parameter for `az functionapp plan update`.

### Dedicated Plan

Enable `Always On` so the app is never unloaded due to idle timeout:

```bash
az functionapp config set -g $RG -n $APP --always-on true
```

### Functions on Container Apps

For new deployments, use the native `Microsoft.App/containerApps` integration and set `kind: 'functionapp'`. A generic container app without this kind doesn't enable the Functions integration. The older `Microsoft.Web/sites` integration is legacy and planned for future deprecation.

```bicep
resource functionApp 'Microsoft.App/containerApps@2024-10-02-preview' = {
  name: appName
  location: location
  kind: 'functionapp'
  properties: {
    managedEnvironmentId: containerAppsEnvironment.id
    configuration: {
      ingress: {
        external: true
        targetPort: 80
      }
    }
    template: {
      containers: [
        {
          name: appName
          image: containerImage
          resources: {
            cpu: json('0.5')
            memory: '1Gi'
          }
        }
      ]
      scale: {
        minReplicas: 1
      }
    }
  }
}
```

> ⚠️ **Warning:** `minReplicas: 0` allows scale-to-zero; set it to `1` or higher to keep at least one replica running. Configure required Functions settings such as `AzureWebJobsStorage` through secrets or managed identity.

## Language-Specific Optimization

| Language | Cold Start Tip |
|----------|---------------|
| .NET | Use ReadyToRun (or Native AOT where supported) compilation; avoid heavy DI registration in startup |
| Node.js | Minimize `node_modules`; bundle with esbuild/webpack; use the latest LTS version supported by Azure Functions |
| Python | Reduce package count; avoid importing unused modules at the top of the file |
| Java | Prefer the latest supported Java version on Functions v4; minimize static initialization and classpath size |
| PowerShell | Minimize modules declared in `requirements.psd1` |

## Recommendation Summary

| Scenario | Recommended Plan | Cold Start Strategy |
|----------|-----------------|----------------------|
| Cost-sensitive, tolerates latency | Consumption | Small deployment package + minimal startup work |
| Low latency, Linux, bursty | Flex Consumption | 1-2 always-ready instances via `az functionapp scale config always-ready set` |
| Enterprise, strict SLA, Windows or slots needed | Premium | App-level `minimumElasticInstanceCount` + default prewarmed buffer |
| Shared App Service plan, always running | Dedicated | `Always On = true` |
| Containerized Functions | Container Apps (Functions-on-ACA) | `minReplicas` set to `1` or higher on a `Microsoft.App/containerApps` resource with `kind: 'functionapp'` |

# Durable Functions

Long-running orchestrations with checkpointing and state management.

## Storage Backend

Durable Functions requires a storage backend to persist orchestration state, queues, and history.

| Backend | Recommendation | Notes |
|---------|---------------|-------|
| **Durable Task Scheduler** | **✅ Required** | Fully managed Azure service. Best performance, lowest latency, built-in monitoring. Supports all languages (.NET, Python, Java, JavaScript). |
| Azure Storage (default) | ⛔ Do not use | Legacy backend. Higher latency, harder to monitor, no built-in RBAC. Not permitted for new projects. |
| MSSQL | Specialized | SQL Server backend. Only when SQL infrastructure already exists and user explicitly requests it. |

> **⛔ MANDATORY**: You **MUST** use **Durable Task Scheduler** as the storage backend for ALL new Durable Functions projects. Do NOT use Azure Storage as the backend — it is legacy and not permitted. Generate the DTS Bicep module (`Microsoft.DurableTask/schedulers` + `taskHubs`), RBAC role assignment (Durable Task Data Contributor), and `DURABLE_TASK_SCHEDULER_CONNECTION_STRING` app setting. See the [Durable Task Scheduler reference](../durable-task-scheduler/README.md) for setup, language-specific guidance, and Bicep templates.

## When to Use

- Multi-step workflows
- Fan-out/fan-in patterns
- Human interaction workflows
- Long-running processes

## Get Durable Templates

Use the [Azure Functions Templates workflow](templates/README.md) to discover and fetch durable samples:

**MCP Tool:** `functions_template_get(language)` → filter `resource == "durable"`

**Fallback:** CDN manifest → filter `resource == "durable"`

Available patterns: Fan-out/Fan-in, Order Processing (with Bicep), Distributed Tracing, Large Payload, Saga, AI Travel Planner, PDF Summarizer, .NET Aspire integration.

# Azure Functions Hosting Plans

## Plan Comparison Matrix

| Feature | Consumption (Y1) | Flex Consumption (FC1) | Premium (EP1-EP3) | Dedicated (App Service) | Container Apps |
|---------|:-:|:-:|:-:|:-:|:-:|
| **Max scale-out (instances)** | 200 | 1,000 | Plan-dependent (up to ~100) | Manual, per plan SKU | Up to 1,000 |
| **Per-function scaling** | ❌ | ✅ | ❌ | ❌ | ❌ |
| **Always-ready / min instances** | ❌ | ✅ (always-ready groups) | ✅ (min instances) | ✅ (Always On) | ✅ (min replicas) |
| **Scale to zero** | ✅ | ✅ | ❌ (min 1 instance) | ❌ | ✅ (`minReplicas: 0`) |
| **VNet integration (outbound)** | ❌ | ✅ | ✅ | ✅ | ✅ |
| **Private endpoints (inbound)** | ❌ | ✅ | ✅ | ✅ | ✅ (environment-level) |
| **Deployment slots (incl. production)** | 2 | ❌ Not supported | 3 | 1-20 (tier-dependent) | Via [revisions](https://learn.microsoft.com/azure/container-apps/revisions) |
| **Function timeout — default / max** | 5 min / 10 min | 30 min / unbounded | 30 min / unbounded | 30 min / unbounded (requires Always On) | 30 min / unbounded |
| **OS support** | Windows + Linux | Linux only | Windows + Linux | Windows + Linux | Linux only |

> ⚠️ **"Unbounded" timeout caveat:** Flex Consumption, Premium, Dedicated, and Container Apps allow `functionTimeout` in `host.json` to be set unbounded, but the platform can still recycle a worker: a 60-minute idle timer, up to a 60-minute scale-in grace period, and a 10-minute grace period during platform upgrades. Design long-running work to be resumable (e.g., Durable Functions) rather than relying on a single uninterrupted execution.

## Instance Sizing

| Plan | SKU | vCPU | Memory |
|------|-----|------|--------|
| Consumption | Y1 | Shared/dynamic | 1.5 GB |
| Flex Consumption | FC1 | 0.25 / 1 / 2 (selectable) | 512 MB / 2,048 MB / 4,096 MB (selectable) |
| Premium | EP1 | 1 | 3.5 GB |
| Premium | EP2 | 2 | 7 GB |
| Premium | EP3 | 4 | 14 GB |
| Dedicated | B1/S1 | 1 | 1.75 GB |
| Dedicated | P1v3 | 2 | 8 GB |

> 💡 Flex Consumption instance memory is user-selectable per app (512 MB, 2,048 MB, or 4,096 MB), each mapping to a fixed vCPU allocation. Use 2,048 MB as the default; go smaller for high fan-out/low-per-invocation-cost workloads, larger for CPU- or memory-intensive functions. Each region has a default 250-core (512,000 MB) Flex quota shared across all Flex apps in that subscription/region — request an increase for large-scale deployments.

## Cost Models

| Plan | Pricing Model | Notes |
|------|--------------|-------|
| Consumption | Per-execution + GB-s; free monthly grant | Lowest cost for spiky, low-volume workloads; no charge while idle |
| Flex Consumption | Per-execution + GB-s; optional always-ready instances billed continuously | Scale-to-zero like Consumption, with opt-in always-ready base cost for latency-sensitive paths |
| Premium (EP1) | Per-instance-hour; at least 1 instance always allocated | Fixed minimum cost even at zero traffic (no scale-to-zero) |
| Dedicated (B1) | Per-instance-hour; plan runs continuously | Cost-effective when Functions co-locate with existing App Service Plan capacity |
| Container Apps | Per-vCPU-second + per-GiB-second; can scale to zero | Pay only while replicas run when `minReplicas: 0` |

## Decision Criteria

```
Need per-function scaling, Linux, and fast/large scale-out?
├─ Yes → Flex Consumption
└─ No
   Need VNet integration or private endpoints?
   ├─ No → Consumption (lowest cost, simplest)
   └─ Yes
      Already running other apps on an App Service Plan, or need Windows + slots + long history of App Service features?
      ├─ Yes → Dedicated (App Service Plan)
      └─ No
         Budget-sensitive with bursty traffic?
         ├─ Yes + Linux → Flex Consumption
         ├─ Yes + Windows → Premium (EP1, cheapest always-on with VNet)
         └─ No → Premium (predictable pre-warmed latency, deployment slots)
```

## Plan-Specific Considerations

### Consumption (Y1)

- Best for: low-traffic, event-driven workloads that tolerate occasional cold starts.
- Limits: 10-minute max execution, no VNet integration, no per-function scaling.
- Slots: 2 total (production + 1 staging) on Windows and Linux.

### Flex Consumption (FC1)

- **Recommended default for new Functions apps.** Best for Linux workloads needing fast/large scale-out, VNet, per-function scaling, and configurable instance memory.
- Limits: Linux only, **no deployment slots** (use [rolling/blue-green site update strategies](https://learn.microsoft.com/azure/azure-functions/flex-consumption-site-updates) instead for zero-downtime deploys).
- Always-ready instances bypass the max-instance-count ceiling and are billed continuously — start small and measure.

### Premium (EP1–EP3)

- Best for: latency-sensitive workloads, longer executions, VNet + private endpoints on Windows, or apps needing 3 deployment slots.
- Always allocates at least 1 instance (no scale-to-zero); minimum instance count and maximum burst are both configurable.
- Migrating an existing app between Consumption and Premium **on Windows** is supported in place via CLI/PowerShell (no new app required). This migration path is **not supported on Linux** — Linux apps require a new function app on the target plan.

### Dedicated (App Service Plan)

- Best for: consolidating Functions onto App Service Plan capacity you already run, or workloads needing the broadest App Service feature set (Hybrid Connections, custom domains, `Always On`).
- Slot count depends on the underlying App Service Plan tier (Basic = 1, Standard = 5, Premium = 20; see [App Service limits](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-subscription-service-limits#azure-app-service-limits)).
- No automatic scale-to-zero; the plan runs (and is billed) continuously unless you scale it down manually.

### Container Apps (Functions-on-ACA)

- Best for: teams standardizing on Container Apps/Dapr/microservices, or needing a custom container image for Functions.
- For new deployments, use the native `Microsoft.App/containerApps` integration with `kind: 'functionapp'`. The older `Microsoft.Web/sites` integration is legacy and planned for future deprecation. See [cold-start.md](cold-start.md#functions-on-container-apps) for the current Bicep shape.
- Scale-to-zero via `minReplicas: 0`; revisions replace deployment slots for staged rollout.

## Migration Notes

Switching hosting plans generally requires creating a new function app, **except**: Consumption ↔ Premium migration **on Windows** is supported in place via `az functionapp update` (see [Plan migration](https://learn.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings#plan-migration)). All Linux plan changes, and any move to/from Flex Consumption, require redeploying to a new app on the target plan. See `azure-upgrade` skill for Consumption→Flex migration guidance.

# Azure Functions

Serverless compute for event-driven workloads, APIs, and scheduled tasks.

> **⚠️ MANDATORY: Use Composition Algorithm**
>
> **NEVER synthesize Bicep or Terraform from scratch for Azure Functions.**
>
> You MUST follow the base + recipe composition workflow:
> 1. Load [selection.md](templates/selection.md) — decision tree for choosing base template + recipe
> 2. Follow [composition.md](templates/recipes/composition.md) — the algorithm for fetching and composing
>
> This ensures proven IaC patterns, correct RBAC, and Flex Consumption defaults.

## When to Use

- Event-driven workloads
- Scheduled tasks (cron jobs)
- HTTP APIs with variable traffic
- Message/queue processing
- Real-time file processing
- MCP servers for AI agents
- Real-time streaming and event processing
- Orchestrations and workflows (Durable Functions)

## Service Type in azure.yaml

```yaml
services:
  my-function:
    host: function
    project: ./src/my-function
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Storage Account | Function runtime state |
| App Service Plan | Hosting (Consumption or Premium) |
| Application Insights | Monitoring |

## Hosting Plans

**Use Flex Consumption for new deployments** (all AZD templates default to Flex).

For the full comparison matrix (scale limits, instance sizing, deployment slots, cost model, and a decision tree), see **[hosting-plans.md](hosting-plans.md)**. For mitigating cold starts on any plan, see **[cold-start.md](cold-start.md)**.

## Runtime Stacks

> **⚠️ ALWAYS QUERY OFFICIAL DOCUMENTATION FOR VERSIONS**
>
> Do NOT use hardcoded versions. Query for latest GA versions before generating code:
>
> **Primary Source:** [Azure Functions Supported Languages](https://learn.microsoft.com/en-us/azure/azure-functions/supported-languages)
>
> Use the azure-documentation MCP tool to fetch current supported versions:
> ```yaml
> intent: "Azure Functions supported language runtime versions"
> learn: true
> ```

### Version Selection Priority
1. **Latest GA** — For new projects (best features, longest support window)
2. **LTS** — For enterprise/compliance requirements
3. **User-specified** — When explicitly requested

| Language | FUNCTIONS_WORKER_RUNTIME | linuxFxVersion |
|----------|-------------------------|----------------|
| Node.js | `node` | `Node\|<version>` |
| Python | `python` | `Python\|<version>` |
| .NET | `dotnet-isolated` | `DOTNET-ISOLATED\|<version>` |
| Java | `java` | `Java\|<version>` |
| PowerShell | `powershell` | `PowerShell\|<version>` |

## References

- **[Selection Guide](templates/selection.md)** — Start here: decision tree for base + recipe
- **[Composition Algorithm](templates/recipes/composition.md)** — How to fetch and compose templates
- [AZD Templates](templates/README.md) — Template overview
- [Bicep Patterns](bicep.md)
- [Terraform Patterns](terraform.md)
- [Durable Functions](durable.md)
- [Aspire + Container Apps](aspire-containerapps.md)
- [Hosting Plans Comparison](hosting-plans.md) — Consumption vs Flex vs Premium vs Dedicated vs Container Apps
- [Cold Start Mitigation](cold-start.md) — Per-plan strategies and CLI/Bicep examples

# Functions Terraform Patterns — REFERENCE ONLY

> ⛔ **DO NOT COPY THIS CODE DIRECTLY**
>
> This file contains **reference patterns** for understanding Azure Functions Terraform structure.
> **You MUST use the composition algorithm** to generate infrastructure:
>
> 1. Load `templates/selection.md` to choose the correct base template
> 2. Follow `templates/recipes/composition.md` for the exact algorithm
> 3. Use `functions_template_get` MCP tool (with `infrastructure: "terraform"`) to list and fetch templates and write `functionFiles[]` + `projectFiles[]` directly — NEVER hand-write Bicep/Terraform and use `azd init -t <template>`/`func init`/`func new` as fallback when composing multiple recipes and required templates are not found
>
> Hand-writing Terraform from these patterns will result in missing RBAC, incorrect managed identity configuration, and security vulnerabilities.

## Flex Consumption (Recommended)

**Use Flex Consumption for new deployments with managed identity (no connection strings).**

> **⚠️ IMPORTANT**: Flex Consumption requires **azurerm provider v4.2 or later**.

```hcl
terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.2"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_storage_account" "function_storage" {
  name                     = "${var.resource_prefix}func${var.unique_hash}"
  location                 = var.location
  resource_group_name      = azurerm_resource_group.main.name
  account_tier             = "Standard"
  account_replication_type = "LRS"
  
  min_tls_version              = "TLS1_2"
  allow_nested_items_to_be_public = false
  shared_access_key_enabled    = false  # Enforce managed identity
}

resource "azurerm_storage_container" "deployment_package" {
  name                  = "deploymentpackage"
  storage_account_id    = azurerm_storage_account.function_storage.id
  container_access_type = "private"
}

resource "azurerm_application_insights" "function_insights" {
  name                = "appi-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  application_type    = "web"
}

resource "azurerm_service_plan" "function_plan" {
  name                = "plan-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  os_type             = "Linux"
  sku_name            = "FC1"
}

resource "azurerm_linux_function_app" "function_app" {
  name                       = "${var.resource_prefix}-${var.service_name}-${var.unique_hash}"
  location                   = var.location
  resource_group_name        = azurerm_resource_group.main.name
  service_plan_id            = azurerm_service_plan.function_plan.id
  storage_account_name       = azurerm_storage_account.function_storage.name
  storage_uses_managed_identity = true
  https_only                 = true

  identity {
    type = "SystemAssigned"
  }

  function_app_config {
    deployment {
      storage {
        type  = "blob_container"
        value = "${azurerm_storage_account.function_storage.primary_blob_endpoint}${azurerm_storage_container.deployment_package.name}"
        authentication {
          type = "SystemAssignedIdentity"
        }
      }
    }

    scale_and_concurrency {
      maximum_instance_count = 100
      instance_memory_mb     = 2048
    }

    runtime {
      name    = "python"  # or "node", "dotnet-isolated"
      version = "3.11"
    }
  }

  site_config {
    application_insights_connection_string = azurerm_application_insights.function_insights.connection_string
    
    application_stack {
      python_version = "3.11"  # Adjust based on runtime
    }
  }

  app_settings = {
    "AzureWebJobsStorage__blobServiceUri"  = azurerm_storage_account.function_storage.primary_blob_endpoint
    "FUNCTIONS_EXTENSION_VERSION"          = "~4"
    "FUNCTIONS_WORKER_RUNTIME"             = "python"
  }
}

# Grant Function App access to Storage for runtime
resource "azurerm_role_assignment" "function_storage_access" {
  scope                = azurerm_storage_account.function_storage.id
  role_definition_name = "Storage Blob Data Owner"
  principal_id         = azurerm_linux_function_app.function_app.identity[0].principal_id
}
```

> 💡 **Key Points:**
> - Use `AzureWebJobsStorage__blobServiceUri` instead of connection string
> - Set `shared_access_key_enabled = false` for enhanced security
> - Use `storage_uses_managed_identity = true` for deployment authentication
> - Grant `Storage Blob Data Owner` role for full access to blobs, queues, and tables
> - Requires azurerm provider **v4.2 or later**

### Using Azure Verified Module

For production deployments, use the official Azure Verified Module:

```hcl
module "function_app" {
  source  = "Azure/avm-res-web-site/azurerm"
  version = "~> 0.0"

  name                = "${var.resource_prefix}-${var.service_name}-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  
  kind    = "functionapp"
  os_type = "Linux"

  sku_name = "FC1"

  function_app_storage_account_name       = azurerm_storage_account.function_storage.name
  function_app_storage_uses_managed_identity = true

  site_config = {
    application_insights_connection_string = azurerm_application_insights.function_insights.connection_string
    
    application_stack = {
      python_version = "3.11"
    }
  }

  app_settings = {
    "AzureWebJobsStorage__blobServiceUri" = azurerm_storage_account.function_storage.primary_blob_endpoint
    "FUNCTIONS_EXTENSION_VERSION"         = "~4"
    "FUNCTIONS_WORKER_RUNTIME"            = "python"
  }

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

> 💡 **Example Reference:** [HashiCorp Flex Consumption Example](https://registry.terraform.io/modules/Azure/avm-res-web-site/azurerm/latest/examples/flex_consumption)

## Consumption Plan (Legacy)

> ⛔ **DO NOT USE** — Y1/Dynamic SKU is deprecated for new deployments.
> **ALWAYS use Flex Consumption (FC1)** for all new Azure Functions.
> The Y1 example below is only for reference when migrating legacy apps.

**⚠️ Not recommended for new deployments. Use Flex Consumption instead.**

> 💡 **OS and Slots Matter for Consumption:**
> - **Linux Consumption** (`os_type = "Linux"`): Does **not** support deployment slots.
> - **Windows Consumption** (`os_type = "Windows"`): Supports **1 staging slot** (2 total including production).
>   If a user specifically needs Windows Consumption with a slot, that is supported — use the Windows pattern below.
>   For new apps needing slots, prefer **Elastic Premium (EP1)** for better performance and no cold-start issues.

### Linux Consumption (no slot support)

```hcl
resource "azurerm_storage_account" "function_storage" {
  name                     = "${var.resource_prefix}func${var.unique_hash}"
  location                 = var.location
  resource_group_name      = azurerm_resource_group.main.name
  account_tier             = "Standard"
  account_replication_type = "LRS"
}

resource "azurerm_service_plan" "function_plan" {
  name                = "${var.resource_prefix}-funcplan-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  os_type             = "Linux"
  sku_name            = "Y1"
}

resource "azurerm_linux_function_app" "function_app" {
  name                = "${var.resource_prefix}-${var.service_name}-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  service_plan_id     = azurerm_service_plan.function_plan.id
  https_only          = true
  
  storage_account_name       = azurerm_storage_account.function_storage.name
  storage_account_access_key = azurerm_storage_account.function_storage.primary_access_key
  
  site_config {
    application_insights_connection_string = azurerm_application_insights.function_insights.connection_string
    
    application_stack {
      python_version = "3.11"
    }
  }

  app_settings = {
    "FUNCTIONS_EXTENSION_VERSION" = "~4"
    "FUNCTIONS_WORKER_RUNTIME"    = "python"
  }

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

### Windows Consumption (supports 1 staging slot)

> ⚠️ **Windows Consumption is not recommended for new projects** — consider Flex Consumption or Elastic Premium.
> Use this pattern only for existing Windows apps or when Windows-specific features are required.

```hcl
resource "azurerm_service_plan" "function_plan" {
  name                = "${var.resource_prefix}-funcplan-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  os_type             = "Windows"
  sku_name            = "Y1"
}

resource "azurerm_windows_function_app" "function_app" {
  name                = "${var.resource_prefix}-${var.service_name}-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  service_plan_id     = azurerm_service_plan.function_plan.id
  https_only          = true

  storage_account_name       = azurerm_storage_account.function_storage.name
  storage_account_access_key = azurerm_storage_account.function_storage.primary_access_key

  site_config {
    application_insights_connection_string = azurerm_application_insights.function_insights.connection_string
    application_stack {
      node_version = "~20"
    }
  }

  app_settings = {
    "FUNCTIONS_EXTENSION_VERSION"             = "~4"
    "FUNCTIONS_WORKER_RUNTIME"                = "node"
    "WEBSITE_CONTENTSHARE"                    = "${lower(var.service_name)}-prod"  # must differ per slot; Azure Files share names are lowercase
    "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING" = azurerm_storage_account.function_storage.primary_connection_string
  }

  sticky_settings {
    app_setting_names = ["WEBSITE_CONTENTSHARE", "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING"]
  }

  identity {
    type = "SystemAssigned"
  }
}

# 1 staging slot is supported on Windows Consumption
resource "azurerm_windows_function_app_slot" "staging" {
  name            = "staging"
  function_app_id = azurerm_windows_function_app.function_app.id

  storage_account_name       = azurerm_storage_account.function_storage.name
  storage_account_access_key = azurerm_storage_account.function_storage.primary_access_key

  site_config {
    application_insights_connection_string = azurerm_application_insights.function_insights.connection_string
    application_stack {
      node_version = "~20"
    }
  }

  app_settings = {
    "FUNCTIONS_EXTENSION_VERSION"             = "~4"
    "FUNCTIONS_WORKER_RUNTIME"                = "node"
    "WEBSITE_CONTENTSHARE"                    = "${var.service_name}-staging"  # MUST differ from production
    "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING" = azurerm_storage_account.function_storage.primary_connection_string
  }
}
```

## Service Bus Integration (Managed Identity)

```hcl
data "azurerm_servicebus_namespace" "example" {
  name                = var.servicebus_namespace_name
  resource_group_name = var.servicebus_resource_group
}

resource "azurerm_linux_function_app" "function_app" {
  # ... (Function App definition from above)
  
  app_settings = {
    # Storage with managed identity
    "AzureWebJobsStorage__blobServiceUri" = azurerm_storage_account.function_storage.primary_blob_endpoint
    
    # Service Bus with managed identity
    "SERVICEBUS__fullyQualifiedNamespace" = "${data.azurerm_servicebus_namespace.example.name}.servicebus.windows.net"
    "SERVICEBUS_QUEUE_NAME"               = var.servicebus_queue_name
    
    # Other settings...
    "FUNCTIONS_EXTENSION_VERSION"  = "~4"
    "FUNCTIONS_WORKER_RUNTIME"     = "python"
    "APPLICATIONINSIGHTS_CONNECTION_STRING" = azurerm_application_insights.function_insights.connection_string
  }
}

# Grant Service Bus Data Receiver role for triggers
resource "azurerm_role_assignment" "servicebus_receiver" {
  scope                = data.azurerm_servicebus_namespace.example.id
  role_definition_name = "Azure Service Bus Data Receiver"
  principal_id         = azurerm_linux_function_app.function_app.identity[0].principal_id
}

# Grant Service Bus Data Sender role (if function sends messages)
resource "azurerm_role_assignment" "servicebus_sender" {
  scope                = data.azurerm_servicebus_namespace.example.id
  role_definition_name = "Azure Service Bus Data Sender"
  principal_id         = azurerm_linux_function_app.function_app.identity[0].principal_id
}
```

> 💡 **Key Points:**
> - Use `SERVICEBUS__fullyQualifiedNamespace` (double underscore) for managed identity
> - Grant `Service Bus Data Receiver` role for reading messages
> - Grant `Service Bus Data Sender` role for sending messages (if needed)
> - Role assignments automatically enable connection via managed identity

## Premium Plan (No Cold Starts)

```hcl
resource "azurerm_service_plan" "function_plan" {
  name                = "${var.resource_prefix}-funcplan-${var.unique_hash}"
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
  os_type             = "Linux"
  sku_name            = "EP1"  # EP1, EP2, or EP3
}

resource "azurerm_linux_function_app" "function_app" {
  # ... (rest of configuration similar to Flex Consumption)
  
  site_config {
    # Premium-specific settings
    always_on                      = true
    pre_warmed_instance_count      = 1
    elastic_instance_minimum       = 1
    
    application_stack {
      python_version = "3.11"
    }
  }
}
```

# Key Vault - Bicep Patterns

## Basic Vault

```bicep
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: '${resourcePrefix}-kv-${uniqueHash}'
  location: location
  properties: {
    tenantId: subscription().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 90
    enablePurgeProtection: true
  }
}
```

## Storing Secrets

```bicep
resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  parent: keyVault
  name: 'database-connection-string'
  properties: {
    value: databaseConnectionString
  }
}
```

## Role Assignment (Managed Identity)

```bicep
resource keyVaultRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(keyVault.id, principalId, 'Key Vault Secrets User')
  scope: keyVault
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

## Referencing in App Service / Functions

```bicep
appSettings: [
  {
    name: 'DATABASE_URL'
    value: '@Microsoft.KeyVault(VaultName=${keyVault.name};SecretName=database-connection-string)'
  }
]
```

## Referencing in Container Apps

```bicep
secrets: [
  {
    name: 'db-connection'
    keyVaultUrl: '${keyVault.properties.vaultUri}secrets/database-connection-string'
    identity: containerApp.identity.principalId
  }
]
```

## Secret with Expiration

```bicep
resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  parent: keyVault
  name: 'api-key'
  properties: {
    value: apiKey
    attributes: {
      exp: dateTimeToEpoch(dateTimeAdd(utcNow(), 'P90D'))
    }
  }
}
```

# Azure Key Vault

Centralized secrets, keys, and certificate management.

## When to Use

- Storing application secrets
- Managing certificates
- Storing encryption keys
- Centralizing secret management
- Enabling secret rotation

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Key Vault is self-contained |
| Private Endpoint | Secure access (optional) |

## SKU Selection

| SKU | Features |
|-----|----------|
| Standard | Software-protected keys |
| Premium | HSM-protected keys |

## RBAC Roles

| Role | Permissions |
|------|-------------|
| Key Vault Administrator | Full access |
| Key Vault Secrets Officer | Manage secrets |
| Key Vault Secrets User | Read secrets |
| Key Vault Certificates Officer | Manage certificates |
| Key Vault Crypto Officer | Manage keys |

## Environment Variables

| Variable | Value |
|----------|-------|
| `KEY_VAULT_URL` | `https://{vault-name}.vault.azure.net/` |
| `KEY_VAULT_NAME` | Vault name |

## Best Practices

1. **Always use RBAC** over access policies
2. **Enable soft delete and purge protection** for production
3. **Use managed identities** instead of storing keys in apps
4. **Set expiration dates** on secrets
5. **Use separate vaults** for different environments

## References

- [Bicep Patterns](bicep.md)
- [SDK Access](sdk.md)

# Key Vault - SDK Patterns

## Node.js

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```javascript
const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new SecretClient(
  process.env.KEY_VAULT_URL,
  new DefaultAzureCredential()
);

const secret = await client.getSecret("database-connection-string");
console.log(secret.value);
```

## Python

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```python
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

client = SecretClient(
    vault_url=os.environ["KEY_VAULT_URL"],
    credential=DefaultAzureCredential()
)

secret = client.get_secret("database-connection-string")
print(secret.value)
```

## .NET

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```csharp
var client = new SecretClient(
    new Uri(Environment.GetEnvironmentVariable("KEY_VAULT_URL")),
    new DefaultAzureCredential()
);

KeyVaultSecret secret = await client.GetSecretAsync("database-connection-string");
Console.WriteLine(secret.Value);
```

## Event Grid Integration (Expiry Notifications)

```bicep
resource kvEventSubscription 'Microsoft.EventGrid/eventSubscriptions@2023-12-15-preview' = {
  name: 'secret-expiry-notification'
  scope: keyVault
  properties: {
    destination: {
      endpointType: 'WebHook'
      properties: {
        endpointUrl: 'https://my-api.example.com/secret-rotation'
      }
    }
    filter: {
      includedEventTypes: [
        'Microsoft.KeyVault.SecretNearExpiry'
        'Microsoft.KeyVault.SecretExpired'
      ]
    }
  }
}
```

# Logic Apps - Bicep Patterns

## Consumption (Multi-tenant)

```bicep
resource logicApp 'Microsoft.Logic/workflows@2019-05-01' = {
  name: '${resourcePrefix}-logic-${uniqueHash}'
  location: location
  properties: {
    state: 'Enabled'
    definition: {
      '$schema': 'https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#'
      contentVersion: '1.0.0.0'
      triggers: {
        manual: {
          type: 'Request'
          kind: 'Http'
          inputs: {
            schema: {}
          }
        }
      }
      actions: {}
    }
    parameters: {}
  }
}
```

## Standard (Single-tenant)

```bicep
resource logicAppPlan 'Microsoft.Web/serverfarms@2022-09-01' = {
  name: '${resourcePrefix}-logicplan-${uniqueHash}'
  location: location
  sku: {
    name: 'WS1'
    tier: 'WorkflowStandard'
  }
  properties: {
    reserved: true
  }
}

resource logicAppStandard 'Microsoft.Web/sites@2022-09-01' = {
  name: '${resourcePrefix}-logic-${uniqueHash}'
  location: location
  kind: 'functionapp,workflowapp'
  properties: {
    serverFarmId: logicAppPlan.id
    siteConfig: {
      appSettings: [
        {
          name: 'FUNCTIONS_EXTENSION_VERSION'
          value: '~4'
        }
        {
          name: 'FUNCTIONS_WORKER_RUNTIME'
          value: 'node'
        }
        {
          name: 'AzureWebJobsStorage'
          value: storageConnectionString
        }
      ]
    }
  }
}
```

## API Connection

```bicep
resource serviceBusConnection 'Microsoft.Web/connections@2016-06-01' = {
  name: 'servicebus-connection'
  location: location
  properties: {
    displayName: 'Service Bus Connection'
    api: {
      id: subscriptionResourceId('Microsoft.Web/locations/managedApis', location, 'servicebus')
    }
    parameterValues: {
      connectionString: serviceBus.listKeys().primaryConnectionString
    }
  }
}
```

# Azure Logic Apps

Low-code workflow automation and integration platform.

## When to Use

- Integration-heavy workloads
- Business process automation
- Connecting multiple SaaS services
- Approval and human workflow processes
- Low-code/visual workflow design
- Event-driven orchestration

## Deployment Note

Logic Apps are typically deployed as infrastructure, not application services:

```yaml
# Logic Apps are defined in Bicep infrastructure
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Storage Account | Workflow state (Standard only) |
| Log Analytics | Monitoring |
| API Connections | External service connections |

## Consumption vs Standard

| Feature | Consumption | Standard |
|---------|-------------|----------|
| Pricing | Per execution | App Service Plan |
| VNET | Limited | Full support |
| State | Azure-managed | Custom storage |
| Deployment | ARM/Bicep | VS Code deployment |
| Multi-workflow | One per resource | Multiple per app |

## References

- [Bicep Patterns](bicep.md)
- [Triggers](triggers.md)

# Logic Apps - Triggers

## HTTP Request

```json
{
  "triggers": {
    "manual": {
      "type": "Request",
      "kind": "Http",
      "inputs": {
        "schema": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string" }
          }
        }
      }
    }
  }
}
```

## Recurrence (Schedule)

```json
{
  "triggers": {
    "Recurrence": {
      "type": "Recurrence",
      "recurrence": {
        "frequency": "Hour",
        "interval": 1
      }
    }
  }
}
```

## Service Bus Queue

```json
{
  "triggers": {
    "When_a_message_is_received": {
      "type": "ApiConnection",
      "inputs": {
        "host": {
          "connection": {
            "name": "@parameters('$connections')['servicebus']['connectionId']"
          }
        },
        "method": "get",
        "path": "/@{encodeURIComponent('orders')}/messages/head"
      }
    }
  }
}
```

## Common Actions

### HTTP Action

```json
{
  "HTTP": {
    "type": "Http",
    "inputs": {
      "method": "POST",
      "uri": "https://api.example.com/orders",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": "@triggerBody()"
    }
  }
}
```

### Approval Email

```json
{
  "Send_approval_email": {
    "type": "ApiConnectionWebhook",
    "inputs": {
      "host": {
        "connection": {
          "name": "@parameters('$connections')['office365']['connectionId']"
        }
      },
      "body": {
        "NotificationUrl": "@{listCallbackUrl()}",
        "Message": {
          "To": "approver@example.com",
          "Subject": "Approval Required",
          "Options": "Approve, Reject"
        }
      },
      "path": "/approvalmail/$subscriptions"
    }
  }
}
```

# Service Bus - Bicep Patterns

## Namespace

```bicep
resource serviceBus 'Microsoft.ServiceBus/namespaces@2022-10-01-preview' = {
  name: '${resourcePrefix}-sb-${uniqueHash}'
  location: location
  sku: {
    name: 'Standard'
    tier: 'Standard'
  }
}
```

## Queue

```bicep
resource queue 'Microsoft.ServiceBus/namespaces/queues@2022-10-01-preview' = {
  parent: serviceBus
  name: 'orders'
  properties: {
    maxDeliveryCount: 10
    deadLetteringOnMessageExpiration: true
    defaultMessageTimeToLive: 'P14D'
    lockDuration: 'PT5M'
  }
}
```

## Topic and Subscription

```bicep
resource topic 'Microsoft.ServiceBus/namespaces/topics@2022-10-01-preview' = {
  parent: serviceBus
  name: 'events'
  properties: {
    defaultMessageTimeToLive: 'P14D'
  }
}

resource subscription 'Microsoft.ServiceBus/namespaces/topics/subscriptions@2022-10-01-preview' = {
  parent: topic
  name: 'order-processor'
  properties: {
    maxDeliveryCount: 10
    deadLetteringOnMessageExpiration: true
    lockDuration: 'PT5M'
  }
}
```

## Subscription Filters

### SQL Filter

```bicep
resource filterRule 'Microsoft.ServiceBus/namespaces/topics/subscriptions/rules@2022-10-01-preview' = {
  parent: subscription
  name: 'high-priority'
  properties: {
    filterType: 'SqlFilter'
    sqlFilter: {
      sqlExpression: 'priority = \'high\''
    }
  }
}
```

### Correlation Filter

```bicep
resource correlationRule 'Microsoft.ServiceBus/namespaces/topics/subscriptions/rules@2022-10-01-preview' = {
  parent: subscription
  name: 'orders-only'
  properties: {
    filterType: 'CorrelationFilter'
    correlationFilter: {
      label: 'order'
    }
  }
}
```

## Managed Identity Access

### Service Bus Data Receiver (for triggers/consumers)

```bicep
resource serviceBusReceiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBus.id, principalId, 'Azure Service Bus Data Receiver')
  scope: serviceBus
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

### Service Bus Data Sender (for producers)

```bicep
resource serviceBusSenderRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBus.id, principalId, 'Azure Service Bus Data Sender')
  scope: serviceBus
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '69a216fc-b8fb-44d8-bc22-1f3c2cd27a39')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

### Both Sender and Receiver

```bicep
// Grant both sender and receiver roles for bidirectional messaging
resource serviceBusReceiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBus.id, principalId, 'receiver')
  scope: serviceBus
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}

resource serviceBusSenderRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(serviceBus.id, principalId, 'sender')
  scope: serviceBus
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '69a216fc-b8fb-44d8-bc22-1f3c2cd27a39')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

> 💡 **Role Selection:**
> - Use **Data Receiver** for Function triggers or message consumers
> - Use **Data Sender** for applications that send messages
> - Use **both roles** for bidirectional communication
> - Roles can be scoped to namespace (all queues/topics) or specific queue/topic

# Service Bus - Messaging Patterns

## Point-to-Point (Queue)

```
Producer → Queue → Consumer
```

Use for: Work distribution, command processing

## Pub/Sub (Topic + Subscriptions)

```
Publisher → Topic → Subscription A → Consumer A
                 → Subscription B → Consumer B
```

Use for: Event broadcasting, multiple consumers

## SDK Patterns

### Managed Identity (Recommended)

#### Node.js

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```javascript
const { ServiceBusClient } = require("@azure/service-bus");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const fullyQualifiedNamespace = process.env.SERVICEBUS_NAMESPACE + ".servicebus.windows.net";
const client = new ServiceBusClient(fullyQualifiedNamespace, credential);

// Send
const sender = client.createSender("orders");
await sender.sendMessages({ body: { orderId: "123" } });

// Receive
const receiver = client.createReceiver("orders");
const messages = await receiver.receiveMessages(10);
for (const message of messages) {
  await receiver.completeMessage(message);
}
```

#### Python

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```python
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
fully_qualified_namespace = f"{os.environ['SERVICEBUS_NAMESPACE']}.servicebus.windows.net"
client = ServiceBusClient(fully_qualified_namespace, credential)

# Send
sender = client.get_queue_sender("orders")
with sender:
    sender.send_messages(ServiceBusMessage('{"orderId": "123"}'))

# Receive
receiver = client.get_queue_receiver("orders")
with receiver:
    messages = receiver.receive_messages(max_message_count=10, max_wait_time=5)
    for message in messages:
        print(message)
        receiver.complete_message(message)
```

#### .NET

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```csharp
using Azure.Identity;
using Azure.Messaging.ServiceBus;

var credential = new DefaultAzureCredential();
var fullyQualifiedNamespace = $"{Environment.GetEnvironmentVariable("SERVICEBUS_NAMESPACE")}.servicebus.windows.net";
var client = new ServiceBusClient(fullyQualifiedNamespace, credential);

// Send
var sender = client.CreateSender("orders");
await sender.SendMessageAsync(new ServiceBusMessage("{\"orderId\": \"123\"}"));

// Receive
var receiver = client.CreateReceiver("orders");
var messages = await receiver.ReceiveMessagesAsync(maxMessages: 10);
foreach (var message in messages)
{
    await receiver.CompleteMessageAsync(message);
}
```

> 💡 **Required Permissions:**
> - `Azure Service Bus Data Sender` (69a216fc-b8fb-44d8-bc22-1f3c2cd27a39) - for sending
> - `Azure Service Bus Data Receiver` (4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0) - for receiving

### Connection String (Legacy)

#### Node.js

```javascript
const { ServiceBusClient } = require("@azure/service-bus");

const client = new ServiceBusClient(process.env.SERVICEBUS_CONNECTION_STRING);

// Send
const sender = client.createSender("orders");
await sender.sendMessages({ body: { orderId: "123" } });

// Receive
const receiver = client.createReceiver("orders");
const messages = await receiver.receiveMessages(10);
for (const message of messages) {
  await receiver.completeMessage(message);
}
```

#### Python

```python
from azure.servicebus import ServiceBusClient, ServiceBusMessage

client = ServiceBusClient.from_connection_string(
    os.environ["SERVICEBUS_CONNECTION_STRING"]
)
sender = client.get_queue_sender("orders")

with sender:
    sender.send_messages(ServiceBusMessage('{"orderId": "123"}'))
```

#### .NET

```csharp
var client = new ServiceBusClient(
    Environment.GetEnvironmentVariable("SERVICEBUS_CONNECTION_STRING")
);
var sender = client.CreateSender("orders");

await sender.SendMessageAsync(new ServiceBusMessage("{\"orderId\": \"123\"}"));
```

## Dead Letter Handling

```javascript
const dlqReceiver = client.createReceiver("orders", {
    subQueueType: "deadLetter"
});
```

# Azure Service Bus

Enterprise messaging with queues and pub/sub topics.

## When to Use

- Reliable message delivery
- Pub/sub messaging patterns
- Message ordering requirements
- Dead-letter handling
- Transaction support
- Enterprise integration

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Service Bus is self-contained |
| Key Vault | Store connection strings (legacy) |

## SKU Selection

| SKU | Features | Use Case |
|-----|----------|----------|
| Basic | Queues only, 256KB messages | Simple messaging |
| Standard | Topics, 256KB messages | Pub/sub patterns |
| Premium | 100MB messages, VNET, zones | Enterprise, high throughput |

## Environment Variables

### Managed Identity (Recommended)

| Variable | Value |
|----------|-------|
| `SERVICEBUS__fullyQualifiedNamespace` | `<namespace>.servicebus.windows.net` |
| `SERVICEBUS_NAMESPACE` | Namespace name (for SDK) |
| `SERVICEBUS_QUEUE` | Queue name |

**Required RBAC roles:**
- `Azure Service Bus Data Sender` (69a216fc-b8fb-44d8-bc22-1f3c2cd27a39) - for sending
- `Azure Service Bus Data Receiver` (4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0) - for receiving

### Connection String (Legacy)

| Variable | Value |
|----------|-------|
| `SERVICEBUS_CONNECTION_STRING` | Connection string (Key Vault) |
| `SERVICEBUS_NAMESPACE` | Namespace name |
| `SERVICEBUS_QUEUE` | Queue name |

## References

- [Bicep Patterns](bicep.md)
- [Messaging Patterns](patterns.md)

# SQL Database - Entra ID Authentication

## Entra ID Admin Configuration (User)

**Recommended for development** — Uses signed-in user as admin.

```bicep
param principalId string
param principalName string
@allowed(['User', 'Group', 'Application'])
param principalType string = 'User'

resource sqlServer 'Microsoft.Sql/servers@2022-05-01-preview' = {
  name: '${resourcePrefix}-sql-${uniqueHash}'
  location: location
  properties: {
    administrators: {
      administratorType: 'ActiveDirectory'
      principalType: principalType
      login: principalName
      sid: principalId
      tenantId: subscription().tenantId
      azureADOnlyAuthentication: true
    }
    minimalTlsVersion: '1.2'
  }
}
```

> ⚠️ **Warning:** If deploying from CI/CD with a service principal, set `principalType` to `'Application'`. The default `'User'` only works for interactive (human) deployments.

**Get signed-in user info:**
```bash
az ad signed-in-user show --query "{id:id, name:displayName}" -o json
```

**Set as azd environment variables:**
```bash
PRINCIPAL_INFO=$(az ad signed-in-user show --query "{id:id, name:displayName}" -o json)
azd env set AZURE_PRINCIPAL_ID $(echo $PRINCIPAL_INFO | jq -r '.id')
azd env set AZURE_PRINCIPAL_NAME $(echo $PRINCIPAL_INFO | jq -r '.name')
```

> 💡 **Tip:** Set these immediately after `azd init` to avoid deployment failures.

## Entra ID Admin Configuration (Group)

**Recommended for production** — Uses Entra group for admin access.

```bicep
resource sqlServer 'Microsoft.Sql/servers@2022-05-01-preview' = {
  name: '${resourcePrefix}-sql-${uniqueHash}'
  location: location
  properties: {
    administrators: {
      administratorType: 'ActiveDirectory'
      principalType: 'Group'
      login: 'SQL Admins'
      sid: entraGroupObjectId
      tenantId: subscription().tenantId
      azureADOnlyAuthentication: true
    }
    minimalTlsVersion: '1.2'
  }
}
```

## Managed Identity Access

Grant app managed identity access via SQL:

```sql
CREATE USER [my-container-app] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-container-app];
ALTER ROLE db_datawriter ADD MEMBER [my-container-app];
```

## Common Database Roles

| Role | Permissions |
|------|-------------|
| `db_datareader` | Read all tables |
| `db_datawriter` | Insert, update, delete |
| `db_ddladmin` | Create/modify schema |
| `db_owner` | Full access |

## Connection Strings

### Entra ID Authentication (Recommended)

> ⚠️ **MANDATORY**: When generating SQL connection strings for apps with Entra-only auth, ALWAYS include an `Authentication` parameter. Use `Authentication=Active Directory Default` for general scenarios (App Service, local dev) or `Authentication=Active Directory Managed Identity` when a user-assigned managed identity with a specific `User Id` is required (e.g., Azure Functions SQL bindings). Do NOT use manual `AccessToken` assignment, `DefaultAzureCredential().GetToken()` patterns, or bare connection strings without an authentication parameter. The `Authentication` parameter is required in both the Bicep infrastructure output (e.g., App Service `connectionStrings` property) and in any application configuration files (e.g., `appsettings.json`).

```
Server=tcp:{server}.database.windows.net,1433;Database={database};Authentication=Active Directory Default;Encrypt=True;TrustServerCertificate=False;
```

**Required for .NET applications:**
- `Microsoft.Data.SqlClient` (v5.1.0+)
- `Azure.Identity` (for local development)

### Legacy SQL Authentication (⛔ DO NOT USE - EVER)

> ❌ **PROHIBITED — NEVER generate connection strings with `User ID` and `Password` parameters, and NEVER generate `administratorLogin` or `administratorLoginPassword` Bicep properties.**
> This applies unconditionally — do not include them in any conditional, ternary, or optional branch.
> SQL admin authentication is disabled in all subscriptions with Entra-only policies and violates Azure security best practices.
> Always use an Entra ID `Authentication=Active Directory Default` or `Authentication=Active Directory Managed Identity` connection string above.

# SQL Database - Bicep Patterns

> ⛔ **CRITICAL — SQL Server Bicep MUST use Entra-only authentication. NEVER include `administratorLogin` or `administratorLoginPassword` anywhere in a Bicep file — not even inside a conditional (`condition ? { ... } : { administratorLoginPassword: ... }`) branch. If either property name appears anywhere in the file, the deployment will be rejected. Always use the pattern below.**

## Basic Setup (Entra-Only Authentication)

**Required approach** — Uses Microsoft Entra ID authentication only. Required for subscriptions with Entra-only policies; SQL admin authentication is disabled by policy in those environments.

```bicep
param principalId string
param principalName string
@allowed(['User', 'Group', 'Application'])
param principalType string = 'User'

resource sqlServer 'Microsoft.Sql/servers@2022-05-01-preview' = {
  name: '${resourcePrefix}-sql-${uniqueHash}'
  location: location
  properties: {
    administrators: {
      administratorType: 'ActiveDirectory'
      principalType: principalType
      login: principalName
      sid: principalId
      tenantId: subscription().tenantId
      azureADOnlyAuthentication: true
    }
    minimalTlsVersion: '1.2'
  }
}

resource sqlDatabase 'Microsoft.Sql/servers/databases@2022-05-01-preview' = {
  parent: sqlServer
  name: 'appdb'
  location: location
  sku: {
    name: 'Basic'
    tier: 'Basic'
  }
  properties: {
    collation: 'SQL_Latin1_General_CP1_CI_AS'
    maxSizeBytes: 2147483648  // 2 GB
  }
}

resource sqlFirewallAzure 'Microsoft.Sql/servers/firewallRules@2022-05-01-preview' = {
  parent: sqlServer
  name: 'AllowAzureServices'
  properties: {
    startIpAddress: '0.0.0.0'
    endIpAddress: '0.0.0.0'
  }
}
```

**Set Entra admin parameters:**

1. Get current user info:
```bash
az ad signed-in-user show --query "{id:id, name:displayName}" -o json
```

> ⚠️ **Warning:** If deploying from CI/CD with a service principal, set `principalType` to `'Application'`. The default `'User'` only works for interactive (human) deployments. Mismatched `principalType` causes `UnmatchedPrincipalType` errors during provisioning.

2. Set as azd environment variables:
```bash
PRINCIPAL_INFO=$(az ad signed-in-user show --query "{id:id, name:displayName}" -o json)
azd env set AZURE_PRINCIPAL_ID $(echo $PRINCIPAL_INFO | jq -r '.id')
azd env set AZURE_PRINCIPAL_NAME $(echo $PRINCIPAL_INFO | jq -r '.name')
```

> 💡 **Tip:** Set these variables immediately after `azd init` to avoid deployment failures. The Bicep `principalId` and `principalName` parameters will automatically use these environment variables.

## ⚠️ MANDATORY: Connection String with Entra Auth Parameter

> **CRITICAL:** When outputting SQL connection strings in Bicep (e.g., in App Service `connectionStrings` or as outputs), ALWAYS include an `Authentication` parameter. Use `Authentication=Active Directory Default` for general scenarios or `Authentication=Active Directory Managed Identity` when a user-assigned managed identity with a specific `User Id` is required. A bare `Server=tcp:...;Database=...;` connection string without this parameter will not authenticate via Entra ID and the app will fail to connect.

**Correct pattern in Bicep (Active Directory Default):**

```bicep
connectionStrings: [
  {
    name: 'DefaultConnection'
    connectionString: 'Server=tcp:${sqlServer.properties.fullyQualifiedDomainName},1433;Database=${sqlDatabase.name};Authentication=Active Directory Default;Encrypt=True;TrustServerCertificate=False;'
    type: 'SQLAzure'
  }
]
```

**With user-assigned managed identity:**

```bicep
connectionStrings: [
  {
    name: 'DefaultConnection'
    connectionString: 'Server=tcp:${sqlServer.properties.fullyQualifiedDomainName},1433;Database=${sqlDatabase.name};Authentication=Active Directory Managed Identity;User Id=${uamiClientId};Encrypt=True;TrustServerCertificate=False;'
    type: 'SQLAzure'
  }
]
```

> ❌ **DO NOT** generate connection strings without an `Authentication=Active Directory Default` or `Authentication=Active Directory Managed Identity` parameter.
> ❌ **DO NOT** use manual `AccessToken` assignment or `DefaultAzureCredential().GetToken()` in application code as an alternative to the connection string parameter.

## Serverless Configuration

```bicep
resource sqlDatabase 'Microsoft.Sql/servers/databases@2022-05-01-preview' = {
  parent: sqlServer
  name: 'appdb'
  location: location
  sku: {
    name: 'GP_S_Gen5'
    tier: 'GeneralPurpose'
    family: 'Gen5'
    capacity: 2
  }
  properties: {
    autoPauseDelay: 60  // minutes
    minCapacity: json('0.5')
  }
}
```

## Private Endpoint

```bicep
resource sqlPrivateEndpoint 'Microsoft.Network/privateEndpoints@2023-05-01' = {
  name: '${sqlServer.name}-pe'
  location: location
  properties: {
    subnet: {
      id: subnet.id
    }
    privateLinkServiceConnections: [
      {
        name: '${sqlServer.name}-connection'
        properties: {
          privateLinkServiceId: sqlServer.id
          groupIds: ['sqlServer']
        }
      }
    ]
  }
}
```

## ⛔ MANDATORY: SQL Data-Plane Access via postprovision Hook

> **CRITICAL:** ARM/Bicep role assignments (`SQL DB Contributor`) only grant **control-plane** access. They do **not** grant the app **data-plane** access to the database. Without the T-SQL grant below, apps using `Authentication=Active Directory Default` will crash on startup with a login failure.
>
> **When you generate SQL + Managed Identity infrastructure you MUST also:**
> 1. Add a `postprovision` hook to `azure.yaml` that runs the SQL grant script
> 2. Copy the pre-built scripts from [scripts/grant-sql-access.sh](scripts/grant-sql-access.sh) and [scripts/grant-sql-access.ps1](scripts/grant-sql-access.ps1) to `scripts/` in the user's project root

**azure.yaml hooks section (add or merge):**

```yaml
hooks:
  postprovision:
    posix:
      shell: sh
      run: ./scripts/grant-sql-access.sh
    windows:
      shell: pwsh
      run: ./scripts/grant-sql-access.ps1
```

**Copy the pre-built scripts** — Read [scripts/grant-sql-access.sh](scripts/grant-sql-access.sh) and [scripts/grant-sql-access.ps1](scripts/grant-sql-access.ps1) and write them verbatim to the project's `scripts/` folder. Do not regenerate them from scratch.

Key behaviours of the scripts:
- Installs the `rdbms-connect` Azure CLI extension if not already present (required for `az sql db query`)
- Loads `azd env get-values` safely (no `eval`)
- Grants `db_datareader` + `db_datawriter` by default (idempotent)
- Set `SQL_GRANT_DDLADMIN=true` in the azd env to also grant `db_ddladmin` (needed for EF Core migrations)
- `SERVICE_WEB_NAME` takes priority over `SERVICE_API_NAME` when resolving the app identity

> 💡 Make executable: `chmod +x scripts/*.sh`

> 💡 If the app also uses EF Core migrations, combine this with the migration hook — see the `azure-deploy` skill's `references/recipes/azd/sql-managed-identity.md`.

## Legacy SQL Authentication (⛔ DO NOT USE - EVER)

> ❌ **PROHIBITED — NEVER generate `administratorLogin` or `administratorLoginPassword` properties.**
> This applies unconditionally: do NOT include them in direct assignments, conditional expressions, ternary branches, parameter defaults, or any other construct. The **text** of these property names must not appear anywhere in a generated `.bicep` file.
> SQL admin authentication is disabled in all subscriptions with Entra-only policies and violates Azure security best practices.
> Always use the Entra-only authentication pattern at the top of this file.
>
> ❌ **DO NOT generate conditional patterns like:**
> ```bicep
> properties: useEntraAuth ? {
>   administrators: {
>     azureADOnlyAuthentication: true
>     // ...
>   }
> } : {
>   administratorLogin: sqlAdminLogin          // ❌ PROHIBITED
>   administratorLoginPassword: sqlAdminPassword  // ❌ PROHIBITED
> }
> ```
> Use only the unconditional Entra-only pattern. No fallback. No toggle. No conditional.

# Azure SQL Database

Managed relational database with ACID compliance and full SQL Server compatibility.

## When to Use

- Relational data with ACID requirements
- Complex queries and joins
- Existing SQL Server workloads
- Reporting and analytics
- Strong schema enforcement

## Authentication

**Default:** Entra-only authentication (recommended)
- Required for subscriptions with Entra-only policies
- More secure than SQL authentication
- Eliminates password management

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| Key Vault | Store connection strings |
| Private Endpoint | Secure access (optional) |

## SKU Selection

| Tier | Use Case | Features |
|------|----------|----------|
| **Basic** | Dev/test, light workloads | 5 DTUs, 2GB |
| **Standard** | Production workloads | 10-3000 DTUs |
| **Premium** | High-performance | In-memory OLTP |
| **Serverless** | Variable workloads | Auto-pause, auto-scale |
| **Hyperscale** | Large databases | 100TB+, instant backup |

## Environment Variables

| Variable | Value | When to Set |
|----------|-------|-------------|
| `AZURE_PRINCIPAL_ID` | Current user's object ID | After `azd init`, before `azd provision` |
| `AZURE_PRINCIPAL_NAME` | Current user's display name | After `azd init`, before `azd provision` |
| `SQL_SERVER` | `{server}.database.windows.net` | Runtime (from Bicep outputs) |
| `SQL_DATABASE` | Database name | Runtime (from Bicep outputs) |
| `SQL_CONNECTION_STRING` | Full connection string (Key Vault) | Runtime (from Bicep outputs) |

**Set principal variables:**
```bash
PRINCIPAL_INFO=$(az ad signed-in-user show --query "{id:id, name:displayName}" -o json)
azd env set AZURE_PRINCIPAL_ID $(echo $PRINCIPAL_INFO | jq -r '.id')
azd env set AZURE_PRINCIPAL_NAME $(echo $PRINCIPAL_INFO | jq -r '.name')
```

## References

- [Bicep Patterns](bicep.md)
- [Entra ID Auth](auth.md)
- [SDK Patterns](sdk.md)

# SQL Database - SDK Patterns

## Node.js (mssql)

```javascript
const sql = require('mssql');

const config = {
  server: process.env.SQL_SERVER,
  database: process.env.SQL_DATABASE,
  authentication: {
    type: 'azure-active-directory-default'
  },
  options: {
    encrypt: true
  }
};

const pool = await sql.connect(config);
```

## Python (pyodbc)

> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../../auth-best-practices.md) for production patterns.

```python
import pyodbc
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default")

conn = pyodbc.connect(
    f"Driver={{ODBC Driver 18 for SQL Server}};"
    f"Server={os.environ['SQL_SERVER']};"
    f"Database={os.environ['SQL_DATABASE']};"
    f"Authentication=ActiveDirectoryMsi"
)
```

## .NET (Entity Framework Core)

**Required NuGet Packages:**
```bash
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.Data.SqlClient --version 5.1.0
dotnet add package Azure.Identity
```

**Connection string (Entra ID):**
```
Server=tcp:{server}.database.windows.net,1433;Database={database};Authentication=Active Directory Default;Encrypt=True;
```

**Configuration:**
```csharp
services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(
        Configuration.GetConnectionString("DefaultConnection"),
        sqlOptions => sqlOptions.EnableRetryOnFailure()
    ));
```

**appsettings.json:**
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=tcp:myserver.database.windows.net,1433;Database=mydb;Authentication=Active Directory Default;Encrypt=True;"
  }
}
```

## Connection String Format

```
Server=tcp:{server}.database.windows.net,1433;Database={database};Authentication=Active Directory Default;Encrypt=True;
```

# Static Web Apps - Bicep Patterns

## Basic Resource

```bicep
resource staticWebApp 'Microsoft.Web/staticSites@2022-09-01' = {
  name: '${resourcePrefix}-${serviceName}-${uniqueHash}'
  location: location
  sku: {
    name: 'Standard'
    tier: 'Standard'
  }
  properties: {
    buildProperties: {
      appLocation: '/'
      apiLocation: 'api'
      outputLocation: 'dist'
    }
  }
}
```

## Custom Domain

```bicep
resource customDomain 'Microsoft.Web/staticSites/customDomains@2022-09-01' = {
  parent: staticWebApp
  name: 'www.example.com'
  properties: {}
}
```

## Application Settings

For the integrated API:

```bicep
resource staticWebAppSettings 'Microsoft.Web/staticSites/config@2022-09-01' = {
  parent: staticWebApp
  name: 'appsettings'
  properties: {
    DATABASE_URL: '@Microsoft.KeyVault(VaultName=${keyVault.name};SecretName=db-url)'
  }
}
```

## Deployment Token

> ⚠️ **Security Warning:** Do NOT expose deployment tokens in Bicep outputs.

See [deployment.md](deployment.md) for secure token handling.

# Static Web Apps - Deployment

## azd Deploy (Default)

Standard deployment via Azure Developer CLI:

```bash
azd deploy
```

## GitHub-Linked Deployments

For CI/CD builds on Azure (instead of azd deploy):

```bicep
properties: {
  repositoryUrl: 'https://github.com/owner/repo'
  branch: 'main'
  buildProperties: {
    appLocation: 'src'
    apiLocation: 'api'
    outputLocation: 'dist'
  }
}
```

## Deployment Token

> ⚠️ **Security Warning:** Do NOT expose deployment tokens in ARM/Bicep outputs. Deployment outputs are visible in Azure portal deployment history and logs.

**Recommended approach** - retrieve token via Azure CLI and store directly in secret store:

```bash
# Capture token to variable (never echo or log)
DEPLOYMENT_TOKEN=$(az staticwebapp secrets list --name <app-name> --query "properties.apiKey" -o tsv)

# Store directly in Key Vault
az keyvault secret set --vault-name <vault-name> --name swa-deployment-token --value "$DEPLOYMENT_TOKEN" --output none
```

**Do NOT do this** (exposes token in deployment history):
```bicep
// ❌ INSECURE - token visible in deployment history
// output deploymentToken string = staticWebApp.listSecrets().properties.apiKey
```

## Terraform Deployment

> ⚠️ **Use `azurerm_static_web_app`** — NOT Storage Account `static_website`.
> Storage Account static websites require anonymous blob access, which is blocked
> by enterprise Azure Policies. See [terraform.md](terraform.md) for correct patterns.

Terraform-based deployments use `azd deploy` the same way as Bicep:

```bash
azd deploy
```

The `azd-service-name` tag on the `azurerm_static_web_app` resource tells azd where to deploy.

**Do NOT do this** (exposes token in Terraform state):
```hcl
# ❌ INSECURE - token stored in Terraform state
# output "deployment_token" {
#   value     = azurerm_static_web_app.web.api_key
#   sensitive = true
# }
```

# Azure Static Web Apps

Serverless hosting for static sites and SPAs with integrated APIs.

## When to Use

- Single Page Applications (React, Vue, Angular)
- Static sites (HTML/CSS/JS)
- JAMstack applications
- Sites with serverless API backends
- Documentation sites

## Service Type in azure.yaml

```yaml
services:
  my-web:
    host: staticwebapp
    project: ./src/web
```

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Static Web Apps is fully managed |
| Application Insights | Monitoring (optional) |

## SKU Selection

| SKU | Features |
|-----|----------|
| Free | 2 custom domains, 0.5GB storage, shared bandwidth |
| Standard | 5 custom domains, 2GB storage, SLA, auth customization |

## Build Configuration

| Framework | outputLocation |
|-----------|----------------|
| React | `build` |
| Vue | `dist` |
| Angular | `dist/my-app` |
| Next.js (Static) | `out` |

## API Integration

Integrated Functions API structure:

```
project/
├── src/           # Frontend
└── api/           # Azure Functions API
    ├── hello/
    │   └── index.js
    └── host.json
```

## References

- [Region Availability](region-availability.md)
- [Bicep Patterns](bicep.md)
- [Terraform Patterns](terraform.md)
- [Routing and Auth](routing.md)
- [Deployment](deployment.md)

# SWA Region Availability

⚠️ **NOT available in many common regions** — Check before deployment.

| ✅ Available | ❌ NOT Available (will FAIL) |
|-------------|------------------------------|
| `westus2` | `eastus` |
| `centralus` | `northeurope` |
| `eastus2` | `southeastasia` |
| `westeurope` | `uksouth` |
| `eastasia` | `canadacentral` |
| | `australiaeast` |
| | `westus3` |

## Recommended Regions

| Pattern | Use |
|---------|-----|
| SWA only | `westus2`, `centralus`, `eastus2`, `westeurope`, `eastasia` |
| SWA + backend | `westus2`, `centralus`, `eastus2`, `westeurope`, `eastasia` |
| SWA + Azure OpenAI | `eastus2` (only region with full overlap) |

# Static Web Apps - Routing & Authentication

## Route Configuration

Create `staticwebapp.config.json` in the app root:

```json
{
  "routes": [
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/api/*", "/*.{png,jpg,gif}"]
  },
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}
```

## Authentication

### Built-in Providers

```json
{
  "routes": [
    {
      "route": "/admin/*",
      "allowedRoles": ["admin"]
    }
  ],
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/{tenant-id}",
          "clientIdSettingName": "AAD_CLIENT_ID",
          "clientSecretSettingName": "AAD_CLIENT_SECRET"
        }
      }
    }
  }
}
```

### Supported Providers

- Azure Active Directory / Entra ID
- GitHub
- Twitter
- Custom OpenID Connect

## Role-Based Access

```json
{
  "routes": [
    { "route": "/admin/*", "allowedRoles": ["admin"] },
    { "route": "/account/*", "allowedRoles": ["authenticated"] },
    { "route": "/*", "allowedRoles": ["anonymous"] }
  ]
}
```

# Static Web Apps — Terraform Patterns — REFERENCE ONLY

> ⛔ **DO NOT COPY THIS CODE DIRECTLY**
>
> This file contains **reference patterns** for understanding Azure Static Web Apps Terraform structure.
> Infrastructure for Static Web Apps must be composed using the Azure Prepare skill workflow, not copied directly from this reference.
>
> When composing infrastructure:
> - Start from an approved base template for Static Web Apps defined by your platform or template team.
> - Use `azurerm_static_web_app` — **NEVER** use Storage Account `static_website` for static web app hosting.
>
> Hand-writing Terraform from these patterns will result in missing tags, broken azd deploy, and policy violations.

> ⚠️ **WARNING: Do NOT use Storage Account static website hosting.**
> Storage Account `static_website` requires anonymous blob access, which violates
> enterprise Azure Policies (`RequestDisallowedByPolicy: "Anonymous blob access is not allowed"`).
> Always use `azurerm_static_web_app` instead — it is fully managed and policy-compliant.

## Basic Resource

```hcl
resource "azurerm_static_web_app" "web" {
  name                = "swa-${var.environment_name}-${var.service_name}-${var.unique_hash}"
  resource_group_name = azurerm_resource_group.main.name
  location            = var.location

  # sku_tier defaults to "Free"; set to "Standard" for production features
  sku_tier = "Standard"

  # Required for azd deploy to find this resource
  tags = merge(var.tags, {
    "azd-service-name" = var.service_name
  })
}
```

> ⚠️ **Region availability is limited.** Check [region-availability.md](region-availability.md) before selecting a region.

> 💡 **Key Points:**
> - No Storage Account, Service Plan, or other supporting resources required
> - Static Web Apps is a fully managed service — storage is built-in
> - The `azd-service-name` tag is **required** for `azd deploy` to locate the resource

## Custom Domain

```hcl
resource "azurerm_static_web_app_custom_domain" "example" {
  static_web_app_id = azurerm_static_web_app.web.id
  domain_name       = "www.example.com"
  validation_type   = "cname-delegation"
}
```

## Application Settings

For the integrated API backend:

```hcl
resource "azurerm_static_web_app_function_app_registration" "api" {
  static_web_app_id = azurerm_static_web_app.web.id
  function_app_id   = azurerm_linux_function_app.api.id
}
```

Environment variables for the SWA (available to both frontend and managed Functions API):

```hcl
resource "azurerm_static_web_app" "web" {
  # ... (base configuration from above)

  app_settings = {
    "DATABASE_URL" = "@Microsoft.KeyVault(VaultName=${azurerm_key_vault.kv.name};SecretName=db-url)"
  }
}
```

## Outputs

```hcl
output "WEB_URL" {
  value = azurerm_static_web_app.web.default_host_name
}

output "STATIC_WEB_APP_NAME" {
  value = azurerm_static_web_app.web.name
}
```

> 💡 **Tip:** Output names in UPPERCASE are automatically set as azd environment variables.

## Deployment Token

> ⚠️ **Security Warning:** Do NOT expose deployment tokens in Terraform outputs.

See [deployment.md](deployment.md) for secure token handling.

## azure.yaml Integration

```yaml
services:
  web:
    project: ./src/web
    language: js
    host: staticwebapp
    dist: dist
```

## References

- [AZD + Terraform](../../recipes/azd/terraform.md) — Full azd+Terraform project setup
- [Region Availability](region-availability.md) — SWA is NOT available in all regions
- [Routing and Auth](routing.md)
- [Deployment](deployment.md)

# Storage - Access Patterns

## Prerequisites for Granting Storage Access

> ⚠️ **Important**: To assign storage roles to managed identities, you need:
> - **User Access Administrator** or **Owner** role on the Storage Account (or parent resource group/subscription)
> - The role must include the `Microsoft.Authorization/roleAssignments/write` permission

**Common scenarios**:
- Granting Storage Blob Data Owner to a Web App or Function App's managed identity (System Assigned or User Assigned)
- Adding read/write access to blobs, queues, and tables for application workloads
- Allowing user identities (developers, data admins) access in dev/test environments
- Allowing applications to access storage using managed identity instead of connection strings

**Scope best practices**:
- Grant roles at the **smallest scope possible** (e.g., specific storage account, not resource group or subscription)
- Avoid broad scopes (Resource Group, Subscription, Tenant) unless absolutely necessary
- Prefer resource-level assignments for production workloads

**Managed identity types**:
- **System Assigned**: Automatically created with the resource (Web App, Function). Default when using `DefaultAzureCredential`.
- **User Assigned**: Standalone identity that can be shared across resources. Requires additional configuration:
  - Set `AZURE_CLIENT_ID` app setting to the User Assigned Managed Identity's client ID
  - Configure identity in Bicep with both `type: 'SystemAssigned, UserAssigned'` and `userAssignedIdentities`

If you encounter `AuthorizationFailed` errors when assigning roles, ensure you have User Access Administrator or Owner permissions at the target scope.

## Managed Identity Role Assignment

```bicep
resource storageRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storageAccount.id, principalId, 'Storage Blob Data Contributor')
  scope: storageAccount
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}
```

## Storage Roles

| Role | Permissions |
|------|-------------|
| Storage Blob Data Reader | Read blobs |
| Storage Blob Data Contributor | Read/write blobs |
| Storage Queue Data Contributor | Read/write queues |
| Storage Table Data Contributor | Read/write tables |

## SDK Connection Patterns

### Node.js

```javascript
const { BlobServiceClient } = require("@azure/storage-blob");

const blobServiceClient = BlobServiceClient.fromConnectionString(
  process.env.AZURE_STORAGE_CONNECTION_STRING
);
const containerClient = blobServiceClient.getContainerClient("uploads");
```

### Python

```python
from azure.storage.blob import BlobServiceClient

blob_service_client = BlobServiceClient.from_connection_string(
    os.environ["AZURE_STORAGE_CONNECTION_STRING"]
)
container_client = blob_service_client.get_container_client("uploads")
```

### .NET

```csharp
var blobServiceClient = new BlobServiceClient(
    Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING")
);
var containerClient = blobServiceClient.GetBlobContainerClient("uploads");
```

## Managed Identity Access

Use `DefaultAzureCredential` for local development (in production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../../auth-best-practices.md)):

```javascript
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const client = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);
```

# Storage - Bicep Patterns

## Storage Account

```bicep
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: '${resourcePrefix}stor${uniqueHash}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
    allowBlobPublicAccess: false
    minimumTlsVersion: 'TLS1_2'
    supportsHttpsTrafficOnly: true
  }
}
```

## Blob Container

```bicep
resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-01-01' = {
  parent: storageAccount
  name: 'default'
  properties: {
    deleteRetentionPolicy: {
      enabled: true
      days: 7
    }
  }
}

resource container 'Microsoft.Storage/storageAccounts/blobServices/containers@2023-01-01' = {
  parent: blobService
  name: 'uploads'
  properties: {
    publicAccess: 'None'
  }
}
```

## Queue

```bicep
resource queueService 'Microsoft.Storage/storageAccounts/queueServices@2023-01-01' = {
  parent: storageAccount
  name: 'default'
}

resource queue 'Microsoft.Storage/storageAccounts/queueServices/queues@2023-01-01' = {
  parent: queueService
  name: 'orders'
}
```

## Table

```bicep
resource tableService 'Microsoft.Storage/storageAccounts/tableServices@2023-01-01' = {
  parent: storageAccount
  name: 'default'
}

resource table 'Microsoft.Storage/storageAccounts/tableServices/tables@2023-01-01' = {
  parent: tableService
  name: 'logs'
}
```

## File Share

```bicep
resource fileService 'Microsoft.Storage/storageAccounts/fileServices@2023-01-01' = {
  parent: storageAccount
  name: 'default'
}

resource fileShare 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-01-01' = {
  parent: fileService
  name: 'shared'
  properties: {
    shareQuota: 100  // GB
  }
}
```

# Azure Storage

Scalable cloud storage for blobs, files, queues, and tables.

## When to Use

- Blob storage (files, images, videos)
- File shares (SMB/NFS)
- Queue storage (simple messaging)
- Table storage (NoSQL key-value)
- Static website hosting

## Required Supporting Resources

| Resource | Purpose |
|----------|---------|
| None required | Storage is self-contained |
| Key Vault | Store connection strings |
| Private Endpoint | Secure access (optional) |

## SKU Selection

| SKU | Replication | Use Case |
|-----|-------------|----------|
| Standard_LRS | Local (3 copies) | Dev/test, non-critical |
| Standard_ZRS | Zone-redundant | Production, regional HA |
| Standard_GRS | Geo-redundant | DR requirements |
| Premium_LRS | Premium SSD | High performance |

## Storage Types

| Type | Best For |
|------|----------|
| Blob | Files, images, videos, backups, logs |
| Queue | Simple message queuing, decoupling |
| Table | NoSQL key-value data |
| File Share | Lift-and-shift, SMB/NFS access |

## Access Tiers

| Tier | Use Case |
|------|----------|
| Hot | Frequent access |
| Cool | Infrequent access (30+ days) |
| Archive | Rare access (180+ days) |

## Environment Variables

| Variable | Value |
|----------|-------|
| `AZURE_STORAGE_CONNECTION_STRING` | Connection string (Key Vault) |
| `AZURE_STORAGE_ACCOUNT` | Account name |
| `AZURE_STORAGE_CONTAINER` | Container name |

## References

- [Bicep Patterns](bicep.md)
- [Access Patterns](access.md)