fix: prevent azd+Terraform template variable interpolation failures

[tmeschter]

Summary

Fixes #1558. Addresses the azd+Terraform template variable interpolation gap that caused the terraform-azure-container-apps-deploy integration test to time out at 30 minutes.

The root cause: azure-prepare generated main.tfvars.json with Go-style template variables ({{ .Env.AZURE_ENV_NAME }}), but azd does NOT interpolate these in .tfvars.json files -- only in azure.yaml. Literal template strings were passed to Terraform, causing cascading failures (resource naming errors, state conflicts, retry spirals).

Changes

Fix 1: azure-prepare (v1.1.3 → v1.1.4) -- Prevent the problem at source

• plugin/skills/azure-prepare/references/recipes/azd/terraform.md
  • Added warning against using Go-style template variables in .tfvars.json files
  • Documented correct variable passing: azd auto-mapping, TF_VAR_* env vars, terraform.tfvars HCL
  • Removed incorrect env("DATABASE_NAME") example that encouraged template-style usage
  • Added troubleshooting entries for template interpolation failures

Fix 2: azure-validate (v1.0.3 → v1.0.4) -- Catch it before deployment

• plugin/skills/azure-validate/references/recipes/terraform/README.md
  • Added Step 10: Template Variable Resolution Check for azd+Terraform
  • Includes grep commands to detect unresolved {{ .Env.* }} patterns and .tfvars.json files
  • Provides remediation steps so the error surfaces during validation, not at deploy time

Fix 3: azure-deploy (v1.0.11 → v1.0.12) -- Document error and add pre-deploy guard

• plugin/skills/azure-deploy/references/recipes/azd/errors.md
  • Added "Unresolved Terraform Template Variables" error section with full symptom/cause/solution
• plugin/skills/azure-deploy/references/pre-deploy-checklist.md
  • Added Step 9: Verify Terraform Variable Resolution (azd+Terraform only)
• plugin/skills/azure-deploy/references/recipes/terraform/errors.md
  • Added entries for template interpolation failure and state clearing behavior

Testing

These are documentation/skill-instruction changes (no runtime code). The fixes guide the agent to:

1. Never generate main.tfvars.json with template expressions (prevention)
2. Detect unresolved template variables during azure-validate (early detection)
3. Recover correctly if the error is encountered during azure-deploy (error handling)

[Copilot]

Pull request overview

Updates the Azure skill documentation to prevent and detect azd + Terraform variable interpolation failures caused by unresolved Go-template expressions being passed into Terraform via .tfvars.json files (Fixes #1558).

Changes:

• Bumps skill versions for azure-prepare, azure-validate, and azure-deploy.
• Adds azd+Terraform guidance to prevent generating main.tfvars.json with {{ .Env.* }} templates and recommends alternative variable passing approaches.
• Adds pre-validation and pre-deploy checks plus error-recovery documentation to surface unresolved template variables earlier.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
plugin/skills/azure-validate/SKILL.md	Version bump to reflect documentation updates.
plugin/skills/azure-validate/references/recipes/terraform/README.md	Adds Step 10 to detect unresolved {{ .Env.* }} and .tfvars.json usage for azd+Terraform.
plugin/skills/azure-prepare/SKILL.md	Version bump to reflect documentation updates.
plugin/skills/azure-prepare/references/recipes/azd/terraform.md	Adds warning and revised guidance for passing variables to Terraform without template interpolation.
plugin/skills/azure-deploy/SKILL.md	Version bump to reflect documentation updates.
plugin/skills/azure-deploy/references/recipes/terraform/errors.md	Adds new Terraform error entries related to unresolved templates and state persistence behavior.
plugin/skills/azure-deploy/references/recipes/azd/errors.md	Adds a dedicated error section for unresolved Terraform template variables with remediation steps.
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	Adds a pre-deploy guard step to detect unresolved templates / main.tfvars.json before running azd up.

Comments suppressed due to low confidence (1)

plugin/skills/azure-prepare/references/recipes/azd/terraform.md:132

• The “azd auto-mapping” description is internally inconsistent: it says azd passes AZURE_ENV_NAME/AZURE_LOCATION as Terraform variables “when they match variable names in variables.tf”, but the common Terraform variable names shown (environment_name, location) do not match those AZD env var names. Please reword this to accurately describe the mapping behavior (e.g., whether azd maps specific AZURE_* env vars to conventional Terraform variable names, or only passes variables whose names exactly match).

> **Do NOT generate `main.tfvars.json`** with template variables. Instead, pass variables to Terraform
> using one of these methods (in order of preference):
>
> 1. **azd auto-mapping** — azd automatically passes `AZURE_ENV_NAME`, `AZURE_LOCATION`, and
>    `AZURE_SUBSCRIPTION_ID` as Terraform variables when they match variable names in `variables.tf`
> 2. **`TF_VAR_*` environment variables** — Set via `azd env set TF_VAR_myvar value`
> 3. **`terraform.tfvars` (HCL format)** — Static defaults only; no template expressions

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

plugin/skills/azure-deploy/references/pre-deploy-checklist.md:145

• Step 9 fails only if infra/main.tfvars.json exists, but the azure-validate recipe flags any *.tfvars.json files as problematic for azd+Terraform. This mismatch can let other .tfvars.json files slip past the pre-deploy guard (or confuse readers). Consider either checking for all *.tfvars.json here too, or narrowing the validation guidance so both documents align.

# Fail if main.tfvars.json exists (should not be used with azd)
if test -f infra/main.tfvars.json; then
  echo "ERROR: Remove main.tfvars.json — use TF_VAR_* env vars instead"
  exit 1
fi

plugin/skills/azure-prepare/references/recipes/azd/terraform.md:257

• The example implies that azd env set DATABASE_NAME mydb will be automatically passed to Terraform as var.database_name. Elsewhere in this PR the documented “auto-mapping” is specifically for AZURE_ENV_NAME, AZURE_LOCATION, and AZURE_SUBSCRIPTION_ID; Terraform itself only auto-reads environment variables via the TF_VAR_ prefix. To avoid misleading guidance and broken deployments, clarify what azd actually maps automatically and/or update the example to use TF_VAR_database_name (or the supported azd→Terraform variable mechanism).

azd automatically maps its environment variables to Terraform variables. Define the variable
in `variables.tf` and set it via `azd env set`:

```bash
# Set azd variable
azd env set DATABASE_NAME mydb

# In variables.tf — azd passes this automatically
variable "database_name" {
  type    = string
}

[wbreza]

🔍 Code Review: PR #1585

What Looks Good

• Defense-in-depth strategy is excellent — the prevent (prepare) → detect (validate) → recover (deploy) layering across three skills is great architecture
• Root cause correctly identified — Go-style {{ .Env.* }} template syntax truly is the problem in .tfvars.json files
• Correctly removes the bogus env("DATABASE_NAME") Terraform function that doesn't exist in Terraform >= 0.12
• Version bumps are correct across all three skills
• The "State cleared on each azd provision" error entry captures a real gotcha

Key Concern: Remediation Contradicts Standard azd Patterns

The diagnosis is spot-on, but the remediation goes too far — it tells the agent to delete main.tfvars.json and never generate it, when main.tfvars.json is actually azd's standard parameter template file for Terraform projects. The azd source code (terraform_provider.go) reads this file, runs envsubst to substitute `` references, then passes the resolved file to Terraform via -var-file=. Microsoft's own sample templates (e.g., `todo-nodejs-mongo-terraform`) use exactly this pattern.

The correct fix should be: "Use `` syntax in main.tfvars.json, not Go-style `{{ .Env. }}`"* — rather than eliminating the file entirely.

Similarly, the "azd auto-mapping" claims (that azd automatically passes environment variables to Terraform by matching names in variables.tf) don't reflect azd's actual mechanism. Variables flow through main.tfvars.json substitution or explicit TF_VAR_* environment variables.

It looks like there are patterns across the PR that contradict the existing azd patterns for Terraform development. If any of the existing azd patterns are wrong or need updating, it'd be great to figure out what those are and collaborate on getting them fixed — rather than working around them. Let's align the guidance to match how azd actually works.

Findings Summary

Priority	Count	Description
🔴 Critical	3	Incorrect main.tfvars.json prohibition; wrong auto-mapping claims; misleading variable guidance
🟠 High	2	Wrong remediation approach; grep pattern scope issues
🟡 Medium	2	Pre-deploy check would reject standard templates; repeated content (~500+ tokens)
🟢 Low	2	Prior Copilot bot comments on get-value are incorrect (PR is right); legacy spec note is valid
Total	9

Overall Assessment: Comment

Note: The 3 unresolved Copilot bot comments about azd env get-value vs get-values are incorrect — both are valid azd CLI commands. The PR's singular form is the correct one for single-value retrieval.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

plugin/skills/azure-validate/references/recipes/terraform/README.md:133

• azd env get-value is used here, but the rest of the repo consistently documents azd env get-values (plural) for reading environment variables (e.g., plugin/skills/azure-deploy/references/pre-deploy-checklist.md:113-117). If get-value isn’t supported by the azd version users have, this command will fail; please switch to the documented get-values pattern (and extract the single variable) or use the existing eval $(azd env get-values) approach used elsewhere in the repo.

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

</details>

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

plugin/skills/azure-validate/references/recipes/terraform/README.md:132

• azd env get-value <NAME> isn’t used elsewhere in this repo’s docs (they consistently use azd env get-values). To avoid relying on a possibly-nonexistent subcommand and to match existing guidance, switch this example to azd env get-values (then grep/parse) or eval $(azd env get-values) before referencing $AZURE_ENV_NAME.

2. For additional variables, use **`TF_VAR_*` environment variables**:
   ```bash
   azd env set TF_VAR_environment_name "$(azd env get-value AZURE_ENV_NAME)"

</details>

[tmeschter]

@wbreza This is ready for another look.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates Azure skill documentation to prevent and detect unresolved Go-template variables being passed into Terraform via main.tfvars.json in azd+Terraform projects, addressing integration test timeouts and cascading deploy failures (Fixes #1558).

Changes:

• Documented the azd+Terraform interpolation limitation and the correct ${VAR} / TF_VAR_* patterns.
• Added validation + pre-deploy checks to detect unresolved {{ .Env.* }} in Terraform inputs early.
• Expanded error troubleshooting guidance for unresolved template variables and state behavior.

Show a summary per file

File	Description
plugin/skills/azure-validate/references/recipes/terraform/README.md	Adds a validation step to detect unresolved Go-style template variables in Terraform inputs.
plugin/skills/azure-validate/SKILL.md	Bumps azure-validate skill version to reflect the documentation update.
plugin/skills/azure-prepare/references/recipes/azd/terraform.md	Adds warnings + corrected examples for passing variables from azd to Terraform without Go templates.
plugin/skills/azure-prepare/SKILL.md	Bumps azure-prepare skill version to reflect the documentation update.
plugin/skills/azure-deploy/references/recipes/terraform/errors.md	Adds troubleshooting entries for unresolved templates and azd state-copy behavior.
plugin/skills/azure-deploy/references/recipes/azd/errors.md	Adds a dedicated “Unresolved Terraform Template Variables” error section with remediation steps.
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	Adds a mandatory pre-deploy guard step for azd+Terraform to catch unresolved templates.
plugin/skills/azure-deploy/SKILL.md	Bumps azure-deploy skill version to reflect the documentation update.

Copilot's findings

• Files reviewed: 8/8 changed files
• Comments generated: 2

[Copilot]

The PR description says azure-prepare is being bumped from v1.1.3 → v1.1.4, but this change bumps azure-prepare/SKILL.md from 1.1.6 → 1.1.7. Similarly, the description mentions azure-deploy v1.0.11 → v1.0.12 while the diff bumps 1.0.14 → 1.0.15. Please reconcile the PR description with the actual version bumps (either update the description or adjust the versions) so release notes stay accurate.

[Copilot]

This guard silently passes when infra/ doesn’t exist (grep exits non-zero, so the if body won’t run), which can produce a false sense of safety in docs meant to be 'MANDATORY for azd+Terraform'. Consider adding an explicit test -d infra/ check with a clear error (or an explicit 'skip' message) so the snippet behaves deterministically and avoids false negatives.

[wbreza]

Code Review: PR #1585

✅ What Looks Good

• Defense-in-depth architecture is excellent — prevent (prepare) → detect (validate) → recover (deploy) layering across three skills is well-designed
• Prior critical feedback addressed — the latest version correctly keeps main.tfvars.json with ${VAR} syntax instead of prohibiting the file entirely; auto-mapping claims replaced with accurate envsubst description
• Correctly removes bogus env("DATABASE_NAME") — this Terraform function doesn’t exist in Terraform ≥0.12
• Version bumps correct across all three skills

🟡 Medium (3 findings)

See inline comments for details.

#	Finding	File
1	JSON code blocks contain // comments — invalid JSON that agent may copy literally	terraform.md
2	Content repetition across skills (~500+ tokens) — acceptable trade-off for self-contained skill context	Multiple
3	Version conflict with PR #1587 — both bump azure-prepare to 1.1.7; coordinate merge order	SKILL.md

🟢 Low (2 findings)

#	Finding
4	Pre-deploy grep scope is a subset of validate grep (intentional quick guard vs thorough check)
5	PR description version numbers stale from rebasing

Summary

Priority	Count
Critical	0
High	0
Medium	3
Low	2
Total	5

Overall Assessment: Approve — prior critical concerns have been addressed. Remaining findings are non-blocking suggestions.

⚠️ Note: Both this PR and #1587 bump azure-prepare from 1.1.6 → 1.1.7. Whichever merges second will need to bump to 1.1.8.

[wbreza]

[🟡 Medium] JSON code block contains // comments

JSON doesn’t support comments. If the agent copies this block literally into main.tfvars.json, it will produce invalid JSON.

Consider moving the comment outside the code fence, or switching the language tag to jsonc.