1# AZD Validation
2 
3Validation steps for Azure Developer CLI projects.
4 
5## Prerequisites
6 
7- `azure.yaml` exists in project root
8- Infrastructure files exist:
9  - For Bicep: `./infra/` contains Bicep files
10  - For Terraform: `./infra/` contains `.tf` files and `azure.yaml` has `infra.provider: terraform`
11 
12## Validation Steps
13 
14- [ ] 1. AZD Installation
15- [ ] 2. Schema Validation
16- [ ] 3. Environment Setup
17- [ ] 4. Authentication Check
18- [ ] 5. Subscription/Location Check
19- [ ] 6. Aspire Pre-Provisioning Checks
20- [ ] 7. Provision Preview
21- [ ] 8. Build Verification
22- [ ] 9. Docker Build Context Validation
23- [ ] 10. Package Validation
24- [ ] 11. Azure Policy Validation
25- [ ] 12. Aspire Post-Provisioning Checks
26 
27## Validation Details
28 
29### 1. AZD Installation
30 
31Verify AZD is installed:
32 
33```bash
34azd version
35```
36 
37**If not installed:**
38```
39mcp_azure_mcp_extension_cli_install(cli-type: "azd")
40```
41 
42### 2. Schema Validation
43 
44Validate azure.yaml against official schema:
45 
46```
47mcp_azure_mcp_azd(command: "validate_azure_yaml", parameters: { path: "./azure.yaml" })
48```
49 
50### 3. Environment Setup
51 
52Verify AZD environment exists and is configured. See [Environment Setup](environment.md) for detailed steps.
53 
54### 4. Authentication Check
55 
56```bash
57azd auth login --check-status
58```
59 
60**If not logged in:**
61```bash
62azd auth login
63```
64 
65### 5. Subscription/Location Check
66 
67Check environment values:
68```bash
69azd env get-values
70```
71 
72**If AZURE_SUBSCRIPTION_ID or AZURE_LOCATION not set:**
73 
74Use Azure MCP tools to list subscriptions:
75```
76mcp_azure_mcp_subscription_list
77```
78 
79Use Azure MCP tools to list resource groups (check for conflicts):
80```
81mcp_azure_mcp_group_list
82  subscription: <subscription-id>
83```
84 
85Prompt user to confirm subscription and location before continuing.
86 
87Refer to the region availability reference to select a region supported by all services in this template:
88- [Region availability](../../region-availability.md)
89 
90```bash
91azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
92azd env set AZURE_LOCATION <location>
93```
94 
95### 6. Aspire Pre-Provisioning Checks
96 
97**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.**
98 
99### 7. Provision Preview
100 
101Validate IaC is ready (must complete without error):
102 
103```bash
104azd provision --preview --no-prompt
105```
106 
107> 💡 **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`).
108 
109**If `azd provision --preview` fails with `unsupported resource type`:**
110 
111⛔ **Stop deployment immediately.** Do NOT attempt to fix or work around the error.
112 
113This 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.
114 
115**Required actions:**
1161. ⛔ **Do NOT modify source code** to suppress the error (e.g., do not add `.ExcludeFromManifest()`).
1172. ⛔ **Do NOT proceed with `azd provision` or `azd deploy`.**
1183. ✅ 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."
1194. ✅ Record a blocker: "Deployment blocked — AppHost contains unsupported resource types with no Azure deployment target."
120 
121> ⚠️ 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.
122 
123### 8. Build Verification
124 
125Build 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.
126 
127### 9. Docker Build Context Validation
128 
129**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:
130 
1311. Read each service's `Dockerfile`
1322. If the Dockerfile contains `npm ci`, verify `package-lock.json` exists in the same directory
1333. If `package-lock.json` is missing, generate it in the service's `project` path directory before proceeding:
134 
135```bash
136cd <service-project-path>
137npm install --package-lock-only
138```
139 
140> ⚠️ **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`.
141 
142### 10. Package Validation
143 
144Confirm all services package successfully:
145 
146```bash
147azd package --no-prompt
148```
149 
150### 11. Azure Policy Validation
151 
152See [Policy Validation Guide](../../policy-validation.md) for instructions on retrieving and validating Azure policies for your subscription.
153 
154### 12. Aspire Post-Provisioning Checks
155 
156**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.**
157 
158## References
159 
160- [Environment Setup](environment.md)
161- [Aspire Validation](aspire.md)
162- [Error Handling](./errors.md)
163 
164## Next
165 
166All checks pass → **azure-deploy**
167