Azure Developer CLI (azd)

Azure Developer CLI manages project environments and provisioning. In APEX, the matching Deploy agent uses the method selected by the approved plan and handoff. azd does not replace the workflow’s policy, preview, or approval gates.

Quick decision

Situation	Action
Approved project includes `azure.yaml`	Use its azd path through the matching Deploy agent.
Expected manifest, code, or handoff is missing	Return to CodeGen. Do not generate a generic preparation plan.
Existing project uses standalone Bicep or Terraform	Follow its verified handoff and the applicable legacy procedure.
Request is validation-only or preview-only	Report results and blockers within that scope, then stop.

Comparison

azd provision manages infrastructure through the configured provider. azd deploy deploys application code for configured services. azd up combines lifecycle work and must not be used as a shortcut for an infrastructure-only authorization.

Legacy deploy.ps1 procedures remain relevant only to existing projects that use them. Do not create a new legacy script to work around a missing manifest. Manifest migration belongs to CodeGen.

Per-project convention

Run commands in the relevant generated project directory:

infra/bicep/{project}/
infra/terraform/{project}/

When the project uses azd, azure.yaml and environment state under .azure/ belong there, not at the multi-project repository root. Review environment files before sharing them; they can contain sensitive configuration.

APEX uses the contracts in agent-output/{project}/. It does not require a generic .azure/plan.md. The generic preparation flow in apex-azure-prepare explicitly returns APEX requests to their step owner.

Azd workflow

1. Prepare

Requirements, Architecture, Governance, and Plan establish the approved inputs. CodeGen produces the IaC, required manifest, and 05-iac-handoff.json. Do not ask Deploy to repair or regenerate those artifacts.

2. Validate

Select 07b-Bicep Deploy or 07t-Terraform Deploy and request the intended scope. For example:

Validate the APEX project payment-gateway without preview or deployment.
Check the current handoff and environment manifest. Report unperformed checks
and missing prerequisites. Do not create resources or regenerate code.

Validation reuse requires matching current inputs, scope, and tool evidence. An old PASSED status or the presence of azure.yaml is not sufficient.

3. Deploy

For an explicitly requested deployment, the agent resolves the approved environment, checks policy, presents the current preview, and obtains apply approval. Changed inputs or a changed preview require fresh approval.

Prepare to deploy the approved payment-gateway project to its recorded target.
Show the current preview and policy results, then wait for apply approval.

Provisioning success does not prove application health. Record both outcomes.

Environment preflight

Verify the intended subscription, location, environment, resource scope, and authentication before provisioning. Azure CLI and azd have separate authentication contexts.

az account show --output table
az account get-access-token --resource https://management.azure.com/ --output none
azd auth login --check-status

Do not print tokens. Inspect environment values locally, and redact them before including logs in an issue. A missing Terraform backend is a blocker in validation-only or preview-only scope. Bootstrap needs a separate explicit setup/deployment request and authorization.

Legacy deploy.ps1 workflow

Use an existing legacy procedure only when the project and its approved deployment method require it. Do not assume generic flags exist in every generated script. Read the script and plan before running it.

Single deployment

The selected agent must preview the same inputs and scope that it will apply. Do not copy an apply command from a historical case study.

Phased deployment

Follow the phases in the approved implementation plan. Preview, obtain approval, apply, and verify one phase at a time. A phase name or a previous phase’s success does not authorize the next phase.

Azd hooks

Review lifecycle hooks in azure.yaml before running azd. A hook can create resources, change access, or run migrations. Its effects belong in the requested scope and approval.

Do not append || true to suppress role-assignment errors. Inspect the actual result, confirm the intended assignment when it already exists, and surface unexpected failures. Idempotency means repeated execution preserves the intended result, not that all errors are ignored.

Azure.YAML schema

The manifest declares the infrastructure provider and path, optional application services, and hooks. Their values must match the generated project and the approved handoff. Terraform parameter mapping must match the actual variable definitions.

Use the official schema for syntax. Do not add placeholder services or hooks merely to copy an example.

Troubleshooting

Failure	Next step
`azure.yaml` not found	Check the working directory; return a missing expected manifest to CodeGen.
Missing parameter or environment value	Resolve it against the environment manifest and owner decisions.
Preview fails despite Azure CLI login	Check azd authentication separately.
Terraform backend is missing	Report the blocker; do not bootstrap during validation-only or preview-only work.
Policy or preview evidence is stale	Repeat the affected check against current inputs before approval.
A hook fails	Preserve the error and repair its cause through the owning step.