Skip to content

Commit e3ddc9d

Browse files
srnicholssrnichols
committed
docs(alz): add Azure Landing Zones guide and link from docs hub
1 parent 230ff7d commit e3ddc9d

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎docs/DOCS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ graph LR
4949
5. **🚀 [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)** - Step-by-step implementation *(45 minutes)*
5050
6. **📋 [PARAMETERIZATION_GUIDE.md](./PARAMETERIZATION_GUIDE.md)** - Template customization *(15 minutes)*
5151
7. **🗂️ [MANAGEMENT_PORTAL_USER_GUIDE.md](./MANAGEMENT_PORTAL_USER_GUIDE.md)** - Manage tenants and cells *(20 minutes)*
52+
8. **🏢 [LANDING_ZONES_GUIDE.md](./LANDING_ZONES_GUIDE.md)** - Map Stamps to Azure Landing Zones *(20 minutes)*
5253

5354
### **Phase 3: Operations & Security (60-75 minutes)**
5455
7. **⚙️ [OPERATIONS_GUIDE.md](./OPERATIONS_GUIDE.md)** - AI-driven operations and monitoring *(30 minutes)*

‎docs/LANDING_ZONES_GUIDE.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Azure Landing Zones Guide for the Stamps Pattern
2+
3+
Audience: Cloud architects, platform engineers, and workload teams adopting the Stamps Pattern within an Azure Landing Zone (ALZ) enterprise environment.
4+
5+
Last updated: August 2025
6+
7+
## TL;DR – Where things go
8+
9+
- Platform landing zones host shared enterprise services: Identity (process), Management, Connectivity, and Shared Services (global edge, shared gateways). Do not put all infra into the Management subscription.
10+
- Application (workload) landing zones host your CELLs (shared or dedicated) per region. Use one subscription per CELL for isolation, quotas, and billing clarity.
11+
- Control Plane (management portal, DAB GraphQL, control metadata): either a) Platform Shared-Services subscription if used by many apps/org-wide, or b) a dedicated “ControlPlane” workload subscription under Landing Zones for autonomy and SDLC separation.
12+
13+
## Management groups and subscriptions
14+
15+
Recommended CAF-aligned hierarchy:
16+
17+
```
18+
Tenant Root Group (TRG)
19+
├─ Platform (MG)
20+
│ ├─ Identity (process-owned; Entra ID tenant scope)
21+
│ ├─ Management (subscription)
22+
│ ├─ Connectivity (subscription)
23+
│ └─ Shared-Services (subscription)
24+
└─ Landing Zones (MG)
25+
├─ Corp (MG)
26+
│ ├─ Sub: corp-dev
27+
│ ├─ Sub: corp-test
28+
│ └─ Sub: corp-prod
29+
├─ Online (MG)
30+
│ ├─ Sub: online-eus-cell-shared-z2
31+
│ ├─ Sub: online-weu-cell-shared-z2
32+
│ └─ Sub: online-eus-cell-dedicated-tenantX
33+
└─ Sandbox (MG)
34+
└─ Sub: sandbox
35+
```
36+
37+
Subscriptions at a glance:
38+
39+
- Platform/Management: Log Analytics, Sentinel, Defender, Automation; central diagnostics.
40+
- Platform/Connectivity: vWAN/Hub VNets, Azure Firewall, Private DNS, DDoS plan.
41+
- Platform/Shared-Services: Traffic Manager, Front Door, global APIM (if shared), optional Control Plane.
42+
- Workload (Application) landing zones: CELL per subscription; VNet-injected Container Apps Env, App Gateway, Redis, SQL, Storage, per-CELL Key Vault, Private Endpoints.
43+
44+
## Component-to-landing-zone mapping
45+
46+
| Component (repo) | Resource examples | Landing zone | Rationale |
47+
|---|---|---|---|
48+
| Global Layer (traffic-routing.bicep) | Traffic Manager, Front Door | Platform/Shared-Services | Global edge, shared across workloads |
49+
| Geodes/Global Control Plane (globalLayer.bicep, b2c-setup.bicep) | APIM (global), B2C, Control Plane Cosmos (if shared) | Platform/Shared-Services (or dedicated ControlPlane workload sub) | Central governance & reuse |
50+
| Regional Layer (regionalLayer.bicep) | App Gateway, Key Vault, Automation | Platform/Connectivity (shared) or per-workload if required | Regional entry, shared networking |
51+
| CELL Layer (deploymentStampLayer.bicep, geodesLayer.bicep) | Container Apps Env and apps, Redis, SQL/Storage, KV, Private Endpoints | Application/Workload LZ (per-CELL subscription) | Isolation, quotas, billing |
52+
| Management Portal (management-portal) | Blazor Server app, DAB GraphQL, control-plane Cosmos DB | Platform/Shared-Services or dedicated ControlPlane workload sub | Org-wide mgmt or app autonomy |
53+
| Monitoring (monitoringLayer.bicep, monitoringDashboards.bicep) | Log Analytics, Dashboards, alerts | Platform/Management (central) + per-CELL in workload subs | Central visibility + local SLOs |
54+
| Security/Policy (policyAsCode.bicep, zeroTrustSecurity.bicep) | Policy assignments, Defender, Sentinel | MG scopes (Platform, Landing Zones) | Inheritance and guardrails |
55+
56+
## Governance & policy
57+
58+
- Apply policy at MG scope; inherit to subscriptions. At minimum:
59+
- Required: Diagnostic settings to Log Analytics, Defender for Cloud on, baseline tag requirements, allowed locations/SKUs, secure transfer, TLS minimums, managed identity enforced.
60+
- Workload MG: allow list of PaaS services, regional/AZ constraints, Private Endpoint requirement for data services.
61+
- Use your `policyAsCode.bicep` to assign initiatives at MG scope. Example (Bicep):
62+
63+
```bicep
64+
targetScope = 'managementGroup'
65+
66+
@description('ID of the management group (e.g., platform or landingzones)')
67+
param mgId string
68+
69+
module diagnostics './policy/assign-diagnostics.bicep' = {
70+
name: 'assign-diagnostics'
71+
scope: managementGroup(mgId)
72+
params: {
73+
logAnalyticsResourceId: resourceId('/subscriptions/<mgmt-sub-id>/resourceGroups/rg-mgmt/providers/Microsoft.OperationalInsights/workspaces/law-central')
74+
}
75+
}
76+
```
77+
78+
## Networking & connectivity
79+
80+
- Hub-and-spoke or vWAN in Platform/Connectivity subscription.
81+
- Private DNS zones central in hub; link CELL spokes across subscriptions.
82+
- Container Apps: use VNet-injected CAE in each CELL subscription; ensure hub-spoke peering/vWAN route propagation and Private DNS resolution.
83+
- Private Endpoints for SQL/Storage/etc. in CELL spokes; integrate with central Private DNS.
84+
85+
## Identity & access
86+
87+
- Entra ID tenant-level ownership for identity; PIM-enforced RBAC.
88+
- Platform team owns Platform subscriptions; workload teams own CELL subscriptions.
89+
- Managed identities everywhere (Functions/Apps/APIM/CAE); separate Key Vault per CELL; platform KV for shared secrets.
90+
91+
## Monitoring & security
92+
93+
- Central Log Analytics workspace(s) in Platform/Management; optional per-CELL workspaces for autonomy.
94+
- Defender for Cloud enabled across Platform and Landing Zones; Sentinel in Management.
95+
- Standardize diagnostic settings via policy; use workbooks/dashboards (see `monitoringDashboards.bicep`).
96+
97+
## CI/CD & environments
98+
99+
- Platform pipelines (infrequent): Management/Connectivity/Shared-Services; policy assignments at MG.
100+
- Workload pipelines (frequent): deploy stamps (CELLs) to workload subscriptions; parameterize subscription IDs and regions.
101+
- Separate MGs or folders per env (dev/test/prod); align subscriptions accordingly.
102+
103+
## IaC structure & parameters
104+
105+
- Keep Bicep modules layer-aligned (already reflected in repo). Parameterize:
106+
- platformSubscriptionId, connectivitySubscriptionId, sharedServicesSubscriptionId
107+
- cellSubscriptionId, region, azZone, environment, cellId
108+
- Example (Bicep entry-point):
109+
110+
```bicep
111+
param platformSubId string
112+
param sharedServicesSubId string
113+
param cellSubId string
114+
param region string
115+
param cellId string
116+
117+
// Global edge
118+
module global './traffic-routing.bicep' = {
119+
name: 'global-edge'
120+
scope: subscription(sharedServicesSubId)
121+
params: {
122+
// ... your params
123+
}
124+
}
125+
126+
// Control plane (optional centralized)
127+
module controlPlane './AzureArchitecture/globalLayer.bicep' = {
128+
name: 'control-plane'
129+
scope: subscription(sharedServicesSubId)
130+
params: {
131+
// ... your params
132+
}
133+
}
134+
135+
// CELL in workload subscription
136+
module cell './AzureArchitecture/deploymentStampLayer.bicep' = {
137+
name: 'cell-' + cellId
138+
scope: subscription(cellSubId)
139+
params: {
140+
location: region
141+
cellId: cellId
142+
// ... your params
143+
}
144+
}
145+
```
146+
147+
## Tags, cost, and quotas
148+
149+
- Standard tags: `env`, `costCenter`, `owner`, `app`, `cellId`, `tenantId`, `azd-env-name`.
150+
- Budgets at subscription level per CELL; cost analysis by tag.
151+
- Dedicated CELLs per enterprise tenant ease chargeback and increase quota limits vs shared.
152+
153+
## Resiliency & DR
154+
155+
- Global: Front Door/Traffic Manager (active-active across regions).
156+
- Regional: duplicate CELLs across at least two regions; align data replication (SQL/Cosmos) to RPO/RTO.
157+
- Control Plane: geo-replicate Cosmos DB (if used centrally) and deploy portal/DAB in two regions.
158+
159+
## Quick decisions checklist
160+
161+
- [ ] Control Plane placement: Platform Shared-Services vs dedicated workload subscription
162+
- [ ] Per-CELL subscription model: shared vs dedicated per enterprise tenant
163+
- [ ] Hub/spoke or vWAN topology; Private DNS ownership location
164+
- [ ] Single vs dual Log Analytics strategy; Sentinel enabled
165+
- [ ] Region pairs and DR pattern; target RPO/RTO
166+
- [ ] Policy initiatives at Platform and Landing Zones MGs
167+
168+
## References
169+
170+
- Azure CAF – Landing Zones: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/
171+
- Azure Architecture Center: https://learn.microsoft.com/azure/architecture/
172+
- Repo docs: `ARCHITECTURE_GUIDE.md`, `OPERATIONS_GUIDE.md`, `SECURITY_GUIDE.md`, `NAMING_CONVENTIONS.md`

0 commit comments

Comments
 (0)