# AZCLI Validation Errors

| Error | Fix |
|-------|-----|
| `AADSTS700082: Token expired` | `az login` |
| `Please run 'az login'` | `az login` |
| `AADSTS50076: MFA required` | `az login --use-device-code` |
| `AuthorizationFailed` | Request Contributor role |
| `npm ci` fails with `missing: package-lock.json` | Run `npm install --package-lock-only` in the service directory before building |
| `Template validation failed` | Check Bicep syntax |

## Debug

```bash
az <command> --verbose --debug
```

# AZCLI Validation

Validation steps for Azure CLI deployments.

## Prerequisites

- `./infra/main.bicep` exists
- Docker available (if containerized)

## Validation Steps

- [ ] 1. Core Validation (CLI, auth, build, validate, what-if) — run [`validate-deployment` script](../scripts/validate-deployment.sh)
- [ ] 2. Docker Build (if containerized)
- [ ] 3. Azure Policy Validation

## Validation Details

### 1. Core Validation Script

The core validation checks are a fixed, deterministic sequence. Run the shared
**validate-deployment** helper instead of executing and parsing each command by hand. It
confirms the Azure CLI is installed and authenticated, compiles the Bicep template
(`az bicep build`), validates it against the target scope (`az deployment ... validate`),
and runs a what-if preview — printing a compact PASS/FAIL summary plus a what-if change
count (Create/Modify/Delete).

- Bash: [`../scripts/validate-deployment.sh`](../scripts/validate-deployment.sh)
- PowerShell: [`../scripts/validate-deployment.ps1`](../scripts/validate-deployment.ps1)

**Subscription scope:**

```bash
../scripts/validate-deployment.sh --scope sub --location <location>
```
```powershell
../scripts/validate-deployment.ps1 -Scope sub -Location <location>
```

**Resource group scope:**

```bash
../scripts/validate-deployment.sh --scope group --resource-group <rg-name>
```
```powershell
../scripts/validate-deployment.ps1 -Scope group -ResourceGroup <rg-name>
```

Defaults: `--template ./infra/main.bicep`, `--parameters ./infra/main.parameters.json`
(skipped if absent). Pass `--subscription <id>` to target a specific subscription.

**Interpreting results:**

- `OVERALL: PASS` — all five checks passed; record the summary in Section 7 (Validation Proof).
- Any step `FAIL` — the script prints the failing command's error. Remediate:
  - **Authenticated** fails → `az login`, then `az account set --subscription <id>`.
  - **Azure CLI installed** fails → install via `mcp_azure_mcp_extension_cli_install(cli-type: "az")`.
  - Otherwise see [Error handling](./errors.md).

### 2. Docker Build (if containerized)

**Before building**, validate the Docker build context:

1. Read the `Dockerfile` in `./src/<service>`
2. If the Dockerfile contains `npm ci`, verify `package-lock.json` exists in the same directory
3. If `package-lock.json` is missing, generate it:

```bash
cd ./src/<service>
npm install --package-lock-only
```

**Then build:**

```bash
docker build -t <image>:test ./src/<service>
```

### 3. Azure Policy Validation

See [Policy Validation Guide](../../policy-validation.md) for instructions on retrieving and validating Azure policies for your subscription.

## References

- [Error handling](./errors.md)

## Next

All checks pass → **azure-deploy**

# Aspire Validation

> ⚠️ **Only load this file when the project is a .NET Aspire application.**

Validation steps specific to .NET Aspire projects deployed via AZD.

## Detection

A project is Aspire-based if any of these are true:

| Indicator | Check |
|-----------|-------|
| AppHost project | `find . -name "*.AppHost.csproj"` |
| Aspire.Hosting package | `grep -r "Aspire.Hosting" . --include="*.csproj"` |

**If none found → skip this file entirely.**

---

## Pre-Provisioning: Functions Secret Storage

> ⚠️ **CRITICAL — Must run BEFORE `azd provision`.**

Check if the project uses Azure Functions within Aspire and ensure `AzureWebJobsSecretStorageType` is configured.
See [Aspire Functions Secrets Reference](../../aspire-functions-secrets.md) for detection commands, fix examples, and full details.

**If `AddAzureFunctionsProject` is NOT found**, skip this section.

---

## Post-Provisioning: Container Apps Environment Variables

> ⚠️ **CRITICAL — Run AFTER `azd provision` but BEFORE `azd deploy`.**

When using Aspire with Container Apps in "limited mode" (in-memory infrastructure generation), `azd provision` creates Azure resources but doesn't automatically populate environment variables that `azd deploy` needs.

**Run the helper script** ([scripts/set-aspire-aca-env.sh](scripts/set-aspire-aca-env.sh) or [scripts/set-aspire-aca-env.ps1](scripts/set-aspire-aca-env.ps1)). It sets `AZURE_CONTAINER_REGISTRY_ENDPOINT`, `AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID`, and `MANAGED_IDENTITY_CLIENT_ID` (only the ones that are missing).

**bash:**
```bash
./scripts/set-aspire-aca-env.sh          # or: -e <azd-env-name>
```

**PowerShell:**
```powershell
./scripts/set-aspire-aca-env.ps1         # or: -Environment <azd-env-name>
```

# AZD Environment Setup

> **⛔ MANDATORY**: You MUST set up an AZD environment before running any deployment commands.

## Step 1: Check Existing Environments

```bash
azd env list
```

**If an environment is already selected** (marked with `*`), check its current values:

```bash
azd env get-values
```

If `AZURE_ENV_NAME`, `AZURE_SUBSCRIPTION_ID`, and `AZURE_LOCATION` are already set, confirm with user:

```
Question: "An AZD environment is already configured. Would you like to use it?"

  Environment: {env-name}
  Subscription: {subscription-id}
  Location: {location}

Choices: [
  "Yes, use this environment (Recommended)",
  "No, create a new environment"
]
```

If user confirms → skip to **Verify Configuration**. Otherwise → continue to Step 2.

**If NO environment exists or none is selected:**
- Continue to Step 2

---

## Step 2: Create New Environment

> **⛔ DO NOT use generic names like "dev", "prod", or "test"**
>
> These cause naming conflicts in Azure resource groups and resources. Always generate a unique name.

### Generate Suggested Name

Use this pattern:
```
{project-name}-{random-4-chars}
```

**Examples:**
- `dadjokes-x7k2`
- `todoapp-m3p9`
- `myapi-q5w8`

### Prompt User

**You MUST use `ask_user` to confirm the environment name:**

```
I need to create an AZD environment for this deployment.

Suggested name: {project-name}-{random-4-chars}

Would you like to use this name or enter a custom one?
```

### Create Environment

After user confirms:
```bash
azd env new <environment-name> --no-prompt
```

---

## Step 3: Configure Environment

Set subscription and location:

```bash
azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
azd env set AZURE_LOCATION <location>
```

---

## Verify Configuration

```bash
azd env get-values
```

Confirm these values are set:
- `AZURE_ENV_NAME`
- `AZURE_SUBSCRIPTION_ID`
- `AZURE_LOCATION`

---

## Only Then Proceed

After environment is configured, proceed with `azd up --no-prompt`.

# AZD Validation Errors

## Pre-Deployment Errors

These errors can be caught **before** running `azd up`:

| Error | Cause | Resolution |
|-------|-------|------------|
| `Please run 'az login'` | Not authenticated | `az login` or `azd auth login` |
| `No environment selected` | Missing azd environment | `azd env select <name>` or `azd env new <name> --no-prompt` |
| `no default response for prompt 'Enter a unique environment name'` | No azd environment created, or missing `-e` flag | Run `azd env new <name> --no-prompt` OR use `azd init --from-code -e <name> --no-prompt` with the `-e` flag |
| `no default response for prompt 'Enter a value for the 'environmentName'` | Environment variables not set | Run `azd env set AZURE_ENV_NAME <name>` |
| `Service not found` | Service name mismatch | Check service name in azure.yaml |
| `Invalid azure.yaml` | YAML syntax error | Fix YAML syntax |
| `Project path does not exist` | Wrong service project path | Fix service project path in azure.yaml |
| `Cannot connect to Docker daemon` | Docker not running | Start Docker Desktop |
| `npm ci` fails with `missing: package-lock.json` | Dockerfile uses `npm ci` but `package-lock.json` not in build context | Run `npm install --package-lock-only` in the service directory before building |
| `Could not find a part of the path 'infra\main.bicep'` | Missing infrastructure files | Generate infra/ folder before `azd up` |
| `Invalid resource group location '<loc>'. The Resource group already exists in location '<other>'` | RG exists in different region | Check RG location first with `az group show`, use that region or new env name |
| `expecting only '1' resource tagged with 'azd-service-name: web', but found '2'` | Multiple resources with same tag **in the same RG** | Delete duplicate or rename service |

## Static Web App Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `language 'html' is not supported` | Invalid language value | Omit `language` for pure static sites |
| `language 'static' is not supported` | Invalid language value | Omit `language` for pure static sites |
| `dist folder not found` | Wrong dist path or missing build | Check `dist` is relative to `project`; add `language: js` if build needed |
| `LocationNotAvailableForResourceType` | SWA not in region | See [Region Availability](../../region-availability.md) for valid regions |

## SWA Path Validation

Before deployment, verify:
1. `project` path exists and contains source files
2. For framework apps: `language: js` is set
3. `dist` is relative to `project` (not project root)
4. Bicep has `azd-service-name` tag matching service name

## Debug

```bash
azd <command> --debug
```

# AZD Validation

Validation steps for Azure Developer CLI projects.

## Prerequisites

- `azure.yaml` exists in project root
- Infrastructure files exist:
  - For Bicep: `./infra/` contains Bicep files
  - For Terraform: `./infra/` contains `.tf` files and `azure.yaml` has `infra.provider: terraform`

## Validation Steps

- [ ] 1. AZD Installation
- [ ] 2. Schema Validation
- [ ] 3. Environment Setup
- [ ] 4. Authentication Check
- [ ] 5. Subscription/Location Check
- [ ] 6. Aspire Pre-Provisioning Checks
- [ ] 7. Provision Preview
- [ ] 8. Build Verification
- [ ] 9. Docker Build Context Validation
- [ ] 10. Package Validation
- [ ] 11. Azure Policy Validation
- [ ] 12. Aspire Post-Provisioning Checks

## Validation Details

### 1. AZD Installation

Verify AZD is installed:

```bash
azd version
```

**If not installed:**
```
mcp_azure_mcp_extension_cli_install(cli-type: "azd")
```

### 2. Schema Validation

Validate azure.yaml against official schema:

```
mcp_azure_mcp_azd(command: "validate_azure_yaml", parameters: { path: "./azure.yaml" })
```

### 3. Environment Setup

Verify AZD environment exists and is configured. See [Environment Setup](environment.md) for detailed steps.

### 4. Authentication Check

```bash
azd auth login --check-status
```

**If not logged in:**
```bash
azd auth login
```

### 5. Subscription/Location Check

Check environment values:
```bash
azd env get-values
```

**If AZURE_SUBSCRIPTION_ID or AZURE_LOCATION not set:**

Use Azure MCP tools to list subscriptions:
```
mcp_azure_mcp_subscription_list
```

Use Azure MCP tools to list resource groups (check for conflicts):
```
mcp_azure_mcp_group_list
  subscription: <subscription-id>
```

Prompt user to confirm subscription and location before continuing.

Refer to the region availability reference to select a region supported by all services in this template:
- [Region availability](../../region-availability.md)

```bash
azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
azd env set AZURE_LOCATION <location>
```

### 6. Aspire Pre-Provisioning Checks

**If this is a .NET Aspire project** (detected by `*.AppHost.csproj` or `Aspire.Hosting` package reference), run the **Pre-Provisioning** checks in [Aspire Validation](aspire.md) before continuing. **If not Aspire, skip this step.**

### 7. Provision Preview

Validate IaC is ready (must complete without error):

```bash
azd provision --preview --no-prompt
```

> 💡 **Note:** This works for both Bicep and Terraform. azd will automatically detect the provider from `azure.yaml` and run the appropriate validation (`bicep build` or `terraform plan`).

**If `azd provision --preview` fails with `unsupported resource type`:**

⛔ **Stop deployment immediately.** Do NOT attempt to fix or work around the error.

This error means the Aspire AppHost contains custom resource types that have no Azure deployment target (e.g., `HealthChecksUI`, custom child resources, or local-only integrations). These resources are intentionally designed for local development tooling and cannot be meaningfully deployed to Azure.

**Required actions:**
1. ⛔ **Do NOT modify source code** to suppress the error (e.g., do not add `.ExcludeFromManifest()`).
2. ⛔ **Do NOT proceed with `azd provision` or `azd deploy`.**
3. ✅ Inform the user: "This application contains custom Aspire resource types (`unsupported resource type: <type-name>`) that cannot be deployed to Azure. The application is designed for local development only."
4. ✅ Record a blocker: "Deployment blocked — AppHost contains unsupported resource types with no Azure deployment target."

> ⚠️ Adding `.ExcludeFromManifest()` to suppress the error may allow provisioning to proceed, but the resulting deployment will not represent the application's actual functionality and is not a valid deployment.

### 8. Build Verification

Build the project and verify there are no errors. If the build fails, fix the issues and re-build until it succeeds. Do NOT proceed to packaging or deployment with build errors.

### 9. Docker Build Context Validation

**If any service in `azure.yaml` uses a Dockerfile** (check the service's `project` path from `azure.yaml` for a `Dockerfile`), validate the build context before packaging:

1. Read each service's `Dockerfile`
2. If the Dockerfile contains `npm ci`, verify `package-lock.json` exists in the same directory
3. If `package-lock.json` is missing, generate it in the service's `project` path directory before proceeding:

```bash
cd <service-project-path>
npm install --package-lock-only
```

> ⚠️ **Warning:** `npm ci` will fail during Docker build if `package-lock.json` is missing. This check prevents Docker build failures during `azd package` and `azd up`.

### 10. Package Validation

Confirm all services package successfully:

```bash
azd package --no-prompt
```

### 11. Azure Policy Validation

See [Policy Validation Guide](../../policy-validation.md) for instructions on retrieving and validating Azure policies for your subscription.

### 12. Aspire Post-Provisioning Checks

**If this is a .NET Aspire project**, run the **Post-Provisioning** checks in [Aspire Validation](aspire.md) before proceeding to deployment. **If not Aspire, skip this step.**

## References

- [Environment Setup](environment.md)
- [Aspire Validation](aspire.md)
- [Error Handling](./errors.md)

## Next

All checks pass → **azure-deploy**

# Bicep Validation Errors

| Error | Fix |
|-------|-----|
| `BCP035: Invalid type` | Check API version |
| `BCP037: Not a member` | Check resource schema |
| `BCP018: Expected character` | Fix syntax |
| `Module not found` | Check relative paths |
| `Template validation failed` | Review error details |

## Debug

```bash
az bicep build --file ./infra/main.bicep 2>&1
```

# Bicep Validation

Validation steps for standalone Bicep deployments.

## Prerequisites

- `./infra/main.bicep` exists
- `./infra/main.parameters.json` exists
- Azure CLI authenticated

## Validation Steps

- [ ] 1. Core Validation (CLI, auth, build, validate, what-if) — run [`validate-deployment` script](../scripts/validate-deployment.sh)
- [ ] 2. Linting (optional)
- [ ] 3. Azure Policy Validation

## Validation Details

### 1. Core Validation Script

The core validation checks are a fixed, deterministic sequence — identical to the AZCLI
recipe. Run the shared **validate-deployment** helper instead of executing and parsing each
command by hand. It confirms the Azure CLI is installed and authenticated, compiles the Bicep
template (`az bicep build`), validates it against the target scope (`az deployment ...
validate`), and runs a what-if preview — printing a compact PASS/FAIL summary plus a what-if
change count (Create/Modify/Delete).

- Bash: [`../scripts/validate-deployment.sh`](../scripts/validate-deployment.sh)
- PowerShell: [`../scripts/validate-deployment.ps1`](../scripts/validate-deployment.ps1)

**Subscription scope:**

```bash
../scripts/validate-deployment.sh --scope sub --location <location>
```
```powershell
../scripts/validate-deployment.ps1 -Scope sub -Location <location>
```

**Resource group scope:**

```bash
../scripts/validate-deployment.sh --scope group --resource-group <rg-name>
```
```powershell
../scripts/validate-deployment.ps1 -Scope group -ResourceGroup <rg-name>
```

Defaults: `--template ./infra/main.bicep`, `--parameters ./infra/main.parameters.json`
(skipped if absent). Pass `--subscription <id>` to target a specific subscription.

**Interpreting results:**

- `OVERALL: PASS` — all checks passed; record the summary in Section 7 (Validation Proof).
- Any step `FAIL` — the script prints the failing command's error. If **Authenticated** fails,
  run `az login`. Otherwise see [Error handling](./errors.md).

### 2. Linting (optional)

Use Bicep linter rules:

```bash
az bicep lint --file ./infra/main.bicep
```

### 3. Azure Policy Validation

See [Policy Validation Guide](../../policy-validation.md) for instructions on retrieving and validating Azure policies for your subscription.

## Checklist

| Check | Command | Pass |
|-------|---------|------|
| Core validation (CLI, auth, build, validate, what-if) | `validate-deployment` script | ☐ |
| Policies validated | MCP Policy tool | ☐ |

## References

- [Error handling](./errors.md)

## Next

All checks pass → **azure-deploy**

#!/usr/bin/env bash
# validate-deployment.sh
# Runs the standard Azure CLI pre-deployment validation sequence for a Bicep
# template and reports PASS/FAIL for each step. Shared by the AZCLI and Bicep
# validation recipes.
#
# Steps (in order):
#   1. az version         - Azure CLI is installed
#   2. az account show    - authenticated to Azure
#   3. az bicep build     - template compiles cleanly
#   4. az deployment ... validate  - template validates against the target scope
#   5. az deployment ... what-if   - preview changes (with a Create/Modify/Delete summary)
#
# Usage:
#   ./validate-deployment.sh --scope sub   --location <location>       [options]
#   ./validate-deployment.sh --scope group --resource-group <rg-name>  [options]
#
# Options:
#   --scope <sub|group>       Deployment scope (required)
#   --location <location>     Location (required when --scope sub)
#   --resource-group <name>   Resource group (required when --scope group)
#   --template <path>         Bicep template (default: ./infra/main.bicep)
#   --parameters <path>       Parameters file (default: ./infra/main.parameters.json;
#                             skipped automatically if the file does not exist)
#   --subscription <id>       Subscription to target (optional)
#
# Examples:
#   ./validate-deployment.sh --scope sub --location eastus
#   ./validate-deployment.sh --scope group --resource-group my-rg \
#       --template ./infra/main.bicep --parameters ./infra/main.parameters.json
#
# Exit codes:
#   0 - every validation step passed
#   1 - a validation step failed
#   2 - usage / argument error (unknown or valueless option, missing required flag)

set -uo pipefail

# Ensure an option that consumes a value actually has one ($@ = remaining args).
need_val() {
    [ "$#" -ge 2 ] || { echo "ERROR: $1 requires a value." >&2; exit 2; }
}

SCOPE=""
LOCATION=""
RESOURCE_GROUP=""
TEMPLATE="./infra/main.bicep"
PARAMETERS="./infra/main.parameters.json"
SUBSCRIPTION=""

while [ $# -gt 0 ]; do
    case "$1" in
        --scope)          need_val "$@"; SCOPE="$2"; shift 2 ;;
        --location)       need_val "$@"; LOCATION="$2"; shift 2 ;;
        --resource-group) need_val "$@"; RESOURCE_GROUP="$2"; shift 2 ;;
        --template)       need_val "$@"; TEMPLATE="$2"; shift 2 ;;
        --parameters)     need_val "$@"; PARAMETERS="$2"; shift 2 ;;
        --subscription)   need_val "$@"; SUBSCRIPTION="$2"; shift 2 ;;
        -h|--help)
            grep '^#' "$0" | grep -v '^#!' | sed 's/^# \{0,1\}//'
            exit 0 ;;
        *)
            echo "Unknown argument: $1" >&2
            exit 2 ;;
    esac
done

# Validate arguments
if [ "$SCOPE" != "sub" ] && [ "$SCOPE" != "group" ]; then
    echo "ERROR: --scope must be 'sub' or 'group'." >&2
    exit 2
fi
if [ "$SCOPE" = "sub" ] && [ -z "$LOCATION" ]; then
    echo "ERROR: --location is required when --scope is 'sub'." >&2
    exit 2
fi
if [ "$SCOPE" = "group" ] && [ -z "$RESOURCE_GROUP" ]; then
    echo "ERROR: --resource-group is required when --scope is 'group'." >&2
    exit 2
fi

# Build shared argument arrays
SUB_ARGS=()
[ -n "$SUBSCRIPTION" ] && SUB_ARGS=(--subscription "$SUBSCRIPTION")

PARAM_ARGS=()
if [ -f "$PARAMETERS" ]; then
    PARAM_ARGS=(--parameters "$PARAMETERS")
else
    echo "NOTE: parameters file '$PARAMETERS' not found; validating without --parameters."
fi

if [ "$SCOPE" = "sub" ]; then
    SCOPE_TARGET_ARGS=(--location "$LOCATION")
    SCOPE_DESC="subscription (location: $LOCATION)"
else
    SCOPE_TARGET_ARGS=(--resource-group "$RESOURCE_GROUP")
    SCOPE_DESC="resource group '$RESOURCE_GROUP'"
fi

# Track overall result (0 = all passed, 1 = at least one failure).
OVERALL=0

echo "=== Azure deployment validation ==="
echo "Template:   $TEMPLATE"
echo "Scope:      $SCOPE_DESC"
echo ""

# Step 1: Azure CLI installed
echo "--- Step 1: Azure CLI installed (az version) ---"
if az version >/dev/null 2>&1; then
    echo "PASS: Azure CLI is installed."
else
    echo "FAIL: Azure CLI not found. Install it, then re-run."
    # Nothing else can run without the CLI.
    echo ""
    echo "OVERALL: FAIL"
    exit 1
fi
echo ""

# Step 2: Authenticated
echo "--- Step 2: Authenticated (az account show) ---"
if ACCOUNT_NAME=$(az account show "${SUB_ARGS[@]}" --query name -o tsv 2>/dev/null); then
    echo "PASS: Authenticated (subscription: ${ACCOUNT_NAME:-unknown})."
else
    echo "FAIL: Not logged in. Run 'az login' (and 'az account set --subscription <id>')."
    OVERALL=1
fi
echo ""

# Step 3: Bicep compilation
echo "--- Step 3: Bicep compilation (az bicep build) ---"
BUILD_OUTPUT=$(az bicep build --file "$TEMPLATE" 2>&1)
BUILD_RC=$?
if [ $BUILD_RC -eq 0 ]; then
    echo "PASS: Template compiles cleanly."
else
    echo "FAIL: Bicep compilation errors:"
    echo "$BUILD_OUTPUT"
    OVERALL=1
fi
echo ""

# Step 4: Template validation
echo "--- Step 4: Template validation (az deployment $SCOPE validate) ---"
VALIDATE_OUTPUT=$(az deployment "$SCOPE" validate "${SCOPE_TARGET_ARGS[@]}" \
    --template-file "$TEMPLATE" \
    "${PARAM_ARGS[@]}" "${SUB_ARGS[@]}" 2>&1)
VALIDATE_RC=$?
if [ $VALIDATE_RC -eq 0 ]; then
    echo "PASS: Template validated against the target scope."
else
    echo "FAIL: Template validation errors:"
    echo "$VALIDATE_OUTPUT"
    OVERALL=1
fi
echo ""

# Step 5: What-if preview
echo "--- Step 5: What-if preview (az deployment $SCOPE what-if) ---"
WHATIF_OUTPUT=$(az deployment "$SCOPE" what-if "${SCOPE_TARGET_ARGS[@]}" \
    --template-file "$TEMPLATE" \
    "${PARAM_ARGS[@]}" "${SUB_ARGS[@]}" 2>&1)
WHATIF_RC=$?
if [ $WHATIF_RC -eq 0 ]; then
    CREATE_COUNT=$(echo "$WHATIF_OUTPUT" | grep -c '^[[:space:]]*+ ')
    MODIFY_COUNT=$(echo "$WHATIF_OUTPUT" | grep -c '^[[:space:]]*~ ')
    DELETE_COUNT=$(echo "$WHATIF_OUTPUT" | grep -c '^[[:space:]]*- ')
    echo "PASS: What-if completed. Changes -> Create: $CREATE_COUNT, Modify: $MODIFY_COUNT, Delete: $DELETE_COUNT"
else
    echo "FAIL: What-if errors:"
    echo "$WHATIF_OUTPUT"
    OVERALL=1
fi
echo ""

# Overall result
if [ $OVERALL -eq 0 ]; then
    echo "OVERALL: PASS"
else
    echo "OVERALL: FAIL"
fi
exit $OVERALL

# Terraform Validation Errors

| Error | Fix |
|-------|-----|
| `Backend init failed` | Check storage account access |
| `Provider version conflict` | Update required_providers |
| `State lock failed` | Wait or force unlock |
| `Validation failed` | Check terraform validate output |
| `Error: Cycle:` | See [Cycle Errors](#cycle-errors) below |

## Cycle Errors

`terraform validate` reports a cycle when two or more resources reference each other's attributes, creating a circular dependency.

### Common Pattern: CORS Cross-Reference

Multi-service App Service deployments often introduce a cycle when the API's CORS configuration references the frontend hostname and the frontend's app settings reference the API hostname:

```
Error: Cycle: azurerm_linux_web_app.frontend, azurerm_linux_web_app.api
```

**Cause — circular attribute references:**

```hcl
# API references frontend.default_hostname in CORS
resource "azurerm_linux_web_app" "api" {
  site_config {
    cors {
      allowed_origins = ["https://${azurerm_linux_web_app.frontend.default_hostname}"]
    }
  }
}

# Frontend references api.default_hostname in app_settings
resource "azurerm_linux_web_app" "frontend" {
  app_settings = {
    API_URL = "https://${azurerm_linux_web_app.api.default_hostname}"
  }
}
```

### Fix Strategies

**Option A (recommended):** Use a Terraform variable for the frontend origin so CORS is restrictive by default and the cycle is broken. Define the variable with a sensible default and pass the real frontend URL after the first deployment:

```hcl
variable "frontend_origin" {
  type        = string
  description = "Frontend origin for API CORS. Set after first deployment."
  default     = ""
}

resource "azurerm_linux_web_app" "api" {
  site_config {
    cors {
      allowed_origins     = var.frontend_origin != "" ? [var.frontend_origin] : ["*"]
      support_credentials = var.frontend_origin != "" ? true : false
    }
  }
}
```

> ⚠️ **Warning:** If using `["*"]` as a temporary bootstrap value, you **must** set `frontend_origin` to the actual URL (e.g., `https://app-web-*.azurewebsites.net`) and re-run `terraform apply` in the same deployment session before reporting success. Do not leave wildcard CORS in a completed deployment.

**Option B:** Use `azurerm_app_service_custom_hostname_binding` or a `null_resource` with a `local-exec` provisioner to configure CORS after both resources are created, breaking the dependency chain.

**Option C:** Use `lifecycle { ignore_changes = [site_config[0].cors] }` on the API resource and configure CORS via a separate `azurerm_web_app_active_slot` or post-deployment script.

### After Fixing

1. Run `terraform fmt -recursive` to fix formatting
2. Re-run `terraform validate` to confirm the cycle is resolved
3. Run `terraform plan` to verify the configuration is correct

## Debug

```bash
TF_LOG=DEBUG terraform plan
```

# Terraform Validation

Validation steps for Terraform deployments.

## Prerequisites

- `./infra/main.tf` exists
- State backend accessible

## Run the preflight script

Run the pre-built validation script instead of executing each check by hand. It runs the
full deterministic preflight sequence in one call and prints a compact **PASS / FAIL / SKIP**
summary plus captured error text for any failed step — jump straight to remediation without
re-parsing raw command output.

| Script | Purpose |
|--------|---------|
| [`scripts/validate-terraform.sh`](scripts/validate-terraform.sh) | Bash preflight runner |
| [`scripts/validate-terraform.ps1`](scripts/validate-terraform.ps1) | PowerShell preflight runner |

The script runs, in order: Terraform installed → Azure CLI installed → authenticated
(`az account show`) → `terraform init` → `fmt -check` → `validate` → `plan` →
`state list` → Go-style `{{ .Env.* }}` template-variable scan → `main.tfvars.json`
JSON-syntax check. A subscription-selection step is added when a subscription id is
supplied. It runs **every** check even if an earlier one fails, and exits non-zero when
any step fails.

**Usage:**

```bash
./scripts/validate-terraform.sh [infra-dir] [subscription-id]   # infra-dir defaults to ./infra
```
```powershell
.\scripts\validate-terraform.ps1 [-InfraDir <path>] [-SubscriptionId <id>]
```

**Examples:**

```bash
./scripts/validate-terraform.sh                 # validate ./infra
./scripts/validate-terraform.sh ./infra 00000000-0000-0000-0000-000000000000
```
```powershell
.\scripts\validate-terraform.ps1 -InfraDir ./infra
```

**Reading the output:** the summary table lists every step as `PASS`, `FAIL`, or `SKIP`
(skipped when a prerequisite such as Terraform or the infra directory is missing). Each
`FAIL` is expanded in a **FAILURE DETAILS** section with the captured error text. Fix
failed steps using the guidance below, then re-run the script.

## Remediation

The script only **runs and reports** — fixing failures is manual. Guidance per step:

### Terraform / Azure CLI not installed

- Terraform: see https://developer.hashicorp.com/terraform/install
- Azure CLI: `mcp_azure_mcp_extension_cli_install(cli-type: "az")`

### Not authenticated / wrong subscription

```bash
az login
az account set --subscription <subscription-id>
```

### Format check failed

```bash
terraform fmt -recursive
```

### Init / validate / plan / state failures

Read the captured error text in the script output, then consult
[Error handling](./errors.md).

### Azure Policy Validation

The script does not cover policy checks. See
[Policy Validation Guide](../../policy-validation.md) for retrieving and validating Azure
policies for your subscription.

### Template Variable Resolution (AZD+Terraform)

> ⚠️ **CRITICAL for azd+Terraform projects.** azd substitutes `${VAR}` references in
> `main.tfvars.json` via envsubst, but does NOT interpolate Go-style template variables
> (`{{ .Env.* }}`). Unresolved Go-style template strings passed to Terraform cause
> cascading deployment failures, state conflicts, and timeouts.

When the template-variable scan reports `FAIL`:

1. **Fix the syntax** in `main.tfvars.json` — replace `{{ .Env.VAR }}` with `${VAR}`:
   ```json
   { "environment_name": "${AZURE_ENV_NAME}", "location": "${AZURE_LOCATION}" }
   ```
2. For additional variables, use **`TF_VAR_*` environment variables**:
   ```bash
   azd env set TF_VAR_environment_name "$(azd env get-value AZURE_ENV_NAME)"
   ```
3. **Verify** that `variables.tf` declares all required variables.
4. **Re-run** the script to confirm `terraform validate` / `plan` and the scan now pass.

> Prefer putting static defaults in `variables.tf` `default` values. Using `terraform.tfvars`
> (HCL) for static defaults is acceptable if your team prefers it; this restriction is
> specifically about avoiding Go-style template expressions in `.tfvars.json` files.

## References

- [Error handling](./errors.md)

## Next

All checks pass → **azure-deploy**