docs: complete Epic #8 AVD documentation plan

docs/README.md

@@ -0,0 +1,27 @@
+# Documentation Index
+
+This index maps the core architecture, guide, operations, and reference pages.
+
+## Architecture
+- [Architecture Overview](architecture.md)
+- [Architecture Deep Design](architecture/deep-design.md)
+- [FSLogix Integration](architecture/fslogix-integration.md)
+
+## Guides
+- [AVD Deployment Guide](guides/avd-deployment-guide.md)
+- [RemoteApps Guide](guides/rdapps.md)
+
+## Operations and Security
+- [Cost Management](operations/cost-management.md)
+- [Defender Operations](security/defender-operations.md)
+
+## Reference
+- [Host Pool Options](reference/host-pool-options.md)
+- [Monitoring Queries](reference/monitoring-queries.md)
+- [RBAC Reference](reference/rbac.md)
+- [Docs Validation Checklist](reference/docs-validation-checklist.md)
+- [Variable Mapping](reference/variable-mapping.md)
+- [Tool Parity Matrix](reference/tool-parity-matrix.md)
+
+## Diagrams
+- [Diagrams Index](diagrams/index.md)

docs/architecture.md

@@ -60,6 +60,10 @@ The AVD architecture has two distinct planes:
     └──────────────┘
 ```
 
+Diagram asset:
+
+![AVD on Azure Local reference architecture](diagrams/avd-reference-architecture.png)
+
 ---
 
 ## Key Components
@@ -135,3 +139,16 @@ Reference docs:
 - [FSLogix documentation](https://learn.microsoft.com/en-us/fslogix/)
 - [Arc Resource Bridge](https://learn.microsoft.com/en-us/azure/azure-arc/resource-bridge/overview)
 - [Companion SOFS/FSLogix repository](https://github.com/AzureLocal/azurelocal-sofs-fslogix)
+
+## Extended Documentation
+
+- [Architecture Deep Design](architecture/deep-design.md)
+- [FSLogix Integration Guide](architecture/fslogix-integration.md)
+- [Host Pool Options](reference/host-pool-options.md)
+- [RBAC Reference](reference/rbac.md)
+- [Monitoring Queries](reference/monitoring-queries.md)
+- [Cost Management](operations/cost-management.md)
+- [Defender Operations](security/defender-operations.md)
+- [RemoteApps Guide](guides/rdapps.md)
+- [Docs Validation Checklist](reference/docs-validation-checklist.md)
+- [Diagrams Index](diagrams/index.md)

docs/architecture/deep-design.md

@@ -0,0 +1,87 @@
+# Architecture Deep Design
+
+This page provides detailed architecture and decision guidance for AVD control-plane resources in Azure and session hosts on Azure Local.
+
+## Control plane: components and responsibilities
+- Host Pool: logical grouping of session hosts. Defines `personal` vs `pooled` assignment, load-balancing behavior, and diagnostics scope.
+- Application Group: publishes desktops or RemoteApps; ties to role assignments for end-user access.
+- Workspace: user-facing aggregator; maps Application Groups to user experience.
+- Key Vault: stores secrets used during provisioning (domain join credentials, certificates). Access controlled via Managed Identity or service principal.
+- Log Analytics (LAW): central diagnostics ingestion for AVD control-plane categories and session-host telemetry.
+- Storage: optional Azure Storage for MSIX app attach or cloud-backed FSLogix scenarios.
+
+Design notes:
+- 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).
+- Use `Key Vault` for secrets; grant least-privilege access via managed identities on deployment principals.
+
+## Session-host topologies
+- Single-cluster: one Azure Local cluster hosting all session hosts — simpler management, single point of failure at host level.
+- Multi-cluster: multiple Azure Local clusters (regional or fault-domain separation) — requires cross-cluster identity and network planning.
+- Distributed SOFS (guest cluster approach): recommended pattern — guest S2D cluster inside VMs provides FSLogix SMB shares with stacked resiliency (host CSV + guest S2D).
+
+## Identity patterns
+- AD DS (domain-join): required for Azure Local when using on-premises SMB and Kerberos for FSLogix.
+- Hybrid Entra ID: domain-joined + Entra registration; supports SSO and Conditional Access while maintaining Kerberos SMB for profiles.
+- Entra-only + Cloud Cache: viable for Entra-only scenarios — requires FSLogix Cloud Cache (CCD) and cloud storage backing; increases complexity for SOFS integration.
+
+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.
+
+## Network design
+- Egress: session-hosts must reach broker endpoints, Entra ID, Windows Update, and Log Analytics over HTTPS (443).
+- SMB: keep FSLogix SMB traffic on the same L2/L3 domain (low latency). Avoid routing SMB across wide-area links.
+- DNS: ensure session-hosts resolve both on-prem and Azure endpoints; consider split-horizon DNS for internal names.
+- Ports & rules: document minimal required ports (RDP/UDP via AVD gateway handled by Azure; SMB 445 for profiles; WinRM 5985/5986 for automation).
+
+## DR, backups and availability
+- Control-plane: maintain ARM/Bicep source of truth; backup Key Vault contents via Key Vault backup and export parameterized templates for faster recovery.
+- FSLogix profiles: recommend backups of profile containers or use replication for SOFS (storage-level replication) and regularly test restore procedures.
+- Disaster scenarios: document runbooks for control-plane redeploy from IaC, profile restore, and reprovisioning session-hosts from golden images.
+
+## Cost and sizing guidance
+- Log Analytics: retention and ingestion drive costs; keep diagnostic categories scoped (only required categories) and use sampling for high-volume telemetry.
+- Session-host sizing: provision VMs based on expected concurrency; prefer tested session density per SKU rather than overcommitting CPU; use autoscale to optimize costs.
+
+## Worked deployment patterns
+
+### Small footprint (up to 100 users)
+- One pooled host pool.
+- Single Azure Local cluster.
+- One SOFS share and one Log Analytics workspace.
+
+### Medium footprint (100-500 users)
+- Multiple app groups on shared host pools.
+- Separate prod/non-prod host pools.
+- Dedicated monitoring workspace and defined DR for profile containers.
+
+### Large footprint (500+ users)
+- Multi-cluster session-host strategy.
+- Segmented host pools by workload tier.
+- Replicated profile storage and tested DR runbooks.
+
+## Outputs and contracts
+- Ensure the control-plane module exports canonical outputs:
+	- `hostPoolResourceId`
+	- `applicationGroupResourceId`
+	- `workspaceResourceId`
+	- `logAnalyticsWorkspaceId`
+	- `keyVaultResourceId`
+
+These outputs are consumed by session-host provisioning modules and orchestration scripts.
+
+## Parameter mapping summary
+
+| Functional area | Canonical config | Bicep parameter family | Terraform variable family | PowerShell input |
+|---|---|---|---|---|
+| Host pool | `host_pool.*` | `hostPool*` | `host_pool_*` | `-HostPool*` |
+| Diagnostics | `monitoring.*` | `logAnalytics*`, `diagnostic*` | `log_analytics_*` | `-LogAnalytics*` |
+| Identity/RBAC | `identity.*`, `rbac.*` | `principal*`, `roleAssignment*` | `principal_*`, `role_assignment_*` | `-Principal*`, `-Role*` |
+| FSLogix | `fslogix.*` | `fslogix*` | `fslogix_*` | `-FSLogix*` |
+
+## References
+- Microsoft AVD docs: https://learn.microsoft.com/azure/virtual-desktop/
+- FSLogix docs: https://learn.microsoft.com/fslogix/
+- Azure Monitor diagnostic settings: https://learn.microsoft.com/azure/azure-monitor/alerts/diagnostic-settings
+- Host pool guide: ../reference/host-pool-options.md
+- FSLogix guide: ./fslogix-integration.md
+- Monitoring guide: ../reference/monitoring-queries.md
+- Cost guide: ../operations/cost-management.md

docs/architecture/fslogix-integration.md

@@ -0,0 +1,135 @@
+# FSLogix Integration
+
+This guide defines how to run FSLogix profile containers for AVD session hosts on Azure Local with operationally safe defaults.
+
+## 1) Profile container model selection
+
+### VHDX on SMB (SOFS)
+- Best for: Azure Local with low-latency SMB and AD DS/Kerberos.
+- Pros: simple operations, predictable performance, no cloud dependency in steady state.
+- Cons: recovery depends on storage replication/backup maturity.
+
+### Cloud Cache (CCD)
+- Best for: multi-site resiliency, Entra-only patterns, or mixed storage backends.
+- Pros: supports multiple providers and tolerates backend outages.
+- Cons: higher write amplification, more tuning/monitoring complexity.
+
+Recommended default: use VHDX on SOFS for primary Azure Local designs and introduce CCD only where explicit DR/availability requirements justify complexity.
+
+## 2) Sizing and capacity planning
+
+Baseline sizing:
+- Profile target per user: 25-40 GB (start with 30 GB).
+- Free space buffer: 30% on the profile volume.
+- Metadata growth allowance: 10% additional capacity.
+
+Planning formula:
+
+$$
+Required\ Capacity = (Users \times Profile\ Size) \times 1.4
+$$
+
+Example:
+- 400 users, 30 GB each: $400 \times 30 \times 1.4 = 16.8$ TB usable.
+
+## 3) SOFS and SMB configuration guidance
+
+Storage layout:
+- Use dedicated CSV volumes for profile containers (separate from golden image/app content volumes).
+- Use continuous availability SMB shares for profile paths.
+- Keep storage traffic on dedicated east-west networks.
+
+SMB recommendations:
+- SMB Multichannel enabled.
+- SMB encryption only where required by policy (measure impact first).
+- Access-based enumeration enabled for profile shares.
+
+Permissions baseline:
+- Share permissions: `Authenticated Users` change, `Administrators` full control.
+- NTFS: Creator Owner full on subfolders/files, users only to their own folders, admins/system full control.
+
+## 4) FSLogix registry baseline
+
+Primary keys under `HKLM:\SOFTWARE\FSLogix\Profiles`:
+- `Enabled` (DWORD) = `1`
+- `DeleteLocalProfileWhenVHDShouldApply` (DWORD) = `1`
+- `FlipFlopProfileDirectoryName` (DWORD) = `1`
+- `IsDynamic` (DWORD) = `1`
+- `SizeInMBs` (DWORD) = `30720` (30 GB default)
+- `VolumeType` (String) = `vhdx`
+- `VHDLocations` (Multi-String) = `\\sofs\fslogixprofiles`
+
+PowerShell example:
+
+```powershell
+$base = 'HKLM:\SOFTWARE\FSLogix\Profiles'
+New-Item -Path $base -Force | Out-Null
+New-ItemProperty -Path $base -Name Enabled -PropertyType DWord -Value 1 -Force | Out-Null
+New-ItemProperty -Path $base -Name DeleteLocalProfileWhenVHDShouldApply -PropertyType DWord -Value 1 -Force | Out-Null
+New-ItemProperty -Path $base -Name FlipFlopProfileDirectoryName -PropertyType DWord -Value 1 -Force | Out-Null
+New-ItemProperty -Path $base -Name IsDynamic -PropertyType DWord -Value 1 -Force | Out-Null
+New-ItemProperty -Path $base -Name SizeInMBs -PropertyType DWord -Value 30720 -Force | Out-Null
+New-ItemProperty -Path $base -Name VolumeType -PropertyType String -Value 'vhdx' -Force | Out-Null
+New-ItemProperty -Path $base -Name VHDLocations -PropertyType MultiString -Value '\\sofs\fslogixprofiles' -Force | Out-Null
+```
+
+Ansible example:
+
+```yaml
+- name: Configure FSLogix registry baseline
+	ansible.windows.win_regedit:
+		path: HKLM:\SOFTWARE\FSLogix\Profiles
+		name: "{{ item.name }}"
+		data: "{{ item.data }}"
+		type: "{{ item.type }}"
+		state: present
+	loop:
+		- { name: Enabled, type: dword, data: 1 }
+		- { name: DeleteLocalProfileWhenVHDShouldApply, type: dword, data: 1 }
+		- { name: FlipFlopProfileDirectoryName, type: dword, data: 1 }
+		- { name: IsDynamic, type: dword, data: 1 }
+		- { name: SizeInMBs, type: dword, data: 30720 }
+		- { name: VolumeType, type: string, data: vhdx }
+		- { name: VHDLocations, type: multistring, data: '\\sofs\fslogixprofiles' }
+```
+
+## 5) Antivirus and performance exclusions
+
+Validate against security policy before applying exclusions. Common exclusions include:
+- FSLogix process paths (`frxsvc.exe`, `frxrobocopy.exe`).
+- Profile container share path.
+- VHD(X) attach points.
+
+Always verify exclusions with security operations and Defender policy owners.
+
+## 6) DR and backup strategy
+
+Minimum controls:
+- Daily backup of FSLogix container volumes.
+- Replication across fault domains or secondary site for critical workloads.
+- Quarterly restore test using representative profile containers.
+
+Recovery objective guidance:
+- Define profile RPO/RTO explicitly in operations runbooks.
+- Validate sign-in performance after restore and check profile lock cleanup.
+
+## 7) Validation tests
+
+Post-deployment checks:
+- User sign-in creates and mounts profile VHDX.
+- Re-sign-in lands on same profile state across hosts.
+- Event logs show no recurring `frxsvc` attach errors.
+- SMB latency and IO remain within baseline thresholds.
+
+PowerShell validation example:
+
+```powershell
+Get-WinEvent -LogName 'Microsoft-FSLogix-Apps/Operational' -MaxEvents 100 |
+	Where-Object { $_.LevelDisplayName -in 'Error','Warning' } |
+	Select-Object TimeCreated, Id, Message
+```
+
+## Related references
+- Companion SOFS repo: https://github.com/AzureLocal/azurelocal-sofs-fslogix
+- FSLogix docs: https://learn.microsoft.com/fslogix/
+- Deep architecture design: ../deep-design.md

docs/audit/docs-audit.md

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

docs/diagrams/README.md

@@ -0,0 +1,20 @@
+# Diagrams
+
+This directory contains architecture diagram sources and rendered assets for AVD on Azure Local documentation.
+
+## Standards
+- Use draw.io (`.drawio`) for editable sources.
+- Keep exported `.png` and `.svg` for MkDocs compatibility.
+- Name diagrams by function and scope (for example `control-plane`, `network-flow`, `dr-recovery`).
+
+## Included assets
+- `control-plane.drawio`
+- `avd-reference-architecture.drawio`
+- `avd-reference-architecture.png`
+- `sofs-deployment-phases.drawio`
+- `sofs-deployment-phases.png`
+
+## Workflow
+1. Edit diagram in draw.io.
+2. Export PNG and SVG to this folder.
+3. Update `docs/diagrams/index.md` if a new asset is added.