1# Cosmos DB Recipe — REFERENCE ONLY
2 
3Adds Azure Cosmos DB (NoSQL) integration to an App Service base template.
4 
5## Overview
6 
7This recipe composes with a Web API or Web App base template to add Cosmos DB data access. It provides the IaC delta (Cosmos account, database, container, RBAC) and per-language source code using the Cosmos DB SDK.
8 
9## Integration Type
10 
11| Aspect | Value |
12|--------|-------|
13| **Database** | Azure Cosmos DB for NoSQL |
14| **Auth** | Managed identity (DefaultAzureCredential) |
15| **SDK** | Microsoft.Azure.Cosmos (.NET), @azure/cosmos (Node.js), azure-cosmos (Python) |
16| **Hosting** | App Service (from base template) |
17| **Local Auth** | Disabled (`disableLocalAuth: true`) — RBAC-only |
18 
19## Composition Steps
20 
21Apply these steps AFTER `azd init -t <base-template>`:
22 
23| # | Step | Details |
24|---|------|---------|
25| 1 | **Add IaC module** | Add Cosmos DB Bicep module to `infra/app/` |
26| 2 | **Wire into main** | Add module reference in `main.bicep` |
27| 3 | **Add app settings** | Add Cosmos endpoint + database + container settings |
28| 4 | **Add source code** | Add Cosmos client setup from `source/{lang}.md` |
29| 5 | **Add packages** | Add Cosmos SDK + Azure Identity packages |
30 
31## App Settings
32 
33| Setting | Value | Purpose |
34|---------|-------|---------|
35| `COSMOS_ENDPOINT` | `https://{account}.documents.azure.com:443/` | Cosmos account endpoint |
36| `COSMOS_DATABASE_NAME` | `app-db` | Target database |
37| `COSMOS_CONTAINER_NAME` | `items` | Target container |
38 
39### Bicep App Settings Block
40 
41```bicep
42appSettings: [
43  { name: 'COSMOS_ENDPOINT', value: cosmos.outputs.endpoint }
44  { name: 'COSMOS_DATABASE_NAME', value: cosmos.outputs.databaseName }
45  { name: 'COSMOS_CONTAINER_NAME', value: cosmos.outputs.containerName }
46]
47```
48 
49> **Note:** No connection string or key is needed. The SDK uses `DefaultAzureCredential` which automatically resolves to the app's managed identity in Azure.
50 
51## RBAC Roles Required
52 
53| Role | GUID | Scope | Purpose |
54|------|------|-------|---------|
55| **Cosmos DB Account Reader** | `fbdf93bf-df7d-467e-a4d2-9458aa1360c8` | Cosmos account | Read account metadata |
56| **Cosmos DB Built-in Data Contributor** | `00000000-0000-0000-0000-000000000002` | Cosmos account (SQL role) | Read/write data |
57 
58> **Important:** Cosmos DB uses its own SQL RBAC system (`sqlRoleAssignments`) for data plane operations, not standard Azure RBAC.
59 
60## Networking (when VNET_ENABLED=true)
61 
62| Component | Details |
63|-----------|---------|
64| **Private endpoint** | Cosmos account → App Service VNet subnet |
65| **Private DNS zone** | `privatelink.documents.azure.com` |
66 
67## Resources Created
68 
69| Resource | Type | Purpose |
70|----------|------|---------|
71| Cosmos DB Account | `Microsoft.DocumentDB/databaseAccounts` | Serverless NoSQL database |
72| SQL Database | `databaseAccounts/sqlDatabases` | Application database |
73| Container | `sqlDatabases/containers` | Data container with partition key |
74| Role Assignment | `Microsoft.Authorization/roleAssignments` | Control plane access |
75| SQL Role Assignment | `databaseAccounts/sqlRoleAssignments` | Data plane access |
76 
77## Source Code Examples
78 
79| Language | Source File |
80|----------|-------------|
81| C# (.NET) | [source/dotnet.md](source/dotnet.md) |
82| Python | [source/python.md](source/python.md) |
83| Node.js | [source/nodejs.md](source/nodejs.md) |
84 
85## References
86 
87- [Cosmos DB + App Service tutorial](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/tutorial-dotnet-web-app)
88- [Passwordless Cosmos DB connections](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/how-to-dotnet-get-started)
89- [Cosmos DB RBAC](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac)
90