Skip to content

Commit 50d6ddf

Browse files
kristopherjturnerkristopherjturner
authored
Merge pull request #43 from AzureLocal/feature/epic-8-completion
docs: complete Epic #8 AVD documentation plan
2 parents b64cdb8 + 3b82868 commit 50d6ddf

24 files changed

Lines changed: 1465 additions & 18 deletions

.github/pull_request_template.md renamed to .github/PULL_REQUEST_TEMPLATE.md

File renamed without changes.

‎docs/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Documentation Index
2+
3+
This index maps the core architecture, guide, operations, and reference pages.
4+
5+
## Architecture
6+
- [Architecture Overview](architecture.md)
7+
- [Architecture Deep Design](architecture/deep-design.md)
8+
- [FSLogix Integration](architecture/fslogix-integration.md)
9+
10+
## Guides
11+
- [AVD Deployment Guide](guides/avd-deployment-guide.md)
12+
- [RemoteApps Guide](guides/rdapps.md)
13+
14+
## Operations and Security
15+
- [Cost Management](operations/cost-management.md)
16+
- [Defender Operations](security/defender-operations.md)
17+
18+
## Reference
19+
- [Host Pool Options](reference/host-pool-options.md)
20+
- [Monitoring Queries](reference/monitoring-queries.md)
21+
- [RBAC Reference](reference/rbac.md)
22+
- [Docs Validation Checklist](reference/docs-validation-checklist.md)
23+
- [Variable Mapping](reference/variable-mapping.md)
24+
- [Tool Parity Matrix](reference/tool-parity-matrix.md)
25+
26+
## Diagrams
27+
- [Diagrams Index](diagrams/index.md)

‎docs/architecture.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,10 @@ The AVD architecture has two distinct planes:
6060
└──────────────┘
6161
```
6262

63+
Diagram asset:
64+
65+
![AVD on Azure Local reference architecture](diagrams/avd-reference-architecture.png)
66+
6367
---
6468

6569
## Key Components
@@ -135,3 +139,16 @@ Reference docs:
135139
- [FSLogix documentation](https://learn.microsoft.com/en-us/fslogix/)
136140
- [Arc Resource Bridge](https://learn.microsoft.com/en-us/azure/azure-arc/resource-bridge/overview)
137141
- [Companion SOFS/FSLogix repository](https://github.com/AzureLocal/azurelocal-sofs-fslogix)
142+
143+
## Extended Documentation
144+
145+
- [Architecture Deep Design](architecture/deep-design.md)
146+
- [FSLogix Integration Guide](architecture/fslogix-integration.md)
147+
- [Host Pool Options](reference/host-pool-options.md)
148+
- [RBAC Reference](reference/rbac.md)
149+
- [Monitoring Queries](reference/monitoring-queries.md)
150+
- [Cost Management](operations/cost-management.md)
151+
- [Defender Operations](security/defender-operations.md)
152+
- [RemoteApps Guide](guides/rdapps.md)
153+
- [Docs Validation Checklist](reference/docs-validation-checklist.md)
154+
- [Diagrams Index](diagrams/index.md)

‎docs/architecture/deep-design.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Architecture Deep Design
2+
3+
This page provides detailed architecture and decision guidance for AVD control-plane resources in Azure and session hosts on Azure Local.
4+
5+
## Control plane: components and responsibilities
6+
- Host Pool: logical grouping of session hosts. Defines `personal` vs `pooled` assignment, load-balancing behavior, and diagnostics scope.
7+
- Application Group: publishes desktops or RemoteApps; ties to role assignments for end-user access.
8+
- Workspace: user-facing aggregator; maps Application Groups to user experience.
9+
- Key Vault: stores secrets used during provisioning (domain join credentials, certificates). Access controlled via Managed Identity or service principal.
10+
- Log Analytics (LAW): central diagnostics ingestion for AVD control-plane categories and session-host telemetry.
11+
- Storage: optional Azure Storage for MSIX app attach or cloud-backed FSLogix scenarios.
12+
13+
Design notes:
14+
- Treat the control plane as subscription-scoped and idempotent; prefer modules (Bicep modules / AVM) and expose outputs used by session-host provisioning (hostPoolId, workspaceId, lawResourceId).
15+
- Use `Key Vault` for secrets; grant least-privilege access via managed identities on deployment principals.
16+
17+
## Session-host topologies
18+
- Single-cluster: one Azure Local cluster hosting all session hosts — simpler management, single point of failure at host level.
19+
- Multi-cluster: multiple Azure Local clusters (regional or fault-domain separation) — requires cross-cluster identity and network planning.
20+
- Distributed SOFS (guest cluster approach): recommended pattern — guest S2D cluster inside VMs provides FSLogix SMB shares with stacked resiliency (host CSV + guest S2D).
21+
22+
## Identity patterns
23+
- AD DS (domain-join): required for Azure Local when using on-premises SMB and Kerberos for FSLogix.
24+
- Hybrid Entra ID: domain-joined + Entra registration; supports SSO and Conditional Access while maintaining Kerberos SMB for profiles.
25+
- Entra-only + Cloud Cache: viable for Entra-only scenarios — requires FSLogix Cloud Cache (CCD) and cloud storage backing; increases complexity for SOFS integration.
26+
27+
Recommendation: default to AD DS / hybrid Entra ID for Azure Local deployments unless the environment is Entra-native and cloud-based profile caching is acceptable.
28+
29+
## Network design
30+
- Egress: session-hosts must reach broker endpoints, Entra ID, Windows Update, and Log Analytics over HTTPS (443).
31+
- SMB: keep FSLogix SMB traffic on the same L2/L3 domain (low latency). Avoid routing SMB across wide-area links.
32+
- DNS: ensure session-hosts resolve both on-prem and Azure endpoints; consider split-horizon DNS for internal names.
33+
- Ports & rules: document minimal required ports (RDP/UDP via AVD gateway handled by Azure; SMB 445 for profiles; WinRM 5985/5986 for automation).
34+
35+
## DR, backups and availability
36+
- Control-plane: maintain ARM/Bicep source of truth; backup Key Vault contents via Key Vault backup and export parameterized templates for faster recovery.
37+
- FSLogix profiles: recommend backups of profile containers or use replication for SOFS (storage-level replication) and regularly test restore procedures.
38+
- Disaster scenarios: document runbooks for control-plane redeploy from IaC, profile restore, and reprovisioning session-hosts from golden images.
39+
40+
## Cost and sizing guidance
41+
- Log Analytics: retention and ingestion drive costs; keep diagnostic categories scoped (only required categories) and use sampling for high-volume telemetry.
42+
- Session-host sizing: provision VMs based on expected concurrency; prefer tested session density per SKU rather than overcommitting CPU; use autoscale to optimize costs.
43+
44+
## Worked deployment patterns
45+
46+
### Small footprint (up to 100 users)
47+
- One pooled host pool.
48+
- Single Azure Local cluster.
49+
- One SOFS share and one Log Analytics workspace.
50+
51+
### Medium footprint (100-500 users)
52+
- Multiple app groups on shared host pools.
53+
- Separate prod/non-prod host pools.
54+
- Dedicated monitoring workspace and defined DR for profile containers.
55+
56+
### Large footprint (500+ users)
57+
- Multi-cluster session-host strategy.
58+
- Segmented host pools by workload tier.
59+
- Replicated profile storage and tested DR runbooks.
60+
61+
## Outputs and contracts
62+
- Ensure the control-plane module exports canonical outputs:
63+
- `hostPoolResourceId`
64+
- `applicationGroupResourceId`
65+
- `workspaceResourceId`
66+
- `logAnalyticsWorkspaceId`
67+
- `keyVaultResourceId`
68+
69+
These outputs are consumed by session-host provisioning modules and orchestration scripts.
70+
71+
## Parameter mapping summary
72+
73+
| Functional area | Canonical config | Bicep parameter family | Terraform variable family | PowerShell input |
74+
|---|---|---|---|---|
75+
| Host pool | `host_pool.*` | `hostPool*` | `host_pool_*` | `-HostPool*` |
76+
| Diagnostics | `monitoring.*` | `logAnalytics*`, `diagnostic*` | `log_analytics_*` | `-LogAnalytics*` |
77+
| Identity/RBAC | `identity.*`, `rbac.*` | `principal*`, `roleAssignment*` | `principal_*`, `role_assignment_*` | `-Principal*`, `-Role*` |
78+
| FSLogix | `fslogix.*` | `fslogix*` | `fslogix_*` | `-FSLogix*` |
79+
80+
## References
81+
- Microsoft AVD docs: https://learn.microsoft.com/azure/virtual-desktop/
82+
- FSLogix docs: https://learn.microsoft.com/fslogix/
83+
- Azure Monitor diagnostic settings: https://learn.microsoft.com/azure/azure-monitor/alerts/diagnostic-settings
84+
- Host pool guide: ../reference/host-pool-options.md
85+
- FSLogix guide: ./fslogix-integration.md
86+
- Monitoring guide: ../reference/monitoring-queries.md
87+
- Cost guide: ../operations/cost-management.md

‎docs/architecture/fslogix-integration.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# FSLogix Integration
2+
3+
This guide defines how to run FSLogix profile containers for AVD session hosts on Azure Local with operationally safe defaults.
4+
5+
## 1) Profile container model selection
6+
7+
### VHDX on SMB (SOFS)
8+
- Best for: Azure Local with low-latency SMB and AD DS/Kerberos.
9+
- Pros: simple operations, predictable performance, no cloud dependency in steady state.
10+
- Cons: recovery depends on storage replication/backup maturity.
11+
12+
### Cloud Cache (CCD)
13+
- Best for: multi-site resiliency, Entra-only patterns, or mixed storage backends.
14+
- Pros: supports multiple providers and tolerates backend outages.
15+
- Cons: higher write amplification, more tuning/monitoring complexity.
16+
17+
Recommended default: use VHDX on SOFS for primary Azure Local designs and introduce CCD only where explicit DR/availability requirements justify complexity.
18+
19+
## 2) Sizing and capacity planning
20+
21+
Baseline sizing:
22+
- Profile target per user: 25-40 GB (start with 30 GB).
23+
- Free space buffer: 30% on the profile volume.
24+
- Metadata growth allowance: 10% additional capacity.
25+
26+
Planning formula:
27+
28+
$$
29+
Required\ Capacity = (Users \times Profile\ Size) \times 1.4
30+
$$
31+
32+
Example:
33+
- 400 users, 30 GB each: $400 \times 30 \times 1.4 = 16.8$ TB usable.
34+
35+
## 3) SOFS and SMB configuration guidance
36+
37+
Storage layout:
38+
- Use dedicated CSV volumes for profile containers (separate from golden image/app content volumes).
39+
- Use continuous availability SMB shares for profile paths.
40+
- Keep storage traffic on dedicated east-west networks.
41+
42+
SMB recommendations:
43+
- SMB Multichannel enabled.
44+
- SMB encryption only where required by policy (measure impact first).
45+
- Access-based enumeration enabled for profile shares.
46+
47+
Permissions baseline:
48+
- Share permissions: `Authenticated Users` change, `Administrators` full control.
49+
- NTFS: Creator Owner full on subfolders/files, users only to their own folders, admins/system full control.
50+
51+
## 4) FSLogix registry baseline
52+
53+
Primary keys under `HKLM:\SOFTWARE\FSLogix\Profiles`:
54+
- `Enabled` (DWORD) = `1`
55+
- `DeleteLocalProfileWhenVHDShouldApply` (DWORD) = `1`
56+
- `FlipFlopProfileDirectoryName` (DWORD) = `1`
57+
- `IsDynamic` (DWORD) = `1`
58+
- `SizeInMBs` (DWORD) = `30720` (30 GB default)
59+
- `VolumeType` (String) = `vhdx`
60+
- `VHDLocations` (Multi-String) = `\\sofs\fslogixprofiles`
61+
62+
PowerShell example:
63+
64+
```powershell
65+
$base = 'HKLM:\SOFTWARE\FSLogix\Profiles'
66+
New-Item -Path $base -Force | Out-Null
67+
New-ItemProperty -Path $base -Name Enabled -PropertyType DWord -Value 1 -Force | Out-Null
68+
New-ItemProperty -Path $base -Name DeleteLocalProfileWhenVHDShouldApply -PropertyType DWord -Value 1 -Force | Out-Null
69+
New-ItemProperty -Path $base -Name FlipFlopProfileDirectoryName -PropertyType DWord -Value 1 -Force | Out-Null
70+
New-ItemProperty -Path $base -Name IsDynamic -PropertyType DWord -Value 1 -Force | Out-Null
71+
New-ItemProperty -Path $base -Name SizeInMBs -PropertyType DWord -Value 30720 -Force | Out-Null
72+
New-ItemProperty -Path $base -Name VolumeType -PropertyType String -Value 'vhdx' -Force | Out-Null
73+
New-ItemProperty -Path $base -Name VHDLocations -PropertyType MultiString -Value '\\sofs\fslogixprofiles' -Force | Out-Null
74+
```
75+
76+
Ansible example:
77+
78+
```yaml
79+
- name: Configure FSLogix registry baseline
80+
ansible.windows.win_regedit:
81+
path: HKLM:\SOFTWARE\FSLogix\Profiles
82+
name: "{{ item.name }}"
83+
data: "{{ item.data }}"
84+
type: "{{ item.type }}"
85+
state: present
86+
loop:
87+
- { name: Enabled, type: dword, data: 1 }
88+
- { name: DeleteLocalProfileWhenVHDShouldApply, type: dword, data: 1 }
89+
- { name: FlipFlopProfileDirectoryName, type: dword, data: 1 }
90+
- { name: IsDynamic, type: dword, data: 1 }
91+
- { name: SizeInMBs, type: dword, data: 30720 }
92+
- { name: VolumeType, type: string, data: vhdx }
93+
- { name: VHDLocations, type: multistring, data: '\\sofs\fslogixprofiles' }
94+
```
95+
96+
## 5) Antivirus and performance exclusions
97+
98+
Validate against security policy before applying exclusions. Common exclusions include:
99+
- FSLogix process paths (`frxsvc.exe`, `frxrobocopy.exe`).
100+
- Profile container share path.
101+
- VHD(X) attach points.
102+
103+
Always verify exclusions with security operations and Defender policy owners.
104+
105+
## 6) DR and backup strategy
106+
107+
Minimum controls:
108+
- Daily backup of FSLogix container volumes.
109+
- Replication across fault domains or secondary site for critical workloads.
110+
- Quarterly restore test using representative profile containers.
111+
112+
Recovery objective guidance:
113+
- Define profile RPO/RTO explicitly in operations runbooks.
114+
- Validate sign-in performance after restore and check profile lock cleanup.
115+
116+
## 7) Validation tests
117+
118+
Post-deployment checks:
119+
- User sign-in creates and mounts profile VHDX.
120+
- Re-sign-in lands on same profile state across hosts.
121+
- Event logs show no recurring `frxsvc` attach errors.
122+
- SMB latency and IO remain within baseline thresholds.
123+
124+
PowerShell validation example:
125+
126+
```powershell
127+
Get-WinEvent -LogName 'Microsoft-FSLogix-Apps/Operational' -MaxEvents 100 |
128+
Where-Object { $_.LevelDisplayName -in 'Error','Warning' } |
129+
Select-Object TimeCreated, Id, Message
130+
```
131+
132+
## Related references
133+
- Companion SOFS repo: https://github.com/AzureLocal/azurelocal-sofs-fslogix
134+
- FSLogix docs: https://learn.microsoft.com/fslogix/
135+
- Deep architecture design: ../deep-design.md

‎docs/audit/docs-audit.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Documentation Audit — azurelocal-avd
2+
3+
Generated: 2026-03-22
4+
5+
## Overview
6+
This audit lists existing documentation files in `azurelocal-avd` and recommended edits/additions to align with Epic #8 documentation plan.
7+
8+
## Existing key docs (reviewed)
9+
- `docs/architecture.md` — High-level architecture (exists)
10+
- `docs/guides/avd-deployment-guide.md` — Deployment guide (exists)
11+
- `docs/reference/monitoring-queries.md` — Monitoring KQLs (exists)
12+
- `docs/reference/tool-parity-matrix.md` — Tool parity (exists)
13+
- `docs/reference/variable-mapping.md` — Variable mapping (exists)
14+
15+
## Recommended new pages (stubs created)
16+
- `docs/architecture/deep-design.md` — deeper design (created)
17+
- `docs/architecture/fslogix-integration.md` — FSLogix integration (created)
18+
- `docs/reference/host-pool-options.md` — host-pool config options (created)
19+
- `docs/guides/rdapps.md` — RemoteApps publishing guide (created)
20+
- `docs/operations/defender-operations.md` — Defender & security (created)
21+
- `docs/operations/cost-management.md` — cost management (created)
22+
- `docs/diagrams/README.md` — diagrams guidance (created)
23+
- `docs/README.md` — docs index (created)
24+
25+
## Files that should be updated (high priority)
26+
- `docs/architecture.md` — add links to new deep-design and FSLogix pages; include decision flows and diagram references
27+
- `docs/guides/avd-deployment-guide.md` — update steps to reference new RBAC/FSLogix/host-pool docs
28+
- `docs/reference/monitoring-queries.md` — expand with LAW table mappings and cost-related KQL samples
29+
- `mkdocs.yml` — ensure `docs/diagrams` included and `mkdocs-drawio` plugin is configured (CI currently installs mkdocs-drawio)
30+
- `.github/workflows/validate-repo-structure.yml` — ensure checks accept new files; add docs lint/check step if not present
31+
32+
## Reusable assets in `azurelocal-sofs-fslogix`
33+
(Do NOT edit SOFS repo; reference or copy exported PNGs)
34+
- `docs/assets/diagrams/sofs-deployment-phases.drawio` (draw.io source)
35+
- `docs/assets/images/sofs-deployment-phases.png` (exported image)
36+
- `docs/architecture/storage-design.md`, `capacity-planning.md`, `scenarios.md`, `avd-considerations.md`
37+
38+
## Next recommended actions (short-term)
39+
1. Review and accept the created stubs in a docs PR.
40+
2. Copy selected exported PNGs from `azurelocal-sofs-fslogix` into `docs/diagrams/` in this repo (no edits to SOFS repo).
41+
3. Populate `deep-design.md` and `fslogix-integration.md` with content adapted from SOFS docs and Microsoft references.
42+
4. Add draw.io source files in `docs/diagrams/` for AVD-specific diagrams (control-plane, network, DR) and export PNG/SVG.
43+
44+
## Contacts / Owners
45+
- Docs owner: maintainers of `azurelocal-avd` (please assign an architecture reviewer)
46+

‎docs/diagrams/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Diagrams
2+
3+
This directory contains architecture diagram sources and rendered assets for AVD on Azure Local documentation.
4+
5+
## Standards
6+
- Use draw.io (`.drawio`) for editable sources.
7+
- Keep exported `.png` and `.svg` for MkDocs compatibility.
8+
- Name diagrams by function and scope (for example `control-plane`, `network-flow`, `dr-recovery`).
9+
10+
## Included assets
11+
- `control-plane.drawio`
12+
- `avd-reference-architecture.drawio`
13+
- `avd-reference-architecture.png`
14+
- `sofs-deployment-phases.drawio`
15+
- `sofs-deployment-phases.png`
16+
17+
## Workflow
18+
1. Edit diagram in draw.io.
19+
2. Export PNG and SVG to this folder.
20+
3. Update `docs/diagrams/index.md` if a new asset is added.

0 commit comments

Comments
 (0)