1# Composition Algorithm
2 
3Combine multiple templates into a single deployable project.
4 
5## Azure MCP Path
6 
7```
8INPUT: language, user_requirements
9OUTPUT: Complete project ready for `azd up`
10 
111. DISCOVER
12   functions_template_get(language) → template list with descriptions
13 
142. CHECK SINGLE-TEMPLATE MATCH
15   If one template's description covers ALL requirements → use it alone
16 
173. SELECT TEMPLATES
18   - Trigger template (REQUIRED) — base project with IaC
19   - Binding templates (OPTIONAL) — extract patterns only
20 
214. FETCH TEMPLATES
22   - Single match: 1 call
23   - Multiple: parallel calls
24 
255. COMPOSE
26   - Use trigger template as BASE (functionFiles + projectFiles)
27   - EXTRACT binding patterns from binding templates
28   - MERGE IaC resources and RBAC roles
29   - ADD user's custom business logic
30 
316. TRIM unused demo code (keep AzureWebJobsStorage)
32 
337. WRITE files — for each entry { path, content } in functionFiles[] AND projectFiles[]:
34      a. Create parent directories from path
35      b. Write content to path
36      NEVER hand-write Bicep/Terraform and use azd init -t/func init/func new as fallback when composing multiple recipes and required templates are not found
37 
388. DEPLOY: azd up --no-prompt
39```
40 
41## Fallback Path (Azure MCP Unavailable)
42 
43```
44INPUT: language, user_requirements
45OUTPUT: Complete project ready for `azd up`
46 
471. FETCH MANIFEST
48   GET https://cdn.functions.azure.com/public/templates-manifest/manifest.json
49   If fetch fails → fall back to: https://github.com/Azure/azure-functions-templates/blob/dev/Functions.Templates/Template-Manifest/manifest.json
50   If both fail → fall back to known-good Azure-Samples/functions-quickstart-* repos by language+resource
51   If all fail → report error and ask user to retry later
52 
532. FILTER TEMPLATES
54   Filter by: language, resource (from selection.md), iac
55 
563. CHECK SINGLE-TEMPLATE MATCH
57   If one template covers ALL requirements → use it alone
58 
594. SELECT TEMPLATES
60   - Trigger template (REQUIRED) — base project
61   - Binding templates (OPTIONAL) — extract patterns only
62 
635. DOWNLOAD TEMPLATES
64   For each template:
65   - If folderPath == "." → ZIP download + unzip
66   - If folderPath != "." → fetch tree + raw github url file downloads
67   - Fallback: git clone --depth 1
68 
696. COMPOSE
70   - Use trigger template as BASE
71   - EXTRACT binding patterns from binding templates
72   - MERGE IaC resources, RBAC roles and settings, README and other files.
73   - ADD user's custom business logic
74 
757. TRIM unused demo code (keep AzureWebJobsStorage)
76 
778. WRITE all files
78 
799. DEPLOY: azd up --no-prompt
80```
81 
82## Example (MCP)
83 
84**User:** "HTTP function that writes to Cosmos DB"
85 
86```
871. Discover: functions_template_get(language: "python") → returns template list
882. Check: No single template description mentions BOTH HTTP trigger AND Cosmos output
893. Select from discovered list:
90   - Template with resource: "http" (trigger, base)
91   - Template with resource: "cosmos" and description mentioning "output" (binding)
924. Fetch both templates by templateName from discovery results
935. Compose:
94   - Base: HTTP template (has IaC, azure.yaml)
95   - Extract: Cosmos output binding + RBAC from cosmos template
96   - Merge: Add Cosmos module to infra/main.bicep
976. Trim: Remove HTTP demo response code
987. Write files
998. Deploy
100```
101 
102## Example (Fallback)
103 
104**User:** "HTTP function that writes to Cosmos DB"
105 
106```
1071. Fetch: GET manifest.json from CDN
1082. Filter: language=Python, resource=http OR resource=cosmos, iac=bicep
1093. Check: No single template covers both
1104. Select:
111   - http-trigger-python-azd (trigger, base) → repositoryUrl + folderPath
112   - cosmos-trigger-python-azd (binding) → repositoryUrl + folderPath
1135. Download: ZIP download both repos (folderPath = ".")
1146. Compose:
115   - Base: HTTP template (has infra/, azure.yaml)
116   - Extract: Cosmos IaC module + RBAC from cosmos template
117   - Merge: Add cosmos.bicep to infra/app/, wire into main.bicep
1187. Trim: Remove demo code
1198. Write files
1209. Deploy
121```
122 
123## Critical Rules
124 
1251. **NEVER hardcode template names** — always discover/fetch manifest first
1262. **PRESERVE generated IaC patterns** — keep RBAC roles, managed identity config, and security settings intact when merging
1273. **ALWAYS keep AzureWebJobsStorage** — runtime requires it
1284. **ALWAYS use `--no-prompt`** — the agent must never elicit user input during azd commands
1295. **ALWAYS include ALL THREE UAMI settings for every binding** — see UAMI Configuration below
1306. **ALWAYS wait for RBAC propagation** — use two-phase deploy if 403 errors occur
1317. **NEVER enable `allowSharedKeyAccess: true`** — correct solution is waiting for RBAC, not disabling security
132 
133## IaC Merge Guidelines
134 
135When composing multiple templates:
136 
137| Action | Allowed | Not Allowed |
138|--------|---------|-------------|
139| Add resource modules from binding templates | ✅ | |
140| Add RBAC role assignments from binding templates | ✅ | |
141| Merge environment variables | ✅ | |
142| Remove RBAC roles | | ❌ |
143| Change managed identity to connection strings | | ❌ |
144| Remove security configurations | | ❌ |
145| Modify resource SKUs without user request | | ❌ |
146 
147**Merge = additive combination, not modification of security patterns.**
148 
149## UAMI Configuration (CRITICAL)
150 
151Templates use User Assigned Managed Identity (UAMI). ALL service bindings require explicit `credential` and `clientId` app settings. Missing these causes 500/401/403 errors at runtime.
152 
153**Required pattern for EVERY service binding:**
154 
155```bicep
156appSettings: {
157  // Endpoint (varies by service)
158  EventHubConnection__fullyQualifiedNamespace: eventhubs.outputs.fullyQualifiedNamespace
159  // UAMI credentials - REQUIRED, prefix vary by example
160  EventHubConnection__credential: 'managedidentity'
161  EventHubConnection__clientId: apiUserAssignedIdentity.outputs.clientId
162}
163```
164 
165**Validation Checklist (MANDATORY before deploy):**
166 
167| Setting Pattern | Required | Example |
168|-----------------|:--------:|---------|
169| `{Connection}__fullyQualifiedNamespace` or `{Connection}__accountEndpoint` | ✅ | `EventHubConnection__fullyQualifiedNamespace` |
170| `{Connection}__credential` | ✅ | `'managedidentity'` (exact case) |
171| `{Connection}__clientId` | ✅ | `apiUserAssignedIdentity.outputs.clientId` |
172 
173> ⛔ **STOP if any check fails.** The function WILL fail at runtime with 500/Unauthorized errors.
174 
175## Language-Specific Entry Points
176 
177### Node.js (JavaScript/TypeScript)
178 
179> ⛔ **Do NOT delete `src/index.js` (JS) or `src/index.ts` (TS).**
180> This file contains `app.setup()` which initializes the Functions runtime.
181> Without it, functions deploy but return 404 on all endpoints.
182 
183> ⛔ **Glob pattern REQUIRED in package.json:**
184>
185> ```json
186> { "main": "src/{index.js,functions/*.js}" }
187> ```
188>
189> Using `"main": "src/index.js"` alone results in 404 on ALL endpoints.
190 
191> ⛔ **package.json must be at project ROOT** (same level as `azure.yaml`), NOT inside `src/`.
192 
193> 📦 **TypeScript:** Run `npm run build` before deployment.
194> Use: `"main": "dist/src/{index.js,functions/*.js}"`
195 
196### C# (.NET)
197 
198> ⛔ **Do NOT replace `Program.cs` from the base template.**
199> The base template uses `ConfigureFunctionsWebApplication()` with App Insights integration.
200> Recipes only ADD trigger function files (`.cs`) and package references (`.csproj`).
201 
202## Deployment Strategy
203 
204**Option A: Single command** (fast, may fail on first deploy due to RBAC propagation)
205 
206```bash
207azd up --no-prompt
208```
209 
210**Option B: Two-phase** (recommended for reliability)
211 
212```bash
213azd provision --no-prompt     # Create resources + RBAC assignments
214sleep 60                       # Wait for RBAC propagation (Azure AD needs 30-60s)
215azd deploy --no-prompt        # Deploy code (RBAC now active)
216```
217 
218## Terraform-Specific Requirements
219 
220> ⚠️ **CRITICAL**: All Terraform must use `sku_name = "FC1"` (Flex Consumption). **NEVER use Y1/Dynamic.**
221 
222### Runtime Versions
223 
224> ⚠️ **ALWAYS QUERY OFFICIAL DOCUMENTATION** — Do NOT use hardcoded versions.
225>
226> **Primary Source:** [Azure Functions Supported Languages](https://learn.microsoft.com/en-us/azure/azure-functions/supported-languages)
227>
228> Query for latest GA/LTS versions before generating IaC.
229 
230| Language | `function_runtime` | Version Source |
231|----------|-------------------|----------------|
232| C# (.NET) | `dotnet-isolated` | Latest LTS from docs |
233| TypeScript/JS | `node` | Latest LTS from docs |
234| Python | `python` | Latest GA from docs |
235| Java | `java` | Latest LTS from docs |
236| PowerShell | `powershell` | Latest GA from docs |
237 
238### Flex Consumption (FC1) Requires azapi
239 
240> ⚠️ Use `azapi_resource` instead of `azurerm_linux_function_app` for FC1.
241> The AzureRM provider doesn't support FC1's `functionAppConfig` block.
242 
243```hcl
244resource "azapi_resource" "function_app" {
245  type      = "Microsoft.Web/sites@2023-12-01"
246  name      = "func-${local.name}"
247  location  = azurerm_resource_group.rg.location
248  parent_id = azurerm_resource_group.rg.id
249 
250  body = {
251    kind = "functionapp,linux"
252    properties = {
253      serverFarmId = azapi_resource.plan.id
254      functionAppConfig = {
255        runtime = { name = "node", version = "22" }
256        scaleAndConcurrency = { maximumInstanceCount = 100, instanceMemoryMB = 2048 }
257        deployment = {
258          storage = {
259            type  = "blobContainer"
260            value = "${azurerm_storage_account.storage.primary_blob_endpoint}deploymentpackage"
261            authentication = {
262              type                           = "UserAssignedIdentity"
263              userAssignedIdentityResourceId = azurerm_user_assigned_identity.api.id
264            }
265          }
266        }
267      }
268    }
269  }
270  depends_on = [time_sleep.rbac_propagation]
271}
272```
273 
274### RBAC Propagation Delay
275 
276Azure RBAC takes 30-60s to propagate. Terraform's `depends_on` only waits for resource creation, not RBAC propagation.
277 
278**Solution 1: Add `time_sleep` resource**
279 
280```hcl
281resource "time_sleep" "rbac_propagation" {
282  depends_on      = [azurerm_role_assignment.storage_blob_owner]
283  create_duration = "60s"
284}
285 
286resource "azapi_resource" "function_app" {
287  depends_on = [time_sleep.rbac_propagation]
288  # ...
289}
290```
291 
292**Solution 2: Create deployment container explicitly**
293 
294```hcl
295resource "azurerm_storage_container" "deployment" {
296  name                  = "deploymentpackage"
297  storage_account_id    = azurerm_storage_account.storage.id
298  container_access_type = "private"
299  depends_on            = [azurerm_role_assignment.storage_blob_owner]
300}
301```
302 
303> ⚠️ **Common Failures Without These Fixes:**
304>
305> - `403 Forbidden` — RBAC not yet propagated
306> - `404 Container Not Found` — deployment container not created
307> - `Tag Not Found: azd-service-name` — Azure resource tags take time to be queryable
308 
309### Required: azd-service-name Tag
310 
311```hcl
312tags = {
313  "azd-service-name" = "api"   # MUST match service name in azure.yaml
314}
315```
316 
317> ⚠️ **Without this tag, `azd deploy` fails with:**
318> `resource not found: unable to find a resource tagged with 'azd-service-name: api'`
319 
320### Disabled Local Auth (Policy Required)
321 
322Azure Policy often enforces RBAC-only authentication. Always disable local auth (connection strings, SAS keys) and use managed identity instead.
323 
324```hcl
325# Storage
326shared_access_key_enabled = false
327 
328# Service Bus
329local_auth_enabled = false
330 
331# Event Hubs
332local_authentication_enabled = false
333 
334# Cosmos DB
335local_authentication_disabled = true
336```
337