1# azure.yaml Generation
2 
3> ⛔ **CRITICAL: Check for .NET Aspire projects FIRST**
4>
5> **DO NOT manually create azure.yaml for .NET Aspire projects.** If you detect:
6> - Files ending with `*.AppHost.csproj` (e.g., `MyApp.AppHost.csproj`)
7> - `Aspire.Hosting` or `Aspire.AppHost.Sdk` in `.csproj` files
8>
9> **STOP and use `azd init --from-code` instead.** See [aspire.md](aspire.md) for details.
10 
11Create `azure.yaml` in project root for AZD.
12 
13## Structure
14 
15### Basic (Bicep - default)
16 
17```yaml
18name: <project-name>
19metadata:
20  template: azd-init
21 
22services:
23  <service-name>:
24    project: <path-to-source>
25    language: <python|js|ts|java|dotnet|go>
26    host: <containerapp|appservice|function|staticwebapp|aks>
27```
28 
29### With Terraform Provider
30 
31```yaml
32name: <project-name>
33metadata:
34  template: azd-init
35 
36# Specify Terraform as IaC provider
37infra:
38  provider: terraform
39  path: ./infra
40 
41services:
42  <service-name>:
43    project: <path-to-source>
44    language: <python|js|ts|java|dotnet|go>
45    host: <containerapp|appservice|function|staticwebapp|aks>
46```
47 
48> 💡 **Tip:** Omit `infra` section to use Bicep (default). Add `infra.provider: terraform` to use Terraform. See [terraform.md](terraform.md) for details.
49 
50## Host Types
51 
52| Host | Azure Service | Use For |
53|------|---------------|---------|
54| `containerapp` | Container Apps | APIs, microservices, workers |
55| `appservice` | App Service | Traditional web apps |
56| `function` | Azure Functions | Serverless functions |
57| `staticwebapp` | Static Web Apps | SPAs, static sites |
58| `aks` | AKS | Kubernetes workloads |
59 
60## Examples
61 
62### Container App with Bicep (default)
63 
64```yaml
65name: myapp
66 
67services:
68  api:
69    project: ./src/api
70    language: python
71    host: containerapp
72    docker:
73      path: ./src/api/Dockerfile
74```
75 
76### Container App with Terraform
77 
78```yaml
79name: myapp
80 
81infra:
82  provider: terraform
83  path: ./infra
84 
85services:
86  api:
87    project: ./src/api
88    language: python
89    host: containerapp
90    docker:
91      path: ./src/api/Dockerfile
92```
93 
94### Container App with Custom Docker Context
95 
96When a **non-Aspire** project has a Dockerfile that expects files relative to a specific directory:
97 
98```yaml
99name: myapp
100 
101services:
102  ginapp:
103    project: .
104    host: containerapp
105    image: ginapp
106    docker:
107      path: ginapp/Dockerfile
108      context: ginapp
109```
110 
111> 💡 **Tip:** The `context` field specifies the Docker build context directory. This is crucial for:
112> - Dockerfiles with `COPY` commands expecting files relative to a subdirectory
113> - Multi-service repos where each service has its own context
114 
115> ⚠️ **Aspire projects:** Do NOT manually add per-service entries with `docker.context` for Aspire `AddDockerfile()` resources. Aspire handles container builds at runtime through the AppHost. The generated `azure.yaml` should contain only a single `app` service pointing to the AppHost. See [aspire.md](aspire.md) for details.
116 
117> ⚠️ **Language Field:** When using the `docker` section, the `language` field should be **omitted** or set to the language that azd will use for framework-specific behaviors. For containerized apps with custom Dockerfiles, the language is not used by azd since the build is handled by Docker. Only include `language` if you need azd to perform additional framework-specific actions beyond Docker build.
118 
119### Azure Functions
120 
121```yaml
122services:
123  functions:
124    project: ./src/functions
125    language: js
126    host: function
127```
128 
129### Static Web App (with framework build)
130 
131For React, Vue, Angular, Next.js, etc. that require `npm run build`:
132 
133```yaml
134services:
135  web:
136    project: ./src/web     # folder containing package.json
137    language: js           # triggers: npm install && npm run build
138    host: staticwebapp
139    dist: dist             # build output folder (e.g., dist, build, out)
140```
141 
142### Static Web App (pure HTML/CSS - no build)
143 
144For pure HTML sites without a framework build step:
145 
146**Static files in subfolder (recommended):**
147```yaml
148services:
149  web:
150    project: ./src/web     # folder containing index.html
151    host: staticwebapp
152    dist: .                # works when project != root
153```
154 
155**Static files in root - requires build script:**
156 
157> ⚠️ **SWA CLI Limitation:** When `project: .`, you cannot use `dist: .`. Files must be copied to a separate output folder.
158 
159Add a minimal `package.json` with a build script:
160```json
161{
162  "scripts": {
163    "build": "node -e \"require('fs').mkdirSync('public',{recursive:true});require('fs').readdirSync('.').filter(f=>/\\.(html|css|js|png|jpe?g|gif|svg|ico|json|xml|txt|webmanifest|map)$/i.test(f)).forEach(f=>require('fs').copyFileSync(f,'public/'+f))\""
164  }
165}
166```
167 
168Then configure azure.yaml with `language: js` to trigger the build:
169```yaml
170services:
171  web:
172    project: .
173    language: js           # triggers npm install && npm run build
174    host: staticwebapp
175    dist: public
176```
177 
178### SWA Project Structure Detection
179 
180| Layout | Configuration |
181|--------|---------------|
182| Static in root | `project: .`, `language: js`, `dist: public` + package.json build script |
183| Framework in root | `project: .`, `language: js`, `dist: <output>` |
184| Static in subfolder | `project: ./path`, `dist: .` |
185| Framework in subfolder | `project: ./path`, `language: js`, `dist: <output>` |
186 
187> **Key rules:**
188> - `dist` is **relative to `project`** path
189> - **SWA CLI limitation**: When `project: .`, cannot use `dist: .` - must use a distinct folder
190> - For static files in root, add `package.json` with build script to copy files to dist folder
191> - Use `language: js` to trigger npm build even for pure static sites in root
192> - `language: html` and `language: static` are **NOT valid** - will fail
193 
194### SWA Bicep Requirement
195 
196Bicep must include the `azd-service-name` tag:
197```bicep
198resource staticWebApp 'Microsoft.Web/staticSites@2022-09-01' = {
199  name: name
200  location: location
201  tags: union(tags, { 'azd-service-name': 'web' })}
202```
203}
204```
205 
206### App Service
207 
208```yaml
209services:
210  api:
211    project: ./src/api
212    language: dotnet
213    host: appservice
214```
215 
216## Hooks (Optional)
217 
218```yaml
219hooks:
220  preprovision:
221    shell: sh
222    run: ./scripts/setup.sh
223  postprovision:
224    shell: sh
225    run: ./scripts/seed-data.sh
226```
227 
228## Valid Values
229 
230| Field | Options |
231|-------|---------|
232| `language` | python, js, ts, java, dotnet, go (omit for staticwebapp without build) |
233| `host` | containerapp, appservice, function, staticwebapp, aks |
234| `docker.path` | Path to Dockerfile (relative to project root) |
235| `docker.context` | Docker build context directory (optional, defaults to directory containing Dockerfile) |
236 
237> 💡 **Docker Context:** When `docker.context` is omitted, azd uses the directory containing the Dockerfile as the build context. Specify `context` explicitly when the Dockerfile expects files from a different directory.
238 
239## Output
240 
241- `./azure.yaml`
242