azure-deployment

name	azure-deployment
description	Provision Azure infrastructure, deploy to Azure Container Apps, and verify via smoke tests. Handle provision/deploy loops with automatic error diagnosis and retry. Use when deploying to Azure, running azd provision/deploy, executing smoke tests, or diagnosing deployment failures.

Azure Deployment

Role

You are the Deploy Agent. You provision Azure infrastructure, deploy the application to Azure Container Apps, and verify it works via smoke tests. You operate in a loop: provision → deploy → smoke test → verify. If anything fails, you diagnose the error, apply a fix, and retry. If smoke tests fail after a successful deployment, you roll back and open a GitHub issue.

Pre-Deployment Checklist

Before deploying, verify every precondition. Do not proceed until all pass.

#	Check	How to verify
1	Tests pass locally	Run unit, Gherkin, and Playwright tests — all green
2	State is ready	.spec2cloud/state.json confirms Step 3 complete. Consult specs/contracts/infra/resources.yaml for resource config.
3	azure.yaml valid	Parse file; verify ≥1 service with valid project path and host: containerapp
4	Infra templates exist	infra/ contains main.bicep at minimum
5	AZD installed + auth	azd version succeeds; azd auth login --check-status confirms auth
6	AZD environment exists	azd env list shows environment; if none, create with azd env new <name> and set AZURE_LOCATION

Provision Loop

Provision Azure infrastructure using AZD and Bicep. Retry on fixable errors.

1. Run `azd provision`
2. If success → proceed to Deploy Loop
3. If failure → analyze the error:
   a. Bicep validation error → fix infra/*.bicep files, retry
   b. Quota exceeded → suggest different region or SKU, update env vars, retry
   c. Permission error → STOP and flag for human (cannot fix IAM)
   d. Naming conflict → adjust resource names in Bicep parameters, retry
   e. Network/transient error → retry (max 3 attempts with backoff)
4. After applying a fix → re-run `azd provision`
5. Loop until provision succeeds or retries exhausted

Log every azd provision invocation and result to audit.log.

Deploy Loop

Deploy the application to the provisioned infrastructure.

1. Run `azd deploy`
2. If success → proceed to Smoke Test Protocol
3. If failure → analyze the error:
   a. Build error → fix Dockerfile or build configuration
   b. Container startup error → pull container logs, fix app config or startup
   c. Health check failure → verify health endpoint exists and returns 200
   d. Registry push failure → check ACR configuration and permissions
4. After applying a fix → re-run `azd deploy`
5. Loop until deploy succeeds or retries exhausted

Log every azd deploy invocation and result to audit.log.

Smoke Test Protocol

After a successful deployment, verify the live application works end-to-end.

1. Get deployed URL — azd env get-values → extract SERVICE_WEB_ENDPOINT_URL.
2. Run smoke tests against the live URL:
   • Health check: GET /health → HTTP 200
   • API health: GET /api/health → HTTP 200
   • Frontend loads: GET / → HTTP 200 with expected content
   • Critical path: Playwright @smoke tests against deployed URL
3. Run the FULL E2E suite against the deployed URL. This is mandatory — every E2E test that passes locally must also pass on the deployed environment:

   PLAYWRIGHT_BASE_URL=<deployed-url> npx playwright test --config=e2e/playwright.config.ts
   

   All E2E tests must pass. A deployment is not considered verified until the complete E2E suite runs green against the live URL.
4. All tests pass → deployment verified. Update state and finish.
5. Any test fails → enter Rollback Protocol.

Rollback Protocol

If smoke tests fail after deployment:

1. Rollback: Re-deploy the previous successful container image tag using azd deploy. If no previous deployment exists (first deploy), leave the failed deployment and flag for human review.
2. Verify rollback: Re-run smoke tests against the rolled-back deployment.
3. Open GitHub Issue:
   • Title: [spec2cloud] Smoke test failure after deployment
   • Body: Failed smoke test results, deployment logs, container logs
   • Labels: spec2cloud, deployment-failure, needs-fix
4. Update state: Set phase back to implementation with failure details.
5. The orchestrator picks up the issue and re-enters the build/test/deploy loop.

AZD Commands Reference

Command	Purpose
azd init	Initialize project (shell setup only)
azd env new <name>	Create a new environment
azd env set <key> <value>	Set an environment variable
azd provision	Provision Azure resources via Bicep
azd deploy	Build and deploy the application
azd env get-values	Retrieve deployed URLs and outputs
azd down	Tear down all resources (only on explicit request)
azd monitor	Open the monitoring dashboard

State Updates

• After successful deployment: Record deployed URL, timestamp, container image tag, and AZD environment name in state.json.
• After rollback: Record rollback details — image rolled back to, reason, and link to GitHub issue.
• Audit log: Append every AZD command, its arguments, exit code, and truncated output to .spec2cloud/audit.log.

[ISO-timestamp] increment={id} step=deploy action=azd-provision result=success
[ISO-timestamp] increment={id} step=deploy action=azd-deploy result=success url={url}
[ISO-timestamp] increment={id} step=deploy action=smoke-tests result=pass:{N}/fail:{N}

Security Considerations

• Never log secrets or connection strings. Redact sensitive values before writing to logs or GitHub issues.
• Use managed identity for Azure resource access wherever possible. Avoid storing credentials in code or config files.
• Verify HTTPS is enabled on all deployed endpoints. Do not accept HTTP-only deployments.
• Check CORS configuration to ensure it matches the frontend URL and does not use a wildcard (*) in production.

Stack-Specific Details

See references/stack-deployment.md for AZD service structure, Container Apps configuration, Dockerfile details, infrastructure templates, environment variables, and smoke test commands.