AVM Example for Spec Kit

<!-- markdownlint-disable -->
<!--
SYNC IMPACT REPORT
==================
Version Change: N/A → 1.0.0 (Initial constitution ratification)

Modified Principles:
- N/A (Initial version)

Added Sections:
- Core Principles (6 principles defined)
- Infrastructure Standards
- Security & Compliance Requirements
- Development Workflow
- Governance

Removed Sections:
- N/A (Initial version)

Templates Requiring Updates:
- ✅ plan-template.md: Constitution Check section aligns with principles
- ✅ spec-template.md: Requirements structure aligns with security principles
- ✅ tasks-template.md: Task categorization aligns with validation-first workflow

Follow-up TODOs:
- None (all placeholders filled)

Change Rationale:
- MAJOR version (1.0.0) because this is the initial constitution establishing governance framework
- Principles focused on legacy workload characteristics: compliance retention, IaC-first with Bicep, AVM-only modules, validation-before-deployment
-->

# Legacy Azure Workload Constitution

## Core Principles

### I. Infrastructure-as-Code First (NON-NEGOTIABLE)
All Azure resources MUST be defined in Bicep templates. Manual Azure Portal configurations are STRICTLY PROHIBITED.

**Rationale**: Ensures compliance auditability, repeatability, and version control for regulatory requirements. Manual changes create configuration drift that violates compliance mandates.

**Rules**:
- Every feature starts with Bicep code defining the infrastructure
- Custom scripts are permitted ONLY when Bicep/ARM capabilities are insufficient
- All infrastructure changes MUST go through version control
- Single-template approach: define everything in one main.bicep, let ARM handle dependencies

### II. AVM-Only Modules
All Bicep infrastructure MUST use Azure Verified Modules (AVM). Direct resource declarations are permitted only when no AVM module exists.

**Rationale**: AVM modules are officially maintained, follow security best practices, and are compliance-tested by Microsoft.

**Rules**:
- Search for AVM module first (using `#list_avm_metadata` tool)
- Use latest stable version of AVM modules
- Document justification when direct resource declaration is necessary
- Follow AVM module documentation for parameter configuration

### III. Validation Before Deployment (NON-NEGOTIABLE)
Every deployment MUST be preceded by ARM validation. Deployments without prior validation are STRICTLY PROHIBITED.

**Rationale**: Prevents configuration errors that could impact compliance-required systems. Validation catches issues before they affect production.

**Rules**:
- Run `az deployment group validate` before every deployment
- Run `az deployment group what-if` to preview changes
- Document validation results in deployment logs
- Address all validation errors before proceeding

### IV. Security & Reliability First
Security and reliability best practices MUST be followed under all circumstances, even for legacy workloads.

**Rationale**: Compliance requirements mandate security controls regardless of workload age. Legacy status does not exempt from security obligations.

**Rules**:
- Enable Azure Monitor and diagnostic logs for all resources
- Apply network security groups and private endpoints where applicable
- Use managed identities instead of connection strings/keys
- Follow principle of least privilege for all access
- Enable Azure Security Center recommendations

### V. Minimal Naming with Type Identification
Resource names MUST be concise: minimal random characters for uniqueness + resource type identifier.

**Rationale**: Improves resource identification while respecting Azure naming limitations. Avoids verbose names that exceed character limits.

**Rules**:
- Format: `{resourceType}-{purpose}-{randomSuffix}`
- Example: `st-legacyvm-k7m3p` for storage account
- Respect Azure resource-specific length limits (e.g., storage: 24 chars, lowercase/numbers only)
- Random suffix: 4-6 alphanumeric characters
- Document naming pattern in infrastructure documentation

### VI. Region Standardization
All resources MUST deploy to US West 3 (westus3) region unless technically impossible.

**Rationale**: Centralizes resources for simplified management and cost tracking. Reduces complexity for legacy workloads with no multi-region requirements.

**Rules**:
- Default region parameter: `westus3`
- Document exceptions with technical justification
- Global resources (e.g., Azure Front Door) exempted by nature

## Infrastructure Standards

### Bicep Template Requirements
- Single main.bicep file as deployment entry point
- Use main.bicepparam for environment-specific parameters
- Leverage ARM dependency management (avoid explicit dependsOn unless necessary)
- Include detailed parameter descriptions and constraints
- Use Bicep decorators for validation (`@minLength`, `@maxLength`, `@allowed`)

### Module Management
- Reference AVM modules via Bicep Registry (br/public:avm/...)
- Pin to specific module versions (never use 'latest')
- Document module selection rationale in comments
- Review AVM module documentation for breaking changes during updates

### Documentation Requirements
- Maintain README.md with deployment instructions
- Document all parameters in main.bicepparam
- Include architecture diagram showing resource relationships
- Record compliance justifications for resource configurations

## Security & Compliance Requirements

### Mandatory Controls
- **Logging**: Enable diagnostic settings for all resources supporting it
- **Access Control**: Use Azure RBAC, no shared keys in parameters
- **Network Security**: Apply NSGs to subnet/NIC resources
- **Encryption**: Use Azure-managed encryption (minimum); customer-managed keys where compliance requires
- **Secrets Management**: Store sensitive values in Azure Key Vault, reference via Bicep getSecret()

### Compliance Documentation
- Tag all resources with compliance identifiers (e.g., `compliance: "legacy-retention"`)
- Document retention policies for data resources
- Record security exceptions with business justification
- Maintain audit trail of all infrastructure changes

### Prohibited Practices
- Hardcoded secrets or connection strings in Bicep files
- Public IP addresses without business justification
- Unrestricted network access (0.0.0.0/0 rules)
- Disabled diagnostic logging

## Development Workflow

### Pre-Deployment Phase
1. Research and select appropriate AVM modules
2. Draft Bicep templates with parameter documentation
3. Run local Bicep linting (`bicep build`)
4. Commit code to version control

### Validation Phase (MANDATORY GATE)
1. Run `az deployment group validate` and resolve all errors
2. Run `az deployment group what-if` and review changes
3. Document validation results
4. Obtain approval for resource changes (if required by organization)

### Deployment Phase
1. Deploy using validated parameters
2. Monitor deployment progress
3. Verify resource creation via Azure Portal/CLI
4. Test resource functionality
5. Document deployment outcomes

### Post-Deployment Phase
1. Verify diagnostic settings are active
2. Confirm tags applied correctly
3. Review security recommendations in Azure Security Center
4. Update documentation with deployed resource details

## Governance

This constitution supersedes all other development practices and guidelines. All infrastructure changes MUST comply with these principles.

### Amendment Process
1. Propose amendment with business/technical justification
2. Document impact on existing infrastructure
3. Update constitution with version increment following semantic versioning
4. Update all dependent templates and documentation
5. Communicate changes to all stakeholders

### Versioning Policy
- **MAJOR**: Breaking changes to core principles (e.g., removing AVM-only requirement)
- **MINOR**: New principle added or existing principle materially expanded
- **PATCH**: Clarifications, wording improvements, non-semantic fixes

### Compliance Review
All pull requests MUST verify compliance with this constitution. Constitution violations require explicit justification and approval exception.

Complexity that deviates from simplicity principles MUST be documented and justified with business or technical rationale.

**Version**: 1.0.0 | **Ratified**: 2026-01-27 | **Last Amended**: 2026-01-27

<!-- markdownlint-disable -->
# Specification Quality Checklist: Legacy VM Workload Infrastructure

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-01-27
**Feature**: [spec.md](../spec.md)

## Content Quality

- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed

## Requirement Completeness

- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified

## Feature Readiness

- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification

## Validation Results

**Status**: ✅ PASSED - All checklist items completed successfully

**Validation Date**: 2026-01-27

**Details**:
- Specification includes 5 user stories, properly prioritized (P1-P3)
- 16 functional requirements defined with concrete Azure resources
- 8 security & compliance requirements aligned with constitution
- 6 infrastructure constraints following project standards
- 5 monitoring & alerting requirements for operational visibility
- 11 success criteria, all measurable and deployment-focused
- Edge cases identified (6 scenarios)
- Assumptions documented (13 items)
- Out of scope clearly defined (13 items)
- No [NEEDS CLARIFICATION] markers - all requirements are concrete and actionable

**Readiness**: ✅ Specification is ready for `/speckit.plan` phase

<!-- markdownlint-disable -->
# Feature Specification: Legacy VM Workload Infrastructure

**Feature Branch**: `001-legacy-vm-workload`
**Created**: 2026-01-27
**Status**: Draft
**Input**: User description: "legacy business application, running as a single virtual machine connected to a virtual network with Windows Server 2016, 2 CPU cores, 8 GB RAM, standard HDD, 500 GB data disk, bastion access, file share via private endpoint, NAT gateway internet access, NSGs, Key Vault for VM password, Log Analytics with diagnostic logging and critical alerts"

## User Scenarios & Testing *(mandatory)*

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
  you should still have a viable MVP (Minimum Viable Product) that delivers value.

  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
  Think of each story as a standalone slice of functionality that can be:
  - Developed independently
  - Tested independently
  - Deployed independently
  - Demonstrated to users independently
-->

### User Story 1 - Core VM Infrastructure Deployment (Priority: P1)

Deploy the fundamental infrastructure including virtual network, VM with required specifications, and basic connectivity. This establishes the baseline workload environment.

**Why this priority**: Without the VM and network infrastructure, no other components can function. This is the foundation for the entire workload.

**Independent Test**: Can be fully tested by deploying the infrastructure and verifying VM is created with correct specifications (Windows Server 2016, 2 cores, 8GB RAM, standard HDD) and can communicate within the VNet.

**Acceptance Scenarios**:

1. **Given** no existing infrastructure, **When** deployment is executed, **Then** VM is created with Windows Server 2016, 2 CPU cores, 8GB RAM
2. **Given** deployment is complete, **When** checking VM configuration, **Then** VM has standard HDD OS disk and is placed in correct VNet
3. **Given** VM is deployed, **When** checking computer name, **Then** NetBIOS name is 15 characters or fewer

---

### User Story 2 - Secure Storage and Data Disk (Priority: P2)

Provision the 500GB data disk for the VM and configure the storage account with file share accessible via private endpoint. This provides the data storage layer for the application.

**Why this priority**: Data storage is critical for application functionality but depends on the VM infrastructure being in place first.

**Independent Test**: Can be tested by verifying the 500GB HDD data disk is attached to the VM and the file share is accessible from the VM through the private endpoint.

**Acceptance Scenarios**:

1. **Given** VM infrastructure exists, **When** data disk deployment executes, **Then** 500GB HDD-based managed disk is attached to the VM
2. **Given** storage account is deployed, **When** checking storage configuration, **Then** HDD-backed file share is created
3. **Given** private endpoint is deployed, **When** VM attempts to access file share, **Then** connection succeeds through private network without traversing internet

---

### User Story 3 - Secure Access and Secrets Management (Priority: P2)

Implement bastion host for secure remote access and Key Vault for storing the VM administrator password. This ensures secure access patterns for operations teams.

**Why this priority**: Secure access is essential for ongoing operations but the infrastructure must exist before access can be configured.

**Independent Test**: Can be tested by connecting to the VM through bastion host using credentials retrieved from Key Vault.

**Acceptance Scenarios**:

1. **Given** bastion and Key Vault are deployed, **When** VM administrator password is generated at deployment, **Then** password is stored in Key Vault secret
2. **Given** bastion host is deployed, **When** operator attempts to connect to VM, **Then** connection succeeds through bastion without public IP on VM
3. **Given** Key Vault access is configured, **When** retrieving VM password, **Then** secret can be accessed only by authorized identities
4. **Given** VM subnet NSG is configured, **When** bastion attempts RDP connection to VM, **Then** traffic is allowed through NSG rule (port 3389 from Bastion subnet)

---

### User Story 4 - Internet Connectivity and Network Security (Priority: P3)

Configure NAT gateway for outbound internet access and implement Network Security Groups for all subnets with least-privilege rules.

**Why this priority**: Network security controls are important but the workload can function for testing without full NSG configuration initially.

**Independent Test**: Can be tested by verifying VM can reach internet through NAT gateway and that NSG rules block unauthorized traffic.

**Acceptance Scenarios**:

1. **Given** NAT gateway is deployed, **When** VM initiates outbound internet connection, **Then** traffic routes through NAT gateway
2. **Given** NSGs are configured, **When** unauthorized traffic attempts to reach VM, **Then** traffic is blocked by NSG rules
3. **Given** NSGs are deployed, **When** checking subnet associations, **Then** each subnet has appropriate NSG assigned

---

### User Story 5 - Monitoring and Alerting (Priority: P3)

Deploy Log Analytics workspace, configure diagnostic settings for all resources, and set up critical alerts (VM stopped, disk full, Key Vault access failures).

**Why this priority**: Monitoring is important for operations but the workload can function without it. It provides operational visibility rather than core functionality.

**Independent Test**: Can be tested by verifying diagnostic logs are flowing to Log Analytics and triggering test scenarios that generate alerts.

**Acceptance Scenarios**:

1. **Given** Log Analytics workspace is deployed, **When** resources are created, **Then** diagnostic settings send logs to workspace
2. **Given** alerting is configured, **When** VM is stopped, **Then** critical alert is triggered
3. **Given** alerting is configured, **When** Key Vault access fails, **Then** critical alert is triggered
4. **Given** diagnostic logging is active, **When** querying Log Analytics, **Then** logs are available within 5 minutes

---

## Clarifications

### Session 2026-01-27

- Q: VNet address space and subnet sizing for VM, bastion, and private endpoint subnets? → A: VNet: 10.0.0.0/24, VM subnet: 10.0.0.0/27, Bastion subnet: 10.0.0.64/26, Private endpoint subnet: 10.0.0.128/27
- Q: Storage file share quota size? → A: 1024 GiB (1 TiB)
- Q: Disk space alert threshold percentage? → A: 85% full
- Q: Alert notification method for critical alerts? → A: Azure Portal notifications only
- Q: VM size SKU for 2 cores and 8GB RAM requirement? → A: Standard_D2s_v3

### Edge Cases

- What happens when VM computer name parameter would exceed 15 characters? (NetBIOS limit must be enforced)
- How does deployment handle when Key Vault secret name parameter is not provided or is invalid?
- What happens when storage account name would exceed 24 characters or contains invalid characters?
- How does system handle when no availability zone is specified for resources requiring zone selection?
- What happens when private endpoint deployment fails but storage account succeeds?
- How does deployment handle if bastion subnet already exists in the VNet from a previous deployment?

## Requirements *(mandatory)*

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right functional requirements.
-->

### Functional Requirements

<!-- NOTE: "Standard HDD" refers to Azure Standard_LRS disk SKU (magnetic disk storage) -->

- **FR-001**: Infrastructure MUST provision a Windows Server 2016 Virtual Machine with size Standard_D2s_v3 (2 vCPUs, 8 GiB RAM) using Standard HDD for OS disk
- **FR-002**: Infrastructure MUST attach a 500GB HDD-based managed disk to the VM as a data disk
- **FR-003**: Infrastructure MUST create Virtual Network with address space 10.0.0.0/24 containing three subnets: VM subnet (10.0.0.0/27), Bastion subnet (10.0.0.64/26), and private endpoint subnet (10.0.0.128/27)
- **FR-004**: Infrastructure MUST deploy Azure Bastion for secure remote access to the VM without public IP
- **FR-005**: Infrastructure MUST provision Storage Account with HDD-backed file share (1024 GiB quota) accessible via private endpoint
- **FR-006**: Infrastructure MUST deploy NAT Gateway for VM outbound internet connectivity
- **FR-007**: Infrastructure MUST create Network Security Groups for each subnet with least-privilege rules
- **FR-008**: Infrastructure MUST deploy Azure Key Vault to store VM administrator password
- **FR-009**: Infrastructure MUST set VM administrator account name to "vmadmin"
- **FR-010**: Infrastructure MUST ensure VM computer name (NetBIOS name) is 15 characters or fewer
- **FR-011**: Infrastructure MUST generate and store VM administrator password in Key Vault at deployment time
- **FR-012**: Infrastructure MUST accept Key Vault secret name as a parameter from main.bicepparam
- **FR-013**: Infrastructure MUST deploy all resources to a single resource group representing production environment
- **FR-014**: Infrastructure MUST select availability zone between 1-3 for zone-capable resources (never use -1)
- **FR-015**: Infrastructure MUST include rich comments in both main.bicep and main.bicepparam explaining resource purpose and parameters
- **FR-016**: Infrastructure MUST rely exclusively on parameters defined in main.bicepparam file

### Security & Compliance Requirements (Mandatory for all features)

- **SEC-001**: All resources MUST enable diagnostic settings and send logs to Log Analytics Workspace
- **SEC-002**: VM MUST use managed identity for Azure resource authentication (no connection strings/keys in configuration)
- **SEC-003**: Network Security Groups MUST restrict traffic to only necessary ports and protocols per subnet
- **SEC-003a**: VM subnet NSG MUST allow inbound RDP (port 3389) from Bastion subnet (10.0.0.64/26) to enable bastion connectivity
- **SEC-004**: All resources MUST be tagged with compliance identifier "legacy-retention"
- **SEC-005**: VM administrator password MUST be stored in Azure Key Vault, never in code or parameters
- **SEC-006**: VM MUST NOT have public IP address assigned (access only through bastion)
- **SEC-007**: Storage account file share MUST be accessible only through private endpoint, not public endpoint
- **SEC-008**: Key Vault MUST restrict access to only authorized identities using RBAC

### Infrastructure Constraints

- **IC-001**: MUST deploy to westus3 region (US West 3)
- **IC-002**: MUST use Azure Verified Modules (AVM) exclusively (read module readme.md for parameter documentation)
- **IC-003**: MUST validate deployment with `az deployment group validate` before applying
- **IC-004**: MUST run `az deployment group what-if` to preview changes
- **IC-005**: Resource names MUST follow pattern: {resourceType}-{purpose}-{random4-6chars}
- **IC-006**: MUST NOT create additional environments (dev, test, staging) - production only

### Monitoring & Alerting Requirements

- **MON-001**: Infrastructure MUST deploy Log Analytics workspace for centralized logging
- **MON-002**: Infrastructure MUST configure diagnostic logging for VM, Key Vault, Storage Account, and network resources
- **MON-003**: Infrastructure MUST create critical alert for VM stopped/deallocated condition (Portal notifications)
- **MON-004**: Infrastructure MUST create critical alert for disk space exceeding 85% threshold (Portal notifications)
- **MON-005**: Infrastructure MUST create critical alert for Key Vault access failures (Portal notifications)

### Key Azure Resources

- **Virtual Machine**: Windows Server 2016 VM with size Standard_D2s_v3 (2 vCPUs, 8 GiB RAM), Standard HDD OS disk, managed identity enabled
- **Managed Disk**: 500GB HDD-based data disk attached to VM
- **Virtual Network**: VNet with subnets for VM, bastion, and private endpoints
- **Azure Bastion**: Secure RDP access to VM without public IP
- **Storage Account**: Standard HDD storage with file share
- **Private Endpoint**: Secure connectivity between VM and storage account file share
- **NAT Gateway**: Outbound internet connectivity for VM subnet
- **Network Security Groups**: One per subnet with least-privilege rules
- **Key Vault**: Stores VM administrator password as secret
- **Log Analytics Workspace**: Centralized logging for all resources
- **Azure Monitor Alerts**: Critical alerts for VM stopped, disk full, Key Vault access failures

## Success Criteria *(mandatory)*

<!--
  ACTION REQUIRED: Define measurable success criteria.
  These must be technology-agnostic and measurable.
-->

### Measurable Outcomes

- **SC-001**: Infrastructure deploys successfully within 20 minutes including all resources
- **SC-002**: ARM validation (`az deployment group validate`) passes without errors
- **SC-003**: ARM what-if analysis shows all expected resources will be created
- **SC-004**: VM is accessible via bastion host within 5 minutes of deployment completion
- **SC-005**: VM can access file share through private endpoint connection
- **SC-006**: VM can reach internet through NAT gateway for outbound connections
- **SC-007**: Diagnostic logs from all resources appear in Log Analytics within 5 minutes
- **SC-008**: All resources pass Azure Security Center baseline compliance checks
- **SC-009**: NSG rules successfully block unauthorized traffic in test scenarios
- **SC-010**: VM administrator password can be retrieved from Key Vault by authorized identities
- **SC-011**: Critical alerts can be triggered and verified (VM stop, simulated disk full warning, Key Vault access attempt)

## Assumptions

- Azure subscription has sufficient quota for Standard_D2s_v3 VM size
- Azure Bastion service is available in westus3 region
- Windows Server 2016 image is available in Azure Marketplace for westus3 region
- Log Analytics workspace can be deployed in westus3 region
- Private endpoint feature is available for storage accounts in westus3 region
- NAT Gateway is available in westus3 region
- Deployment is executed by identity with sufficient permissions to create all resource types
- Resource group name will be provided as parameter in main.bicepparam
- Random suffix for resource names will be generated or provided as parameter
- Default log retention period of 30 days is acceptable for Log Analytics (compliance requirement may differ)
- Standard_LRS storage redundancy is acceptable for this legacy workload
- VM will be deployed without availability sets or scale sets (single instance acceptable)
- Availability zone selection (1, 2, or 3) will be provided as parameter

## Out of Scope

- Multi-region deployment or disaster recovery configuration
- High availability (availability sets, load balancers, multiple VMs)
- Auto-scaling capabilities
- Backup and restore automation (Azure Backup configuration)
- Additional environments (development, test, staging)
- Application installation or configuration on the VM
- Custom monitoring dashboards or complex alerting logic beyond critical alerts
- Network connectivity to on-premises networks (VPN or ExpressRoute)
- Azure Active Directory domain join
- Additional data disks beyond the single 500GB disk specified
- Storage account configuration beyond file share (no blob containers, tables, or queues)
- Advanced network features (Azure Firewall, Application Gateway, Traffic Manager)
- Cost optimization recommendations or reserved instance planning

## Clarifications

- Q: How should the Azure file share be mounted on the Windows VM? → A: Post-deployment manual mount by administrator following documented procedure (no automation, aligns with IaC-first principle)
- Q: What level of monitoring and alerting should be configured for this legacy workload? → A: Diagnostic logging plus critical-only alerts (VM stopped, disk full, Key Vault access failures)
- Q: If the initial deployment partially fails (e.g., VM creates but Bastion fails), what should the recovery procedure be? → A: Keep existing resources, fix errors in template/parameters, redeploy entire template (ARM incremental mode handles already-deployed resources)
- Q: File share initial quota and growth strategy? → A: 1TB initial quota with documented growth monitoring procedure
- Q: VM administrator username? → A: vmadmin
- Q: VNet address space and subnet sizing for VM, bastion, and private endpoint subnets? → A: VNet: 10.0.0.0/24, VM subnet: 10.0.0.0/27, Bastion subnet: 10.0.0.64/26, Private endpoint subnet: 10.0.0.128/27
- Q: Storage file share quota size? → A: 1024 GiB (1 TiB)
- Q: Disk space alert threshold percentage? → A: 85% full
- Q: Alert notification method for critical alerts? → A: Azure Portal notifications only
- Q: VM size SKU for 2 cores and 8GB RAM requirement? → A: Standard_D2s_v3

<!-- markdownlint-disable -->
# Implementation Plan: Legacy VM Workload

**Branch**: `001-legacy-vm-workload` | **Date**: 2026-01-27 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-legacy-vm-workload/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

Deploy a legacy Windows Server 2016 virtual machine workload to Azure using Infrastructure-as-Code (Bicep) with the following capabilities:

- **Core Infrastructure**: Windows Server 2016 VM (Standard_D2s_v3) in availability zone 1, with system-assigned managed identity, 500GB HDD data disk, no public IP, deployed in dedicated VNet (10.0.0.0/24)
- **Secure Access**: Azure Bastion for RDP access, password stored in Key Vault, no direct internet exposure
- **Storage**: 1TB Azure Files share accessible via private endpoint from VM subnet
- **Network Security**: NAT Gateway for outbound internet, NSGs on all subnets with least-privilege rules, private endpoint for storage account
- **Monitoring**: Log Analytics workspace with diagnostic settings on all resources, three critical alerts (VM stopped, disk space >85%, Key Vault access failures), portal-only notifications
- **Naming**: Minimal naming convention with resource type prefix and 4-6 character random suffix
- **Region**: All resources in westus3 (US West 3)

**Technical Approach**: Single-template Bicep deployment using 12 Azure Verified Modules (latest stable versions), ARM-managed dependencies, parameter-driven configuration with uniqueString() for password generation.

## Technical Context

**IaC Language**: Bicep v0.33.0 or later (latest stable)
**Module Framework**: Azure Verified Modules (AVM) - 12 modules identified
**Target Region**: westus3 (US West 3)
**Deployment Tool**: Azure CLI v2.65.0+ (`az deployment group create`)
**Validation Required**: `bicep build` + `az deployment group validate` + `what-if` analysis
**Workload Type**: Legacy compliance-retained workload (Windows Server 2016)
**High Availability**: Single-zone deployment (availability zone parameter: 1, 2, or 3)
**Disaster Recovery**: Not required
**Scalability Requirements**: Static single VM, no auto-scaling
**Security Baseline**: Diagnostic logging to Log Analytics, managed identities, NSGs, private endpoints, Key Vault for secrets
**Naming Convention**: `{resourceType}-{purpose}-{random4-6chars}` (e.g., `vm-legacyvm-k7m3p`)
**Compliance Tags**: `workload: legacy-vm`, `environment: production`, `compliance: legacy-retention`

### AVM Modules Selected (Latest Versions)

| Module | Version | Purpose |
|--------|---------|---------|
| avm/res/network/virtual-network | 0.7.2 | VNet with 3 subnets (VM, Bastion, PE) |
| avm/res/compute/virtual-machine | 0.21.0 | Windows Server 2016 VM with data disk |
| avm/res/network/bastion-host | 0.8.2 | Secure RDP access |
| avm/res/storage/storage-account | 0.31.0 | File share with private endpoint |
| avm/res/network/nat-gateway | 2.0.1 | Outbound internet connectivity |
| avm/res/network/network-security-group | 0.5.2 | Subnet-level network security (3 NSGs) |
| avm/res/key-vault/vault | 0.13.3 | Store VM admin password |
| avm/res/operational-insights/workspace | 0.15.0 | Centralized logging |
| avm/res/network/private-endpoint | 0.11.1 | Private storage access |
| avm/res/insights/metric-alert | 0.4.1 | Monitoring alerts (3 alerts) |
| avm/res/network/private-dns-zone | 0.8.0 | DNS for private endpoints |

**Module Documentation**: See [research.md](./research.md) for detailed module analysis and alternatives considered.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- [x] **I. Infrastructure-as-Code First**: ✅ All resources defined in single `main.bicep` template, no manual Portal configurations, deployment via Azure CLI only
- [x] **II. AVM-Only Modules**: ✅ Using 12 AVM modules with latest stable versions (0.7.2 to 2.0.1), no direct resource declarations except where AVM unavailable (none identified)
- [x] **III. Validation Before Deployment**: ✅ Quickstart guide includes `bicep build`, `az deployment group validate`, and `what-if` analysis steps before deployment
- [x] **IV. Security & Reliability First**: ✅ Diagnostic logs to Log Analytics for all resources, managed identities (VM system-assigned), NSGs on all subnets, private endpoint for storage, Key Vault for password, least-privilege RBAC
- [x] **V. Minimal Naming with Type ID**: ✅ Naming pattern: `{type}-{purpose}-{random}` (e.g., `vm-legacyvm-k7m3p`, `kv-legacyvm-k7m3p`), random suffix via `uniqueString(resourceGroup().id)` - 6 chars
- [x] **VI. Region Standardization**: ✅ All resources deploy to westus3, parameter default set to `'westus3'`, no exceptions needed

**Constitution Compliance Status**: **PASSED** ✅

All 6 constitution principles satisfied. No violations requiring justification.

## Project Structure

### Documentation (this feature)

## Project Structure

### Documentation (this feature)

```text
specs/001-legacy-vm-workload/
├── spec.md              # Feature specification (completed)
├── plan.md              # This file - implementation plan (in progress)
├── research.md          # AVM module research (Phase 0 - completed)
├── data-model.md        # Network topology & resource model (Phase 1 - completed)
├── quickstart.md        # Deployment guide (Phase 1 - completed)
├── checklists/
│   └── requirements.md  # Quality validation checklist (passed)
└── tasks.md             # Task decomposition (Phase 2 - not yet created)
```

### Infrastructure Code Structure

```text
avm-workload/
├── infra/
│   ├── main.bicep           # Main deployment template (to be created)
│   ├── main.bicepparam      # Deployment parameters (to be created)
│   └── bicepconfig.json     # Bicep analyzer configuration (to be created)
├── specs/
│   └── 001-legacy-vm-workload/  # This feature documentation
├── .specify/
│   ├── memory/
│   │   └── constitution.md  # Governance framework
│   ├── templates/           # SpecKit templates
│   └── scripts/             # SpecKit automation scripts
└── README.md                # Project overview (to be created)
```

**Structure Decision**: Single-template Infrastructure-as-Code approach using Bicep with Azure Verified Modules. All 20+ resources (VM, VNet, Bastion, Storage, Key Vault, NSGs, NAT Gateway, Log Analytics, Alerts, Private Endpoint, DNS Zone, diagnostic settings, RBAC assignments) defined in one `main.bicep` file with ARM handling dependency ordering automatically. No custom modules needed - all functionality provided by AVM modules.

## Complexity Tracking

**No Constitution Violations** - This section is intentionally empty.

All 6 constitution principles are satisfied with no exceptions required. See Constitution Check section above for detailed compliance status.

---

## Implementation Phases

### Phase 0: Research & Architecture ✅ COMPLETED

**Objective**: Identify required AVM modules, resolve technical unknowns, document architectural decisions.

**Artifacts Created**:
- ✅ [research.md](./research.md) - AVM module inventory with latest versions, alternatives considered, implementation patterns
- ✅ [data-model.md](./data-model.md) - Network topology, resource dependencies, configuration model, security model
- ✅ [quickstart.md](./quickstart.md) - Step-by-step deployment guide with validation commands

**Key Decisions**:
1. **VM Password Generation**: Use Bicep `uniqueString()` function with multiple seeds (resourceGroup().id, deployment().name) - no external scripts needed
2. **Network Addressing**: VNet 10.0.0.0/24 with VM subnet /27, Bastion subnet /26, PE subnet /27
3. **Storage Access**: Private endpoint with private DNS zone integration (privatelink.file.core.windows.net)
4. **Naming Pattern**: `{type}-{purpose}-{uniqueString(6)}` for all resources
5. **Dependency Management**: Single-template approach, let ARM handle resource ordering automatically
6. **Diagnostic Settings**: All resources send logs/metrics to centralized Log Analytics workspace

**Unknowns Resolved**:
- ✅ VNet sizing: 10.0.0.0/24 confirmed sufficient (256 IPs)
- ✅ File share quota: 1TB (1024 GiB)
- ✅ Disk alert threshold: 85%
- ✅ Notification method: Azure Portal only (no Action Groups)
- ✅ VM size: Standard_D2s_v3
- ✅ AVM modules exist for all 11 required Azure resource types

### Phase 1: Infrastructure Code Implementation 🔄 IN PROGRESS

**Objective**: Create Bicep templates with AVM module references, parameter file, and configuration.

#### Task 1.1: Create bicepconfig.json ⏳ PENDING

**File**: `infra/bicepconfig.json`

**Purpose**: Configure Bicep analyzer to enforce AVM best practices and warn on outdated module versions.

**Configuration**:
```json
{
  "analyzers": {
    "core": {
      "enabled": true,
      "rules": {
        "use-recent-module-versions": {
          "level": "warning"
        }
      }
    }
  },
  "moduleAliases": {
    "br": {
      "public": {
        "registry": "mcr.microsoft.com",
        "modulePath": "bicep"
      }
    }
  }
}
```

**Validation**: Run `bicep build main.bicep` and verify no analyzer warnings.

#### Task 1.2: Create main.bicep ⏳ PENDING

**File**: `infra/main.bicep`

**Purpose**: Single deployment template referencing 12 AVM modules with proper parameters.

**Structure** (700-900 lines estimated):

1. **Header** (lines 1-30):
  - Metadata: name, description, owner
  - Target scope: `targetScope = 'resourceGroup'`
  - Parameters: vmSize, vmAdminUsername, availabilityZone, fileShareQuotaGiB, logAnalyticsRetentionDays

2. **Variables** (lines 31-80):
  - Random suffix: `var suffix = uniqueString(resourceGroup().id)`
  - Resource names: all following `{type}-{purpose}-${suffix}` pattern
  - VM password: `var vmPassword = 'P@ssw0rd!${uniqueString(resourceGroup().id, deployment().name)}'`
  - Network configuration: subnet CIDR blocks, NSG rules
  - Tags: workload, environment, compliance, managedBy, deploymentDate

3. **Log Analytics Workspace** (lines 81-110):
  ```bicep
  module logAnalytics 'br/public:avm/res/operational-insights/workspace:0.15.0' = {
    name: 'deploy-log-analytics'
    params: {
      name: 'law-legacyvm-${suffix}'
      location: location
      retentionInDays: logAnalyticsRetentionDays
      tags: tags
    }
  }
  ```

4. **Virtual Network** (lines 111-200):
  - Module: `avm/res/network/virtual-network:0.7.2`
  - 3 subnets: VM (10.0.0.0/27), Bastion (10.0.0.64/26), PE (10.0.0.128/27)
  - Diagnostic settings to Log Analytics

5. **Network Security Groups** (lines 201-350):
  - Module: `avm/res/network/network-security-group:0.5.2` (3 instances)
  - NSG 1: VM subnet (deny all inbound, allow internet + VNet outbound)
  - NSG 2: Bastion subnet (standard Azure Bastion rules)
  - NSG 3: PE subnet (allow VM subnet inbound on 445, allow all outbound)
  - Associate each NSG with its subnet
  - Diagnostic settings to Log Analytics

6. **NAT Gateway** (lines 351-380):
  - Module: `avm/res/network/nat-gateway:2.0.1`
  - Public IP auto-created
  - Associate with VM subnet
  - Diagnostic settings to Log Analytics

7. **Azure Bastion** (lines 381-410):
  - Module: `avm/res/network/bastion-host:0.8.2`
  - Depends on VNet and Bastion NSG
  - Public IP auto-created
  - Diagnostic settings to Log Analytics

8. **Key Vault** (lines 411-470):
  - Module: `avm/res/key-vault/vault:0.13.3`
  - SKU: Standard
  - Access model: RBAC
  - Secret: VM admin password (generated variable)
  - RBAC assignment: VM managed identity → Key Vault Secrets User role
  - Diagnostic settings to Log Analytics

9. **Private DNS Zone** (lines 471-500):
  - Module: `avm/res/network/private-dns-zone:0.8.0`
  - Zone name: `privatelink.file.core.windows.net`
  - VNet link to main VNet
  - Depends on VNet

10. **Storage Account** (lines 501-580):
    - Module: `avm/res/storage/storage-account:0.31.0`
    - Kind: StorageV2, SKU: Standard_LRS
    - Public network access: Disabled
    - File share: 1024 GiB quota
    - Diagnostic settings to Log Analytics

11. **Private Endpoint** (lines 581-620):
    - Module: `avm/res/network/private-endpoint:0.11.1`
    - Service: file
    - Subnet: Private Endpoint subnet
    - DNS integration: Private DNS zone
    - Depends on Storage Account, VNet, Private DNS Zone

12. **Virtual Machine** (lines 621-730):
    - Module: `avm/res/compute/virtual-machine:0.21.0`
    - OS: Windows Server 2016
    - Size: Standard_D2s_v3
    - Admin username: parameter
    - Admin password: Key Vault secret reference
    - System-assigned managed identity
    - OS disk: Standard HDD
    - Data disk: 500GB Standard HDD, LUN 0
    - NIC: VM subnet, dynamic private IP, no public IP
    - Availability zone: parameter (1, 2, or 3)
    - Diagnostic settings to Log Analytics
    - Depends on VNet, Key Vault

13. **Metric Alerts** (lines 731-850):
    - Module: `avm/res/insights/metric-alert:0.4.1` (3 instances)
    - Alert 1: VM stopped (CPU < 1% for 15 min, Sev 0)
    - Alert 2: Disk space >85% (OS disk used %, Sev 0)
    - Alert 3: Key Vault access failures (SecretGet failures, Sev 0)
    - No action groups (portal-only notifications)
    - Depends on VM and Key Vault

14. **Outputs** (lines 851-900):
    - VM name and resource ID
    - Key Vault name and resource ID
    - Storage account name and file share name
    - Bastion name
    - Log Analytics workspace ID
    - VNet name and resource ID

**Key Implementation Notes**:
- Use AVM module built-in interfaces for diagnostic settings (NOT direct `Microsoft.Insights/diagnosticSettings` resources)
- Use AVM module built-in interfaces for RBAC role assignments (NOT direct `Microsoft.Authorization/roleAssignments` resources)
- Use AVM module built-in interfaces for locks if needed (NOT direct `Microsoft.Authorization/locks` resources)
- Reference Key Vault secret for VM password using AVM module's secret reference parameter
- ARM will automatically determine deployment order based on dependencies
- All resource names use `uniqueString(resourceGroup().id)` for suffix (6 chars, consistent across all resources)
- Storage account name: no hyphens (Azure requirement), format: `st${replace(suffix, '-', '')}` (max 24 chars)
- VM computer name: max 15 chars, format: `vm-${substring(suffix, 0, 10)}`

#### Task 1.3: Create main.bicepparam ⏳ PENDING

**File**: `infra/main.bicepparam`

**Purpose**: Parameter file for deployment with sensible defaults.

**Content**:
```bicep
using './main.bicep'

// VM Configuration
param vmSize = 'Standard_D2s_v3'
param vmAdminUsername = 'vmadmin'
param availabilityZone = 1

// Storage Configuration
param fileShareQuotaGiB = 1024

// Monitoring Configuration
param logAnalyticsRetentionDays = 30

// Optional overrides (uncomment to customize)
// param vmName = 'vm-custom-name'
// param keyVaultName = 'kv-custom-name'
```

**Validation**: Ensure all parameters match those defined in `main.bicep`.

#### Task 1.4: Create project README.md ⏳ PENDING

**File**: `README.md` (root of repository)

**Purpose**: Project overview with quickstart and links to detailed documentation.

**Sections**:
1. Project Overview
2. Architecture Summary (link to data-model.md)
3. Prerequisites (link to quickstart.md)
4. Quick Deployment (3-step process)
5. Documentation Links (spec.md, plan.md, research.md, quickstart.md)
6. Governance (link to constitution.md)
7. Support and Contributing

### Phase 2: Validation & Testing 🔄 NEXT PHASE

**Objective**: Validate Bicep templates and perform what-if analysis before deployment.

#### Task 2.1: Bicep Build Validation

```powershell
cd infra
bicep build main.bicep
# Expected: main.json created, zero warnings
```

**Success Criteria**:
- No compilation errors
- No analyzer warnings
- Output ARM JSON file created successfully

#### Task 2.2: ARM Template Validation

```powershell
az group create --name rg-legacyvm-test --location westus3

az deployment group validate `
  --resource-group rg-legacyvm-test `
  --template-file main.bicep `
  --parameters main.bicepparam `
  --verbose
```

**Success Criteria**:
- Validation passes with `provisioningState: Succeeded`
- No errors related to missing resource providers
- No errors related to invalid parameters

#### Task 2.3: What-If Analysis

```powershell
az deployment group what-if `
  --resource-group rg-legacyvm-test `
  --template-file main.bicep `
  --parameters main.bicepparam `
  --verbose
```

**Success Criteria**:
- All expected resources show as "Create" (green +)
- No unexpected deletions or modifications
- Resource count: 20-25 resources total
- No warnings about deprecated API versions

#### Task 2.4: Code Review Checklist

Manual review of `main.bicep`:

- [ ] All 12 AVM modules referenced with exact versions (no floating versions)
- [ ] All module versions match research.md documentation
- [ ] uniqueString() used consistently for resource name suffixes
- [ ] Storage account name respects 24-char limit and no-hyphen requirement
- [ ] VM computer name respects 15-char limit
- [ ] All subnets have NSG associations
- [ ] NAT Gateway associated with VM subnet only
- [ ] Bastion deployed to AzureBastionSubnet (exact name required)
- [ ] **VM subnet NSG allows inbound RDP (port 3389) from Bastion subnet (10.0.0.64/26) - CRITICAL for bastion connectivity**
- [ ] Private endpoint connects to correct storage service (file)
- [ ] Private DNS zone has VNet link
- [ ] Key Vault secret created with generated password
- [ ] VM references Key Vault secret for password (not plaintext)
- [ ] VM has system-assigned managed identity
- [ ] RBAC assignment: VM identity → Key Vault (Key Vault Secrets User role)
- [ ] All resources have diagnostic settings to Log Analytics
- [ ] All resources have tags applied
- [ ] All resources deploy to westus3 region
- [ ] VM data disk configured: 500GB, Standard HDD, LUN 0
- [ ] File share quota: 1024 GiB
- [ ] 3 metric alerts configured with correct thresholds
- [ ] No action groups on alerts (portal-only requirement)
- [ ] Comments explain each major section

### Phase 3: Deployment 🔄 FUTURE PHASE

**Objective**: Deploy infrastructure to Azure and verify all resources operational.

#### Task 3.1: Initial Deployment

**Pre-deployment**:
- Create resource group: `rg-legacyvm-prod`
- Ensure subscription quotas sufficient (VMs, Public IPs, etc.)
- Authenticate to Azure CLI with sufficient permissions

**Deployment Command**:
```powershell
az deployment group create `
  --name "legacyvm-$(Get-Date -Format 'yyyyMMdd-HHmmss')" `
  --resource-group rg-legacyvm-prod `
  --template-file infra/main.bicep `
  --parameters infra/main.bicepparam `
  --verbose
```

**Expected Duration**: 15-20 minutes

**Monitoring**: Track deployment progress in Azure Portal → Resource Groups → rg-legacyvm-prod → Deployments

#### Task 3.2: Post-Deployment Verification

Follow checklist in [quickstart.md](./quickstart.md):

1. **Resource Count Verification**:
  ```powershell
  az resource list --resource-group rg-legacyvm-prod --output table
  # Expected: 20-25 resources
  ```

2. **Bastion Connectivity Test**:
  - Retrieve VM password from Key Vault
  - Connect to VM via Azure Portal Bastion
  - Verify Windows Server 2016 desktop loads

3. **Log Analytics Verification**:
  - Run sample Kusto queries
  - Verify logs appearing for all resources
  - Check for any error logs

4. **Network Connectivity Tests** (from VM):
  - Test internet access via NAT Gateway
  - Verify private endpoint DNS resolution
  - Ping storage account private IP

5. **Alert Verification**:
  - Trigger test alert (Key Vault access failure)
  - Verify alert visible in Azure Portal within 5-10 minutes
  - Confirm alert severity (Sev 0)

#### Task 3.3: Documentation Updates

- Update README.md with actual deployed resource names
- Record deployment timestamp and duration
- Document any deployment issues encountered and resolutions
- Create CHANGELOG.md entry for initial deployment

### Phase 4: Operational Handoff 🔄 FUTURE PHASE

**Objective**: Provide operational documentation and ensure supportability.

#### Task 4.1: Operational Runbooks

Create runbooks for common operations:
- VM start/stop procedures
- File share quota increase
- Bastion troubleshooting
- Alert acknowledgment workflow
- Disaster recovery procedure (VM rebuild)

#### Task 4.2: Cost Monitoring Setup

Document estimated monthly costs:
- VM (Standard_D2s_v3): ~$70/month
- Storage (1TB + disks): ~$50/month
- Bastion: ~$140/month
- Other services: ~$10/month
- **Total**: ~$270/month (westus3 region)

Set up Azure Cost Management alerts:
- Budget: $300/month
- Alert threshold: 80% ($240)

#### Task 4.3: Security Review

Complete post-deployment security checklist:
- [ ] All resources have diagnostic logging enabled
- [ ] VM has no public IP address
- [ ] Storage account public access disabled
- [ ] Key Vault access restricted to VM managed identity
- [ ] NSG rules follow least-privilege principle
- [ ] Azure Security Center recommendations reviewed
- [ ] No high-severity vulnerabilities identified

#### Task 4.4: Compliance Documentation

Document compliance controls met:
- Infrastructure-as-Code: All resources in version control
- Audit logging: All activity logged to Log Analytics
- Secret management: Passwords in Key Vault, not plaintext
- Network isolation: Private endpoints, no public exposure
- Change management: Deployments require validation gate

### Phase 5: Future Enhancements 🔄 OUT OF SCOPE (DOCUMENTED FOR REFERENCE)

Items explicitly out of scope for initial deployment but may be added later:

1. **File Share VM Integration**:
  - Map file share as network drive in VM
  - Configure persistent drive mapping via Group Policy or startup script
  - Document in operational runbooks

2. **Advanced Monitoring**:
  - Custom Log Analytics queries and workbooks
  - Action Groups for email/SMS notifications
  - Integration with external monitoring systems

3. **Backup Configuration**:
  - Azure Backup for VM
  - Azure Files snapshot/backup policies
  - Backup retention policy aligned with compliance requirements

4. **High Availability** (if requirements change):
  - Availability Set or multiple VMs across zones
  - Load Balancer for multi-VM scenarios
  - Azure Site Recovery for disaster recovery

5. **Security Enhancements**:
  - Just-In-Time VM Access
  - Azure Policy assignments
  - Microsoft Defender for Cloud integration
  - Network Watcher flow logs

---

## Risk Assessment & Mitigation

### Technical Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| AVM module breaking changes | Low | Medium | Pin exact module versions, monitor AVM changelogs |
| Bastion deployment timeout | Medium | Low | Allow 20-30 min deployment window, retry if needed |
| Key Vault access issues | Low | High | Thorough RBAC testing, fallback manual password retrieval |
| Private endpoint DNS resolution failures | Low | Medium | Verify Private DNS Zone VNet link, wait for propagation |
| VM extension failures (Windows diagnostics) | Medium | Low | Monitor deployment, acceptable to complete manually |
| Storage account naming conflicts | Low | Low | uniqueString() ensures uniqueness per resource group |

### Operational Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Lost VM password | Low | High | Key Vault provides secure retrieval, document procedure |
| Excessive costs (Bastion always-on) | Medium | Medium | Document monthly costs, set budget alerts at 80% |
| Alert fatigue (too many alerts) | Low | Medium | Start with 3 critical alerts, expand based on operations feedback |
| Insufficient disk space (500GB data disk) | Medium | Low | Alert at 85%, expansion procedure documented |
| Network connectivity issues | Low | High | NAT Gateway provides reliable outbound, private endpoint for inbound |
| Manual Portal changes breaking IaC | Medium | High | Enforce constitution principle I, document prohibition clearly |

### Compliance Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Configuration drift from manual changes | Medium | High | Constitution principle I (IaC-First) prohibits manual changes |
| Audit log gaps | Low | High | All resources send logs to Log Analytics, monitor for gaps |
| Secret exposure (VM password) | Low | Critical | Password generated in Bicep variable, stored only in Key Vault |
| Unauthorized access attempts | Low | High | No public IPs, Bastion-only access, NSG least-privilege rules |
| Non-compliance with retention policies | Low | Medium | Log Analytics retention set to 30+ days, configurable parameter |

---

## Success Criteria

### Deployment Success

- [x] All Bicep templates compile without warnings
- [ ] ARM validation passes successfully
- [ ] What-if analysis shows expected resource creation only
- [ ] Deployment completes in <30 minutes
- [ ] All 20-25 resources created successfully
- [ ] No failed resources or partial deployments

### Functional Success

- [ ] VM accessible via Azure Bastion RDP
- [ ] VM admin password retrievable from Key Vault
- [ ] VM has internet connectivity via NAT Gateway
- [ ] File share accessible from VM via private endpoint
- [ ] Storage account private endpoint resolves to internal IP (10.0.0.128/27 range)
- [ ] All resources logging to Log Analytics
- [ ] 3 metric alerts visible in Azure Portal
- [ ] Test alert fires successfully within 10 minutes

### Compliance Success

- [x] All 6 constitution principles satisfied (see Constitution Check)
- [ ] All resources deployed to westus3 region
- [ ] All resources follow naming convention: {type}-{purpose}-{random}
- [ ] No manual Portal configurations required post-deployment
- [ ] Deployment process documented in quickstart.md
- [ ] All secrets stored in Key Vault, none in version control

### Operational Success

- [ ] Quickstart guide executed successfully by independent tester
- [ ] VM operational for 24 hours with no errors
- [ ] Monitoring dashboards show healthy resource state
- [ ] No high-severity Security Center alerts
- [ ] Total monthly cost projection: $250-$300 USD
- [ ] Documentation sufficient for operational handoff

---

## Appendices

### A. Resource Naming Reference

| Resource Type | Name Pattern | Example |
|---------------|-------------|---------|
| Virtual Machine | `vm-legacyvm-{random}` | `vm-legacyvm-k7m3p` |
| Virtual Network | `vnet-legacyvm-{random}` | `vnet-legacyvm-k7m3p` |
| Subnets | `snet-{purpose}-legacyvm-{random}` | `snet-vm-legacyvm-k7m3p` |
| Network Security Group | `nsg-{purpose}-legacyvm-{random}` | `nsg-vm-legacyvm-k7m3p` |
| NAT Gateway | `nat-legacyvm-{random}` | `nat-legacyvm-k7m3p` |
| Azure Bastion | `bas-legacyvm-{random}` | `bas-legacyvm-k7m3p` |
| Key Vault | `kv-legacyvm-{random}` | `kv-legacyvm-k7m3p` |
| Storage Account | `st{random-no-hyphens}` | `stk7m3p2a` |
| Log Analytics Workspace | `law-legacyvm-{random}` | `law-legacyvm-k7m3p` |
| Metric Alert | `alert-{purpose}-legacyvm-{random}` | `alert-disk-space-legacyvm-k7m3p` |
| Private Endpoint | `pe-{service}-legacyvm-{random}` | `pe-file-legacyvm-k7m3p` |
| Private DNS Zone | `privatelink.{service}.core.windows.net` | `privatelink.file.core.windows.net` |

**Random Suffix**: Generated using `uniqueString(resourceGroup().id)` - produces 13 characters, take first 6: `k7m3p2`

### B. Network Address Allocation

| Component | CIDR | Usable IPs | Purpose |
|-----------|------|------------|---------|
| VNet | 10.0.0.0/24 | 256 | Overall network |
| VM Subnet | 10.0.0.0/27 | 27 usable | Virtual machine NICs |
| Bastion Subnet | 10.0.0.64/26 | 59 usable | Azure Bastion (requires /26) |
| Private Endpoint Subnet | 10.0.0.128/27 | 27 usable | Storage private endpoint |
| Reserved | 10.0.0.160/27 | 27 usable | Future expansion |
| Reserved | 10.0.0.192/26 | 59 usable | Future expansion |

### C. Required Azure Permissions

**Subscription-Level**:
- `Contributor` role OR specific resource provider permissions
- `User Access Administrator` role (for RBAC assignments to Key Vault)

**Resource Providers** (must be registered):
- `Microsoft.Compute`
- `Microsoft.Network`
- `Microsoft.Storage`
- `Microsoft.KeyVault`
- `Microsoft.Insights`
- `Microsoft.OperationalInsights`

### D. Tool Version Requirements

| Tool | Minimum Version | Recommended Version | Check Command |
|------|----------------|---------------------|---------------|
| Azure CLI | 2.65.0 | Latest | `az --version` |
| Bicep CLI | 0.33.0 | Latest | `az bicep version` |
| PowerShell | 7.4 | Latest | `$PSVersionTable.PSVersion` |

### E. Related Documentation

- **Feature Specification**: [spec.md](./spec.md) - Detailed requirements and user stories
- **Module Research**: [research.md](./research.md) - AVM module analysis and alternatives
- **Data Model**: [data-model.md](./data-model.md) - Network topology and resource relationships
- **Deployment Guide**: [quickstart.md](./quickstart.md) - Step-by-step deployment instructions
- **Quality Checklist**: [checklists/requirements.md](./checklists/requirements.md) - Validation results
- **Governance**: [../../.specify/memory/constitution.md](../../.specify/memory/constitution.md) - Project constitution

### F. Change Log

| Date | Version | Author | Changes |
|------|---------|--------|---------|
| 2026-01-27 | 1.0.0 | SpecKit | Initial implementation plan created |

---

**Plan Status**: Phase 1 (Infrastructure Code Implementation) - Ready for bicepconfig.json and main.bicep creation

**Next Command**: `/speckit.tasks` to decompose Phase 1 tasks into granular implementation steps

<!-- markdownlint-disable -->
# Data Model: Legacy VM Workload Infrastructure

**Date**: 2026-01-27
**Feature**: [spec.md](../spec.md)
**Purpose**: Document network topology, resource relationships, and configuration data model

## Network Topology

### Virtual Network Structure

```
VNet: 10.0.0.0/24 (vnet-legacyvm-{random})
│
├── VM Subnet: 10.0.0.0/27 (snet-vm-legacyvm-{random})
│   ├── NAT Gateway attached
│   ├── NSG attached (nsg-vm-legacyvm-{random})
│   ├── VM Network Interface
│   └── Hosts: Virtual Machine
│
├── Bastion Subnet: 10.0.0.64/26 (AzureBastionSubnet - required name)
│   ├── NSG attached (nsg-bastion-legacyvm-{random})
│   └── Hosts: Azure Bastion
│
└── Private Endpoint Subnet: 10.0.0.128/27 (snet-pe-legacyvm-{random})
    ├── NSG attached (nsg-pe-legacyvm-{random})
    └── Hosts: Storage Account Private Endpoint
```

### Address Space Allocation

| Resource | CIDR | Usable IPs | Purpose |
|----------|------|------------|---------|
| VNet | 10.0.0.0/24 | 256 | Overall network |
| VM Subnet | 10.0.0.0/27 | 32 (27 usable) | Virtual machine network interfaces |
| Bastion Subnet | 10.0.0.64/26 | 64 (59 usable) | Azure Bastion (requires /26 minimum) |
| Private Endpoint Subnet | 10.0.0.128/27 | 32 (27 usable) | Storage account private endpoints |
| Reserved | 10.0.0.160/27 | 32 | Future expansion |
| Reserved | 10.0.0.192/26 | 64 | Future expansion |

## Resource Dependency Graph

```
Resource Group
│
├── Log Analytics Workspace
│   └── (Used by all diagnostic settings)
│
├── Virtual Network
│   ├── Depends on: None
│   └── Used by: Bastion, VM NIC, Private Endpoint
│
├── Network Security Groups (3)
│   ├── nsg-vm-legacyvm-{random}
│   ├── nsg-bastion-legacyvm-{random}
│   └── nsg-pe-legacyvm-{random}
│   ├── Depends on: VNet (for subnet association)
│   └── Diagnostic settings → Log Analytics
│
├── NAT Gateway
│   ├── Public IP (auto-created)
│   ├── Depends on: None
│   ├── Associated with: VM Subnet
│   └── Diagnostic settings → Log Analytics
│
├── Azure Bastion
│   ├── Public IP (auto-created)
│   ├── Depends on: VNet (Bastion subnet)
│   ├── Depends on: NSG (bastion subnet)
│   └── Diagnostic settings → Log Analytics
│
├── Key Vault
│   ├── Depends on: None (deployed early)
│   ├── Secret: VM admin password (generated)
│   ├── RBAC: VM managed identity (Key Vault Secrets User)
│   └── Diagnostic settings → Log Analytics
│
├── Private DNS Zone
│   ├── Name: privatelink.file.core.windows.net
│   ├── VNet Link: Main VNet
│   └── Depends on: VNet
│
├── Storage Account
│   ├── File Share (1024 GiB)
│   ├── Depends on: None
│   ├── Public access: Disabled
│   ├── Diagnostic settings → Log Analytics
│   └── Private Endpoint
│       ├── Depends on: Storage Account, VNet, Private DNS Zone
│       ├── Subnet: Private Endpoint Subnet
│       └── DNS integration: Private DNS Zone
│
└── Virtual Machine
    ├── Depends on: VNet, Key Vault (for password)
    ├── Managed Identity: System-assigned
    ├── OS Disk: Standard HDD
    ├── Data Disk: 500GB Standard HDD
    ├── Network Interface
    │   ├── Depends on: VM Subnet
    │   └── No Public IP
    ├── Password: Retrieved from Key Vault secret
    └── Diagnostic settings → Log Analytics

├── Azure Monitor Alerts (3)
    ├── VM Stopped Alert
    │   └── Depends on: VM
    ├── Disk Space Alert
    │   └── Depends on: VM
    └── Key Vault Access Failures Alert
        └── Depends on: Key Vault
```

## Resource Configuration Model

### Virtual Machine
```yaml
Name Pattern: vm-legacyvm-{random}
Computer Name: vm-{random} (≤15 chars total)
Configuration:
  Size: Standard_D2s_v3
  OS: Windows Server 2016
  OS Disk:
    Type: Standard_LRS (HDD performance tier)
    Size: Default (127 GB or OS default)
  Data Disks:
    - Name: datadisk-01
      Size: 500 GB
      Type: Standard_LRS (HDD performance tier)
      LUN: 0
  Admin:
    Username: vmadmin
    Password: {From Key Vault secret}
  Identity:
    Type: SystemAssigned
  Zone: {Parameter: 1, 2, or 3}
  Network:
    NIC:
      Subnet: VM Subnet
      Public IP: None
      Private IP: Dynamic
  Diagnostics:
    Boot Diagnostics: Enabled (Managed)
    Guest Diagnostics: Windows (via Log Analytics agent)
```

### Key Vault
```yaml
Name Pattern: kv-legacyvm-{random}
Configuration:
  SKU: Standard
  Access Model: RBAC (Azure role-based access control)
  Public Network Access: Enabled (simplified for legacy workload)
  Soft Delete: Enabled (90 days)
  Purge Protection: Disabled (not required for legacy workload)
  Secrets:
    - Name: {Parameter: vmAdminPasswordSecretName}
      Value: {Generated: uniqueString-based password}
      Content Type: text/plain
  RBAC Assignments:
    - Principal: VM Managed Identity
      Role: Key Vault Secrets User
      Scope: Key Vault
  Diagnostics:
    Logs: All categories
    Metrics: All metrics
    Destination: Log Analytics
```

### Storage Account
```yaml
Name Pattern: st{random-no-hyphens} (≤24 chars)
Configuration:
  Kind: StorageV2
  SKU: Standard_LRS (HDD-based)
  Access Tier: Hot
  Public Network Access: Disabled
  Minimum TLS: 1.2
  File Services:
    Shares:
      - Name: fileshare
        Quota: 1024 GiB
        Access Tier: TransactionOptimized
  Private Endpoints:
    - Service: file
      Subnet: Private Endpoint Subnet
      DNS Integration: privatelink.file.core.windows.net
  Diagnostics:
    Logs: All categories (StorageRead, StorageWrite, StorageDelete)
    Metrics: All metrics
    Destination: Log Analytics
```

### Network Security Groups

#### VM Subnet NSG
```yaml
Name: nsg-vm-legacyvm-{random}
Security Rules:
  Inbound:
    - Name: DenyAllInbound
      Priority: 4096
      Direction: Inbound
      Access: Deny
      Protocol: *
      Source: *
      Destination: *
      SourcePort: *
      DestinationPort: *
  Outbound:
    - Name: AllowInternetOutbound
      Priority: 100
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: *
      Destination: Internet
      SourcePort: *
      DestinationPort: *
    - Name: AllowVnetOutbound
      Priority: 200
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: *
      Destination: VirtualNetwork
      SourcePort: *
      DestinationPort: *
    - Name: DenyAllOutbound
      Priority: 4096
      Direction: Outbound
      Access: Deny
      Protocol: *
      Source: *
      Destination: *
      SourcePort: *
      DestinationPort: *
```

#### Bastion Subnet NSG
```yaml
Name: nsg-bastion-legacyvm-{random}
Security Rules:
  # Standard Azure Bastion required rules
  Inbound:
    - Name: AllowHttpsInbound
      Priority: 100
      Direction: Inbound
      Access: Allow
      Protocol: Tcp
      Source: Internet
      Destination: *
      SourcePort: *
      DestinationPort: 443
    - Name: AllowGatewayManagerInbound
      Priority: 110
      Direction: Inbound
      Access: Allow
      Protocol: Tcp
      Source: GatewayManager
      Destination: *
      SourcePort: *
      DestinationPort: 443
    - Name: AllowAzureLoadBalancerInbound
      Priority: 120
      Direction: Inbound
      Access: Allow
      Protocol: Tcp
      Source: AzureLoadBalancer
      Destination: *
      SourcePort: *
      DestinationPort: 443
    - Name: AllowBastionHostCommunication
      Priority: 130
      Direction: Inbound
      Access: Allow
      Protocol: *
      Source: VirtualNetwork
      Destination: VirtualNetwork
      SourcePort: *
      DestinationPort: 8080,5701
  Outbound:
    - Name: AllowSshRdpOutbound
      Priority: 100
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: *
      Destination: VirtualNetwork
      SourcePort: *
      DestinationPort: 22,3389
    - Name: AllowAzureCloudOutbound
      Priority: 110
      Direction: Outbound
      Access: Allow
      Protocol: Tcp
      Source: *
      Destination: AzureCloud
      SourcePort: *
      DestinationPort: 443
    - Name: AllowBastionCommunication
      Priority: 120
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: VirtualNetwork
      Destination: VirtualNetwork
      SourcePort: *
      DestinationPort: 8080,5701
    - Name: AllowGetSessionInformation
      Priority: 130
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: *
      Destination: Internet
      SourcePort: *
      DestinationPort: 80
```

#### Private Endpoint Subnet NSG
```yaml
Name: nsg-pe-legacyvm-{random}
Security Rules:
  Inbound:
    - Name: AllowVMSubnetInbound
      Priority: 100
      Direction: Inbound
      Access: Allow
      Protocol: Tcp
      Source: 10.0.0.0/27
      Destination: *
      SourcePort: *
      DestinationPort: 445
    - Name: DenyAllInbound
      Priority: 4096
      Direction: Inbound
      Access: Deny
      Protocol: *
      Source: *
      Destination: *
      SourcePort: *
      DestinationPort: *
  Outbound:
    - Name: AllowAllOutbound
      Priority: 100
      Direction: Outbound
      Access: Allow
      Protocol: *
      Source: *
      Destination: *
      SourcePort: *
      DestinationPort: *
```

### Azure Monitor Alerts

#### Alert 1: VM Stopped/Deallocated
```yaml
Name: alert-vm-stopped-legacyvm-{random}
Configuration:
  Type: Metric
  Target: Virtual Machine
  Metric:
    Namespace: Microsoft.Compute/virtualMachines
    Name: Percentage CPU
  Condition:
    Operator: LessThan
    Threshold: 1
    Aggregation: Average
    Window: 15 minutes
  Severity: Critical (Sev 0)
  Auto-Mitigate: false
  Description: "Critical: VM appears to be stopped or deallocated"
```

#### Alert 2: Disk Space Exceeded
```yaml
Name: alert-disk-space-legacyvm-{random}
Configuration:
  Type: Metric
  Target: Virtual Machine
  Metric:
    Namespace: Microsoft.Compute/virtualMachines
    Name: OS Disk Used Percentage
  Condition:
    Operator: GreaterThan
    Threshold: 85
    Aggregation: Average
    Window: 5 minutes
  Severity: Critical (Sev 0)
  Auto-Mitigate: false
  Description: "Critical: Disk space exceeded 85% threshold"
```

#### Alert 3: Key Vault Access Failures
```yaml
Name: alert-kv-access-fail-legacyvm-{random}
Configuration:
  Type: Metric
  Target: Key Vault
  Metric:
    Namespace: Microsoft.KeyVault/vaults
    Name: ServiceApiHit
  Filter:
    Dimension: ActivityName
    Values: SecretGet
    Result: Failed
  Condition:
    Operator: GreaterThan
    Threshold: 0
    Aggregation: Count
    Window: 5 minutes
  Severity: Critical (Sev 0)
  Auto-Mitigate: false
  Description: "Critical: Key Vault secret access failures detected"
```

## Deployment Sequence

Based on ARM dependency analysis, resources will deploy in this approximate order:

1. **Phase 1: Foundation** (Parallel)
  - Log Analytics Workspace
  - Virtual Network (with subnets)
  - Network Security Groups

2. **Phase 2: Network & Security** (Depends on Phase 1)
  - NAT Gateway (associates with VM subnet)
  - Azure Bastion (requires subnet and NSG)
  - Private DNS Zone (requires VNet)
  - Key Vault (generates and stores password)

3. **Phase 3: Storage** (Depends on Phase 2)
  - Storage Account (with file share)
  - Private Endpoint (requires storage account, VNet, DNS zone)

4. **Phase 4: Compute** (Depends on Phases 1-3)
  - Virtual Machine (requires VNet, Key Vault secret, zone assignment)

5. **Phase 5: Monitoring** (Depends on Phase 4)
  - Azure Monitor Alerts (require VM and Key Vault to be deployed)

## Parameter Data Model

```yaml
# Required Parameters
parameters:
  resourceGroupName: string
    description: Name of the resource group for deployment
    example: rg-legacyvm-prod

  location: string
    description: Azure region for deployment
    default: westus3
    validation: Must be valid Azure region

  vmSize: string
    description: Virtual machine size
    default: Standard_D2s_v3
    validation: Must support Windows Server 2016

  vmAdminUsername: string
    description: VM administrator username
    default: vmadmin
    minLength: 1
    maxLength: 20

  vmAdminPasswordSecretName: string
    description: Name of Key Vault secret for VM admin password
    default: vm-admin-password
    minLength: 1
    maxLength: 127

  availabilityZone: int
    description: Availability zone for zone-capable resources
    allowed: [1, 2, 3]
    default: 1

  fileShareQuotaGiB: int
    description: File share quota in GiB
    default: 1024
    minValue: 100
    maxValue: 102400

  logAnalyticsRetentionDays: int
    description: Log Analytics data retention in days
    default: 30
    minValue: 30
    maxValue: 730

# Generated Values (not parameters)
variables:
  randomSuffix: uniqueString(resourceGroup().id)
  vmPassword: P@ssw0rd!{uniqueString(resourceGroup().id, deployment().name)}

  # Resource Names
  vnetName: vnet-legacyvm-{randomSuffix}
  vmName: vm-legacyvm-{randomSuffix}
  storageAccountName: st{replace(randomSuffix, '-', '')}
  keyVaultName: kv-legacyvm-{randomSuffix}
  logAnalyticsName: law-legacyvm-{randomSuffix}
```

## Tags Model

All resources will be tagged with:

```yaml
tags:
  workload: legacy-vm
  environment: production
  compliance: legacy-retention
  managedBy: bicep-avm
  deploymentDate: {deployment().timestamp}
```

## Security Model

### RBAC Assignments

| Principal | Role | Scope | Purpose |
|-----------|------|-------|---------|
| VM Managed Identity | Key Vault Secrets User | Key Vault | Read VM admin password |
| VM Managed Identity | Storage Blob Data Contributor | Storage Account | Access file share (future) |

### Network Security

| Source | Destination | Protocol/Port | Action | Purpose |
|--------|-------------|---------------|--------|---------|
| Internet | Bastion (443) | TCP/443 | Allow | Admin RDP access |
| Bastion | VM (3389) | TCP/3389 | Allow | RDP to VM |
| VM | Internet | Any | Allow | Outbound via NAT Gateway |
| VM | Storage PE (445) | TCP/445 | Allow | File share access |
| Any | VM | Any | Deny | No direct access to VM |

## Monitoring Data Model

### Diagnostic Settings Targets

All resources with diagnostic settings send to:
- **Primary**: Log Analytics Workspace
- **Categories**: All available log categories
- **Metrics**: All available metrics

### Alert Notification Model

- **Channel**: Azure Portal only
- **No Action Groups**: Alerts visible in portal alerts blade
- **Severity**: All set to Critical (Sev 0)
- **Auto-Mitigation**: Disabled (require manual acknowledgment)

<!-- markdownlint-disable -->
# Research: Legacy VM Workload AVM Modules

**Date**: 2026-01-27
**Feature**: [spec.md](../spec.md)
**Purpose**: Research and document AVM module selections, versions, and configuration approaches

## AVM Module Inventory

### Primary Infrastructure Modules

#### 1. Virtual Network
- **Module**: `avm/res/network/virtual-network`
- **Latest Version**: 0.7.2
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/virtual-network/0.7.2/avm/res/network/virtual-network/README.md
- **Decision**: Use this module for VNet and subnet deployment
- **Rationale**: Official AVM module with built-in support for subnets, NSG assignments, NAT gateway association, and diagnostic settings
- **Key Parameters Needed**:
  - Address space: 10.0.0.0/24
  - Subnets: VM (10.0.0.0/27), Bastion (10.0.0.64/26), Private endpoint (10.0.0.128/27)
  - NSG associations per subnet
  - NAT gateway assignment to VM subnet

#### 2. Virtual Machine
- **Module**: `avm/res/compute/virtual-machine`
- **Latest Version**: 0.21.0
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/compute/virtual-machine/0.21.0/avm/res/compute/virtual-machine/README.md
- **Decision**: Use this module for VM deployment
- **Rationale**: Comprehensive AVM module with built-in support for managed disks, managed identity, diagnostic settings, and guest configuration
- **Key Parameters Needed**:
  - VM size: Standard_D2s_v3
  - OS: Windows Server 2016
  - Computer name: ≤15 characters
  - Admin username: vmadmin
  - Admin password: Reference to Key Vault secret
  - Managed identity: System-assigned
  - Data disks: 500GB HDD
  - Availability zone: 1-3 (parameter-driven)
  - No public IP

#### 3. Azure Bastion
- **Module**: `avm/res/network/bastion-host`
- **Latest Version**: 0.8.2
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/bastion-host/0.8.2/avm/res/network/bastion-host/README.md
- **Decision**: Use this module for bastion deployment
- **Rationale**: AVM module with built-in diagnostic settings and public IP creation
- **Key Parameters Needed**:
  - Subnet: Bastion subnet (10.0.0.64/26)
  - SKU: Basic (cost-effective for legacy workload)
  - Diagnostic settings to Log Analytics

#### 4. Storage Account
- **Module**: `avm/res/storage/storage-account`
- **Latest Version**: 0.31.0
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/storage/storage-account/0.31.0/avm/res/storage/storage-account/README.md
- **Decision**: Use this module for storage account and file share
- **Rationale**: Comprehensive AVM module with built-in file share, private endpoint, diagnostic settings, and network rules support
- **Key Parameters Needed**:
  - SKU: Standard_LRS (HDD-based)
  - File share quota: 1024 GiB
  - Private endpoint enabled
  - Public network access disabled
  - Diagnostic settings to Log Analytics

#### 5. NAT Gateway
- **Module**: `avm/res/network/nat-gateway`
- **Latest Version**: 2.0.1
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/nat-gateway/2.0.1/avm/res/network/nat-gateway/README.md
- **Decision**: Use this module for NAT gateway
- **Rationale**: AVM module with public IP creation and zone support
- **Key Parameters Needed**:
  - Zone: parameter-driven (1-3)
  - Public IP: Auto-created by module

#### 6. Network Security Group
- **Module**: `avm/res/network/network-security-group`
- **Latest Version**: 0.5.2
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/network-security-group/0.5.2/avm/res/network/network-security-group/README.md
- **Decision**: Use this module for all three NSGs (VM subnet, bastion subnet, private endpoint subnet)
- **Rationale**: AVM module with built-in diagnostic settings and security rule definitions
- **Key Parameters Needed**:
  - VM subnet NSG: Allow outbound to internet via NAT gateway, deny other traffic
  - Bastion subnet NSG: Standard bastion rules (inbound 443, outbound to VM subnet)
  - Private endpoint subnet NSG: Allow traffic from VM subnet only

#### 7. Key Vault
- **Module**: `avm/res/key-vault/vault`
- **Latest Version**: 0.13.3
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/key-vault/vault/0.13.3/avm/res/key-vault/vault/README.md
- **Decision**: Use this module for Key Vault and secret storage
- **Rationale**: AVM module with built-in secret creation using `secrets` parameter array, RBAC support, diagnostic settings, and network rules
- **Key Features**:
  - Supports `secrets` parameter for creating secrets at deployment time
  - Can generate password using `uniqueString()` and store in secret
  - Built-in RBAC assignments
  - Private endpoint support (optional for this scenario)
  - Diagnostic settings interface
- **Password Generation Approach**:
  - Use Bicep `uniqueString()` function to generate complex password
  - Combine multiple seed values for randomness
  - Store in Key Vault secret via module's `secrets` parameter
  - Reference secret in VM module

#### 8. Log Analytics Workspace
- **Module**: `avm/res/operational-insights/workspace`
- **Latest Version**: 0.15.0
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/operational-insights/workspace/0.15.0/avm/res/operational-insights/workspace/README.md
- **Decision**: Use this module for Log Analytics
- **Rationale**: AVM module with retention configuration and solution deployment support
- **Key Parameters Needed**:
  - Retention days: 30 (default assumption)
  - SKU: PerGB2018

#### 9. Private Endpoint
- **Module**: `avm/res/network/private-endpoint`
- **Latest Version**: 0.11.1
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/private-endpoint/0.11.1/avm/res/network/private-endpoint/README.md
- **Decision**: Use this module for storage account file share private endpoint
- **Rationale**: AVM module with built-in private DNS zone group configuration
- **Key Parameters Needed**:
  - Service connection: Storage account file service
  - Subnet: Private endpoint subnet
  - Private DNS zone: privatelink.file.core.windows.net (manual creation)

#### 10. Azure Monitor Alerts
- **Module**: `avm/res/insights/metric-alert`
- **Latest Version**: 0.4.1
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/insights/metric-alert/0.4.1/avm/res/insights/metric-alert/README.md
- **Decision**: Use this module for all three critical alerts
- **Rationale**: AVM module supporting metric-based alerts for VM and Key Vault
- **Alerts to Create**:
  1. VM stopped/deallocated
  2. Disk space > 85%
  3. Key Vault access failures
- **Note**: Portal-only notifications (no action groups needed for this scenario)

### Supporting Modules

#### 11. Managed Disk
- **Included in VM Module**: The Virtual Machine module handles data disk creation inline
- **No separate module needed**: Data disks are specified as parameters to the VM module

#### 12. Private DNS Zone
- **Module**: `avm/res/network/private-dns-zone`
- **Latest Version**: 0.8.0
- **Documentation**: https://github.com/Azure/bicep-registry-modules/tree/avm/res/network/private-dns-zone/0.8.0/avm/res/network/private-dns-zone/README.md
- **Decision**: Use this module for private DNS zone for file share private endpoint
- **Rationale**: Required for DNS resolution of storage account file share through private endpoint
- **Key Parameters Needed**:
  - Zone name: privatelink.file.core.windows.net
  - VNet link to main VNet

## Alternative Approaches Considered

### Alternative 1: Direct Resource Declarations
- **Approach**: Use direct Bicep resource declarations instead of AVM modules
- **Rejected**: Violates constitution principle II (AVM-Only Modules)
- **Trade-offs**: Would provide more control but lose benefits of tested, maintained, secure-by-default configurations

### Alternative 2: Pattern Module for VM Workloads
- **Approach**: Search for existing AVM pattern module combining VM, networking, and storage
- **Evaluated**: No suitable pattern module exists for this specific legacy VM scenario
- **Decision**: Compose solution from resource modules per constitution

### Alternative 3: Deployment Scripts for Password Generation
- **Approach**: Use Azure Deployment Scripts to generate and store VM password
- **Rejected**: User requirement specifies using uniqueString() and avoiding external helper scripts
- **Decision**: Generate password inline using Bicep uniqueString() function and store via Key Vault module's secrets parameter

### Alternative 4: Azure Backup Integration
- **Approach**: Include Azure Backup configuration for VM
- **Rejected**: Explicitly out of scope per specification
- **Note**: Can be added later if requirements change

## Bicep Language Features Required

### Password Generation Pattern
```bicep
// Generate complex password using uniqueString with multiple seeds
var generatedPassword = 'P@ssw0rd!${uniqueString(resourceGroup().id, deployment().name, utcNow('u'))}'
```

### Resource Dependency Management
- Let ARM manage dependencies automatically
- Explicit `dependsOn` only when implicit dependency isn't detected
- Use resource symbolic names for references

### Parameter Validation
- Use decorators: `@minLength()`, `@maxLength()`, `@allowed()`
- Validate VM computer name length (≤15 chars)
- Validate storage account name (≤24 chars, lowercase, alphanumeric)

## Key Configuration Decisions

### Resource Naming
- **Pattern**: {resourceType}-{purpose}-{randomSuffix}
- **Random Suffix**: Use uniqueString() with 6 characters
- **Examples**:
  - VNet: `vnet-legacyvm-${uniqueString(resourceGroup().id)}`
  - VM: `vm-legacyvm-${uniqueString(resourceGroup().id)}`
  - Storage: `st${replace(uniqueString(resourceGroup().id), '-', '')}` (no hyphens, ≤24 chars)
  - Key Vault: `kv-legacyvm-${uniqueString(resourceGroup().id)}`

### Network Security
- **VM Subnet NSG**: Allow outbound internet (via NAT), deny all inbound except from bastion
- **Bastion Subnet NSG**: Follow Azure Bastion NSG requirements
- **Private Endpoint Subnet NSG**: Allow inbound from VM subnet on port 445 (SMB)

### Diagnostic Settings
- **Target**: Log Analytics Workspace (centralized)
- **Resources to Monitor**: VM, Key Vault, Storage Account, NSGs, Bastion
- **Log Categories**: All available categories
- **Metrics**: All available metrics

### Availability Zones
- **VM**: Deploy to zone specified by parameter (1, 2, or 3)
- **NAT Gateway**: Deploy to same zone as VM
- **Managed Disks**: Automatically zone-aligned with VM

## Implementation Notes

### Single Template Approach
- All resources in main.bicep
- No nested modules or separate Bicep files
- ARM dependency management handles deployment order

### Parameter Management
- All configurable values in main.bicepparam
- Rich comments explaining each parameter
- Default values where appropriate
- No hardcoded values in template

### Bicep CLI Version
- **Minimum**: Latest stable version (0.33.0 or higher at time of writing)
- **Recommendation**: Always use latest for newest AVM module support
- **Verification**: Run `bicep --version` before deployment

### Module Version Pinning
- **Required**: Always pin to specific versions (never 'latest' tag)
- **Format**: `br/public:avm/res/network/virtual-network:0.7.2`
- **Maintenance**: Update versions explicitly when needed

## Open Questions Resolved

1. **How to generate VM password without external scripts?**
  - **Resolution**: Use Bicep `uniqueString()` function with multiple seeds
  - **Implementation**: Store generated password in Key Vault using module's `secrets` parameter

2. **How to connect file share to VM?**
  - **Resolution**: Out of scope for initial deployment per user guidance
  - **Future**: Will require VM extension or post-deployment script

3. **Should we use private endpoint for Key Vault?**
  - **Resolution**: No, not required for this legacy workload
  - **Justification**: Adds complexity without clear benefit for single VM scenario

4. **What alert notification channels?**
  - **Resolution**: Portal notifications only (clarified during specification)
  - **Implementation**: Create metric alerts without action groups

5. **Module version for optimal features?**
  - **Resolution**: Always use latest stable version listed in AVM metadata
  - **Verification**: Confirmed all required features available in latest versions

## Next Steps

1. Create data-model.md with network topology and resource relationships
2. Write deployment quickstart guide
3. Fill implementation plan template
4. Create bicepconfig.json with module version analyzer

<!-- markdownlint-disable -->
# Quickstart: Deploy Legacy VM Workload

**Date**: 2026-01-27
**Feature**: [spec.md](../spec.md)
**Purpose**: Step-by-step deployment guide with validation and troubleshooting

## Prerequisites

### Required Tools

1. **Azure CLI** (v2.65.0 or later)
  ```powershell
  # Check version
  az --version

  # Install/upgrade if needed
  # Windows: Download from https://aka.ms/installazurecliwindows
  # Or use winget
  winget install -e --id Microsoft.AzureCLI
  ```

2. **Bicep CLI** (v0.33.0 or later)
  ```powershell
  # Check version
  az bicep version

  # Install/upgrade
  az bicep install
  az bicep upgrade
  ```

3. **PowerShell** (v7.4 or later recommended)
  ```powershell
  # Check version
  $PSVersionTable.PSVersion

  # Install if needed
  winget install --id Microsoft.Powershell --source winget
  ```

### Azure Permissions

You need the following permissions on the target subscription:

- **Owner** or **Contributor** role at subscription or resource group level
- **User Access Administrator** role (if deploying RBAC assignments)
- Permissions to create resources in **westus3** region

### Authentication

```powershell
# Login to Azure
az login

# Set the target subscription
az account set --subscription "<subscription-id-or-name>"

# Verify current context
az account show --output table
```

## Repository Structure

```
avm-workload/
├── infra/
│   ├── main.bicep            # Main infrastructure template
│   ├── main.bicepparam       # Deployment parameters
│   └── bicepconfig.json      # Bicep configuration
├── specs/
│   └── 001-legacy-vm-workload/
│       ├── spec.md           # Feature specification
│       ├── plan.md           # Implementation plan
│       ├── data-model.md     # Architecture documentation
│       └── quickstart.md     # This file
└── .specify/
    └── memory/
        └── constitution.md   # Governance framework
```

## Deployment Workflow

### Step 1: Review Parameters

Edit `infra/main.bicepparam` to customize deployment:

```bicep
using './main.bicep'

// Required parameters
param vmSize = 'Standard_D2s_v3'
param vmAdminUsername = 'vmadmin'
param availabilityZone = 1
param fileShareQuotaGiB = 1024
param logAnalyticsRetentionDays = 30

// Optional: Override resource names
// param vmName = 'vm-custom-name'
// param vnetName = 'vnet-custom-name'
```

**Key Parameters**:
- `vmSize`: Virtual machine SKU (must support Windows Server 2016)
- `vmAdminUsername`: Administrator username for the VM
- `availabilityZone`: Availability zone (1, 2, or 3)
- `fileShareQuotaGiB`: Storage file share quota (default 1024 GiB)
- `logAnalyticsRetentionDays`: Log retention period (30-730 days)

### Step 2: Pre-Deployment Validation

#### 2.1 Bicep Compilation

Verify the template compiles without errors:

```powershell
# Navigate to infrastructure directory
cd C:\SOURCE\avm-workload\infra

# Build Bicep template
bicep build main.bicep

# Check for warnings
# Fix any warnings reported by the analyzer
```

**Expected Output**: `main.json` file created with no errors or warnings.

#### 2.2 Template Validation

Validate deployment against Azure:

```powershell
# Create resource group (if it doesn't exist)
az group create `
  --name rg-legacyvm-prod `
  --location westus3

# Validate deployment
az deployment group validate `
  --resource-group rg-legacyvm-prod `
  --template-file main.bicep `
  --parameters main.bicepparam `
  --verbose

# Check validation result
if ($LASTEXITCODE -eq 0) {
    Write-Host "✅ Validation passed" -ForegroundColor Green
} else {
    Write-Host "❌ Validation failed - review errors above" -ForegroundColor Red
    exit 1
}
```

**Expected Output**: `provisioningState: Succeeded`

#### 2.3 What-If Analysis

Preview what resources will be created:

```powershell
# Run what-if analysis
az deployment group what-if `
  --resource-group rg-legacyvm-prod `
  --template-file main.bicep `
  --parameters main.bicepparam `
  --verbose

# Review output:
# - Green (+): Resources to be created
# - Yellow (~): Resources to be modified
# - Red (x): Resources to be deleted
# - White (=): No change
```

**Review Checklist**:
- [ ] 1 Virtual Network with 3 subnets
- [ ] 3 Network Security Groups
- [ ] 1 NAT Gateway with Public IP
- [ ] 1 Azure Bastion with Public IP
- [ ] 1 Key Vault with 1 secret
- [ ] 1 Storage Account with 1 file share
- [ ] 1 Private Endpoint
- [ ] 1 Private DNS Zone with VNet link
- [ ] 1 Virtual Machine with NIC, OS disk, data disk
- [ ] 1 Log Analytics Workspace
- [ ] 3 Metric Alerts
- [ ] Multiple diagnostic settings
- [ ] RBAC role assignments

**STOP**: Do not proceed if what-if shows unexpected resource deletions or modifications.

### Step 3: Deploy Infrastructure

#### 3.1 Execute Deployment

```powershell
# Deploy infrastructure
az deployment group create `
  --name "legacyvm-$(Get-Date -Format 'yyyyMMdd-HHmmss')" `
  --resource-group rg-legacyvm-prod `
  --template-file main.bicep `
  --parameters main.bicepparam `
  --verbose

# Deployment typically takes 15-20 minutes
# Monitor progress in Azure Portal: Resource Groups > rg-legacyvm-prod > Deployments
```

**Expected Duration**: 15-20 minutes

**Deployment Phases**:
1. **0-2 min**: Log Analytics, VNet, NSGs
2. **2-8 min**: NAT Gateway, Bastion, Private DNS Zone, Key Vault
3. **8-12 min**: Storage Account, Private Endpoint
4. **12-18 min**: Virtual Machine (longest phase)
5. **18-20 min**: Monitor Alerts

#### 3.2 Monitor Deployment

**Option A: Azure CLI**
```powershell
# Watch deployment status
az deployment group show `
  --name "legacyvm-<timestamp>" `
  --resource-group rg-legacyvm-prod `
  --query "{State:properties.provisioningState, Duration:properties.duration}" `
  --output table
```

**Option B: Azure Portal**
1. Navigate to: [Azure Portal](https://portal.azure.com)
2. Go to: **Resource Groups** > **rg-legacyvm-prod** > **Deployments**
3. Click on the active deployment to see detailed progress
4. Monitor each resource deployment status

### Step 4: Post-Deployment Verification

#### 4.1 Verify Resources

```powershell
# List all resources in the resource group
az resource list `
  --resource-group rg-legacyvm-prod `
  --output table

# Expected count: 20-25 resources
# Key resources to verify:
# - Virtual Machine
# - Virtual Network
# - Storage Account
# - Key Vault
# - Azure Bastion
# - Log Analytics Workspace
```

#### 4.2 Test Bastion Connectivity

**Via Azure Portal**:
1. Go to: **Virtual Machines** > **vm-legacyvm-{random}**
2. Click: **Connect** > **Bastion**
3. Enter credentials:
  - **Username**: `vmadmin`
  - **Password**: Get from Key Vault (see below)
4. Click: **Connect**

**Retrieve VM Password**:
```powershell
# Get Key Vault name
$kvName = az keyvault list `
  --resource-group rg-legacyvm-prod `
  --query "[0].name" `
  --output tsv

# Get VM admin password from Key Vault
az keyvault secret show `
  --name vm-admin-password `
  --vault-name $kvName `
  --query "value" `
  --output tsv
```

**Expected Result**: Successful RDP connection to Windows Server 2016 VM.

#### 4.3 Verify Logs in Log Analytics

```powershell
# Get Log Analytics workspace ID
$workspaceId = az monitor log-analytics workspace show `
  --resource-group rg-legacyvm-prod `
  --workspace-name law-legacyvm-{random} `
  --query "customerId" `
  --output tsv

Write-Host "Log Analytics Workspace ID: $workspaceId"
Write-Host "Portal: https://portal.azure.com#blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/resourceId/%2Fsubscriptions%2F{subscription-id}%2FresourceGroups%2Frg-legacyvm-prod%2Fproviders%2FMicrosoft.OperationalInsights%2Fworkspaces%2Flaw-legacyvm-{random}"
```

**Via Azure Portal**:
1. Go to: **Log Analytics Workspaces** > **law-legacyvm-{random}**
2. Click: **Logs**
3. Run query to verify diagnostic logs:

```kusto
// Query 1: Verify VM activity logs
AzureActivity
| where ResourceGroup == "rg-legacyvm-prod"
| where ResourceType == "Microsoft.Compute/virtualMachines"
| summarize count() by OperationName
| order by count_ desc

// Query 2: Verify Key Vault audit logs
AzureDiagnostics
| where ResourceType == "VAULTS"
| where ResourceGroup == "rg-legacyvm-prod"
| summarize count() by OperationName, ResultType
| order by count_ desc

// Query 3: Verify Storage Account logs
StorageFileLogs
| where AccountName startswith "st"
| summarize count() by OperationName
| order by count_ desc

// Query 4: Check for any errors
AzureDiagnostics
| where ResourceGroup == "rg-legacyvm-prod"
| where Level == "Error"
| project TimeGenerated, ResourceType, OperationName, ResultDescription
| order by TimeGenerated desc
```

**Expected Results**: Logs appearing for all resources within 5-10 minutes of deployment.

#### 4.4 Test Alerts

**Test 1: Disk Space Alert** (Optional - requires VM modification)
```powershell
# WARNING: This will consume disk space on the VM
# Only run if you want to test alert firing

# Connect to VM via Bastion, then run in VM:
# fsutil file createnew C:\testfile.tmp 100000000000  # 100GB file

# Wait 5-10 minutes for alert to fire
# Check: Azure Portal > Monitor > Alerts
```

**Test 2: Key Vault Access Failure** (Safe test)
```powershell
# Attempt to get a non-existent secret (should generate access failure log)
az keyvault secret show `
  --name "non-existent-secret" `
  --vault-name $kvName 2>$null

# Wait 5 minutes, then check:
# Azure Portal > Monitor > Alerts > alert-kv-access-fail-legacyvm-{random}
```

**Expected Behavior**: Alerts visible in Azure Portal within 5-10 minutes of trigger condition.

#### 4.5 Verify Network Connectivity

**From VM (via Bastion RDP session)**:

```powershell
# Test internet connectivity via NAT Gateway
Test-NetConnection -ComputerName google.com -Port 443

# Test Azure DNS resolution
nslookup st{random}.file.core.windows.net

# Verify private endpoint resolution
nslookup st{random}.privatelink.file.core.windows.net

# Expected: Private IP from 10.0.0.128/27 range

# Test file share access (future - after mapping)
# net use Z: \\st{random}.file.core.windows.net\fileshare
```

**Expected Results**:
- Internet access works (NAT Gateway)
- Private endpoint resolves to internal IP (10.0.0.128/27)
- File share accessible from VM

## Troubleshooting

### Issue: Bicep Build Fails

**Symptoms**: `bicep build` reports errors or warnings

**Solutions**:
1. **Check Bicep CLI version**:
  ```powershell
  az bicep version
  # Should be v0.33.0 or later
  az bicep upgrade
  ```

2. **Review analyzer warnings**:
  - Open `main.bicep` in VS Code with Bicep extension
  - Fix any red/yellow squiggles
  - Common issues: outdated module versions, missing required parameters

3. **Validate bicepconfig.json**:
  ```powershell
  # Ensure file exists and is valid JSON
  Get-Content infra/bicepconfig.json | ConvertFrom-Json
  ```

### Issue: Validation Fails

**Symptoms**: `az deployment group validate` returns errors

**Common Errors**:

1. **"Resource provider not registered"**
  ```powershell
  # Register required providers
  az provider register --namespace Microsoft.Compute
  az provider register --namespace Microsoft.Network
  az provider register --namespace Microsoft.Storage
  az provider register --namespace Microsoft.KeyVault
  az provider register --namespace Microsoft.Insights

  # Wait for registration to complete (2-5 minutes)
  az provider show --namespace Microsoft.Compute --query "registrationState"
  ```

2. **"Quota exceeded"**
  - Check Azure subscription quotas
  - Request quota increase if needed: Portal > Subscriptions > Usage + quotas

3. **"Invalid parameter value"**
  - Review `main.bicepparam` for typos
  - Ensure `vmSize` is valid for westus3 region
  - Verify availability zone is 1, 2, or 3

### Issue: Deployment Hangs or Times Out

**Symptoms**: Deployment runs longer than 30 minutes

**Diagnosis**:
```powershell
# Check deployment status
az deployment group show `
  --name "legacyvm-<timestamp>" `
  --resource-group rg-legacyvm-prod `
  --query "properties.{State:provisioningState, SubState:provisioningDetails}" `
  --output json

# View deployment operations
az deployment operation group list `
  --resource-group rg-legacyvm-prod `
  --name "legacyvm-<timestamp>" `
  --query "[?properties.provisioningState=='Failed' || properties.provisioningState=='Running']" `
  --output table
```

**Solutions**:
1. **VM creation timeout**: May indicate VM extension failures
  - Check: Portal > VM > Extensions and applications
  - Solution: Redeploy with `--no-wait` flag, monitor separately

2. **Bastion timeout**: Check Public IP allocation
  - Verify Public IP quota not exceeded
  - Check NSG rules on Bastion subnet

3. **Private Endpoint timeout**: DNS propagation delay
  - Wait additional 5-10 minutes
  - Verify Private DNS Zone linked to VNet

### Issue: VM Password Not Working

**Symptoms**: Cannot connect to VM via Bastion with retrieved password

**Solutions**:
1. **Re-retrieve password from Key Vault**:
  ```powershell
  $kvName = az keyvault list --resource-group rg-legacyvm-prod --query "[0].name" -o tsv
  $password = az keyvault secret show --name vm-admin-password --vault-name $kvName --query "value" -o tsv
  Write-Host "Password: $password"
  ```

2. **Check Key Vault access**:
  ```powershell
  # Ensure you have Key Vault Secrets User role
  az role assignment list `
    --scope /subscriptions/{subscription-id}/resourceGroups/rg-legacyvm-prod/providers/Microsoft.KeyVault/vaults/$kvName `
    --query "[?principalName=='<your-user-email>']" `
    --output table
  ```

3. **Reset VM password** (if secret retrieval works but password is wrong):
  ```powershell
  # This should not be necessary if deployment succeeded
  # Only use as last resort
  az vm user update `
    --resource-group rg-legacyvm-prod `
    --name vm-legacyvm-{random} `
    --username vmadmin `
    --password "NewP@ssw0rd!123"
  ```

### Issue: Bastion Connection Fails

**Symptoms**: Cannot establish Bastion RDP session

**Diagnosis**:
```powershell
# Check Bastion health
az network bastion show `
  --resource-group rg-legacyvm-prod `
  --name bas-legacyvm-{random} `
  --query "{ProvisioningState:provisioningState, DNSName:dnsName}" `
  --output table

# Check VM status
az vm get-instance-view `
  --resource-group rg-legacyvm-prod `
  --name vm-legacyvm-{random} `
  --query "instanceView.statuses[?starts_with(code, 'PowerState/')].displayStatus" `
  --output tsv
```

**Solutions**:
1. **VM is stopped**: Start the VM
  ```powershell
  az vm start --resource-group rg-legacyvm-prod --name vm-legacyvm-{random}
  ```

2. **Bastion NSG rules incorrect**: Verify Bastion subnet NSG
  - Required: Allow inbound 443 from Internet
  - Required: Allow outbound 3389/22 to VirtualNetwork
  - Check: Portal > NSG > nsg-bastion-legacyvm-{random} > Security rules

3. **Browser issues**: Try different browser or incognito mode

### Issue: No Logs in Log Analytics

**Symptoms**: Queries return no results 10+ minutes after deployment

**Diagnosis**:
```kusto
// Check if workspace is receiving any data
Heartbeat
| where TimeGenerated > ago(1h)
| summarize count()

// Check diagnostic settings configuration
AzureDiagnostics
| where TimeGenerated > ago(1h)
| summarize count() by ResourceType
```

**Solutions**:
1. **Wait longer**: Initial log ingestion can take 10-15 minutes
2. **Verify diagnostic settings**:
  ```powershell
  # Check VM diagnostic settings
  az monitor diagnostic-settings list `
    --resource /subscriptions/{subscription-id}/resourceGroups/rg-legacyvm-prod/providers/Microsoft.Compute/virtualMachines/vm-legacyvm-{random} `
    --query "value[].{Name:name, LogAnalytics:workspaceId}" `
    --output table
  ```

3. **Manual diagnostic setting creation** (if missing):
  - Portal > VM > Diagnostic settings > Add diagnostic setting
  - Select all log categories and metrics
  - Send to Log Analytics workspace: law-legacyvm-{random}

### Issue: Alerts Not Firing

**Symptoms**: Test conditions met but no alerts visible in Portal

**Diagnosis**:
```powershell
# Check alert rules
az monitor metrics alert list `
  --resource-group rg-legacyvm-prod `
  --query "[].{Name:name, Enabled:enabled, Severity:severity}" `
  --output table

# Check alert condition evaluation
az monitor metrics alert show `
  --resource-group rg-legacyvm-prod `
  --name alert-disk-space-legacyvm-{random} `
  --query "{Enabled:enabled, Condition:criteria, State:properties.state}" `
  --output json
```

**Solutions**:
1. **Wait for evaluation window**: Alerts evaluate every 1-5 minutes
2. **Verify alert is enabled**: Should show `"enabled": true`
3. **Check metric availability**:
  ```powershell
  # List available metrics for VM
  az monitor metrics list-definitions `
    --resource /subscriptions/{subscription-id}/resourceGroups/rg-legacyvm-prod/providers/Microsoft.Compute/virtualMachines/vm-legacyvm-{random} `
    --query "[].{Name:name.value, Unit:unit}" `
    --output table
  ```

4. **Review activity log for alert evaluation**:
  - Portal > Monitor > Activity Log
  - Filter: Resource Type = "microsoft.insights/metricalerts"
  - Look for "Evaluate Action" events

## Clean Up Resources

**WARNING**: This will delete ALL resources and data. Ensure you have backups before proceeding.

```powershell
# Delete resource group and all resources
az group delete `
  --name rg-legacyvm-prod `
  --yes `
  --no-wait

# Verify deletion status (takes 5-10 minutes)
az group exists --name rg-legacyvm-prod
# Expected output: false
```

**Cost Estimate**: Keeping resources deployed costs approximately:
- VM (Standard_D2s_v3): ~$70/month
- Storage (1TB file share + disks): ~$50/month
- Bastion: ~$140/month
- Other services (negligible): ~$10/month
- **Total**: ~$270/month in westus3 region

## Next Steps

After successful deployment:

1. **Configure VM**:
  - Install required applications on Windows Server 2016
  - Map file share as network drive: `\\st{random}.file.core.windows.net\fileshare`
  - Configure Windows Firewall rules as needed

2. **Set Up Monitoring**:
  - Configure Log Analytics queries and save as functions
  - Create custom workbooks in Azure Monitor
  - Set up action groups for email/SMS notifications (currently Portal-only)

3. **Implement Backup** (not in scope of this deployment):
  - Azure Backup for VM
  - Azure Files snapshot/backup for file share

4. **Security Hardening** (additional measures):
  - Enable Azure Security Center recommendations
  - Implement Just-In-Time VM access
  - Review and tighten NSG rules based on actual traffic

5. **Operational Procedures**:
  - Document VM maintenance schedules
  - Create runbooks for common tasks
  - Establish change management process

## Support

For issues related to:
- **Bicep**: Review [research.md](./research.md) for module documentation
- **Azure resources**: Check [data-model.md](./data-model.md) for architecture
- **Requirements**: See [spec.md](./spec.md) for detailed specifications
- **Governance**: Review [constitution.md](../../.specify/memory/constitution.md) for principles

For Azure support, visit: https://azure.microsoft.com/support/