diff --git a/.github/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE.md similarity index 100% rename from .github/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 8199019..0000000 --- a/README.adoc +++ /dev/null @@ -1,126 +0,0 @@ -= Azure Local Load Tools -:toc: macro -:toclevels: 2 -:icons: font -:url-docs: docs/main.adoc - -image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform: Azure Local] image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell 7.2+] image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License: MIT] image:https://img.shields.io/badge/Status-Pre--Release-orange?style=flat-square[Status: Pre-Release] - -[CAUTION] -==== -**Pre-Release Solution** — This project is under active development and has not been officially released. -It should be considered experimental. Scripts, configuration formats, and module interfaces may change without notice. -Use in production environments is not recommended at this time. -==== - -Comprehensive load testing framework for **Azure Local** (formerly Azure Stack HCI) clusters. Validates storage, network, and compute performance before production workloads are migrated or deployed. - -toc::[] - -== Overview - -Azure Local Load Tools provides an automated, config-driven pipeline for running load tests against Azure Local clusters using multiple industry-standard tools: - -[cols="1,1,1,2"] -|=== -| Tool | Type | Status | Description - -| **VMFleet** | Storage I/O | ✅ Implemented | Fleet VMs running DiskSpd on S2D clusters -| **fio** | Storage I/O | 🔲 Planned | Flexible I/O tester for Linux VMs -| **iPerf3** | Network | 🔲 Planned | Network throughput and latency testing -| **HammerDB** | Database | 🔲 Planned | TPC-C/TPC-H benchmarks against SQL Server -| **stress-ng** | Compute | 🔲 Planned | CPU, memory, and I/O stress testing -|=== - -== Key Features - -* **Config-driven**: Master YAML config with tagged variables → per-solution JSON configs -* **Parameterized**: Three-level override chain (explicit param > solution config > master default) -* **Credential management**: Azure Key Vault, interactive, or parameter-based — never hardcoded -* **State tracking**: Checkpoint-based resume with JSON state files and mutex locking -* **Structured logging**: JSON-lines per component with correlation IDs -* **Monitoring**: Local PerfMon collection + optional Azure Monitor push -* **Multi-format reports**: PDF (asciidoctor-pdf), DOCX (Pandoc), XLSX (ImportExcel) -* **CI/CD ready**: GitHub Actions primary, Azure DevOps + GitLab CI placeholders - -== Quick Start - -[source,powershell] ----- -# 1. Clone the repository -git clone https://github.com/AzureLocal/azurelocal-loadtools.git -cd azurelocal-loadtools - -# 2. Install PowerShell prerequisites -Install-Module powershell-yaml -Force -Install-Module ImportExcel -Force -Install-Module VMFleet -Force - -# 3. Copy and edit environment configuration -cp config/variables.example.yml config/variables/variables.yml -# Edit variables.yml with your cluster details - -# 4. Initialize environment -.\common\helpers\Initialize-Environment.ps1 ` - -ClusterConfigPath config\variables\variables.yml ` - -Solution VMFleet - -# 5. Run the full VMFleet pipeline -.\tools\vmfleet\Invoke-VMFleetPipeline.ps1 ` - -ClusterConfigPath config\variables\variables.yml ` - -ProfilePath tools\vmfleet\config\profiles\general.yml ` - -ReportFormats @('PDF', 'XLSX') ----- - -== Project Structure - -[source] ----- -azurelocal-loadtools/ -├── common/ # Shared modules, helpers, ansible roles, bicep -│ ├── modules/ # 6 core PowerShell modules -│ ├── helpers/ # Bootstrap & common functions -│ ├── ansible/ # Roles for Linux tool deployment -│ └── bicep/ # Shared Bicep templates (Key Vault) -├── config/ # Global configuration -│ └── variables/ # Master config + schema -├── docs/ # MkDocs documentation -├── tools/ # One directory per load tool -│ ├── vmfleet/ # Full implementation -│ │ ├── scripts/ # 7 pipeline scripts -│ │ ├── monitoring/ # 5 metric collection scripts -│ │ ├── infrastructure/ # Bicep templates (monitoring) -│ │ ├── config/profiles/ # Workload profiles -│ │ ├── logs/ # Runtime logs -│ │ └── reports/templates/ # Report templates -│ ├── fio/ # Placeholder -│ ├── iperf/ # Placeholder -│ ├── hammerdb/ # Placeholder -│ └── stress-ng/ # Placeholder -├── examples/ # Sample result files -├── logs/ # Pipeline-level logs -├── state/ # Run state files -├── tests/ # Pester tests & PSScriptAnalyzer -└── .github/workflows/ # GitHub Actions workflows ----- - -== Documentation - -Full documentation is available in AsciiDoc format at link:{url-docs}[docs/main.adoc]. Build PDF with: - -[source,bash] ----- -asciidoctor-pdf -a pdf-theme=docs/themes/azurelocal-theme.yml docs/main.adoc ----- - -== Prerequisites - -* PowerShell 7.2+ -* `powershell-yaml` module -* `VMFleet` module (for VMFleet solution) -* Azure Local cluster with WinRM access -* Optional: `ImportExcel`, `Az.KeyVault`, `Az.Monitor`, `asciidoctor-pdf`, `pandoc` - -== License - -This project is licensed under the MIT License — see link:LICENSE[LICENSE] for details. diff --git a/README.md b/README.md new file mode 100644 index 0000000..fa6eabc --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# azurelocal-loadtools + +Automated performance and load testing for **Azure Local** clusters — storage, network, database, and system stress — with standardised reporting. + +> **Note:** This repository is under active development. Scripts, templates, and automation are not guaranteed to work at this time. Use at your own risk and expect breaking changes. + +--- + +## Repository Structure + +``` +azurelocal-loadtools/ +├── config/ # Central variable reference (variables.example.yml) +├── src/ # Shared modules and helpers +├── tools/ # One folder per test tool +│ ├── vmfleet/ # Storage IOPS / throughput / latency (DiskSpd) +│ ├── fio/ # Fine-grained storage I/O benchmarking +│ ├── iperf/ # Network bandwidth, jitter, packet loss +│ ├── hammerdb/ # SQL Server OLTP / OLAP benchmarking +│ └── stress-ng/ # CPU, memory, and system stress testing +├── docs/ # Documentation (MkDocs source) +├── tests/ # Validation scripts +├── monitoring/ # Monitoring dashboards and alerting +├── reports/ # Generated test reports +└── .github/workflows/ # GitHub Actions workflows +``` + +--- + +## Quick Start + +```powershell +# 1. Clone and configure +git clone https://github.com/AzureLocal/azurelocal-loadtools +cd azurelocal-loadtools +Copy-Item config\variables.example.yml config\variables.yml +# Edit config\variables.yml with your cluster details + +# 2. Run a VMFleet storage benchmark +.\tools\vmfleet\Invoke-VMFleetPipeline.ps1 ` + -ConfigPath "config\variables.yml" ` + -Profiles @("General") ` + -CredentialSource Interactive ` + -GenerateReports +``` + +See the [documentation site](https://azurelocal.github.io/azurelocal-loadtools/) for full instructions. + +--- + +## Tools + +Each tool targets a specific performance domain and runs independently from a PowerShell terminal. + +| Tool | What It Tests | Target OS | Status | +|------|--------------|-----------|--------| +| VMFleet | Storage IOPS, throughput, latency via DiskSpd VM fleet | Windows (HCI host) | Fully Implemented | +| fio | Fine-grained storage I/O benchmarking | Linux VMs | Structure Ready | +| iPerf3 | Network bandwidth, jitter, packet loss | Linux / Windows | Structure Ready | +| HammerDB | SQL Server OLTP / OLAP benchmarking | Windows VMs | Structure Ready | +| stress-ng | CPU, memory, and system stress testing | Linux VMs | Structure Ready | + +Every tool follows the same pattern: **Install → Run Test → Collect Results**. + +--- + +## Documentation + +- [Getting Started](./docs/getting-started/introduction.md) +- [Architecture Overview](./docs/architecture/overview.md) +- [Tools Overview](./docs/tools/index.md) +- [Variable Reference](./docs/reference/variables.md) +- [Contributing](./docs/contributing.md) + +--- + +## Prerequisites + +- **Azure Local** cluster (23H2+) registered with Azure Arc +- Azure subscription with appropriate RBAC +- PowerShell 7+ +- See tool-specific requirements in the documentation + +--- + +## Contributing + +See [Contributing Guide](./docs/contributing.md) for coding standards, branch strategy, and PR guidelines. diff --git a/docs/_archived_adoc/getting-started/architecture.adoc b/docs/_archived_adoc/getting-started/architecture.adoc deleted file mode 100644 index 1f70cd3..0000000 --- a/docs/_archived_adoc/getting-started/architecture.adoc +++ /dev/null @@ -1,122 +0,0 @@ -= Solution Architecture -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -This document describes the overall architecture of the {project-name}, including component relationships, data flow, and integration points. - -== High-Level Architecture - -// TODO: Export from docs/diagrams/solution-architecture.drawio -// image::solution-architecture.svg[Solution Architecture,width=100%,align=center] - -The framework consists of five major layers: - -[horizontal] -Configuration Layer:: Master environment variables, cluster configs, workload profiles, credential management -Automation Layer:: PowerShell modules, Ansible roles, orchestrator scripts -Execution Layer:: Load testing tools (VMFleet, fio, iPerf3, HammerDB, stress-ng) running on cluster nodes and VMs -Monitoring Layer:: PerfMon counter collection, Azure Monitor integration, real-time dashboards -Reporting Layer:: Metric aggregation, AsciiDoc template population, multi-format output generation - -== Configuration Flow - -// TODO: Export from docs/diagrams/config-flow.drawio -// image::config-flow.svg[Configuration Flow,width=100%,align=center] - -.Configuration Pipeline -[source,text] ----- -master-environment.yml → ConfigManager Module → vmfleet.json - (all variables, (filters by (only VMFleet - tagged by solution) solution tag) variables) ----- - -The `ConfigManager` PowerShell module reads the master environment file, filters variables by their solution tags, and generates solution-specific JSON files. Downstream scripts consume only the generated JSON — never the master YAML directly. - -== Component Diagram - -.Core Components -[cols="1,2,1"] -|=== -| Component | Responsibility | Location - -| ConfigManager -| Variable management, filtering, override chain -| `src/core/powershell/modules/ConfigManager/` - -| Logger -| Structured JSON-lines logging with correlation IDs -| `src/core/powershell/modules/Logger/` - -| StateManager -| Run state tracking, checkpoints, resume capability -| `src/core/powershell/modules/StateManager/` - -| CredentialManager -| KeyVault, interactive, or parameter-based credential retrieval -| `src/core/powershell/modules/CredentialManager/` - -| MonitoringManager -| PerfMon collection, Azure Monitor push -| `src/core/powershell/modules/MonitoringManager/` - -| ReportGenerator -| PDF, DOCX, XLSX report generation -| `src/core/powershell/modules/ReportGenerator/` -|=== - -== Tool Automation Workflows - -Each tool follows a common workflow pattern, adapted to its specific requirements: - -. **Pre-Check** — Validate cluster connectivity, tool-specific prerequisites -. **Install** — Install required modules and dependencies on target nodes -. **Deploy** — Deploy test workloads (VMs, containers, services) -. **Test** — Execute workload profiles -. **Monitor** — Collect metrics in parallel with test execution -. **Collect** — Parse results, aggregate metrics -. **Report** — Generate PDF, DOCX, and XLSX reports -. **Cleanup** — (Optional) Remove test workloads - -Each phase is checkpoint-tracked via `StateManager`, enabling resume after failure. - -See individual tool guides for tool-specific workflow details: - -* link:../tools/vmfleet/overview.adoc[VMFleet Workflow] -* link:../tools/fio/overview.adoc[fio Workflow] -* link:../tools/iperf/overview.adoc[iPerf3 Workflow] -* link:../tools/hammerdb/overview.adoc[HammerDB Workflow] -* link:../tools/stress-ng/overview.adoc[stress-ng Workflow] - -== Network Topology - -// TODO: Export from docs/diagrams/network-topology.drawio -// image::network-topology.svg[Network Topology,width=100%,align=center] - -A typical Azure Local cluster deployment includes: - -* **Management Network** — Cluster management, PowerShell remoting, monitoring traffic -* **Storage Network** — RDMA/SMB Direct traffic between cluster nodes (dedicated NICs) -* **Compute/VM Network** — Virtual machine workload traffic -* **Management Station** — Automation execution host with line-of-sight to management network - -== Security Model - -All credential handling follows the principle of least privilege: - -* Credentials are **never hardcoded** in scripts or configuration files -* Three credential retrieval modes: Azure Key Vault, interactive prompt, or parameter injection -* Key Vault access via managed identity or service principal -* CI/CD pipelines use GitHub Secrets / Azure DevOps Service Connections / GitLab CI Variables -* All credential access is logged (value masked) for audit trail - -See link:../operations/credential-management.adoc[Credential Management] for full details. diff --git a/docs/_archived_adoc/getting-started/configuration.adoc b/docs/_archived_adoc/getting-started/configuration.adoc deleted file mode 100644 index 4525673..0000000 --- a/docs/_archived_adoc/getting-started/configuration.adoc +++ /dev/null @@ -1,201 +0,0 @@ -= Configuration System -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -The configuration system is the backbone of the {project-name}. It ensures that *nothing is hardcoded* and every value is parameterizable. - -== Configuration Architecture - -.Configuration Hierarchy -[source,text] ----- -config/ -├── variables/ -│ ├── master-environment.yml ← Single source of truth for ALL variables -│ ├── schema.json ← JSON Schema for validation -│ └── solutions/ ← Generated per-solution config files -│ ├── vmfleet.json -│ ├── fio.json -│ └── ... -├── clusters/ ← Per-cluster connection configs -│ └── example-cluster.yml -├── profiles/ ← Workload test profiles -│ ├── vmfleet/ -│ └── ... -└── credentials/ - └── keyvault-config.yml ← Key Vault connection settings ----- - -== Master Environment File - -The `master-environment.yml` file contains *every* variable used across all solutions. Each variable is tagged with the solutions that consume it. - -.Variable Structure -[source,yaml] ----- -variables: - - name: vm_count_per_node - value: 10 - type: integer - required: true - description: "Number of fleet VMs to deploy per cluster node" - solutions: [vmfleet] - category: deployment ----- - -.Variable Properties -[cols="1,2,1"] -|=== -| Property | Description | Required - -| `name` -| Unique variable identifier (snake_case) -| Yes - -| `value` -| Default value -| Yes - -| `type` -| Data type: string, integer, boolean, array -| Yes - -| `required` -| Whether the variable must have a non-empty value -| Yes - -| `description` -| Human-readable description -| Yes - -| `solutions` -| Array of solution tags: vmfleet, fio, iperf, hammerdb, stress-ng -| Yes - -| `category` -| Logical grouping: cluster, deployment, testing, monitoring, reporting -| No - -| `sensitive` -| If true, value should come from Key Vault (never stored in YAML) -| No -|=== - -== Solution Configuration Generation - -The `ConfigManager` module reads the master environment, filters by solution tag, and writes JSON: - -[source,powershell] ----- -# Generate VMFleet-specific configuration -Import-Module ./src/core/powershell/modules/ConfigManager/ConfigManager.psm1 - -Export-SolutionConfig -Solution "vmfleet" ` - -MasterConfigPath "./config/variables/master-environment.yml" ` - -OutputPath "./config/variables/solutions/vmfleet.json" ----- - -The generated `vmfleet.json` contains only variables tagged with `vmfleet`: - -[source,json] ----- -{ - "vm_count_per_node": 10, - "vm_vcpu_count": 2, - "vm_memory_gb": 2, - "test_duration_seconds": 300, - "warmup_seconds": 60 -} ----- - -== Variable Override Chain - -Every script supports a three-level override chain: - -. **Explicit Parameter** — Highest priority. Pass `-VmCountPerNode 20` to any script. -. **Solution JSON** — Read from `config/variables/solutions/{solution}.json` -. **Master Default** — Fallback value from `master-environment.yml` - -[source,powershell] ----- -# Override chain example: -# 1. Explicit parameter wins -Start-VMFleetTest -VmCountPerNode 20 - -# 2. Without parameter, reads from vmfleet.json -Start-VMFleetTest - -# 3. If vmfleet.json missing, falls back to master-environment.yml default ----- - -== Cluster Configuration - -Cluster configs in `config/clusters/` define target cluster details. To switch clusters, change the `-ClusterConfig` parameter: - -[source,powershell] ----- -# Target different clusters by swapping config files -.\Invoke-VMFleetPipeline.ps1 -ClusterConfig "config/clusters/prod-cluster.yml" -.\Invoke-VMFleetPipeline.ps1 -ClusterConfig "config/clusters/dev-cluster.yml" ----- - -== Workload Profiles - -Each solution has predefined workload profiles in `config/profiles/{solution}/`: - -[source,yaml] ----- -# config/profiles/vmfleet/general.yml -profile: - name: "General" - description: "Balanced read/write workload for general validation" - parameters: - block_size: "8k" - write_ratio: 30 - random_ratio: 70 - outstanding_io: 8 - threads_per_vm: 2 - duration_seconds: 300 - warmup_seconds: 60 ----- - -== Credential Configuration - -The `keyvault-config.yml` maps logical credential names to Key Vault secrets: - -[source,yaml] ----- -keyvault: - name: "my-keyvault-name" - resource_group: "my-rg" - secrets: - cluster_admin_password: "hci-cluster-admin-pwd" - cluster_admin_username: "hci-cluster-admin-user" - azure_client_secret: "sp-client-secret" ----- - -Scripts use `CredentialManager` to retrieve credentials without knowing the storage mechanism: - -[source,powershell] ----- -$cred = Get-ManagedCredential -Name "cluster_admin" -Source KeyVault ----- - -See link:../operations/credential-management.adoc[Credential Management] for full details on the three credential modes. - -== Next Steps - -Choose a tool to get started: - -* link:../tools/vmfleet/overview.adoc[VMFleet Guide] — Storage load testing -* link:../tools/fio/overview.adoc[fio Guide] — Flexible I/O benchmarking -* link:../tools/iperf/overview.adoc[iPerf3 Guide] — Network testing diff --git a/docs/_archived_adoc/getting-started/installation.adoc b/docs/_archived_adoc/getting-started/installation.adoc deleted file mode 100644 index ba74d41..0000000 --- a/docs/_archived_adoc/getting-started/installation.adoc +++ /dev/null @@ -1,145 +0,0 @@ -= Installation -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -This guide walks through the installation and initial setup of the {project-name}. - -== Clone the Repository - -[source,powershell] ----- -git clone https://github.com/AzureLocal/azurelocal-loadtools.git -cd azurelocal-loadtools ----- - -== Install PowerShell Dependencies - -[source,powershell] ----- -# Install required PowerShell modules -Install-Module -Name powershell-yaml -Scope CurrentUser -Force -Install-Module -Name ImportExcel -Scope CurrentUser -Force -Install-Module -Name Az.KeyVault -Scope CurrentUser -Force -Install-Module -Name Az.Monitor -Scope CurrentUser -Force -Install-Module -Name VMFleet -Scope CurrentUser -Force -Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force ----- - -== Install Report Generation Tools - -=== Asciidoctor (PDF Reports) - -[source,powershell] ----- -# Install Ruby (via winget or chocolatey) -winget install RubyInstallerTeam.Ruby.3.2 - -# Install Asciidoctor and PDF generator -gem install asciidoctor asciidoctor-pdf rouge ----- - -=== Pandoc (Word Reports) - -[source,powershell] ----- -# Install Pandoc -winget install JohnMacFarlane.Pandoc ----- - -== Install Ansible (Optional — Linux Tools) - -Ansible is required only for Linux-based tools (fio, iPerf3, HammerDB, stress-ng). - -=== Option A: WSL2 on Windows - -[source,powershell] ----- -# Enable WSL2 and install Ubuntu -wsl --install -d Ubuntu - -# Inside WSL2: -sudo apt update && sudo apt install -y python3-pip -pip3 install ansible ----- - -=== Option B: Linux Jump Box - -[source,bash] ----- -# On a dedicated Linux management VM -sudo apt update && sudo apt install -y python3-pip -pip3 install ansible ----- - -=== Option C: CI Runner Only - -Ansible is installed as part of the CI/CD pipeline. See the link:../operations/ci-cd.adoc[CI/CD Pipelines] guide. - -== Configure Cluster Connection - -Copy the example cluster configuration and customize: - -[source,powershell] ----- -Copy-Item config/clusters/example-cluster.yml config/clusters/my-cluster.yml ----- - -Edit `config/clusters/my-cluster.yml` with your cluster details: - -[source,yaml] ----- -cluster: - name: "my-hci-cluster" - domain: "contoso.local" - nodes: - - name: "hci-node-01" - management_ip: "10.0.0.1" - - name: "hci-node-02" - management_ip: "10.0.0.2" - csv_path: "C:\\ClusterStorage\\Volume1" - collect_volume_path: "C:\\ClusterStorage\\Collect" - base_vhd_path: "C:\\ClusterStorage\\Collect\\BaseImage.vhdx" ----- - -== Initialize the Environment - -[source,powershell] ----- -# Run the environment initialization script -.\src\core\powershell\helpers\Initialize-Environment.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -CredentialSource Interactive ----- - -This will: - -. Load and validate the cluster configuration -. Test connectivity to all cluster nodes -. Verify Storage Spaces Direct health -. Check for required volumes and base VHD -. Generate solution-specific configuration files from the master environment -. Create initial run state - -== Verify Installation - -[source,powershell] ----- -# Run the validation suite -Invoke-Pester tests/unit/ -Output Detailed ----- - -All tests should pass, confirming modules load correctly and configuration is valid. - -== Next Steps - -* link:configuration.adoc[Configuration] — Understand the configuration system -* link:../tools/vmfleet/overview.adoc[VMFleet Guide] — Start with VMFleet storage testing diff --git a/docs/_archived_adoc/getting-started/introduction.adoc b/docs/_archived_adoc/getting-started/introduction.adoc deleted file mode 100644 index 4f33274..0000000 --- a/docs/_archived_adoc/getting-started/introduction.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= Introduction -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -The {project-name} is a comprehensive, automated solution for load testing Azure Local (Azure Stack HCI) clusters. It validates storage, network, and compute performance before production or development workloads are migrated or deployed. - -== Why Load Test Azure Local? - -Azure Local clusters represent significant infrastructure investments. Before committing production workloads, organizations need confidence that: - -* **Storage performance** meets application IOPS, throughput, and latency requirements -* **Network throughput** supports east-west traffic, RDMA/SMB Direct expectations -* **Compute capacity** handles expected virtual machine density -* **The cluster** operates stably under sustained load without thermal throttling or hardware degradation - -== Supported Load Testing Tools - -[cols="1,2,1"] -|=== -| Tool | Purpose | Status - -| link:../tools/vmfleet/overview.adoc[VMFleet] -| Storage load generation via VM fleet running DiskSpd workloads -| ✅ Fully Implemented - -| link:../tools/fio/overview.adoc[fio] -| Fine-grained storage I/O benchmarking (Linux VMs) -| 🔲 Placeholder - -| link:../tools/iperf/overview.adoc[iPerf3] -| Network bandwidth and latency testing -| 🔲 Placeholder - -| link:../tools/hammerdb/overview.adoc[HammerDB] -| Database workload benchmarking (OLTP/OLAP) -| 🔲 Placeholder - -| link:../tools/stress-ng/overview.adoc[stress-ng] -| CPU, memory, and system stress testing -| 🔲 Placeholder -|=== - -== Key Features - -* **100% Automated** — End-to-end pipeline from cluster validation to report generation -* **Configuration-Driven** — Master environment file with tagged variables; nothing hardcoded -* **Credential Security** — Azure Key Vault integration or interactive credential prompting -* **Comprehensive Monitoring** — Real-time storage, network, and compute metric collection -* **Multi-Format Reports** — PDF, Word (DOCX), and Excel (XLSX) output -* **CI/CD Ready** — GitHub Actions, Azure DevOps, and GitLab CI pipeline definitions -* **Modular Architecture** — Add new testing tools without modifying existing automation - -== Project Repository - -The source code is hosted at {project-repo}. - -== Next Steps - -* link:prerequisites.adoc[Prerequisites] — Ensure your environment is ready -* link:installation.adoc[Installation] — Set up the framework -* link:configuration.adoc[Configuration] — Configure your cluster and workloads diff --git a/docs/_archived_adoc/getting-started/prerequisites.adoc b/docs/_archived_adoc/getting-started/prerequisites.adoc deleted file mode 100644 index 68f1c71..0000000 --- a/docs/_archived_adoc/getting-started/prerequisites.adoc +++ /dev/null @@ -1,153 +0,0 @@ -= Prerequisites -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -Before deploying the {project-name}, ensure the following common prerequisites are met. Individual tools may have additional requirements — see each tool's prerequisites page. - -== Azure Local Cluster Requirements - -[cols="1,2"] -|=== -| Requirement | Details - -| Azure Local Version -| Azure Stack HCI 23H2 or later (22H2 supported with limitations) - -| Cluster Nodes -| Minimum 2 nodes; recommended 4+ for meaningful fleet testing - -| Storage Spaces Direct (S2D) -| Enabled and healthy (`Get-StorageSubSystem` shows `HealthStatus: Healthy`) - -| Cluster Shared Volumes -| At least one CSV for VM fleet storage; additional CSV for results collection -|=== - -== Network Requirements - -[cols="1,2"] -|=== -| Requirement | Details - -| Management Network -| IP connectivity from management station to all cluster nodes - -| PowerShell Remoting -| WinRM enabled on all cluster nodes (default for Azure Local) - -| RDMA (Optional) -| Required for storage network performance validation with iPerf3 - -| Firewall -| Ports 5985 (WinRM HTTP), 5986 (WinRM HTTPS) open from management station -|=== - -== Management Station Requirements - -The management station is where automation scripts execute. This can be a physical workstation, jump box, or CI/CD runner. - -[cols="1,2"] -|=== -| Requirement | Details - -| Operating System -| Windows 10/11 or Windows Server 2019+ (PowerShell 7.2+) - -| PowerShell -| Version 7.2 or later (`$PSVersionTable.PSVersion`) - -| PowerShell Modules -| `Az.KeyVault`, `Az.Monitor`, `powershell-yaml`, `ImportExcel` - -| Asciidoctor -| Ruby 3.0+, `asciidoctor`, `asciidoctor-pdf` gems (for report generation) - -| Pandoc -| Version 3.0+ (for DOCX report generation) - -| Git -| Version 2.30+ (for repository management) -|=== - -== Ansible Requirements (for Linux-Based Tools) - -Ansible is required only if using fio, iPerf3, HammerDB, or stress-ng on Linux VMs. - -[cols="1,2"] -|=== -| Requirement | Details - -| Ansible -| Version 2.14+ (installed via `pip install ansible`) - -| Execution Environment -| WSL2 on Windows, Linux jump box, or CI runner (see installation guide) - -| SSH Access -| Key-based SSH authentication to target Linux VMs - -| Python -| Version 3.9+ on the Ansible control node -|=== - -== Azure Requirements (Optional) - -Required only if using Azure Monitor integration or Azure Key Vault for credentials. - -[cols="1,2"] -|=== -| Requirement | Details - -| Azure Subscription -| Active subscription with Contributor access - -| Azure Key Vault -| Provisioned Key Vault with secrets for cluster credentials - -| Log Analytics Workspace -| Provisioned workspace for Azure Monitor metric ingestion - -| Service Principal or Managed Identity -| For non-interactive Azure authentication in CI/CD -|=== - -== Validating Prerequisites - -Run the pre-check script to validate all common prerequisites: - -[source,powershell] ----- -# From the repository root -.\src\core\powershell\helpers\Initialize-Environment.ps1 -ValidateOnly ----- - -This will check: - -* PowerShell version and required modules -* Cluster connectivity and S2D health -* Required volumes availability -* Azure connectivity (if Azure features enabled) -* Ansible availability (if Linux tools enabled) - -== Tool-Specific Prerequisites - -Each tool may have additional requirements beyond the common set above: - -* link:../tools/vmfleet/prerequisites.adoc[VMFleet Prerequisites] — Base VHD, Collect volume, VMFleet module -* link:../tools/fio/overview.adoc[fio Prerequisites] — Linux VMs, fio package -* link:../tools/iperf/overview.adoc[iPerf3 Prerequisites] — iPerf3 binaries, RDMA configuration -* link:../tools/hammerdb/overview.adoc[HammerDB Prerequisites] — SQL Server, HammerDB installation -* link:../tools/stress-ng/overview.adoc[stress-ng Prerequisites] — Linux VMs, stress-ng package - -== Next Steps - -* link:installation.adoc[Installation] — Install the framework and dependencies diff --git a/docs/_archived_adoc/index.adoc b/docs/_archived_adoc/index.adoc deleted file mode 100644 index 762c0e0..0000000 --- a/docs/_archived_adoc/index.adoc +++ /dev/null @@ -1,164 +0,0 @@ -= Azure Local Load Testing Framework — Documentation -:toc: left -:toclevels: 2 -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform: Azure Local] -image:https://img.shields.io/badge/Status-Pre--Release-orange?style=flat-square[Status: Pre-Release] - -Welcome to the {project-name} documentation. This framework automates load testing of Azure Local (Azure Stack HCI) clusters before production or development workloads are migrated or deployed. - -== Getting Started - -Start here regardless of which tool you plan to use. - -[cols="1,3"] -|=== -| Document | Description - -| link:getting-started/introduction.adoc[Introduction] -| Project overview, supported tools, key features - -| link:getting-started/architecture.adoc[Architecture] -| Solution architecture, component relationships, data flow - -| link:getting-started/prerequisites.adoc[Prerequisites] -| Common requirements for all tools (cluster, network, management station) - -| link:getting-started/installation.adoc[Installation] -| Clone, install dependencies, initialize the environment - -| link:getting-started/configuration.adoc[Configuration] -| Master environment file, variable override chain, workload profiles, credentials -|=== - -== Tool Guides - -Each tool has its own self-contained documentation. Pick the tool you need: - -=== VMFleet — Storage Load Testing - -Primary tool for validating Storage Spaces Direct (S2D) performance via fleet VMs running DiskSpd. - -[cols="1,3"] -|=== -| Document | Description - -| link:tools/vmfleet/overview.adoc[Overview] -| What VMFleet is, when to use it, quick-start pipeline command - -| link:tools/vmfleet/prerequisites.adoc[Prerequisites] -| VMFleet-specific requirements (base VHD, Collect volume, S2D health) - -| link:tools/vmfleet/deployment.adoc[Deployment] -| Install VMFleet module, deploy fleet VMs across cluster nodes - -| link:tools/vmfleet/workload-profiles.adoc[Workload Profiles] -| General, Peak IOPS, VDI, SQL OLTP — profile definitions and execution - -| link:tools/vmfleet/monitoring.adoc[Monitoring] -| Storage, network, and compute metric collection during VMFleet runs - -| link:tools/vmfleet/reporting.adoc[Reporting] -| PDF, DOCX, and XLSX report generation from VMFleet results - -| link:tools/vmfleet/troubleshooting.adoc[Troubleshooting] -| Common VMFleet issues and resolutions -|=== - -=== fio — Flexible I/O Benchmarking - -[cols="1,3"] -|=== -| Document | Description - -| link:tools/fio/overview.adoc[Overview] -| Fine-grained storage I/O benchmarking on Linux VMs -|=== - -=== iPerf3 — Network Performance Testing - -[cols="1,3"] -|=== -| Document | Description - -| link:tools/iperf/overview.adoc[Overview] -| Network bandwidth, jitter, and packet loss measurement -|=== - -=== HammerDB — Database Benchmarking - -[cols="1,3"] -|=== -| Document | Description - -| link:tools/hammerdb/overview.adoc[Overview] -| SQL Server OLTP/OLAP workload benchmarking -|=== - -=== stress-ng — System Stress Testing - -[cols="1,3"] -|=== -| Document | Description - -| link:tools/stress-ng/overview.adoc[Overview] -| CPU, memory, and system stress testing for capacity planning -|=== - -== Operations - -Cross-tool operational documentation. - -[cols="1,3"] -|=== -| Document | Description - -| link:operations/ci-cd.adoc[CI/CD Pipelines] -| GitHub Actions, Azure DevOps, and GitLab CI pipeline definitions - -| link:operations/credential-management.adoc[Credential Management] -| Azure Key Vault, interactive, and parameter-based credential modes -|=== - -== Reference - -[cols="1,3"] -|=== -| Document | Description - -| link:reference/variable-reference.adoc[Variable Reference] -| Complete catalog of all configuration variables - -| link:reference/cmdlet-reference.adoc[Cmdlet Reference] -| PowerShell function documentation for all core modules - -| link:reference/glossary.adoc[Glossary] -| Definitions of key terms and abbreviations -|=== - -== Standards - -Internal documentation and coding standards for contributors. - -[cols="1,3"] -|=== -| Document | Description - -| link:standards/documentation-standards.adoc[Documentation Standards] -| AsciiDoc formatting rules and templates - -| link:standards/scripting-standards.adoc[Scripting Standards] -| PowerShell coding conventions - -| link:standards/variables-environment-standards.adoc[Variables & Environment Standards] -| Configuration file and variable naming rules - -| link:standards/asciidoc-reference.adoc[AsciiDoc Reference] -| Quick syntax cheat sheet -|=== diff --git a/docs/_archived_adoc/main.adoc b/docs/_archived_adoc/main.adoc deleted file mode 100644 index 0e9745e..0000000 --- a/docs/_archived_adoc/main.adoc +++ /dev/null @@ -1,118 +0,0 @@ -= Azure Local Load Testing Framework -:author: AzureLocal -:email: azurelocal@microsoft.com -:revdate: 2026-02-13 -:revnumber: 0.1.0 -:doctype: book -:toc: left -:toclevels: 3 -:sectnums: -:sectnumlevels: 3 -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: images -:pdf-themesdir: themes -:pdf-theme: azurelocal-theme -// Document attributes - reusable variables -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools -:vmfleet-version: 2.1.0.0 -:diskspd-version: 2.2 - -[preface] -== Preface - -This document provides comprehensive documentation for the {project-name}. It covers architecture, installation, configuration, usage of each load testing tool, monitoring, reporting, and CI/CD integration. - -The framework is designed to fully automate load testing of Azure Local (Azure Stack HCI) clusters before production or development workloads are migrated or deployed. - -=== Target Audience - -* Infrastructure Engineers preparing Azure Local clusters for production -* DevOps Engineers building automated testing pipelines -* Storage Administrators validating Storage Spaces Direct performance -* Network Engineers validating RDMA and SMB Direct configurations - -=== Document Conventions - -[cols="1,3"] -|=== -| Convention | Meaning - -| `monospace` -| Commands, file paths, variable names - -| *bold* -| Important terms, UI elements - -| _italic_ -| Emphasis, first use of terms - -| NOTE: -| Additional information - -| WARNING: -| Potential issues or data loss risks - -| TIP: -| Best practices and recommendations -|=== - -// Part I: Getting Started -= Getting Started - -include::getting-started/introduction.adoc[leveloffset=+1] - -include::getting-started/architecture.adoc[leveloffset=+1] - -include::getting-started/prerequisites.adoc[leveloffset=+1] - -include::getting-started/installation.adoc[leveloffset=+1] - -include::getting-started/configuration.adoc[leveloffset=+1] - -// Part II: Tool Guides — VMFleet -= VMFleet - -include::tools/vmfleet/overview.adoc[leveloffset=+1] - -include::tools/vmfleet/prerequisites.adoc[leveloffset=+1] - -include::tools/vmfleet/deployment.adoc[leveloffset=+1] - -include::tools/vmfleet/workload-profiles.adoc[leveloffset=+1] - -include::tools/vmfleet/monitoring.adoc[leveloffset=+1] - -include::tools/vmfleet/reporting.adoc[leveloffset=+1] - -include::tools/vmfleet/troubleshooting.adoc[leveloffset=+1] - -// Part III: Tool Guides — Additional Tools -= Additional Tools - -include::tools/fio/overview.adoc[leveloffset=+1] - -include::tools/iperf/overview.adoc[leveloffset=+1] - -include::tools/hammerdb/overview.adoc[leveloffset=+1] - -include::tools/stress-ng/overview.adoc[leveloffset=+1] - -// Part IV: Operations -= Operations - -include::operations/ci-cd.adoc[leveloffset=+1] - -include::operations/credential-management.adoc[leveloffset=+1] - -// Appendices -[appendix] -include::reference/variable-reference.adoc[leveloffset=+1] - -[appendix] -include::reference/cmdlet-reference.adoc[leveloffset=+1] - -[appendix] -include::reference/glossary.adoc[leveloffset=+1] diff --git a/docs/_archived_adoc/operations/ci-cd.adoc b/docs/_archived_adoc/operations/ci-cd.adoc deleted file mode 100644 index 003bb3a..0000000 --- a/docs/_archived_adoc/operations/ci-cd.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= CI/CD Pipelines -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Operations-9B59B6?style=flat-square[Category: Operations] - -The framework includes pipeline definitions for GitHub Actions (primary), Azure DevOps, and GitLab CI. - -== GitHub Actions (Primary) - -=== Documentation Build (`build-docs.yml`) - -Triggers on push to `main` and pull requests. Builds HTML and PDF documentation, exports draw.io diagrams, and publishes artifacts. - -=== Configuration Validation (`validate-config.yml`) - -Triggers on changes to `config/`. Validates `master-environment.yml` against the JSON Schema and verifies solution config generation. - -=== VMFleet Pipeline (`run-vmfleet.yml`) - -Manual trigger (`workflow_dispatch`) with configurable inputs: - -* Cluster configuration file path -* Workload profiles to execute -* Credential source (Key Vault or GitHub Secrets) -* Whether to generate reports -* Whether to cleanup after completion - -Requires a self-hosted runner with network access to the Azure Local cluster. - -=== Unit Tests (`run-tests.yml`) - -Runs Pester unit tests for all core PowerShell modules on every pull request. - -=== Linting (`lint.yml`) - -Runs PSScriptAnalyzer for PowerShell, yamllint for YAML, and AsciiDoc syntax checks. - -== Azure DevOps (Placeholder) - -Pipeline definitions in `.azuredevops/pipelines/` mirror the GitHub Actions workflows, adapted for Azure DevOps syntax. Use Azure DevOps Service Connections for credential management. - -== GitLab CI (Placeholder) - -Pipeline definition in `.gitlab/.gitlab-ci.yml` provides the same workflow stages, adapted for GitLab CI syntax. - -== Manual Execution - -Every pipeline action can also be run manually from a workstation: - -[source,powershell] ----- -# Build documentation -asciidoctor-pdf docs/main.adoc -o output/azurelocal-loadtools.pdf - -# Validate configuration -.\src\core\powershell\helpers\Initialize-Environment.ps1 -ValidateOnly - -# Run VMFleet pipeline -.\src\solutions\vmfleet\orchestrator\Invoke-VMFleetPipeline.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -Profiles @("General", "Peak") ` - -CredentialSource Interactive - -# Run unit tests -Invoke-Pester tests/unit/ -Output Detailed ----- - -== Self-Hosted Runner Setup - -The VMFleet pipeline requires a self-hosted runner on the cluster management network: - -. Install GitHub Actions runner on a Windows management station -. Register with the repository as a self-hosted runner -. Tag with labels: `self-hosted`, `windows`, `hci-management` -. Ensure PowerShell 7.2+ and required modules are installed -. Configure WinRM access to cluster nodes - -See https://docs.github.com/en/actions/hosting-your-own-runners for setup instructions. diff --git a/docs/_archived_adoc/operations/credential-management.adoc b/docs/_archived_adoc/operations/credential-management.adoc deleted file mode 100644 index e43e055..0000000 --- a/docs/_archived_adoc/operations/credential-management.adoc +++ /dev/null @@ -1,109 +0,0 @@ -= Credential Management -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Operations-9B59B6?style=flat-square[Category: Operations] - -All credential handling in the {project-name} follows the principle of least privilege. Credentials are **never hardcoded** in scripts or configuration files. - -== Credential Sources - -The `CredentialManager` module supports three credential retrieval modes: - -[cols="1,2,2"] -|=== -| Source | How It Works | Best For - -| **Key Vault** -| Retrieves secrets from Azure Key Vault via managed identity or service principal -| CI/CD pipelines, production environments - -| **Interactive** -| Prompts the user with `Get-Credential` -| Development, manual testing - -| **Parameter** -| Accepts a `[PSCredential]` object passed directly -| Scripted orchestration, testing -|=== - -== Using Credentials in Scripts - -[source,powershell] ----- -# Key Vault mode -$cred = Get-ManagedCredential -Name "cluster_admin" -Source KeyVault - -# Interactive mode -$cred = Get-ManagedCredential -Name "cluster_admin" -Source Interactive - -# Parameter mode -$cred = Get-ManagedCredential -Name "cluster_admin" -Source Parameter -Credential $myCred ----- - -All scripts accept a `-CredentialSource` parameter: - -[source,powershell] ----- -.\Invoke-VMFleetPipeline.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -CredentialSource KeyVault ----- - -== Key Vault Configuration - -The `config/credentials/keyvault-config.yml` file maps logical credential names to Key Vault secrets: - -[source,yaml] ----- -keyvault: - name: "my-keyvault-name" - resource_group: "my-rg" - secrets: - cluster_admin_password: "hci-cluster-admin-pwd" - cluster_admin_username: "hci-cluster-admin-user" - azure_client_secret: "sp-client-secret" ----- - -=== Deploying Key Vault Infrastructure - -Use the provided Bicep template: - -[source,powershell] ----- -az deployment group create ` - -g "my-resource-group" ` - -f "src/infrastructure/bicep/keyvault.bicep" ` - -p vaultName="my-keyvault-name" ----- - -== CI/CD Credential Patterns - -[cols="1,2"] -|=== -| Platform | Credential Mechanism - -| GitHub Actions -| GitHub Secrets → environment variables → `-CredentialSource Parameter` - -| Azure DevOps -| Service Connections or Variable Groups → pipeline variables - -| GitLab CI -| CI/CD Variables (masked) → environment variables -|=== - -== Security Practices - -* All credential access is logged — values are **masked** in logs for audit trail -* Key Vault access should use managed identity where possible -* Rotate secrets on a regular schedule -* Use `:sensitive: true` in `master-environment.yml` to flag variables that must come from Key Vault -* Never commit credentials to the repository — use `.gitignore` and pre-commit hooks diff --git a/docs/_archived_adoc/reference/cmdlet-reference.adoc b/docs/_archived_adoc/reference/cmdlet-reference.adoc deleted file mode 100644 index 7803509..0000000 --- a/docs/_archived_adoc/reference/cmdlet-reference.adoc +++ /dev/null @@ -1,165 +0,0 @@ -= Cmdlet Reference -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Reference-7F8C8D?style=flat-square[Category: Reference] - -This document covers the custom PowerShell functions provided by the core modules. - -== ConfigManager Module - -=== Export-SolutionConfig - -Generates a solution-specific JSON configuration file from the master environment. - -[source,powershell] ----- -Export-SolutionConfig [-Solution] [-MasterConfigPath ] [-OutputPath ] ----- - -.Parameters -[cols="1,1,3"] -|=== -| Parameter | Type | Description - -| `-Solution` -| string -| Solution name: vmfleet, fio, iperf, hammerdb, stress-ng - -| `-MasterConfigPath` -| string -| Path to master-environment.yml (default: `config/variables/master-environment.yml`) - -| `-OutputPath` -| string -| Output path for generated JSON (default: `config/variables/solutions/{solution}.json`) -|=== - -=== Get-ConfigValue - -Retrieves a configuration value with override chain support. - -[source,powershell] ----- -Get-ConfigValue [-Name] [-Solution ] [-DefaultValue ] [-Override ] ----- - -== Logger Module - -=== Write-Log - -Writes a structured log entry to the component log file. - -[source,powershell] ----- -Write-Log [-Message] [-Severity ] [-Component ] [-Data ] ----- - -.Severity Levels -* `DEBUG` — Detailed diagnostic information -* `INFO` — General operational messages -* `WARNING` — Potential issues that don't stop execution -* `ERROR` — Failures that affect the current operation -* `CRITICAL` — Fatal errors requiring immediate attention - -=== Start-LogSession / Stop-LogSession - -Manages log session lifecycle with correlation IDs. - -[source,powershell] ----- -$sessionId = Start-LogSession -Component "VMFleet" -RunId "run-001" -# ... operations ... -Stop-LogSession -SessionId $sessionId ----- - -== StateManager Module - -=== New-RunState - -Creates a new run state file for tracking automation progress. - -[source,powershell] ----- -New-RunState [-RunId] [-Phases ] ----- - -=== Update-RunPhase - -Updates the status of a specific phase in the run state. - -[source,powershell] ----- -Update-RunPhase [-RunId] [-Phase] [-Status] [-Details ] ----- - -.Phase Statuses -* `pending` — Not yet started -* `running` — Currently executing -* `completed` — Successfully finished -* `failed` — Encountered an error -* `skipped` — Intentionally bypassed - -=== Test-PhaseCompleted - -Checks if a phase has already completed (for resume support). - -[source,powershell] ----- -Test-PhaseCompleted [-RunId] [-Phase] ----- - -== CredentialManager Module - -=== Get-ManagedCredential - -Retrieves credentials from the configured source. - -[source,powershell] ----- -Get-ManagedCredential [-Name] [-Source ] [-VaultConfig ] ----- - -.Credential Sources -* `KeyVault` — Retrieve from Azure Key Vault -* `Interactive` — Prompt user with `Get-Credential` -* `Parameter` — Expect credential passed as parameter - -== MonitoringManager Module - -=== Start-MetricCollection - -Begins background metric collection for the specified categories. - -[source,powershell] ----- -Start-MetricCollection [-Categories ] [-SampleIntervalSeconds ] [-OutputPath ] ----- - -=== Stop-MetricCollection - -Stops background metric collection and finalizes output files. - -[source,powershell] ----- -Stop-MetricCollection [-CollectionId] ----- - -== ReportGenerator Module - -=== New-TestReport - -Generates test reports in the specified formats. - -[source,powershell] ----- -New-TestReport [-RunId] [-ResultsPath ] [-OutputPath ] - [-Formats ] [-IncludeMetrics] [-ClusterConfig ] ----- diff --git a/docs/_archived_adoc/reference/glossary.adoc b/docs/_archived_adoc/reference/glossary.adoc deleted file mode 100644 index 3a4c9bb..0000000 --- a/docs/_archived_adoc/reference/glossary.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= Glossary -:toc: left -:toclevels: 2 -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Reference-7F8C8D?style=flat-square[Category: Reference] - -[glossary] -Azure Local:: Microsoft's on-premises hyperconverged infrastructure (HCI) solution, formerly Azure Stack HCI. Runs Azure services on-premises. - -Cluster Shared Volume (CSV):: A shared storage volume accessible from all nodes in a Windows Server Failover Cluster. Used by VMFleet to store fleet VMs. - -Collect Volume:: A dedicated ReFS volume (200GB+) used by VMFleet to aggregate DiskSpd results from all fleet VMs. - -DiskSpd:: Microsoft's open-source storage performance benchmarking tool. VMFleet uses DiskSpd as the I/O workload generator inside fleet VMs. - -fio (Flexible I/O Tester):: A cross-platform storage I/O benchmarking tool with extensive workload customization. Primarily used on Linux. - -Fleet VM:: A lightweight virtual machine deployed by VMFleet as part of the testing fleet. Runs Windows Server Core with DiskSpd. - -HammerDB:: An open-source database benchmarking tool supporting TPC-C (OLTP) and TPC-H (OLAP) workloads against SQL Server and other databases. - -IOPS:: Input/Output Operations Per Second. A key storage performance metric measuring the number of read/write operations the storage can handle. - -iPerf3:: A network performance measurement tool for testing bandwidth, jitter, and packet loss over TCP, UDP, and SCTP. - -JSON-lines:: A text format where each line is a valid JSON object. Used for structured logging in this framework. - -Latency:: The time delay between issuing an I/O request and receiving the response. Measured in milliseconds. Lower is better. - -Master Environment File:: The `master-environment.yml` file containing all configuration variables tagged by solution. - -PerfMon:: Windows Performance Monitor. A built-in tool for collecting performance counter data from Windows systems. - -RDMA (Remote Direct Memory Access):: A technology enabling direct memory access from one computer to another without involving the operating system. Used for high-speed storage networking in Azure Local. - -SMB Direct:: An enhancement to the SMB protocol that uses RDMA network adapters for high-throughput, low-latency data transfer. - -Solution JSON:: A generated JSON file containing only the variables relevant to a specific testing solution (e.g., `vmfleet.json`). - -Storage Spaces Direct (S2D):: Microsoft's software-defined storage solution that pools local drives across cluster nodes into a highly available, scalable storage system. - -stress-ng:: A stress testing tool with 370+ stress tests for CPU, memory, cache, filesystem, and other system components. - -Throughput:: The amount of data transferred per unit of time. Measured in MB/s or GB/s. Higher is better. - -VMFleet:: A storage load generator that deploys a fleet of VMs running DiskSpd workloads across a Hyper-V cluster to stress-test Storage Spaces Direct. - -Workload Profile:: A predefined set of I/O parameters (block size, read/write ratio, random/sequential ratio, etc.) that defines a specific test scenario. diff --git a/docs/_archived_adoc/reference/variable-reference.adoc b/docs/_archived_adoc/reference/variable-reference.adoc deleted file mode 100644 index 915ade5..0000000 --- a/docs/_archived_adoc/reference/variable-reference.adoc +++ /dev/null @@ -1,274 +0,0 @@ -= Variable Reference -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Reference-7F8C8D?style=flat-square[Category: Reference] - -This document provides a complete catalog of all variables defined in `master-environment.yml`. - -== Cluster Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `cluster_name` -| string -| Yes -| (none) -| Azure Local cluster name - -| `cluster_domain` -| string -| Yes -| (none) -| Active Directory domain for the cluster - -| `cluster_nodes` -| array -| Yes -| (none) -| List of cluster node hostnames - -| `csv_path` -| string -| Yes -| (none) -| Path to the Cluster Shared Volume for VM storage - -| `collect_volume_path` -| string -| Yes -| (none) -| Path to the VMFleet Collect volume (ReFS, 200GB+) - -| `base_vhd_path` -| string -| Yes -| (none) -| Path to the Windows Server Core base VHDX -|=== - -== VMFleet Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `vm_count_per_node` -| integer -| Yes -| 10 -| Number of fleet VMs to create per cluster node - -| `vm_vcpu_count` -| integer -| Yes -| 2 -| Number of virtual CPUs per fleet VM - -| `vm_memory_gb` -| integer -| Yes -| 2 -| Memory allocation (GB) per fleet VM - -| `test_duration_seconds` -| integer -| Yes -| 300 -| Duration of each test pass in seconds - -| `warmup_seconds` -| integer -| No -| 60 -| Warmup period before measurement begins - -| `vmfleet_admin_username` -| string -| Yes -| (none) -| Administrator username for fleet VMs (sensitive) - -| `vmfleet_admin_password` -| string -| Yes -| (none) -| Administrator password for fleet VMs (sensitive — use Key Vault) -|=== - -== Monitoring Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `monitoring_enabled` -| boolean -| No -| true -| Enable metric collection during tests - -| `sample_interval_seconds` -| integer -| No -| 5 -| Metric sampling interval - -| `push_to_azure_monitor` -| boolean -| No -| false -| Send metrics to Azure Monitor / Log Analytics - -| `log_analytics_workspace_id` -| string -| No -| (none) -| Azure Log Analytics workspace ID (required if push enabled) - -| `log_analytics_shared_key` -| string -| No -| (none) -| Log Analytics shared key (sensitive — use Key Vault) -|=== - -== Reporting Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `report_formats` -| array -| No -| ["PDF"] -| Report output formats: PDF, DOCX, XLSX - -| `report_title` -| string -| No -| "Azure Local Load Test Report" -| Title on report cover page - -| `report_author` -| string -| No -| "Azure Local Load Tools" -| Author attribution on reports - -| `include_raw_data` -| boolean -| No -| true -| Include raw metrics in Excel report -|=== - -== fio Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `fio_runtime_seconds` -| integer -| No -| 300 -| Duration of fio test execution - -| `fio_block_size` -| string -| No -| "4k" -| Default block size for fio jobs - -| `fio_io_engine` -| string -| No -| "libaio" -| I/O engine for fio (libaio, io_uring, etc.) -|=== - -== iPerf Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `iperf_duration_seconds` -| integer -| No -| 30 -| Duration of each iPerf test - -| `iperf_parallel_streams` -| integer -| No -| 4 -| Number of parallel streams per iPerf test - -| `iperf_protocol` -| string -| No -| "TCP" -| Protocol: TCP or UDP -|=== - -== HammerDB Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `hammerdb_db_type` -| string -| No -| "mssql" -| Target database: mssql, postgresql, mysql - -| `hammerdb_warehouse_count` -| integer -| No -| 10 -| Number of TPC-C warehouses - -| `hammerdb_virtual_users` -| integer -| No -| 4 -| Number of virtual users for workload generation -|=== - -== stress-ng Variables - -[cols="2,1,1,1,3"] -|=== -| Variable | Type | Required | Default | Description - -| `stress_ng_timeout` -| string -| No -| "5m" -| Stress test duration - -| `stress_ng_stressors` -| array -| No -| ["cpu", "vm", "hdd"] -| Stressor classes to execute - -| `stress_ng_workers` -| integer -| No -| 0 -| Number of workers per stressor (0 = auto-detect CPU count) -|=== diff --git a/docs/_archived_adoc/standards/asciidoc-reference.adoc b/docs/_archived_adoc/standards/asciidoc-reference.adoc deleted file mode 100644 index a9d5511..0000000 --- a/docs/_archived_adoc/standards/asciidoc-reference.adoc +++ /dev/null @@ -1,1172 +0,0 @@ -= AsciiDoc Syntax Reference — Azure Local Load Tools -Kristopher Turner -v1.0, 2026-02-13 - -:description: Quick-reference guide for AsciiDoc syntax used in the Azure Local Load Tools project. Covers formatting, blocks, tables, admonitions, attributes, and cross-references. -:keywords: asciidoc, syntax, reference, cheat-sheet, formatting, documentation, azure-local -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -[abstract] -A project-tailored AsciiDoc syntax reference for contributors to the Azure Local Load Tools repository. -Every example is taken from or modeled after actual project files. -For the full AsciiDoc specification, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Asciidoctor Quick Reference] and https://asciidoc.org/[asciidoc.org]. - -[discrete] -== Quick Navigation - -* <> — Title, author, revision, attributes -* <> — Bold, italic, monospace, highlight -* <> — Normal, literal, lead, hard breaks -* <> — Levels, anchors, discrete headings -* <> — Unordered, ordered, checklists, description lists -* <> — Source blocks, callouts, inline code -* <> — TIP, NOTE, WARNING, CAUTION, IMPORTANT -* <> — Basic tables, column specs, AsciiDoc content in cells -* <> — URLs, anchors, xref, inter-document links -* <> — Block images, inline images, captions -* <> — Including other files, tagged regions, lines -* <> — Declaring and using document attributes -* <> — Sidebars, examples, quotes, open blocks, passthroughs -* <> — UI interaction documentation -* <> — Line comments, block comments, thematic and page breaks - -''' - -[[document-header]] -== Document Header - -The document header contains the title, author, revision, and attribute entries. It must not contain empty lines. - -=== Minimal Header (Chapter Files) - -Chapter files that are included into `main.adoc` need no header — they start at heading level `==`: - -[source,asciidoc] ----- -== Chapter Title - -Content starts here. ----- - -=== Standard Header (README Files) - -[source,asciidoc] ----- -= Azure Local Load Tools -:toc: macro -:toclevels: 2 -:icons: font - -Description paragraph. - -toc::[] ----- - -=== Full Header (Standards Documents) - -[source,asciidoc] ----- -= Document Title — Subtitle -Kristopher Turner -v1.0, 2026-02-13 - -:description: Brief description for metadata. -:keywords: comma, separated, keywords -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ ----- - -=== Book Header (`main.adoc`) - -[source,asciidoc] ----- -= Book Title -:author: AzureLocal -:email: azurelocal@microsoft.com -:revdate: 2026-02-13 -:revnumber: 0.1.0 -:doctype: book -:toc: left -:toclevels: 3 -:sectnums: -:sectnumlevels: 3 -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: images - -// Custom attributes (reusable variables) -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools ----- - -=== Common Attributes Reference - -[cols="2,1,3"] -|=== -| Attribute | Values | Effect - -| `:toc:` -| `left`, `right`, `macro`, `auto`, `preamble` -| Table of contents placement - -| `:toclevels:` -| `1`–`5` -| Depth of headings shown in TOC - -| `:sectnums:` -| (flag) -| Enables section numbering (1, 1.1, 1.2â€Ļ) - -| `:icons:` -| `font`, `image` -| Use Font Awesome icons for admonitions - -| `:source-highlighter:` -| `rouge`, `highlight.js`, `coderay` -| Syntax highlighting engine - -| `:experimental:` -| (flag) -| Enables `kbd:[]`, `btn:[]`, `menu:[]` macros - -| `:imagesdir:` -| path -| Base directory for image references - -| `:tip-caption:` etc. -| text/emoji -| Custom admonition label text -|=== - -[[text-formatting]] -== Text Formatting - -=== Inline Styles - -[cols="2,3,2"] -|=== -| Style | Syntax | Renders As - -| Bold -| `+*bold text*+` -| *bold text* - -| Italic -| `+_italic text_+` -| _italic text_ - -| Monospace -| `++`monospace`++` -| `monospace` - -| Bold italic -| `+*_bold italic_*+` -| *_bold italic_* - -| Bold monospace -| `++*`bold mono`*++` -| *`bold mono`* - -| Highlight -| `+#highlighted#+` -| #highlighted# - -| Underline -| `+[.underline]#underlined#+` -| [.underline]#underlined# - -| Strikethrough -| `+[.line-through]#struck#+` -| [.line-through]#struck# - -| Superscript -| `+^super^+` -| ^super^ - -| Subscript -| `+~sub~+` -| ~sub~ -|=== - -=== Unconstrained Formatting - -Use double marks when formatting is inside a word: - -[source,asciidoc] ----- -**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD) - -fan__freakin__tastic ----- - -Renders as: **C**reate, **R**ead, **U**pdate, and **D**elete (CRUD) - -[[paragraphs-and-line-breaks]] -== Paragraphs and Line Breaks - -=== Normal Paragraph - -Just write text. One or more consecutive lines form a paragraph. Separate paragraphs with a blank line: - -[source,asciidoc] ----- -This is the first paragraph. - -This is the second paragraph. ----- - -=== Hard Line Breaks - -Force a line break with `+` at the end of a line: - -[source,asciidoc] ----- -First line, + -second line, + -third line. ----- - -Or apply to an entire block: - -[source,asciidoc] ----- -[%hardbreaks] -Line one. -Line two. -Line three. ----- - -=== Literal Paragraph - -Indent by one or more spaces to create a literal (preformatted) paragraph: - -[source,asciidoc] ----- - This is a literal paragraph. - Spaces and line breaks are preserved. - It renders in a monospace font. ----- - -=== Lead Paragraph - -[source,asciidoc] ----- -[.lead] -This paragraph will render in a larger font. ----- - -[[section-headings]] -== Section Headings - -=== Heading Levels - -[source,asciidoc] ------ -= Document Title (Level 0) <1> - -== Level 1 Section <2> - -=== Level 2 Section - -==== Level 3 Section - -===== Level 4 Section ------ -<1> Level 0 — only one per document (the title), unless `:doctype: book` -<2> Level 1 — top-level section in chapters - -=== Explicit Anchors - -Add a stable anchor ID above a heading for reliable cross-references: - -[source,asciidoc] ----- -[[deploy-phase]] -== Deploy VMFleet - -Reference it elsewhere: see <>. ----- - -WARNING: Auto-generated anchors break when headings are renamed. Always use explicit `[[anchor]]` IDs for sections referenced from other documents. - -=== Discrete Headings - -A discrete heading looks like a heading but doesn't become a section (excluded from TOC and numbering): - -[source,asciidoc] ----- -[discrete] -== Quick Navigation - -* <> — Description -* <> — Description ----- - -TIP: We use discrete headings for the Quick Navigation block at the top of standards documents. - -[[lists]] -== Lists - -=== Unordered Lists - -[source,asciidoc] ----- -* Item one -* Item two -** Nested item -*** Deeper nested -* Item three ----- - -Renders as: - -* Item one -* Item two -** Nested item -*** Deeper nested -* Item three - -IMPORTANT: Always use `*` for unordered lists in this project. Do not use `-`. - -=== Ordered Lists - -[source,asciidoc] ----- -. First step -. Second step -.. Sub-step A -.. Sub-step B -. Third step ----- - -Renders as: - -. First step -. Second step -.. Sub-step A -.. Sub-step B -. Third step - -=== Checklists - -[source,asciidoc] ----- -* [*] Completed task -* [x] Also completed -* [ ] Incomplete task -* Normal list item ----- - -=== Description Lists - -[source,asciidoc] ----- -Term 1:: Definition on the same line. -Term 2:: -Definition on the next line. ----- - -Renders as: - -Term 1:: Definition on the same line. -Term 2:: -Definition on the next line. - -=== Complex List Content - -Attach additional content to a list item using the list continuation (`+`): - -[source,asciidoc] ------ -* First item with a paragraph. -+ -And a second paragraph attached to it. -+ -[source,powershell] ----- -Get-Process # Code block attached to list item ----- - -* Second item. ------ - -[[code-blocks]] -== Code Blocks - -=== Source Block with Language - -Always specify the language for syntax highlighting: - -[source,asciidoc] ------ -[source,powershell] ----- -$config = Import-MasterConfig -$config | Where-Object { $_.solutions -contains 'vmfleet' } ----- ------ - -=== Source Block with Title - -[source,asciidoc] ------ -.Install-VMFleet.ps1 — Module installation -[source,powershell] ----- -Install-Module -Name VMFleet -RequiredVersion $vmfleetVer -Force ----- ------ - -=== Callouts - -Annotate lines in a code block with numbered callouts: - -[source,asciidoc] ------ -[source,powershell] ----- -$config = Import-MasterConfig # \<1> -$filtered = Get-SolutionConfig -Solution 'VMFleet' # \<2> -Export-SolutionConfig -OutputPath $outputPath # \<3> ----- -\<1> Loads the master YAML into memory -\<2> Filters to VMFleet-tagged variables -\<3> Writes the solution JSON to disk ------ - -NOTE: The callout comment style depends on the language — `# ` for PowerShell/YAML, `// ` for JSON/C-style languages, `` for XML. - -=== Inline Monospace - -Reference code elements inline with backticks: - -[source,asciidoc] ----- -Set `$ErrorActionPreference` to `'Stop'` at the top of every script. - -Run the `Install-VMFleet.ps1` script to install the module. ----- - -=== Literal Block - -A literal block preserves whitespace and uses monospace rendering, but has no syntax highlighting: - -[source,asciidoc] ------ -.... -logs/ -├── vmfleet/ -├── fio/ -└── pipeline/ -.... ------ - -Renders as: - -.... -logs/ -├── vmfleet/ -├── fio/ -└── pipeline/ -.... - -Alternatively, use a listing block with `----` delimiters, or prefix a paragraph with a single space for inline literal paragraphs. - -[[admonitions]] -== Admonitions - -=== Inline Admonitions - -[source,asciidoc] ----- -TIP: Run the linter before committing. - -NOTE: This applies to all PowerShell modules. - -WARNING: This will delete all fleet VMs. - -CAUTION: Risk of data loss if the volume is not backed up. - -IMPORTANT: Never commit credentials to this file. ----- - -Renders as: - -TIP: Run the linter before committing. - -NOTE: This applies to all PowerShell modules. - -WARNING: This will delete all fleet VMs. - -CAUTION: Risk of data loss if the volume is not backed up. - -IMPORTANT: Never commit credentials to this file. - -=== Block Admonitions - -For multi-line admonitions, use the block form: - -[source,asciidoc] ----- -[WARNING] -==== -This operation is destructive and cannot be undone. - -Steps to take: - -. Back up the cluster -. Verify the backup -. Proceed with the operation -==== ----- - -=== When to Use Each Type - -[cols="1,1,3"] -|=== -| Type | Icon | Purpose - -| `TIP` -| 💡 -| Helpful suggestions, shortcuts, best practices - -| `NOTE` -| ℹī¸ -| Extra context, clarifications, "good to know" - -| `WARNING` -| ⚠ī¸ -| Potential problems if instructions are not followed - -| `CAUTION` -| đŸ”Ĩ -| Risk of data loss, security issues, breaking changes - -| `IMPORTANT` -| ❗ -| Critical information that must not be skipped -|=== - -[[tables]] -== Tables - -=== Basic Table with Header - -[source,asciidoc] ----- -[cols="1,2,3"] -|=== -| Name | Type | Description - -| `cluster_name` -| string -| Azure Local cluster name - -| `vm_count_per_node` -| integer -| Fleet VMs created per cluster node -|=== ----- - -Renders as: - -[cols="1,2,3"] -|=== -| Name | Type | Description - -| `cluster_name` -| string -| Azure Local cluster name - -| `vm_count_per_node` -| integer -| Fleet VMs created per cluster node -|=== - -=== Column Width Specifiers - -The `cols` attribute controls column widths as ratios: - -[source,asciidoc] ----- -[cols="1,1,2"] <1> -[cols="2,3,5"] <2> -[cols="1,1,1"] <3> -[cols="3*"] <4> ----- -<1> Three columns: 25%, 25%, 50% -<2> Three columns: 20%, 30%, 50% -<3> Three equal columns -<4> Shorthand: three equal columns (same as `1,1,1`) - -=== Column Alignment and Style - -[cols="1,3,2"] -|=== -| Specifier | Meaning | Example - -| `<` -| Left-align -| `[cols="<1,>2"]` - -| `>` -| Right-align -| Numbers, sizes - -| `^` -| Center-align -| Status columns - -| `a` -| AsciiDoc content -| `[cols="1,2a"]` — allows lists, code, etc. inside cells - -| `e` -| Emphasis (italic) -| `[cols="e,m"]` - -| `m` -| Monospace -| Code values - -| `s` -| Strong (bold) -| Headers/labels -|=== - -=== AsciiDoc Content in Cells - -Use the `a` column type to write rich content inside table cells: - -[source,asciidoc] ----- -[cols="1,2a"] -|=== -| Feature | Details - -| Logging -| -Supports multiple levels: - -* `DEBUG` -* `INFO` -* `WARNING` -* `ERROR` -* `CRITICAL` -|=== ----- - -=== Table from CSV Data - -[source,asciidoc] ----- -[%header,format=csv] -|=== -Tool,Type,Status -VMFleet,Storage I/O,Implemented -fio,Storage I/O,Planned -|=== ----- - -[[links-and-cross-references]] -== Links and Cross-References - -=== External URLs - -[source,asciidoc] ----- -https://github.com/AzureLocal/azurelocal-loadtools[Azure Local Load Tools] - -https://docs.microsoft.com/en-us/azure-stack/hci/[Azure Stack HCI docs] ----- - -URLs with a scheme (`https://`, `http://`) are automatically converted to links. Add `[link text]` to customize the displayed text. - -=== Internal Cross-References - -Link to a section within the same document: - -[source,asciidoc] ----- -See <> for deployment instructions. - -See <> for custom link text. ----- - -=== Inter-Document Cross-References - -Link to a section in a different file using `xref`: - -[source,asciidoc] ----- -See xref:chapters/06-vmfleet-guide.adoc#deploy-phase[the deployment phase]. - -See xref:standards/scripting-standards.adoc[Scripting Standards] for full details. ----- - -=== Inline Anchors - -Create a referenceable anchor anywhere in text: - -[source,asciidoc] ----- -[[my-anchor]]This text is now referenceable. - -[#inline-anchor]#This phrase# is also referenceable. ----- - -=== Link to a Relative File - -[source,asciidoc] ----- -link:../../config/clusters/example-cluster.yml[Example cluster config] ----- - -[[images-and-diagrams]] -== Images and Diagrams - -=== Block Image - -[source,asciidoc] ----- -image::vmfleet-pipeline-workflow.png[VMFleet Pipeline Workflow, width=600] ----- - -* Store images in `docs/images/` -* The `:imagesdir:` attribute resolves the path automatically -* Always include alt text (first positional parameter) -* Specify `width` for large images - -=== Block Image with Caption - -[source,asciidoc] ----- -.Figure 1: VMFleet Pipeline Workflow -image::vmfleet-pipeline-workflow.png[VMFleet Pipeline Workflow, width=600] ----- - -The `.Title` line above the image becomes the figure caption. - -=== Inline Image - -[source,asciidoc] ----- -Click image:play-button.png[Play, 16, 16] to start the test. ----- - -NOTE: Block images use `image::` (two colons). Inline images use `image:` (one colon). - -[[includes]] -== Includes - -=== Include an Entire File - -[source,asciidoc] ----- -\include::chapters/01-introduction.adoc[] ----- - -Used in `main.adoc` to assemble the book from chapters. - -=== Include by Tagged Region - -In the source file, mark regions with tags: - -[source,powershell] ----- -# tag::bootstrap[] -. (Join-Path $ProjectRoot 'src\core\powershell\helpers\Common-Functions.ps1') -Import-Module (Join-Path $ProjectRoot 'src\core\powershell\modules\Logger\Logger.psm1') -Force -# end::bootstrap[] ----- - -Then include only that region: - -[source,asciidoc] ------ -[source,powershell] ----- -\include::../../src/solutions/vmfleet/Invoke-VMFleetPipeline.ps1[tag=bootstrap] ----- ------ - -=== Include by Line Range - -[source,asciidoc] ----- -\include::../../src/solutions/vmfleet/Invoke-VMFleetPipeline.ps1[lines=1..10] ----- - -TIP: Use tagged regions instead of line numbers when possible — line numbers break when the source file changes. - -[[attributes-and-variables]] -== Attributes and Variables - -=== Declaring Attributes - -[source,asciidoc] ----- -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools -:vmfleet-version: 2.1.0.0 ----- - -=== Using Attributes - -Reference with curly braces: - -[source,asciidoc] ----- -The {project-name} is hosted at {project-repo}. - -Requires VMFleet version {vmfleet-version} or later. ----- - -Renders as: "The Azure Local Load Testing Framework is hosted at https://github.com/AzureLocal/azurelocal-loadtools." - -=== Conditional Attributes - -[source,asciidoc] ----- -ifdef::env-github[] -TIP: You are viewing this on GitHub. -endif::[] - -ifndef::backend-pdf[] -NOTE: This section is hidden in PDF output. -endif::[] ----- - -=== Built-in Attributes - -[cols="2,3"] -|=== -| Attribute | Value - -| `\{docname}` -| Document file name (without extension) - -| `\{docdate}` -| Document last-modified date - -| `\{revnumber}` -| Revision number from header - -| `\{author}` -| Author from header - -| `\{nbsp}` -| Non-breaking space - -| `\{empty}` -| Empty string (useful for resetting) - -| `\{zwsp}` -| Zero-width space -|=== - -[[delimited-blocks]] -== Delimited Blocks - -=== Sidebar - -[source,asciidoc] ----- -.Optional Sidebar Title -**** -Sidebars are used to visually separate supplemental content. -They render with a distinct background or border. -**** ----- - -=== Example Block - -[source,asciidoc] ----- -==== -This is an example block. - -It can contain compound content: - -* List items -* More items - -And additional paragraphs. -==== ----- - -=== Blockquote - -[source,asciidoc] ----- -[quote, Microsoft Documentation] -____ -Azure Local is a hyperconverged infrastructure solution -that runs on validated hardware. -____ ----- - -Or the shorthand form: - -[source,asciidoc] ----- -"Azure Local is the future of hybrid cloud infrastructure." --- Microsoft, Azure Local Documentation ----- - -=== Open Block - -An anonymous container that can masquerade as any block type: - -[source,asciidoc] ----- --- -An open block can hold any content. --- - -[source] --- -Or act as a source block. --- ----- - -=== Passthrough Block - -Pass raw HTML or other content through without AsciiDoc processing: - -[source,asciidoc] ----- -++++ -
- Status: Active -
-++++ ----- - -[[keyboard-button-and-menu-macros]] -== Keyboard, Button, and Menu Macros - -NOTE: These macros require `:experimental:` in the document header. - -=== Keyboard Shortcuts - -[source,asciidoc] ----- -Press kbd:[Ctrl+C] to stop the running process. - -Press kbd:[F11] to toggle fullscreen. - -Press kbd:[Ctrl+Shift+P] to open the command palette. ----- - -Renders as: Press kbd:[Ctrl+C] to stop the running process. - -=== Button Macro - -[source,asciidoc] ----- -Click btn:[OK] to confirm. - -Press btn:[Cancel] to abort. ----- - -=== Menu Macro - -[source,asciidoc] ----- -Select menu:File[Save] to save the document. - -Navigate to menu:View[Zoom > Reset] to reset zoom. ----- - -[[comments-and-breaks]] -== Comments and Breaks - -=== Line Comment - -[source,asciidoc] ----- -// This line is a comment — it won't appear in the output. ----- - -=== Block Comment - -[source,asciidoc] ----- -//// -Everything in here is a comment. -Multiple lines are supported. -Won't appear in any output format. -//// ----- - -=== Thematic Break (Horizontal Rule) - -[source,asciidoc] ----- -Content above. - -''' - -Content below. ----- - -Renders as a horizontal line separating the content. - -=== Page Break - -Force a page break (useful for PDF output): - -[source,asciidoc] ----- -<<< ----- - -== Text Replacements - -AsciiDoc automatically converts certain character sequences: - -[cols="2,1,1"] -|=== -| Input | Output | Unicode - -| `+(C)+` -| (C) -| © Copyright - -| `+(R)+` -| (R) -| ® Registered - -| `+(TM)+` -| (TM) -| ™ Trademark - -| `+--+` (between words) -| — -| Em dash - -| `+...+` -| ... -| Ellipsis - -| `+->+` -| -> -| Right arrow - -| `+=>+` -| => -| Double right arrow - -| `+<-+` -| <- -| Left arrow -|=== - -== Escaping - -To prevent AsciiDoc from interpreting special characters, use a backslash: - -[source,asciidoc] ----- -\*Not bold* - -\https://example.org is not an active link. - -In /items/\{id}, the attribute isn't replaced. ----- - -For more complex escaping, use a passthrough: - -[source,asciidoc] ----- -pass:[*not bold*] - -+/user/{id}+ <1> ----- -<1> Single plus passthrough — prevents substitution but still escapes special HTML characters - -== Quick Cheat Sheet - -[cols="3,4"] -|=== -| Task | Syntax - -| Bold -| `+*text*+` - -| Italic -| `+_text_+` - -| Monospace -| `++`text`++` - -| Heading L2 -| `+== Heading+` - -| Unordered list -| `+* Item+` - -| Ordered list -| `+. Item+` - -| Link -| `+https://url[text]+` - -| Cross-ref -| `+<>+` - -| Code block -| `+[source,lang]+ then +----+` - -| Image -| `+image::file.png[alt]+` - -| Admonition -| `+TIP: text+` - -| Include -| `+include::file.adoc[]+` - -| Attribute -| `+:name: value+` / `+{name}+` - -| Table -| `+\|===+` / `+\| cell+` - -| Keyboard -| `+kbd:[Ctrl+S]+` - -| Comment -| `+// comment+` - -| Horizontal rule -| `+'''+` - -| Page break -| `+<<<+` -|=== \ No newline at end of file diff --git a/docs/_archived_adoc/standards/badge-standards.adoc b/docs/_archived_adoc/standards/badge-standards.adoc deleted file mode 100644 index 61709ef..0000000 --- a/docs/_archived_adoc/standards/badge-standards.adoc +++ /dev/null @@ -1,485 +0,0 @@ -= Badge Standards — Azure Local Load Tools -Kristopher Turner -v1.0, 2026-02-16 - -:description: Standards for shields.io badges used across all documents in the Azure Local Load Tools repository. -:keywords: badges, shields, standards, metadata, documentation -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] -image:https://img.shields.io/badge/Updated-2026--02--16-lightgrey?style=flat-square[Updated: 2026-02-16] - -[abstract] -This document defines the standard badges used across all `.adoc` files in the Azure Local Load Tools repository. -Badges provide at-a-glance metadata — platform, tool, status, audience, and version — rendered as shields.io image macros. - -[discrete] -== Quick Navigation - -* <> — AsciiDoc syntax for rendering badges -* <> — Complete list of all project badges -* <> — Where badges go in each document tier -* <> — How to create new badges - -''' - -[[badge-syntax]] -== Badge Syntax - -Badges use the shields.io static badge service rendered as AsciiDoc inline image macros: - -[source,asciidoc] ----- -image:https://img.shields.io/badge/{LABEL}-{VALUE}-{COLOR}?style=flat-square&logo={LOGO}[{ALT TEXT}] ----- - -.URL Encoding Rules -* Spaces → `%20` -* Hyphens in values → `--` (double dash) -* Underscores → `__` (double underscore) - -.Style -All badges in this project use `?style=flat-square` for visual consistency. - -[[badge-catalog]] -== Badge Catalog - -=== Platform & Project Badges - -Used on root README and `docs/index.adoc`. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Platform** -| `image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform: Azure Local]` -| Platform: Azure Local - -| **PowerShell Version** -| `image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell 7.2+]` -| PowerShell 7.2+ - -| **License** -| `image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License: MIT]` -| License: MIT - -| **Project Status** -| `image:https://img.shields.io/badge/Status-Pre--Release-orange?style=flat-square[Status: Pre-Release]` -| Status: Pre-Release - -| **Docs Hub** -| `image:https://img.shields.io/badge/Docs-index.adoc-blue?style=flat-square&logo=readthedocs[Docs]` -| Docs: index.adoc -|=== - -=== Tool Badges - -Identify which load testing tool a document covers. Used on tool guide pages and tool-specific READMEs. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **VMFleet** -| `image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet]` -| Tool: VMFleet - -| **fio** -| `image:https://img.shields.io/badge/Tool-fio-6C3483?style=flat-square[Tool: fio]` -| Tool: fio - -| **iPerf3** -| `image:https://img.shields.io/badge/Tool-iPerf3-1ABC9C?style=flat-square[Tool: iPerf3]` -| Tool: iPerf3 - -| **HammerDB** -| `image:https://img.shields.io/badge/Tool-HammerDB-E74C3C?style=flat-square[Tool: HammerDB]` -| Tool: HammerDB - -| **stress-ng** -| `image:https://img.shields.io/badge/Tool-stress--ng-F39C12?style=flat-square[Tool: stress-ng]` -| Tool: stress-ng -|=== - -=== Version Badges - -Show the version of a tool or component. Used on tool overview pages. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **VMFleet Version** -| `image:https://img.shields.io/badge/VMFleet-2.1.0.0-blue?style=flat-square[VMFleet 2.1.0.0]` -| VMFleet 2.1.0.0 - -| **DiskSpd Version** -| `image:https://img.shields.io/badge/DiskSpd-2.2-blue?style=flat-square[DiskSpd 2.2]` -| DiskSpd 2.2 - -| **Ansible Version** -| `image:https://img.shields.io/badge/Ansible-2.14%2B-EE0000?style=flat-square&logo=ansible[Ansible 2.14+]` -| Ansible 2.14+ -|=== - -=== Implementation Status Badges - -Indicate whether a tool or feature is implemented. Used on tool overview pages and READMEs. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Fully Implemented** -| `image:https://img.shields.io/badge/Status-Implemented-brightgreen?style=flat-square[Status: Implemented]` -| Status: Implemented - -| **In Progress** -| `image:https://img.shields.io/badge/Status-In%20Progress-yellow?style=flat-square[Status: In Progress]` -| Status: In Progress - -| **Placeholder** -| `image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder]` -| Status: Placeholder - -| **Deprecated** -| `image:https://img.shields.io/badge/Status-Deprecated-red?style=flat-square[Status: Deprecated]` -| Status: Deprecated -|=== - -=== Document Category Badges - -Identify the type/category of the document. Used on guide documents. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Getting Started** -| `image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started]` -| Category: Getting Started - -| **Tool Guide** -| `image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide]` -| Category: Tool Guide - -| **Operations** -| `image:https://img.shields.io/badge/Category-Operations-9B59B6?style=flat-square[Category: Operations]` -| Category: Operations - -| **Reference** -| `image:https://img.shields.io/badge/Category-Reference-7F8C8D?style=flat-square[Category: Reference]` -| Category: Reference - -| **Standards** -| `image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards]` -| Category: Standards -|=== - -=== Audience & Difficulty Badges - -Indicate the intended audience or skill level. Used on getting-started and tool guide pages. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Beginner** -| `image:https://img.shields.io/badge/Level-Beginner-brightgreen?style=flat-square[Level: Beginner]` -| Level: Beginner - -| **Intermediate** -| `image:https://img.shields.io/badge/Level-Intermediate-yellow?style=flat-square[Level: Intermediate]` -| Level: Intermediate - -| **Advanced** -| `image:https://img.shields.io/badge/Level-Advanced-red?style=flat-square[Level: Advanced]` -| Level: Advanced -|=== - -=== Audience Role Badges - -Identify the target reader role. Used on guide documents. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Infrastructure Engineer** -| `image:https://img.shields.io/badge/Audience-Infra%20Engineer-0078D4?style=flat-square[Audience: Infra Engineer]` -| Audience: Infra Engineer - -| **DevOps Engineer** -| `image:https://img.shields.io/badge/Audience-DevOps-5C2D91?style=flat-square[Audience: DevOps]` -| Audience: DevOps - -| **Storage Admin** -| `image:https://img.shields.io/badge/Audience-Storage%20Admin-2E86C1?style=flat-square[Audience: Storage Admin]` -| Audience: Storage Admin - -| **Network Engineer** -| `image:https://img.shields.io/badge/Audience-Network%20Engineer-1ABC9C?style=flat-square[Audience: Network Engineer]` -| Audience: Network Engineer - -| **DBA** -| `image:https://img.shields.io/badge/Audience-DBA-E74C3C?style=flat-square[Audience: DBA]` -| Audience: DBA -|=== - -=== OS & Environment Badges - -Indicate required operating system or execution environment. Used on prerequisites and tool pages. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Windows** -| `image:https://img.shields.io/badge/OS-Windows-0078D6?style=flat-square&logo=windows[OS: Windows]` -| OS: Windows - -| **Linux** -| `image:https://img.shields.io/badge/OS-Linux-FCC624?style=flat-square&logo=linux&logoColor=black[OS: Linux]` -| OS: Linux - -| **WSL2** -| `image:https://img.shields.io/badge/OS-WSL2-FCC624?style=flat-square&logo=linux&logoColor=black[OS: WSL2]` -| OS: WSL2 -|=== - -=== CI/CD Pipeline Badges - -Show pipeline status (link to actual workflows once created). Used on root README. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Build Docs** -| `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/build-docs.yml?style=flat-square&label=Docs%20Build[Docs Build]` -| Docs Build: passing - -| **Tests** -| `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/run-tests.yml?style=flat-square&label=Tests[Tests]` -| Tests: passing - -| **Lint** -| `image:https://img.shields.io/github/actions/workflow/status/AzureLocal/azurelocal-loadtools/lint.yml?style=flat-square&label=Lint[Lint]` -| Lint: passing -|=== - -NOTE: CI/CD badges use the GitHub Actions workflow status endpoint. These will show actual pass/fail status once the workflows exist. - -=== Last Updated Badge - -Show when a document was last modified. Used on any document where freshness matters. - -[cols="1,3,1"] -|=== -| Badge | AsciiDoc Syntax | Preview Text - -| **Last Updated** -| `image:https://img.shields.io/badge/Updated-2026--02--16-lightgrey?style=flat-square[Updated: 2026-02-16]` -| Updated: 2026-02-16 -|=== - -TIP: Update the date in the badge URL each time the document is modified. Use ISO 8601 format (`YYYY-MM-DD`) with double-dash escaping. - -[[badge-placement]] -== Badge Placement Rules - -=== Placement by Document Tier - -[cols="1,3"] -|=== -| Tier | Badge Placement - -| **Standards** -| After all attributes, before the `[abstract]` block. One badge per line. - -| **Guides** -| After all attributes, before the first content paragraph. One badge per line. - -| **READMEs** -| After all attributes, before the first content paragraph. Badges on the same line (inline) separated by a space. -|=== - -=== Example: Guide with Badges - -[source,asciidoc] ----- -= VMFleet Deployment -:toc: left -:toclevels: 3 -... - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] -image:https://img.shields.io/badge/Status-Implemented-brightgreen?style=flat-square[Status: Implemented] - -This guide covers installing the VMFleet module... ----- - -=== Example: Standards with Badges - -[source,asciidoc] ----- -= Document Title — Subtitle -Kristopher Turner -v1.0, 2026-02-16 - -:description: ... -:toc: left -... - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -\[abstract] -One to three sentences. ----- - -=== Example: README with Badges - -[source,asciidoc] ----- -= Azure Local Load Tools -:toc: macro -:toclevels: 2 -:icons: font - -image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform] image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell] image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License] - -Comprehensive load testing framework... - -toc::[] ----- - -NOTE: In READMEs, placing badges on the same line (separated by spaces) renders them as an inline row. In guides and standards, one badge per line stacks vertically. - -=== Required Badges by Location - -[cols="2,3"] -|=== -| Document | Required Badges - -| Root `README.adoc` -| Platform, PowerShell Version, License, Project Status - -| `docs/index.adoc` -| Platform, Project Status - -| `docs/getting-started/*.adoc` -| Category (Getting Started) - -| `docs/tools/{tool}/overview.adoc` -| Tool, Status (Implemented/Placeholder), Version (if applicable) - -| `docs/tools/{tool}/*.adoc` (other) -| Tool, Category (Tool Guide) - -| `docs/operations/*.adoc` -| Category (Operations) - -| `docs/reference/*.adoc` -| Category (Reference) - -| `docs/standards/*.adoc` -| Category (Standards) - -| `src/solutions/*/README.md` -| Tool, Status -|=== - -TIP: Audience, Level, OS, and Last Updated badges are **optional** — add them when they provide meaningful context. - -[[custom-badges]] -== Creating Custom Badges - -To create a new badge not listed in the catalog: - -. Go to https://shields.io/badges/static-badge -. Set the label, value, and color -. Always use `?style=flat-square` for consistency -. Add `&logo={logo-name}` if an appropriate https://simpleicons.org[Simple Icons] logo exists -. Add the new badge to this standards document before using it in other files - -=== Color Palette - -Use these colors for consistency across the project: - -[cols="1,1,2"] -|=== -| Color | Hex | Usage - -| `0078D4` -| Microsoft Blue -| Platform, Azure-related, VMFleet - -| `5391FE` -| PowerShell Blue -| PowerShell version - -| `brightgreen` -| (shields default) -| Implemented, Beginner, positive status - -| `green` -| (shields default) -| License, Getting Started category - -| `yellow` -| (shields default) -| In Progress, Intermediate - -| `orange` -| (shields default) -| Pre-Release, Standards category - -| `red` -| (shields default) -| Deprecated, Advanced - -| `lightgrey` -| (shields default) -| Placeholder, Last Updated, neutral - -| `6C3483` -| Purple -| fio tool - -| `1ABC9C` -| Teal -| iPerf3 tool, Network Engineer - -| `E74C3C` -| Red -| HammerDB tool, DBA - -| `F39C12` -| Amber -| stress-ng tool - -| `3498DB` -| Blue -| Tool Guide category - -| `9B59B6` -| Violet -| Operations category - -| `7F8C8D` -| Grey -| Reference category -|=== diff --git a/docs/_archived_adoc/standards/documentation-standards.adoc b/docs/_archived_adoc/standards/documentation-standards.adoc deleted file mode 100644 index 3062f39..0000000 --- a/docs/_archived_adoc/standards/documentation-standards.adoc +++ /dev/null @@ -1,779 +0,0 @@ -= Documentation Standards — Azure Local Load Tools -Kristopher Turner -v1.0, 2026-02-13 - -:description: AsciiDoc documentation standards, templates, and formatting rules for all documents in the Azure Local Load Tools repository. -:keywords: asciidoc, documentation, standards, formatting, templates, azure-local, style-guide -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -[abstract] -This document defines the mandatory AsciiDoc documentation standards for all `.adoc` files in the Azure Local Load Tools repository. -It covers document types, required attributes, formatting conventions, and templates. -All documentation must conform to these standards before merging. - -[discrete] -== Quick Navigation - -* <> — Three tiers: Standards, Guides, READMEs -* <> — Required attributes per document type -* <> — Heading hierarchy, section numbering -* <> — Code blocks, tables, admonitions, links -* <> — Anchors, `xref`, inter-document links -* <> — Copy-paste templates for each document type -* <> — Where files go and how they are named - -''' - -== Document Types - -This project uses three distinct document tiers. **Every document is standalone** — viewable independently on GitHub, in VS Code, or rendered to PDF. - -[cols="1,2,2,2"] -|=== -| Tier | Purpose | Location | Examples - -| **Standards** -| Formal reference documents — rules and specifications -| `docs/standards/` -| This file, scripting-standards.adoc - -| **Guides** -| Standalone documentation — getting-started, tool guides, operations, reference -| `docs/getting-started/`, `docs/tools/*/`, `docs/operations/`, `docs/reference/` -| installation.adoc, tools/vmfleet/overview.adoc, ci-cd.adoc - -| **READMEs** -| Quick-start and overview pages — viewed on GitHub -| Root and `src/solutions/*/` -| README.adoc, src/solutions/vmfleet/README.md -|=== - -=== Tier Comparison - -[cols="2,1,1,1"] -|=== -| Feature | Standards | Guides | READMEs - -| `:toc:` placement -| `left` (sidebar) -| `left` (sidebar) -| `macro` (inline) - -| `:toclevels:` -| `4` (deep) -| `3` (standard) -| `2` (light) - -| `:sectnums:` -| Yes -| Yes -| No - -| Quick Navigation block -| Yes -| No -| No - -| Abstract block -| Yes -| No -| No - -| Admonition captions -| Emoji (💡 ℹī¸ ⚠ī¸) -| Font icons -| Font icons - -| Author / version line -| Yes -| No -| No - -| Badges -| Yes — after attributes, before `[abstract]` -| Yes — after attributes, before first content -| Yes — after attributes, inline on one line - -| Standalone rendering -| Yes — self-contained -| Yes — self-contained -| Yes — self-contained -|=== - -== Header Attribute Standards - -=== Standards Documents - -Full self-contained header with sidebar TOC, emoji admonitions, and abstract: - -[source,asciidoc] ----- -= Document Title — Subtitle -Kristopher Turner -v1.0, 2026-02-13 - -:description: Brief description for metadata. -:keywords: comma, separated, keywords -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -\[abstract] -One to three sentences describing the document's purpose and audience. - -\[discrete] -== Quick Navigation - -* <> — Brief description -* <> — Brief description - -''' ----- - -=== Guide Documents - -Standalone documents with their own sidebar TOC. Each guide has a level-1 title and includes project-wide attributes: - -[source,asciidoc] ----- -= Guide Title -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -Brief introduction to the topic. - -== First Section ----- - -NOTE: Replace the Category badge with the appropriate one for the document location (Tool Guide, Operations, Reference). See link:badge-standards.adoc[Badge Standards] for the full catalog. - -NOTE: Adjust `:imagesdir:` based on folder depth — `../images` for one level deep, `../../images` for two levels (e.g., `tools/vmfleet/`). - -TIP: Guides are also included into `main.adoc` for optional combined PDF builds. When included, the level-1 title is shifted by `leveloffset=+1`. - -=== README Documents - -GitHub-friendly inline TOC: - -[source,asciidoc] ----- -= Project or Solution Name -:toc: macro -:toclevels: 2 -:icons: font - -image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform] image:https://img.shields.io/badge/PowerShell-7.2%2B-5391FE?style=flat-square&logo=powershell[PowerShell] image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License] - -Brief one-paragraph description. - -toc::[] - -== First Section ----- - -TIP: The `:toc: macro` + `toc::[]` pattern places the table of contents exactly where you put the macro — ideal for GitHub rendering where sidebar TOCs are not supported. - -=== Book Document (`main.adoc` — Optional PDF Builder) - -`main.adoc` is retained as an optional combined PDF builder. It includes all standalone guides and is **not** the primary documentation entry point — `docs/index.adoc` is. - -[source,asciidoc] ----- -= Book Title -:author: AzureLocal -:email: azurelocal@microsoft.com -:revdate: 2026-02-13 -:revnumber: 0.1.0 -:doctype: book -:toc: left -:toclevels: 3 -:sectnums: -:sectnumlevels: 3 -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: images -:pdf-themesdir: themes -:pdf-theme: azurelocal-theme - -// Project-wide attributes (reusable variables) -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools ----- - -=== Documentation Hub (`docs/index.adoc`) - -`index.adoc` is the landing page with links to all documentation organized by category. It uses the same header pattern as guides. - -== Heading and Structure Rules - -=== Heading Levels - -[cols="1,2,3"] -|=== -| Level | Usage | Scope - -| `=` -| Document title -| Every standalone document (guides, standards, READMEs, `main.adoc`) - -| `==` -| Major sections -| Top-level sections within any document - -| `===` -| Subsections -| Detailed topic areas within a section - -| `====` -| Sub-subsections -| Granular detail, usually the deepest needed - -| `=====` -| Avoid -| If you need this depth, consider restructuring -|=== - -=== Section Anchors - -AsciiDoc auto-generates anchors from headings, but for cross-reference stability, use explicit anchors for any section you link to: - -[source,asciidoc] ----- -[[my-stable-anchor]] -== My Section Title ----- - -WARNING: Auto-generated anchors break when headings are renamed. Use explicit `[[anchor]]` IDs for any section referenced from other documents. - -=== Section Numbering - -* Standards documents: `:sectnums:` is **on** — sections show as 1, 1.1, 1.2, etc. -* READMEs: `:sectnums:` is **off** — no numbering for casual docs -* Chapters: Inherit from `main.adoc` (on by default) - -== Formatting Conventions - -=== Code Blocks - -Always specify the language for syntax highlighting: - -[source,asciidoc] ------ -[source,powershell] ----- -Get-Process | Where-Object { $_.CPU -gt 100 } ----- ------ - -Supported languages in this project: - -[cols="1,2"] -|=== -| Language | Usage - -| `powershell` -| All PowerShell scripts and examples - -| `yaml` -| Configuration files - -| `json` -| Solution configs, schema files - -| `xml` -| PerfMon counter definitions, event log queries - -| `bash` -| Ansible playbooks, Linux commands - -| `asciidoc` -| Documentation examples (like in this file) -|=== - -=== Code Callouts - -Use numbered callouts to annotate code: - -[source,asciidoc] ------ -[source,powershell] ----- -$config = Import-MasterConfig # \<1> -$filtered = $config | Where-Object { $_.solutions -contains 'vmfleet' } # \<2> ----- -\<1> Loads the master YAML and caches it -\<2> Filters to VMFleet-tagged variables only ------ - -TIP: Callouts make code examples self-documenting. Use them for any code block longer than three lines. - -=== Tables - -Use the AsciiDoc table syntax with explicit column specs: - -[source,asciidoc] ----- -[cols="1,2,3"] -|=== -| Column A | Column B | Column C - -| Data 1 -| Data 2 -| Data 3 -|=== ----- - -Rules for tables: - -* Always include `[cols="..."]` with relative widths -* First row is always the header row -* Put each cell on its own line for readability in source -* Use `a` column type for cells containing AsciiDoc markup: `[cols="1,2a"]` - -=== Admonitions - -Use admonition blocks for callouts. Each type has a specific purpose: - -[cols="1,1,3"] -|=== -| Type | Icon | When to Use - -| `TIP` -| 💡 -| Helpful suggestions, best practices, shortcuts - -| `NOTE` -| ℹī¸ -| Additional context, clarifications, "good to know" - -| `WARNING` -| ⚠ī¸ -| Potential problems if instructions are not followed - -| `CAUTION` -| đŸ”Ĩ -| Risk of data loss, security exposure, or breaking changes - -| `IMPORTANT` -| ❗ -| Critical information that must not be skipped -|=== - -Inline syntax: - -[source,asciidoc] ----- -TIP: Run the linter before committing. - -WARNING: This will delete all fleet VMs. ----- - -Block syntax (for multi-line content): - -[source,asciidoc] ----- -[WARNING] -==== -This operation is destructive and cannot be undone. -Make sure you have a backup before proceeding. -==== ----- - -=== Bold, Italic, and Monospace - -[cols="1,2,2"] -|=== -| Style | Syntax | Usage - -| **Bold** -| `+**bold text**+` -| UI elements, emphasis on key terms - -| _Italic_ -| `+_italic text_+` -| First use of a defined term, file descriptions - -| `Monospace` -| `++`monospace`++` -| Code references, file names, variable names, commands - -| `**Bold mono**` -| `++**`bold mono`**++` -| Tool names in tables (e.g., **VMFleet**) -|=== - -=== Lists - -Use `*` for unordered lists, `.` for ordered lists: - -[source,asciidoc] ----- -* First item -* Second item -** Nested item - -. Step one -. Step two -.. Sub-step ----- - -IMPORTANT: Do not mix `*` and `-` for unordered lists. Always use `*` in this project. - -== Cross-References and Linking - -=== Internal Cross-References - -Link to sections within the same document: - -[source,asciidoc] ----- -See <> for details. - -See <> for details. ----- - -=== Inter-Document References - -Link to sections in other documents using `xref`: - -[source,asciidoc] ----- -See xref:chapters/06-vmfleet-guide.adoc#deploy-phase[the deployment phase]. ----- - -=== External Links - -[source,asciidoc] ----- -https://github.com/AzureLocal/azurelocal-loadtools[Azure Local Load Tools repository] - -https://docs.microsoft.com/en-us/azure-stack/hci/[Azure Stack HCI documentation] ----- - -=== Image References - -[source,asciidoc] ----- -image::diagram-name.png[Alt text, width=600] ----- - -* Store images in `docs/images/` -* Use descriptive file names: `vmfleet-pipeline-workflow.png`, not `diagram1.png` -* Always include alt text -* Specify width for large images to control rendering - -== Templates - -=== Standards Document Template - -[source,asciidoc] ----- -= Title — Subtitle -Kristopher Turner -v1.0, 2026-02-13 - -:description: Single sentence describing the document. -:keywords: relevant, keywords -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -\[abstract] -One to three sentences. - -\[discrete] -== Quick Navigation - -* <> — Description -* <> — Description - -''' - -== First Section - -Content here. - -== Second Section - -Content here. ----- - -=== Guide Template - -[source,asciidoc] ----- -= Guide Title -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Category-Getting%20Started-2ECC71?style=flat-square[Category: Getting Started] - -Brief introduction to the topic. - -== First Section - -Content here. - -== Second Section - -Content here. ----- - -=== README Template (AsciiDoc) - -[source,asciidoc] ----- -= Component Name -:toc: macro -:toclevels: 2 -:icons: font - -image:https://img.shields.io/badge/Platform-Azure%20Local-0078D4?style=flat-square&logo=microsoft-azure[Platform] image:https://img.shields.io/badge/License-MIT-green?style=flat-square[License] - -Brief one-paragraph description of what this component does. - -toc::[] - -== Overview - -What this component does and why it exists. - -== Quick Start - -[source,powershell] -\---- -# Minimal usage example -\---- - -== Configuration - -Describe configuration options. - -== Usage - -Describe detailed usage. ----- - -=== README Template (Markdown) - -For solution READMEs that use Markdown: - -[source,markdown] ----- -# Component Name - -Brief description. - -## Overview - -What this component does. - -## Quick Start - -```powershell -# Minimal usage example -``` - -## Configuration - -Options and settings. ----- - -NOTE: The root `README.adoc` uses AsciiDoc. Solution-level READMEs (`src/solutions/*/README.md`) currently use Markdown. Both are acceptable — but be consistent within each directory. - -== File Organization - -=== Documentation Directory Structure - ----- -docs/ -├── index.adoc # Documentation hub — links to everything -├── main.adoc # Optional combined PDF builder -├── getting-started/ # Shared setup docs (all tools) -│ ├── introduction.adoc -│ ├── architecture.adoc -│ ├── prerequisites.adoc -│ ├── installation.adoc -│ └── configuration.adoc -├── tools/ # One folder per tool — self-contained -│ ├── vmfleet/ -│ │ ├── overview.adoc -│ │ ├── prerequisites.adoc -│ │ ├── deployment.adoc -│ │ ├── workload-profiles.adoc -│ │ ├── monitoring.adoc -│ │ ├── reporting.adoc -│ │ └── troubleshooting.adoc -│ ├── fio/ -│ │ └── overview.adoc -│ ├── iperf/ -│ │ └── overview.adoc -│ ├── hammerdb/ -│ │ └── overview.adoc -│ └── stress-ng/ -│ └── overview.adoc -├── operations/ # Cross-tool operational docs -│ ├── ci-cd.adoc -│ └── credential-management.adoc -├── reference/ # Reference material -│ ├── variable-reference.adoc -│ ├── cmdlet-reference.adoc -│ └── glossary.adoc -├── standards/ # Standards documents (self-contained) -│ ├── documentation-standards.adoc -│ ├── scripting-standards.adoc -│ └── variables-environment-standards.adoc -├── diagrams/ # Draw.io and other diagram sources -├── images/ # Rendered images and screenshots -└── themes/ # PDF theme files ----- - -=== File Naming Rules - -[cols="1,3,2"] -|=== -| Location | Convention | Example - -| `getting-started/` -| `kebab-case.adoc` -| `prerequisites.adoc` - -| `tools/{tool}/` -| `kebab-case.adoc` -| `workload-profiles.adoc` - -| `operations/` -| `kebab-case.adoc` -| `credential-management.adoc` - -| `reference/` -| `kebab-case.adoc` -| `variable-reference.adoc` - -| `standards/` -| `kebab-case-standards.adoc` -| `scripting-standards.adoc` - -| `diagrams/` -| `kebab-case.drawio` -| `vmfleet-workflow.drawio` - -| `images/` -| `kebab-case.png` -| `solution-architecture.png` -|=== - -=== Adding a New Guide - -. Create the file in the appropriate folder (`getting-started/`, `tools/{tool}/`, `operations/`, `reference/`) -. Use the guide header template with `:toc: left` and project attributes -. Add a link to `docs/index.adoc` -. Add an `include::` directive in `docs/main.adoc` for combined PDF builds - -=== Adding a New Tool - -. Create `docs/tools/{tool-name}/` folder -. Add at minimum `overview.adoc`; add `prerequisites.adoc`, `deployment.adoc`, `monitoring.adoc`, `reporting.adoc`, `troubleshooting.adoc` as the tool is implemented -. Add links in `docs/index.adoc` under the Tool Guides section -. Add `include::` directives in `docs/main.adoc` - -=== Adding a New Standards Document - -. Create the file in `docs/standards/` -. Use the full standards header template (see <>) -. Include the Quick Navigation block -. Link from this document's Quick Navigation if related - -== Writing Style - -=== Voice and Tone - -* Use **imperative voice** for instructions: "Run the command" not "You should run" -* Use **present tense**: "The script validates" not "The script will validate" -* Be **direct**: "Set `$ErrorActionPreference`" not "It is recommended to set" -* Be **specific**: Include exact file paths, command syntax, and expected output - -=== Terminology - -Use consistent terminology throughout: - -[cols="1,1,2"] -|=== -| Preferred | Avoid | Reason - -| Azure Local -| Azure Stack HCI -| Current product name (unless historical context) - -| fleet VMs -| test VMs, VMFleet VMs -| Consistent with VMFleet terminology - -| cluster nodes -| servers, hosts, machines -| Consistent with failover cluster terminology - -| solution config -| solution JSON, generated config -| Matches the `ConfigManager` naming - -| master config -| master YAML, environment file -| Matches `master-environment.yml` naming - -| override chain -| priority chain, fallback chain -| Project-specific term defined in scripting standards -|=== diff --git a/docs/_archived_adoc/standards/scripting-standards.adoc b/docs/_archived_adoc/standards/scripting-standards.adoc deleted file mode 100644 index 23fff91..0000000 --- a/docs/_archived_adoc/standards/scripting-standards.adoc +++ /dev/null @@ -1,531 +0,0 @@ -= PowerShell Scripting Standards — Azure Local Load Tools -Kristopher Turner -v1.0, 2026-02-13 - -:description: Mandatory PowerShell scripting standards for all scripts and modules in the Azure Local Load Tools repository. -:keywords: powershell, standards, coding, scripting, azure-local, modules, pester, pssa -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -[abstract] -This document defines the mandatory PowerShell scripting standards for all scripts and modules in the Azure Local Load Tools repository. -Every contributor must follow these standards. -Scripts that do not comply must be refactored before merging. - -[discrete] -== Quick Navigation - -* <> — File names, function names, approved verbs -* <> — Required layout for every `.ps1` file -* <> — Mandatory/optional params, validation, override chain -* <> — `.psd1` / `.psm1` layout, exports, versioning -* <> — `try`/`catch`, `$ErrorActionPreference`, `-ErrorAction Stop` -* <> — JSON-lines, correlation IDs, severity levels -* <> — Pester conventions, naming, coverage -* <> — Enforced linting rules and exclusions - -''' - -== File and Naming Conventions - -=== File Naming - -All PowerShell files must follow PascalCase naming with the `Verb-Noun` pattern: - -[cols="2,3,2"] -|=== -| Type | Pattern | Example - -| Standalone scripts -| `Verb-Noun.ps1` -| `Install-VMFleet.ps1` - -| Pipeline orchestrators -| `Invoke-Pipeline.ps1` -| `Invoke-VMFleetPipeline.ps1` - -| Monitoring scripts -| `Verb-Metrics.ps1` -| `Collect-StorageMetrics.ps1` - -| Helper scripts -| `PascalCase-Description.ps1` -| `Common-Functions.ps1` - -| Module files -| `ModuleName.psm1` / `.psd1` -| `ConfigManager.psm1` - -| Test files -| `ModuleName.Tests.ps1` -| `Logger.Tests.ps1` -|=== - -=== Function Naming - -* Use **approved PowerShell verbs** only — run `Get-Verb` to see the full list. -* Common approved verbs in this project: - -[cols="1,3"] -|=== -| Verb | Usage - -| `Install` | Installing modules or prerequisites -| `Deploy` | Creating VMs, provisioning resources -| `Start` | Launching workloads or tests -| `Stop` | Halting workloads -| `Collect` | Gathering results or metrics -| `Remove` | Tearing down resources -| `Invoke` | Running a pipeline or multi-phase workflow -| `Watch` | Real-time monitoring -| `Import` | Loading configuration into memory -| `Export` | Writing configuration or data to disk -| `Get` | Retrieving status, state, or info -| `Set` | Modifying state or configuration -| `New` | Creating objects (e.g., `New-RunState`) -| `Push` | Sending data to external services (e.g., Azure Monitor) -|=== - -CAUTION: Never use unapproved verbs like `Create`, `Delete`, `Run`, or `Setup`. PSScriptAnalyzer will flag these. - -=== Variable Naming - -* **Local variables:** `$camelCase` (e.g., `$vmCount`, `$logSession`) -* **Script-scoped variables:** `$script:PascalCase` (e.g., `$script:ActiveSessions`) -* **Parameters:** `PascalCase` (e.g., `$ProjectRoot`, `$SolutionConfigPath`) -* **Constants:** `$UPPER_SNAKE_CASE` or descriptive `$PascalCase` (e.g., `$ErrorActionPreference`) - -== Script Structure - -Every standalone `.ps1` script must follow this exact structure: - -[source,powershell] ----- -# ============================================================================= -# Verb-Noun.ps1 - Azure Local Load Tools -# ============================================================================= -# Brief description of what this script does. -# Phase N of the pipeline (if applicable). -# ============================================================================= - -#Requires -Version 7.2 # <1> - -[CmdletBinding(SupportsShouldProcess)] # <2> -param( - [Parameter(Mandatory)] # <3> - [string]$RequiredParam, - - [Parameter()] - [string]$OptionalParam, - - [Parameter()] - [string]$ProjectRoot # <4> -) - -$ErrorActionPreference = 'Stop' # <5> - -# ---- Resolve Project Root ---- # <6> -if (-not $ProjectRoot) { - $ProjectRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..\..')).Path -} - -# ---- Bootstrap ---- # <7> -. (Join-Path $ProjectRoot 'src\core\powershell\helpers\Common-Functions.ps1') -Import-Module (Join-Path $ProjectRoot 'src\core\powershell\modules\Logger\Logger.psm1') -Force -Import-Module (Join-Path $ProjectRoot 'src\core\powershell\modules\ConfigManager\ConfigManager.psm1') -Force - -# ---- Initialize Logging ---- # <8> -$logSession = Start-LogSession -Component '-' ` - -LogRootPath (Join-Path $ProjectRoot 'logs\') - -try { - Write-Log -Message 'Starting ' -Severity Information - - # ... main logic ... # <9> - - Write-Log -Message ' completed successfully' -Severity Information - Write-Host ' complete.' -ForegroundColor Green -} -catch { - Write-Log -Message "Error: $_" -Severity Error -ErrorRecord $_ # <10> - throw -} -finally { - Stop-LogSession # <11> -} ----- -<1> Always require PowerShell 7.2+ -<2> All scripts must support `-WhatIf` and `-Confirm` -<3> Mark truly required parameters with `[Parameter(Mandatory)]` -<4> `$ProjectRoot` is always optional — auto-resolved from `$PSScriptRoot` -<5> Set `$ErrorActionPreference = 'Stop'` at the top of every script -<6> Auto-resolve project root relative to script location -<7> Dot-source helpers, import modules with `-Force` -<8> Start a log session before any work -<9> Main logic wrapped in `try` -<10> Log errors with the `$ErrorRecord` for full stack trace -<11> Always close the log session in `finally` - -=== Comment Block Header - -Every script **must** start with the banner comment: - -[source,powershell] ----- -# ============================================================================= -# Script-Name.ps1 - Azure Local Load Tools -# ============================================================================= -# Description of the script purpose. -# ============================================================================= ----- - -NOTE: This banner replaces traditional comment-based help at the _file_ level. Functions inside modules use `<# .SYNOPSIS #>` blocks instead. - -== Parameter Standards - -=== Required vs Optional - -[cols="1,2,3"] -|=== -| Attribute | When to Use | Example - -| `[Parameter(Mandatory)]` -| Value must be provided — no fallback exists -| Rarely used; most params have config fallbacks - -| `[Parameter()]` -| Has a fallback via solution config or master config -| Most parameters in this project - -| `[ValidateSet(...)]` -| Constrained to known values -| `[ValidateSet('PDF', 'DOCX', 'XLSX')]` - -| `[ValidateRange(...)]` -| Numeric bounds -| `[ValidateRange(1, 1000)]` - -| `[PSCredential]` -| Credential parameters -| `[PSCredential]$Credential` - -| `[switch]` -| Boolean flags -| `[switch]$Force`, `[switch]$Resume` -|=== - -=== Three-Level Override Chain - -All configuration-driven parameters must follow this override chain: - -[source,powershell] ----- -$vmCount = if ($VMCount) { $VMCount } # <1> - elseif ($profile) { $profile.vm_count } # <2> - else { [int]$solutionConfig.vmfleet_vm_count } # <3> ----- -<1> **Explicit parameter** — highest priority, user passed it directly -<2> **Profile config** — loaded from `config/profiles//*.yml` -<3> **Solution config** — generated from `master-environment.yml` - -IMPORTANT: Never skip levels. Every configurable parameter must check all three levels in this exact order. - -=== Default Config Path Resolution - -When a config path parameter is not provided, resolve it from `$ProjectRoot`: - -[source,powershell] ----- -if (-not $SolutionConfigPath) { - $SolutionConfigPath = Join-Path $ProjectRoot 'config\variables\solutions\vmfleet.json' -} ----- - -== Module Structure - -=== File Layout - -Each module consists of two files in its own directory: - ----- -src/core/powershell/modules/ -└── ModuleName/ - ├── ModuleName.psd1 # Module manifest - └── ModuleName.psm1 # Module implementation ----- - -=== Manifest Requirements (`.psd1`) - -Every module manifest must include: - -[source,powershell] ----- -@{ - RootModule = 'ModuleName.psm1' - ModuleVersion = '0.1.0' # <1> - GUID = '' - Author = 'AzureLocal' - Description = 'Brief module description' - PowerShellVersion = '7.2' - FunctionsToExport = @('Public-Function1', 'Public-Function2') # <2> - PrivateData = @{ - PSData = @{ - ProjectUri = 'https://github.com/AzureLocal/azurelocal-loadtools' # <3> - } - } -} ----- -<1> Follow semantic versioning -<2> Explicitly list exported functions — never use `'*'` -<3> Always include the project URI - -=== Module Implementation (`.psm1`) - -[source,powershell] ----- -# ============================================================================= -# ModuleName Module - Azure Local Load Tools -# ============================================================================= -# Module description. -# ============================================================================= - -# Module-level variables -$script:ProjectRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..\..\..')).Path - -function Public-Function { - <# - .SYNOPSIS - One-line description. - .DESCRIPTION - Detailed description. - .PARAMETER ParamName - Parameter description. - .OUTPUTS - Output type description. - .EXAMPLE - Public-Function -ParamName 'value' - #> - [CmdletBinding()] - param( ... ) - # Implementation -} ----- - -WARNING: Every public function must have a complete comment-based help block with `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, and `.OUTPUTS` at minimum. - -== Error Handling - -=== Global Error Preference - -Every script sets `$ErrorActionPreference = 'Stop'` at the top. This ensures all errors are terminating. - -=== Try/Catch Pattern - -[source,powershell] ----- -try { - # Operations that may fail - Invoke-Command -ComputerName $node -ScriptBlock { - Import-Module VMFleet -ErrorAction Stop # <1> - # ... - } -Credential $cred -} -catch { - Write-Log -Message "Failed: $_" -Severity Error -ErrorRecord $_ # <2> - throw # <3> -} ----- -<1> Use `-ErrorAction Stop` on individual cmdlets inside remote sessions -<2> Always log before re-throwing -<3> Re-throw to propagate — let the caller decide recovery - -=== ShouldProcess for Destructive Operations - -Wrap all cluster-modifying operations in `$PSCmdlet.ShouldProcess()`: - -[source,powershell] ----- -if ($PSCmdlet.ShouldProcess($primaryNode, 'Stop VMFleet workload')) { - Invoke-Command -ComputerName $primaryNode -ScriptBlock { - Import-Module VMFleet -ErrorAction Stop - Stop-Fleet - } -Credential $clusterCred -} ----- - -TIP: This enables users to run scripts with `-WhatIf` for a dry run or `-Confirm` for step-by-step approval. - -== Logging Standards - -=== Log Format - -All logs are written in **JSON-lines** format (`.jsonl`), one JSON object per line: - -[source,json] ----- -{"timestamp":"2026-02-13T10:30:00.000Z","severity":"INFO","component":"VMFleet-Install","correlation_id":"abc123","message":"VMFleet module installation complete","data":null} ----- - -=== Severity Levels - -[cols="1,3"] -|=== -| Level | When to Use - -| `DEBUG` | Verbose diagnostic info (parameter values, intermediate state) -| `INFO` | Normal operation milestones (phase started, phase completed) -| `WARNING` | Non-fatal issues (fallback used, optional feature unavailable) -| `ERROR` | Failures that stop the current operation -| `CRITICAL` | Unrecoverable failures requiring immediate attention -|=== - -=== Log Session Lifecycle - -[source,powershell] ----- -# Start -$logSession = Start-LogSession -Component 'VMFleet-Deploy' ` - -LogRootPath (Join-Path $ProjectRoot 'logs\vmfleet') - -# Write entries -Write-Log -Message 'Starting deployment' -Severity Information -Write-Log -Message 'Deployment complete' -Severity Information -Data @{ - vm_count = $vmCount - duration = $elapsed.TotalSeconds -} - -# Stop (always in finally block) -Stop-LogSession ----- - -=== Log Directory Convention - ----- -logs/ -├── vmfleet/ # VMFleet component logs -├── fio/ # fio component logs -├── pipeline/ # Orchestrator logs -├── monitoring/ # Metric collection logs -└── reports/ # Report generation logs ----- - -== Testing Requirements - -=== Framework - -All tests use **Pester v5+**. - -=== File Naming - -Test files follow the pattern `.Tests.ps1` and live in the `tests/` directory: - ----- -tests/ -├── ConfigManager.Tests.ps1 -├── Logger.Tests.ps1 -├── ReportGenerator.Tests.ps1 -├── StateManager.Tests.ps1 -└── PSScriptAnalyzer.ps1 ----- - -=== Test Structure - -[source,powershell] ----- -BeforeAll { - $modulePath = Join-Path $PSScriptRoot '..\src\core\powershell\modules\\.psm1' - Import-Module $modulePath -Force -} - -Describe ' Module' { - Context '' { - It 'Should ' { - # Arrange - $input = ... - - # Act - $result = Function-Name -Param $input - - # Assert - $result | Should -Be $expected - } - } -} ----- - -=== Test Isolation - -* Use `$TestDrive` for any file I/O — never write to the real project tree -* Import modules in `BeforeAll`, not at the top of the file -* Each `It` block must be independent — no shared mutable state between tests - -=== Coverage Expectations - -[cols="1,2"] -|=== -| Area | Minimum Requirement - -| Core modules (`ConfigManager`, `Logger`, `StateManager`) -| One `Describe` block per public function - -| Solution scripts -| Integration test via pipeline orchestrator - -| Config validation -| Schema validation tests for all JSON and YAML files -|=== - -== PSScriptAnalyzer Rules - -=== Running the Linter - -[source,powershell] ----- -# Lint all scripts -pwsh -File tests/PSScriptAnalyzer.ps1 - -# Lint with auto-fix -pwsh -File tests/PSScriptAnalyzer.ps1 -Fix ----- - -=== Enforced Rules - -All default PSScriptAnalyzer rules are enforced **except** the following exclusions: - -[cols="2,3"] -|=== -| Excluded Rule | Reason - -| `PSAvoidUsingConvertToSecureStringWithPlainText` -| Used in demo/template code for examples only -|=== - -=== Severity Policy - -[cols="1,3"] -|=== -| Severity | Policy - -| **Error** -| Must be fixed before merge — PR will be blocked - -| **Warning** -| Must be fixed before merge unless a documented exception exists - -| **Information** -| Should be addressed; not a merge blocker -|=== - -TIP: Run `tests/PSScriptAnalyzer.ps1` locally before every commit. The CI pipeline (`lint.yml`) runs this automatically on PR. diff --git a/docs/_archived_adoc/standards/variables-environment-standards.adoc b/docs/_archived_adoc/standards/variables-environment-standards.adoc deleted file mode 100644 index aa3d91c..0000000 --- a/docs/_archived_adoc/standards/variables-environment-standards.adoc +++ /dev/null @@ -1,586 +0,0 @@ -= Variables & Environment Standards — Azure Local Load Tools -Kristopher Turner -v1.0, 2026-02-13 - -:description: Standards for configuration variables, environment files, YAML structure, JSON schemas, and the override chain in the Azure Local Load Tools repository. -:keywords: variables, configuration, yaml, json, schema, environment, azure-local, override-chain -:toc: left -:toclevels: 4 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../images -:tip-caption: 💡 -:note-caption: ℹī¸ -:warning-caption: ⚠ī¸ -:caution-caption: đŸ”Ĩ -:important-caption: ❗ - -image:https://img.shields.io/badge/Category-Standards-E67E22?style=flat-square[Category: Standards] - -[abstract] -This document defines the mandatory standards for all configuration files, environment variables, YAML structures, JSON schemas, and the variable override chain in the Azure Local Load Tools repository. -Every configuration file must conform to these standards before merging. - -[discrete] -== Quick Navigation - -* <> — How config files relate to each other -* <> — `master-environment.yml` structure and rules -* <> — Naming, types, tags, categories -* <> — Auto-generated per-solution JSON files -* <> — Cluster YAML file standards -* <> — Profile YAML format and conventions -* <> — Key Vault mappings, never plaintext -* <> — JSON Schema requirements - -''' - -== Configuration File Hierarchy - -The configuration system follows a layered architecture: - ----- -config/ -├── variables/ -│ ├── master-environment.yml <1> -│ ├── schema.json <2> -│ └── solutions/ -│ ├── vmfleet.json <3> -│ ├── fio.json -│ ├── iperf.json -│ ├── hammerdb.json -│ └── stress-ng.json -├── clusters/ -│ └── example-cluster.yml <4> -├── credentials/ -│ └── keyvault-config.yml <5> -└── profiles/ - └── vmfleet/ <6> - ├── general.yml - ├── peak-iops.yml - ├── sql-oltp.yml - └── vdi.yml ----- -<1> **Master source of truth** — all variables defined here with solution tags -<2> **JSON Schema** — validates the structure of `master-environment.yml` -<3> **Solution configs** — auto-generated by `ConfigManager` from master file -<4> **Cluster configs** — per-cluster connection details and topology -<5> **Credential config** — maps logical names to Key Vault secrets -<6> **Workload profiles** — preset parameter sets for common test scenarios - -=== Data Flow - ----- -master-environment.yml - │ - â–ŧ (ConfigManager filters by solution tag) - solutions/*.json - │ - â–ŧ (Script reads at runtime) - Three-Level Override Chain: - 1. Explicit parameter → highest priority - 2. Profile config → middle priority - 3. Solution config → lowest priority (default) ----- - -IMPORTANT: Variables flow in one direction only: master → solution JSON → runtime. Never edit solution JSON files by hand — they are generated artifacts. - -== Master Environment File - -=== Location - -`config/variables/master-environment.yml` - -=== Required Structure - -[source,yaml] ----- -metadata: - version: "1.0.0" # <1> - description: "Master environment configuration for Azure Local Load Tools" - last_modified: "2026-02-13" # <2> - -variables: # <3> - - name: variable_name - value: default_value - type: string - required: true - description: "Human-readable description" - solutions: [vmfleet, fio] - category: cluster ----- -<1> Semantic version — increment on every change -<2> Update `last_modified` on every edit -<3> `variables` is an array of variable definition objects - -=== Metadata Block - -[cols="1,1,2"] -|=== -| Field | Type | Description - -| `version` -| string -| Semantic version (`major.minor.patch`) - -| `description` -| string -| Purpose of this configuration file - -| `last_modified` -| date -| ISO 8601 date of last modification -|=== - -WARNING: Always update `version` and `last_modified` when editing the master file. CI validation checks for stale dates. - -== Variable Definition Standards - -=== Required Fields - -Every variable entry in `master-environment.yml` must include **all** of these fields: - -[cols="1,1,1,3"] -|=== -| Field | Type | Required | Description - -| `name` -| string -| Yes -| Unique identifier in `snake_case` - -| `value` -| any -| Yes -| Default value (empty string `""` or `[]` for unset) - -| `type` -| string -| Yes -| One of: `string`, `integer`, `boolean`, `array` - -| `required` -| boolean -| Yes -| Whether the variable must have a non-empty value at runtime - -| `description` -| string -| Yes -| Human-readable explanation of the variable's purpose - -| `solutions` -| array -| Yes -| List of solutions that consume this variable - -| `category` -| string -| No -| Logical grouping (see <>) - -| `sensitive` -| boolean -| No -| If `true`, value must come from Key Vault at runtime -|=== - -=== Variable Naming Rules - -[cols="1,3,2"] -|=== -| Rule | Description | Example - -| Format -| Always `snake_case`, lowercase -| `vm_count_per_node` - -| Pattern -| `^[a-z][a-z0-9_]*$` -| Enforced by JSON Schema - -| Solution prefix -| Use solution name as prefix for solution-specific variables -| `vmfleet_admin_username`, `hammerdb_db_name` - -| Shared variables -| No prefix for variables shared across solutions -| `cluster_name`, `csv_path` - -| Avoid abbreviations -| Use full words unless the abbreviation is universally understood -| `vm_memory_gb` not `vm_mem_gb` -|=== - -CAUTION: Variable names are used as JSON keys in solution configs. Renaming a variable is a breaking change — update all scripts that reference it. - -=== Variable Types - -[cols="1,2,2"] -|=== -| Type | YAML Value | JSON Equivalent - -| `string` -| `"text value"` -| `"text value"` - -| `integer` -| `42` -| `42` - -| `boolean` -| `true` / `false` -| `true` / `false` - -| `array` -| `[item1, item2]` -| `["item1", "item2"]` -|=== - -=== Solution Tags - -The `solutions` field is an array of solution identifiers. Valid values: - -* `vmfleet` -* `fio` -* `iperf` -* `hammerdb` -* `stress-ng` - -A variable tagged with multiple solutions will appear in each solution's generated JSON: - -[source,yaml] ----- -- name: cluster_name - value: "" - type: string - required: true - description: "Azure Local cluster name" - solutions: [vmfleet, fio, iperf, hammerdb, stress-ng] # Shared across all - category: cluster ----- - -[[variable-categories]] -=== Variable Categories - -[cols="1,3"] -|=== -| Category | Variables In This Group - -| `cluster` -| Cluster identity, nodes, storage paths, network config - -| `deployment` -| VM counts, memory, CPU, disk sizes - -| `testing` -| Block sizes, write ratios, durations, thresholds - -| `monitoring` -| Log Analytics workspace, collection intervals, Azure Monitor settings - -| `reporting` -| Report formats, output paths, template paths - -| `credentials` -| Usernames, passwords (sensitive — Key Vault only) - -| `logging` -| Log levels, retention, paths -|=== - -=== Sensitive Variables - -Variables marked `sensitive: true` must follow these rules: - -. The `value` field in master config must be empty (`""`) -. Actual values are retrieved at runtime from Azure Key Vault -. The mapping from variable name to Key Vault secret is in `keyvault-config.yml` -. Scripts must never write sensitive values to logs - -[source,yaml] ----- -- name: vmfleet_admin_password - value: "" # <1> - type: string - required: true - sensitive: true # <2> - description: "Password for VMFleet admin account" - solutions: [vmfleet] - category: credentials ----- -<1> Always empty — never store the actual password -<2> Marks this variable for Key Vault retrieval - -CAUTION: Never commit actual credentials to any configuration file. The `.gitignore` should protect against this, but manual vigilance is still required. - -== Solution JSON Configs - -=== Generation - -Solution JSON configs are **generated** by the `Export-SolutionConfig` function in `ConfigManager`: - -[source,powershell] ----- -Export-SolutionConfig -ConfigPath 'config/variables/master-environment.yml' ` - -Solution 'VMFleet' ` - -OutputPath 'config/variables/solutions/vmfleet.json' ----- - -=== Format - -[source,json] ----- -{ - "_metadata": { - "generated_at": "2026-02-13T10:00:00Z", - "solution": "VMFleet", - "source": "config/variables/master-environment.yml", - "variable_count": 25 - }, - "cluster_name": "", - "cluster_domain": "", - "vm_count_per_node": 10, - "vmfleet_admin_username": "FleetAdmin" -} ----- - -=== Rules - -. **Never edit by hand** — these are generated artifacts -. **Always regenerate** after editing `master-environment.yml` -. **Commit the generated files** — they are checked into source control for offline/airgapped use -. The `_metadata` block is informational and ignored by scripts - -TIP: Run `Export-SolutionConfig` for all solutions after any master config change. The CI pipeline validates that generated files are in sync. - -== Cluster Configuration - -=== Location - -`config/clusters/.yml` - -=== Required Structure - -[source,yaml] ----- -cluster: - # Identity - name: "hci-cluster-01" # <1> - domain: "contoso.local" - description: "Production Azure Local cluster" - - # Nodes - nodes: # <2> - - name: "hci-node-01" - management_ip: "10.0.0.1" - storage_ip: "10.0.1.1" - - # Storage - csv_path: "C:\\ClusterStorage\\Volume1" - collect_volume_path: "C:\\ClusterStorage\\Collect" - base_vhd_path: "C:\\ClusterStorage\\Collect\\BaseImage.vhdx" - - # WinRM - winrm: # <3> - port: 5985 - use_ssl: false - authentication: "Kerberos" - skip_ca_check: false - operation_timeout_seconds: 300 - - # Networks - networks: # <4> - management: - subnet: "10.0.0.0/24" - vlan_id: 0 - storage: - subnet: "10.0.1.0/24" - vlan_id: 100 - rdma_enabled: true - compute: - subnet: "10.0.2.0/24" - vlan_id: 200 - - # Linux VMs (for fio, iperf, stress-ng, hammerdb) - linux_vms: [] # <5> ----- -<1> Cluster name must match the actual failover cluster name -<2> List every node — used for remote command execution -<3> WinRM settings for PowerShell remoting into cluster nodes -<4> Network topology for network-aware testing (iPerf) -<5> Empty array for solutions not yet deployed - -=== File Naming - -* Use descriptive names: `prod-seattle-hci01.yml`, `lab-east-cluster.yml` -* The `example-cluster.yml` file is a **template** — copy it, never edit it directly - -WARNING: Cluster config files may contain IP addresses and hostnames. Do **not** commit production cluster configs with real IPs to a public repository. Use `.gitignore` or a separate private config repo. - -== Workload Profiles - -=== Location - -`config/profiles//.yml` - -=== Required Structure - -[source,yaml] ----- -profile: - name: "Peak IOPS" # <1> - description: "100% random 4K reads for maximum IOPS measurement" - category: "iops" # <2> - - parameters: # <3> - block_size: "4k" - write_ratio: 0 - random_ratio: 100 - outstanding_io: 32 - threads_per_vm: 4 - duration_seconds: 300 - warmup_seconds: 60 - - expected_thresholds: # <4> - min_iops_per_node: 50000 - max_latency_ms: 10 - min_throughput_mbps: 200 ----- -<1> Human-readable profile name — shown in reports -<2> Category for grouping (`iops`, `throughput`, `latency`, `mixed`, `oltp`, `olap`) -<3> Parameters that override solution config defaults when this profile is selected -<4> Optional thresholds for pass/fail reporting - -=== Profile Naming Convention - -[cols="2,3"] -|=== -| Profile | Purpose - -| `general.yml` -| Balanced mixed workload — default if no profile specified - -| `peak-iops.yml` -| Maximum IOPS (small random reads) - -| `sql-oltp.yml` -| Simulates SQL Server OLTP patterns - -| `vdi.yml` -| Simulates VDI (Virtual Desktop Infrastructure) patterns -|=== - -TIP: Create new profiles rather than modifying existing ones. Profiles are meant to be reusable presets. - -== Credential Configuration - -=== Location - -`config/credentials/keyvault-config.yml` - -=== Structure - -[source,yaml] ----- -keyvault: - name: "" # <1> - resource_group: "" - subscription_id: "" - tenant_id: "" - - auth_method: "az_cli" # <2> - - service_principal: # <3> - client_id: "" - client_secret_env_var: "AZURE_CLIENT_SECRET" - tenant_id: "" - - secrets: # <4> - cluster_admin_username: "hci-cluster-admin-user" - cluster_admin_password: "hci-cluster-admin-pwd" - vmfleet_admin_username: "vmfleet-admin-user" - vmfleet_admin_password: "vmfleet-admin-pwd" ----- -<1> Key Vault identity — fill in when configuring for your environment -<2> Authentication method: `az_cli`, `managed_identity`, or `service_principal` -<3> Only needed for `service_principal` auth — note the env var reference for the secret -<4> Maps logical names (used in scripts) to actual Key Vault secret names - -=== Rules - -[cols="1,3"] -|=== -| Rule | Description - -| No plaintext secrets -| The `secrets` block maps **names only** — never actual values - -| Environment variables -| Service principal secrets reference env vars, not literal values - -| Auth method -| Use `az_cli` for local development, `managed_identity` for CI/CD - -| Key Vault naming -| Secret names in Key Vault should use `kebab-case` -|=== - -IMPORTANT: The `keyvault-config.yml` file itself is safe to commit — it contains only name mappings. The actual secrets live exclusively in Azure Key Vault. - -== Schema Validation - -=== Master Config Schema - -The file `config/variables/schema.json` validates `master-environment.yml`: - -[cols="2,3"] -|=== -| Validation | Rule - -| Variable name format -| `^[a-z][a-z0-9_]*$` (snake_case only) - -| Variable type -| One of: `string`, `integer`, `boolean`, `array` - -| Solutions array -| At least one solution from the allowed set - -| Category values -| Must be from the defined set (cluster, deployment, testing, etc.) - -| Required fields -| `name`, `value`, `type`, `required`, `description`, `solutions` - -| No extra fields -| `additionalProperties: false` — prevents typos -|=== - -=== Running Validation - -[source,powershell] ----- -# Validate master config structure -$config = Import-MasterConfig -Force - -# Export and validate all solution configs -foreach ($solution in @('vmfleet', 'fio', 'iperf', 'hammerdb', 'stress-ng')) { - Export-SolutionConfig -Solution $solution -} ----- - -NOTE: The CI pipeline (`validate-config.yml`) runs schema validation automatically on every PR that touches files under `config/`. - -=== Adding New Variables - -When adding a new variable, follow this checklist: - -. Add the variable to `master-environment.yml` with all required fields -. Update `schema.json` if adding a new category or solution -. Regenerate the affected solution JSON configs -. Update any scripts that should consume the new variable -. Add the variable to the documentation appendix (Appendix A — Variable Reference) -. Increment the metadata `version` and update `last_modified` diff --git a/docs/_archived_adoc/themes/azurelocal-theme.yml b/docs/_archived_adoc/themes/azurelocal-theme.yml deleted file mode 100644 index 25df3ea..0000000 --- a/docs/_archived_adoc/themes/azurelocal-theme.yml +++ /dev/null @@ -1,113 +0,0 @@ -# ============================================================================= -# Azure Local Load Tools - Custom PDF Theme for asciidoctor-pdf -# ============================================================================= -# Usage: asciidoctor-pdf -a pdf-theme=azurelocal-theme docs/main.adoc -extends: default -font: - catalog: - merge: true -page: - margin: [0.75in, 0.75in, 1in, 0.75in] - size: A4 - layout: portrait -base: - font-family: Noto Sans - font-size: 10 - font-color: #333333 - line-height-length: 15 - line-height: $base_line_height_length / $base_font_size -heading: - font-color: #0078D4 - font-style: bold - h1-font-size: 24 - h2-font-size: 20 - h3-font-size: 16 - h4-font-size: 14 - margin-top: 15 - margin-bottom: 10 -title-page: - align: center - font-color: #0078D4 - title: - top: 40% - font-size: 32 - font-style: bold - font-color: #0078D4 - line-height: 1.2 - subtitle: - font-size: 18 - font-color: #505050 - margin-top: 10 - authors: - font-size: 14 - font-color: #505050 - margin-top: 20 - revision: - font-size: 12 - font-color: #808080 - margin-top: 10 -header: - height: 0.5in - font-size: 8 - font-color: #808080 - border-color: #DDDDDD - border-width: 0.5 - recto: - right: - content: '{document-title}' - verso: - left: - content: '{document-title}' -footer: - height: 0.5in - font-size: 8 - font-color: #808080 - border-color: #DDDDDD - border-width: 0.5 - recto: - center: - content: 'Page {page-number} of {page-count}' - right: - content: '{revdate}' - verso: - center: - content: 'Page {page-number} of {page-count}' - left: - content: '{revdate}' -code: - font-family: Noto Sans Mono - font-size: 9 - background-color: #F5F5F5 - border-color: #DDDDDD - border-width: 0.5 - padding: [8, 10, 8, 10] -table: - head: - font-color: #FFFFFF - background-color: #0078D4 - font-style: bold - body: - stripe-background-color: #F0F6FF - border-color: #CCCCCC - border-width: 0.5 -admonition: - icon: - note: - stroke-color: #0078D4 - tip: - stroke-color: #107C10 - warning: - stroke-color: #FF8C00 - caution: - stroke-color: #D83B01 - important: - stroke-color: #A4262C -sidebar: - background-color: #F0F6FF - border-color: #0078D4 - border-width: 1 -toc: - dot-leader: - font-color: #CCCCCC - indent: 20 - line-height: 1.8 diff --git a/docs/_archived_adoc/tools/fio/overview.adoc b/docs/_archived_adoc/tools/fio/overview.adoc deleted file mode 100644 index 7108f32..0000000 --- a/docs/_archived_adoc/tools/fio/overview.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= fio — Flexible I/O Tester -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-fio-6C3483?style=flat-square[Tool: fio] -image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder] - -CAUTION: *Placeholder* — Structure and Ansible roles scaffolded; implementation pending. - -== Purpose - -Fine-grained storage I/O benchmarking with extensive control over workload parameters. Runs inside Linux VMs on the cluster. - -== When to Use - -* Need precise control over I/O patterns beyond VMFleet's profiles -* Testing Linux VM storage performance specifically -* Validating I/O scheduler behavior, queue depths, or specific block sizes -* Client/server mode for distributed I/O testing - -== Key Capabilities - -* Job file-based workload definition -* Multiple I/O engines (libaio, io_uring, Windows IOCP) -* JSON output for automated parsing -* Verification mode for data integrity testing - -== Prerequisites - -In addition to the link:../../getting-started/prerequisites.adoc[common prerequisites]: - -* Linux VMs deployed on the Azure Local cluster -* Ansible 2.14+ for deployment (see link:../../getting-started/prerequisites.adoc#ansible-requirements-for-linux-based-tools[Ansible Requirements]) -* fio package installed on target VMs (automated via Ansible role) - -== File Locations - -[cols="1,2"] -|=== -| Component | Path - -| Scripts -| `src/solutions/fio/scripts/` - -| Ansible Playbooks -| `src/solutions/fio/playbooks/` - -| Job Files -| `src/solutions/fio/job-files/` - -| Profiles -| `config/profiles/fio/` - -| Ansible Role -| `src/core/ansible/roles/fio/` -|=== diff --git a/docs/_archived_adoc/tools/hammerdb/overview.adoc b/docs/_archived_adoc/tools/hammerdb/overview.adoc deleted file mode 100644 index 476714e..0000000 --- a/docs/_archived_adoc/tools/hammerdb/overview.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= HammerDB — Database Benchmarking -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-HammerDB-E74C3C?style=flat-square[Tool: HammerDB] -image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder] - -CAUTION: *Placeholder* — Structure and Ansible roles scaffolded; implementation pending. - -== Purpose - -Database workload benchmarking for SQL Server running on Azure Local VMs. - -== When to Use - -* Validating SQL Server performance on the cluster -* OLTP (TPROC-C) workload benchmarking -* OLAP/analytics (TPROC-H) workload benchmarking -* Combined storage + compute performance validation - -== Key Capabilities - -* Supports SQL Server, PostgreSQL, MySQL, Oracle, and more -* TPC-C and TPC-H benchmark profiles -* GUI, CLI, and web interfaces -* Docker images for reproducible CI/CD runs - -== Prerequisites - -In addition to the link:../../getting-started/prerequisites.adoc[common prerequisites]: - -* SQL Server instance deployed on an Azure Local VM -* HammerDB installed on the management station or target VM -* Ansible 2.14+ for automated deployment - -== File Locations - -[cols="1,2"] -|=== -| Component | Path - -| Scripts -| `src/solutions/hammerdb/scripts/` - -| Ansible Playbooks -| `src/solutions/hammerdb/playbooks/` - -| Profiles -| `config/profiles/hammerdb/` - -| Ansible Role -| `src/core/ansible/roles/hammerdb/` -|=== diff --git a/docs/_archived_adoc/tools/iperf/overview.adoc b/docs/_archived_adoc/tools/iperf/overview.adoc deleted file mode 100644 index 637452c..0000000 --- a/docs/_archived_adoc/tools/iperf/overview.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= iPerf3 — Network Performance Testing -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-iPerf3-1ABC9C?style=flat-square[Tool: iPerf3] -image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder] - -CAUTION: *Placeholder* — Structure and Ansible roles scaffolded; implementation pending. - -== Purpose - -Network bandwidth, jitter, and packet loss measurement between cluster nodes and VMs. - -== When to Use - -* Validating RDMA/SMB Direct network paths between cluster nodes -* Measuring east-west bandwidth between VMs -* Testing Switch Embedded Teaming (SET) throughput -* Baseline network performance before deploying workloads - -== Key Capabilities - -* TCP, UDP, and SCTP protocol support -* Multi-stream parallel connections -* JSON output for automated parsing -* Server daemon mode for persistent testing endpoints - -== Prerequisites - -In addition to the link:../../getting-started/prerequisites.adoc[common prerequisites]: - -* iPerf3 binaries on target nodes (Windows or Linux) -* RDMA configuration validated (for RDMA testing) -* Ansible 2.14+ for Linux VM deployment - -== File Locations - -[cols="1,2"] -|=== -| Component | Path - -| Scripts -| `src/solutions/iperf/scripts/` - -| Ansible Playbooks -| `src/solutions/iperf/playbooks/` - -| Profiles -| `config/profiles/iperf/` - -| Ansible Role -| `src/core/ansible/roles/iperf/` -|=== diff --git a/docs/_archived_adoc/tools/stress-ng/overview.adoc b/docs/_archived_adoc/tools/stress-ng/overview.adoc deleted file mode 100644 index 200d689..0000000 --- a/docs/_archived_adoc/tools/stress-ng/overview.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= stress-ng — System Stress Testing -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-stress--ng-F39C12?style=flat-square[Tool: stress-ng] -image:https://img.shields.io/badge/Status-Placeholder-lightgrey?style=flat-square[Status: Placeholder] - -CAUTION: *Placeholder* — Structure and Ansible roles scaffolded; implementation pending. - -== Purpose - -CPU, memory, cache, and system stress testing for capacity planning and burn-in validation. - -== When to Use - -* CPU stress testing for thermal and power validation -* Memory stress testing for stability under pressure -* Burn-in testing of new cluster nodes -* Capacity planning — determine maximum safe utilization levels - -== Key Capabilities - -* 370+ stress tests across CPU, memory, filesystem, network categories -* YAML job files for reproducible configurations -* Metrics: bogo ops/s, thermal zones, power measurement -* Stressor class system for targeted testing - -== Prerequisites - -In addition to the link:../../getting-started/prerequisites.adoc[common prerequisites]: - -* Linux VMs deployed on the Azure Local cluster -* Ansible 2.14+ for deployment -* stress-ng package installed on target VMs (automated via Ansible role) - -== File Locations - -[cols="1,2"] -|=== -| Component | Path - -| Scripts -| `src/solutions/stress-ng/scripts/` - -| Ansible Playbooks -| `src/solutions/stress-ng/playbooks/` - -| Profiles -| `config/profiles/stress-ng/` - -| Ansible Role -| `src/core/ansible/roles/stress_ng/` -|=== diff --git a/docs/_archived_adoc/tools/vmfleet/deployment.adoc b/docs/_archived_adoc/tools/vmfleet/deployment.adoc deleted file mode 100644 index c6c9166..0000000 --- a/docs/_archived_adoc/tools/vmfleet/deployment.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= VMFleet Deployment -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -This guide covers installing the VMFleet module and deploying fleet VMs across your Azure Local cluster. - -== Install VMFleet - -Installs the VMFleet PowerShell module and prepares the cluster: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Install-VMFleet.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -CredentialSource Interactive ----- - -== Deploy Fleet VMs - -Creates fleet VMs across all cluster nodes: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Deploy-VMFleet.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -VmCountPerNode 10 ` - -VmVcpuCount 2 ` - -VmMemoryGb 2 ----- - -The number of VMs, vCPUs, and memory per VM are configurable via: - -* Explicit parameters (as shown above) — highest priority -* Solution JSON (`config/variables/solutions/vmfleet.json`) -* Master environment defaults (`config/variables/master-environment.yml`) - -See link:../../getting-started/configuration.adoc[Configuration] for details on the override chain. - -== Cleanup - -To remove fleet VMs and restore the cluster to its pre-test state: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Remove-VMFleet.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -CredentialSource Interactive ` - -Confirm ----- - -== Next Steps - -* link:workload-profiles.adoc[Workload Profiles] — Run test workloads diff --git a/docs/_archived_adoc/tools/vmfleet/monitoring.adoc b/docs/_archived_adoc/tools/vmfleet/monitoring.adoc deleted file mode 100644 index af942c0..0000000 --- a/docs/_archived_adoc/tools/vmfleet/monitoring.adoc +++ /dev/null @@ -1,202 +0,0 @@ -= VMFleet Monitoring -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -The monitoring subsystem collects real-time storage, network, and compute metrics during VMFleet test execution. It uses a hybrid architecture: local PowerShell/PerfMon collection (always active) with optional push to Azure Monitor/Log Analytics. - -== Monitoring Architecture - -.Metric Collection Flow -[source,text] ----- -Cluster Nodes (PerfMon counters) - │ - â–ŧ -PowerShell Get-Counter (remote sessions) - │ - ├──â–ē Local CSV/JSON files (results/{run-id}/metrics/) - │ - └──â–ē Azure Monitor / Log Analytics (optional) - │ - â–ŧ - Azure Portal dashboards, alerts ----- - -== Metric Categories - -=== Storage Metrics - -Collected by `Collect-StorageMetrics.ps1`: - -[cols="2,3"] -|=== -| Counter | Description - -| CSVFS: Read IOPS -| Cluster Shared Volume read operations per second - -| CSVFS: Write IOPS -| Cluster Shared Volume write operations per second - -| CSVFS: Read Throughput (MB/s) -| Aggregate read bandwidth across CSVs - -| CSVFS: Write Throughput (MB/s) -| Aggregate write bandwidth across CSVs - -| CSVFS: Read Latency (ms) -| Average read latency per I/O operation - -| CSVFS: Write Latency (ms) -| Average write latency per I/O operation - -| S2D Cache Hit Ratio -| Percentage of I/O served from cache tier - -| Physical Disk Queue Depth -| Outstanding I/O requests per physical disk - -| Storage Pool Health -| Degraded/healthy status of storage pools -|=== - -=== Network Metrics - -Collected by `Collect-NetworkMetrics.ps1`: - -[cols="2,3"] -|=== -| Counter | Description - -| RDMA Activity: Bytes Sent/sec -| RDMA network adapter transmit throughput - -| RDMA Activity: Bytes Received/sec -| RDMA network adapter receive throughput - -| SMB Direct: Bytes Sent/sec -| SMB Direct (RDMA) data transfer rate - -| Network Adapter: Throughput (Gbps) -| Total NIC throughput per adapter - -| Network Adapter: Packets Dropped -| Dropped packets indicating congestion or errors - -| TCP: Retransmits/sec -| TCP retransmission rate (indicates network issues) -|=== - -=== Compute Metrics - -Collected by `Collect-ComputeMetrics.ps1`: - -[cols="2,3"] -|=== -| Counter | Description - -| Processor: % Total CPU -| Host CPU utilization across all logical processors - -| Hyper-V Hypervisor Logical Processor: % Total Run Time -| Hypervisor-level CPU consumption - -| Guest vCPU Utilization -| Per-VM CPU usage (via VMFleet `Watch-FleetCPU`) - -| Memory: Available MBytes -| Free physical memory on each host - -| Memory: % Committed Bytes In Use -| Memory pressure indicator - -| Hyper-V Dynamic Memory: Current Pressure -| Dynamic memory pressure per VM -|=== - -== Local Metric Collection - -Local collection is always active during test runs: - -[source,powershell] ----- -# Collect all metric categories with 5-second intervals -.\src\solutions\vmfleet\monitoring\Collect-StorageMetrics.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -SampleIntervalSeconds 5 ` - -OutputPath "results/run-001/metrics/storage/" - -.\src\solutions\vmfleet\monitoring\Collect-NetworkMetrics.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -SampleIntervalSeconds 5 ` - -OutputPath "results/run-001/metrics/network/" - -.\src\solutions\vmfleet\monitoring\Collect-ComputeMetrics.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -SampleIntervalSeconds 5 ` - -OutputPath "results/run-001/metrics/compute/" ----- - -Output format is JSON-lines for machine parsing: - -[source,json] ----- -{"timestamp":"2026-02-13T10:05:00Z","node":"hci-node-01","counter":"CSVFS_ReadIOPS","value":45230} -{"timestamp":"2026-02-13T10:05:00Z","node":"hci-node-01","counter":"CSVFS_WriteIOPS","value":12840} ----- - -== Azure Monitor Integration - -Optionally push collected metrics to Azure Monitor for centralized dashboards and alerting: - -[source,powershell] ----- -.\src\solutions\vmfleet\monitoring\Push-MetricsToAzureMonitor.ps1 ` - -MetricsPath "results/run-001/metrics/" ` - -WorkspaceId "your-log-analytics-workspace-id" ` - -CredentialSource KeyVault ----- - -NOTE: Azure Monitor integration requires the `monitoring.bicep` infrastructure template to be deployed. See `src/infrastructure/bicep/monitoring.bicep`. - -== Alert Rules - -Predefined alert thresholds in `monitoring/alerts/alert-rules.yml`: - -[source,yaml] ----- -alerts: - - name: high_storage_latency - metric: csvfs_write_latency_ms - threshold: 50 - severity: warning - description: "Write latency exceeds 50ms — possible storage bottleneck" - - - name: critical_cpu - metric: host_cpu_percent - threshold: 95 - severity: critical - description: "Host CPU exceeds 95% — test may be compute-bound" ----- - -== Real-Time Dashboard - -During test execution, use the monitoring dashboard wrapper: - -[source,powershell] ----- -# Launch real-time monitoring (combines VMFleet Watch-FleetCluster with custom metrics) -.\src\solutions\vmfleet\monitoring\Export-MetricsDashboard.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -RefreshIntervalSeconds 5 ----- diff --git a/docs/_archived_adoc/tools/vmfleet/overview.adoc b/docs/_archived_adoc/tools/vmfleet/overview.adoc deleted file mode 100644 index 699261f..0000000 --- a/docs/_archived_adoc/tools/vmfleet/overview.adoc +++ /dev/null @@ -1,104 +0,0 @@ -= VMFleet Overview -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools -:vmfleet-version: 2.1.0.0 -:diskspd-version: 2.2 - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Status-Implemented-brightgreen?style=flat-square[Status: Implemented] -image:https://img.shields.io/badge/VMFleet-2.1.0.0-blue?style=flat-square[VMFleet 2.1.0.0] - -VMFleet is the primary storage load testing tool in the {project-name}. It deploys a fleet of VMs across Azure Local cluster nodes, each running DiskSpd workloads to stress-test Storage Spaces Direct (S2D). - -== At a Glance - -* **VMFleet Version:** {vmfleet-version} -* **DiskSpd Version:** {diskspd-version} -* **What it tests:** Storage IOPS, throughput, latency under simulated workload -* **How it works:** Deploys lightweight Server Core VMs, each running DiskSpd to generate I/O -* **Status:** ✅ Fully Implemented - -== Quick Start - -[source,powershell] ----- -# Run the full VMFleet pipeline end-to-end -.\src\solutions\vmfleet\orchestrator\Invoke-VMFleetPipeline.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -Profiles @("General", "Peak") ` - -CredentialSource Interactive ` - -GenerateReports ----- - -== Pipeline Phases - -The VMFleet orchestrator executes the following phases: - -. **Pre-Check** — Validate cluster connectivity, S2D health, CSV availability, base VHD -. **Install** — Install VMFleet PowerShell module, create Collect volume -. **Deploy** — Create fleet VMs with configured vCPU and memory settings -. **Test** — Execute workload profiles (General, Peak IOPS, VDI, SQL OLTP) -. **Monitor** — Collect storage, network, and compute metrics in parallel -. **Collect** — Parse DiskSpd XML results, aggregate metrics per profile per node -. **Report** — Generate PDF, DOCX, and XLSX reports from collected data -. **Cleanup** — (Optional) Remove fleet VMs and volumes - -Each phase is checkpoint-tracked via `StateManager`, enabling resume after failure. - -== Resume After Failure - -If the pipeline fails mid-execution, resume from the last successful checkpoint: - -[source,powershell] ----- -.\src\solutions\vmfleet\orchestrator\Invoke-VMFleetPipeline.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -Resume ----- - -The `StateManager` tracks completed phases and skips them on resume. - -== Running Individual Scripts - -Every script can be executed independently: - -[source,powershell] ----- -# Each script is self-contained — reads config, validates params, logs actions -.\src\solutions\vmfleet\scripts\Start-VMFleetTest.ps1 ` - -Profile "Peak" ` - -DurationSeconds 600 ` - -VerboseOutput ----- - -== VMFleet Documentation - -[cols="1,3"] -|=== -| Document | Description - -| link:prerequisites.adoc[Prerequisites] -| VMFleet-specific requirements - -| link:deployment.adoc[Deployment] -| Install and deploy fleet VMs - -| link:workload-profiles.adoc[Workload Profiles] -| Test profiles and execution - -| link:monitoring.adoc[Monitoring] -| Metric collection during tests - -| link:reporting.adoc[Reporting] -| Report generation - -| link:troubleshooting.adoc[Troubleshooting] -| Common issues and solutions -|=== diff --git a/docs/_archived_adoc/tools/vmfleet/prerequisites.adoc b/docs/_archived_adoc/tools/vmfleet/prerequisites.adoc deleted file mode 100644 index f676dc8..0000000 --- a/docs/_archived_adoc/tools/vmfleet/prerequisites.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= VMFleet Prerequisites -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -In addition to the link:../../getting-started/prerequisites.adoc[common prerequisites], VMFleet requires the following. - -== Cluster Storage Requirements - -[cols="1,2"] -|=== -| Requirement | Details - -| Base VHD -| Windows Server 2019+ Server Core VHDX for fleet VMs - -| Collect Volume -| 200GB+ ReFS volume named "Collect" for VMFleet result aggregation - -| CSV Space -| Sufficient free space on CSVs for fleet VMs (count × memory + data disk) -|=== - -== Software Requirements - -[cols="1,2"] -|=== -| Requirement | Details - -| VMFleet Module -| PowerShell VMFleet module (`Install-Module -Name VMFleet`) - -| DiskSpd -| Included with VMFleet; no separate installation required -|=== - -== Validation - -Run pre-checks to verify VMFleet-specific readiness: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Install-VMFleet.ps1 ` - -ClusterConfig "config/clusters/my-cluster.yml" ` - -PreCheckOnly ----- - -Checks performed: - -* Cluster node connectivity via WinRM -* Storage Spaces Direct health status -* Required CSV volumes exist and are online -* Base VHD file exists and is accessible -* Sufficient disk space for fleet VMs -* VMFleet PowerShell module availability diff --git a/docs/_archived_adoc/tools/vmfleet/reporting.adoc b/docs/_archived_adoc/tools/vmfleet/reporting.adoc deleted file mode 100644 index 4df6b5e..0000000 --- a/docs/_archived_adoc/tools/vmfleet/reporting.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= VMFleet Reporting -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -The reporting subsystem generates comprehensive VMFleet test reports in three formats: PDF, Word (DOCX), and Excel (XLSX). - -== Report Formats - -[cols="1,2,2"] -|=== -| Format | Tool | Use Case - -| PDF -| asciidoctor-pdf with custom theme -| Executive summaries, formal documentation, archival - -| DOCX (Word) -| Pandoc (AsciiDoc → DocBook → DOCX) -| Editable reports, stakeholder collaboration - -| XLSX (Excel) -| PowerShell ImportExcel module -| Data analysis, pivot tables, custom charting -|=== - -== Generating Reports - -[source,powershell] ----- -# Generate all three formats from a completed test run -Import-Module ./src/core/powershell/modules/ReportGenerator/ReportGenerator.psm1 - -New-TestReport ` - -RunId "run-2026-02-13-001" ` - -ResultsPath "results/run-2026-02-13-001/" ` - -OutputPath "reports/run-2026-02-13-001/" ` - -Formats @("PDF", "DOCX", "XLSX") ` - -IncludeMetrics ` - -ClusterConfig "config/clusters/my-cluster.yml" ----- - -Or generate reports as part of the results collection: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Collect-VMFleetResults.ps1 ` - -ResultsPath "results/current-run/" ` - -GenerateReports ` - -ReportFormats @("PDF", "DOCX", "XLSX") ----- - -== PDF / DOCX Report Sections - -Both PDF and DOCX reports contain the same sections: - -. *Cover Page* — Cluster name, test date, run ID, framework version -. *Executive Summary* — Key findings, pass/fail assessment, top-line metrics -. *Cluster Configuration* — Node details, storage layout, network configuration -. *Test Results by Profile* — For each workload profile: - ** IOPS (read/write/total) - ** Throughput (MB/s) - ** Latency (average, P50, P95, P99) - ** Per-node breakdown -. *Storage Metrics* — Time-series charts for CSVFS counters -. *Network Metrics* — RDMA/SMB throughput, packet loss summary -. *Compute Metrics* — Host and guest CPU utilization -. *Recommendations* — Automated assessment based on metric thresholds -. *Appendix* — Raw configuration, full variable dump, log excerpts - -== Excel Report - -The XLSX workbook contains multiple worksheets: - -[cols="1,3"] -|=== -| Sheet | Contents - -| Summary -| Executive summary with key metrics, conditional formatting (red/yellow/green) - -| Storage Metrics -| IOPS, throughput, latency time-series data with line charts - -| Network Metrics -| RDMA/SMB throughput, packet loss data with charts - -| Compute Metrics -| CPU/memory utilization data with charts - -| Profile Comparison -| Side-by-side comparison across workload profiles (pivot table) - -| Raw Data -| Complete metric dump for custom analysis -|=== - -== Custom Themes - -The PDF report uses a custom AsciiDoc theme defined in `docs/themes/azurelocal-theme.yml`: - -[source,yaml] ----- -extends: default -page: - margin: [0.75in, 0.75in, 0.75in, 0.75in] - size: A4 -base: - font-family: Segoe UI - font-size: 10 -heading: - font-color: #0078D4 - font-family: Segoe UI Semibold -title-page: - logo-image: image:azure-local-logo.png[width=200] ----- - -== Report Templates - -Templates in `reports/templates/` define the structure: - -* `report-template.adoc` — AsciiDoc template with attribute placeholders for test data -* `cover-page.adoc` — Separated cover page for PDF output -* `excel-template.xlsx` — Pre-formatted Excel workbook with headers, styles, chart templates diff --git a/docs/_archived_adoc/tools/vmfleet/troubleshooting.adoc b/docs/_archived_adoc/tools/vmfleet/troubleshooting.adoc deleted file mode 100644 index 3a91095..0000000 --- a/docs/_archived_adoc/tools/vmfleet/troubleshooting.adoc +++ /dev/null @@ -1,178 +0,0 @@ -= VMFleet Troubleshooting -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -This guide covers common VMFleet issues and their resolutions. - -== Fleet VMs Fail to Start - -*Symptom:* `New-Fleet` completes but VMs remain in "Off" state. - -*Possible Causes:* - -* Insufficient memory on cluster nodes for the configured VM count -* Base VHD file is corrupted or inaccessible -* CSV volume is full - -*Resolution:* - -[source,powershell] ----- -# Check available memory per node -Invoke-Command -ComputerName $ClusterNodes -ScriptBlock { - Get-Counter '\Memory\Available MBytes' | Select-Object -ExpandProperty CounterSamples -} - -# Reduce VM count or memory per VM -.\Deploy-VMFleet.ps1 -VmCountPerNode 5 -VmMemoryGb 1 ----- - -== DiskSpd Results Show Zero IOPS - -*Symptom:* Test completes but IOPS, throughput, and latency are all zero. - -*Possible Causes:* - -* Fleet VMs have no data disk or DiskSpd target file -* VMFleet Collect volume is not properly configured -* DiskSpd binary is not accessible inside VMs - -*Resolution:* - -[source,powershell] ----- -# Verify fleet status -Get-FleetVM | Format-Table Name, State, ComputerName - -# Check Collect volume -Get-ClusterSharedVolume | Where-Object Name -like "*Collect*" ----- - -== Pipeline Fails Mid-Execution - -*Symptom:* Orchestrator exits with an error during a specific phase. - -*Resolution:* - -. Check the orchestration log: `logs/orchestrator/` -. Check the phase-specific log: `logs/vmfleet/` -. Review the state file: `state/run-state.json` to identify the failed phase -. Fix the issue and resume: - -[source,powershell] ----- -.\Invoke-VMFleetPipeline.ps1 -ClusterConfig "config/clusters/my-cluster.yml" -Resume ----- - -== Configuration Issues - -=== Schema Validation Fails - -*Symptom:* `Export-SolutionConfig` reports schema validation errors. - -*Resolution:* - -. Check `master-environment.yml` for syntax errors (use `yamllint`) -. Verify all required fields are present for each variable -. Run schema validation: - -[source,powershell] ----- -.\src\core\powershell\helpers\Initialize-Environment.ps1 -ValidateOnly ----- - -=== Solution JSON Not Generated - -*Symptom:* Files in `config/variables/solutions/` are empty or outdated. - -*Resolution:* - -[source,powershell] ----- -# Regenerate all solution configs -Import-Module ./src/core/powershell/modules/ConfigManager/ConfigManager.psm1 -Export-SolutionConfig -Solution "vmfleet" ----- - -== Credential Issues - -=== Key Vault Access Denied - -*Symptom:* `Get-ManagedCredential -Source KeyVault` returns 403 Forbidden. - -*Resolution:* - -* Verify the service principal or managed identity has `Get` secret permission on the Key Vault -* Check `config/credentials/keyvault-config.yml` for correct vault name -* Ensure Azure authentication: `Connect-AzAccount` - -=== Interactive Credential Prompt Not Appearing - -*Symptom:* Script hangs when using `-CredentialSource Interactive` in non-interactive context. - -*Resolution:* - -* Use `-CredentialSource KeyVault` or `-CredentialSource Parameter` in CI/CD pipelines -* Pass credentials explicitly: `-Credential (Get-Credential)` - -== Monitoring Issues - -=== No Metrics Collected - -*Symptom:* Metric files in `results/{run-id}/metrics/` are empty. - -*Possible Causes:* - -* WinRM connectivity lost during collection -* Performance counter set not available on target nodes -* Insufficient permissions for remote `Get-Counter` - -*Resolution:* - -[source,powershell] ----- -# Test remote counter access -Invoke-Command -ComputerName $NodeName -ScriptBlock { - Get-Counter '\Processor(_Total)\% Processor Time' -SampleInterval 1 -MaxSamples 1 -} ----- - -== Log Locations - -[cols="1,2"] -|=== -| Component | Log Path - -| Orchestrator -| `logs/orchestrator/` - -| VMFleet -| `logs/vmfleet/` - -| Monitoring -| `logs/monitoring/` - -| Report Generation -| `logs/reports/` - -| Configuration -| `logs/orchestrator/` (config operations logged with orchestration) -|=== - -All logs use JSON-lines format. Use PowerShell to filter: - -[source,powershell] ----- -# Find all errors in VMFleet logs -Get-Content logs/vmfleet/*.jsonl | ConvertFrom-Json | Where-Object Severity -eq "ERROR" ----- diff --git a/docs/_archived_adoc/tools/vmfleet/workload-profiles.adoc b/docs/_archived_adoc/tools/vmfleet/workload-profiles.adoc deleted file mode 100644 index f83de2b..0000000 --- a/docs/_archived_adoc/tools/vmfleet/workload-profiles.adoc +++ /dev/null @@ -1,125 +0,0 @@ -= VMFleet Workload Profiles -:toc: left -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:imagesdir: ../../images -:project-name: Azure Local Load Testing Framework -:project-repo: https://github.com/AzureLocal/azurelocal-loadtools - -image:https://img.shields.io/badge/Tool-VMFleet-0078D4?style=flat-square[Tool: VMFleet] -image:https://img.shields.io/badge/Category-Tool%20Guide-3498DB?style=flat-square[Category: Tool Guide] - -This guide covers the predefined workload profiles for VMFleet testing and how to execute them. - -== Built-in Profiles - -.Workload Profiles -[cols="1,3"] -|=== -| Profile | Description - -| General -| Balanced 70/30 read/write, 70% random, 8K blocks — general purpose validation - -| Peak IOPS -| 100% random 4K reads — maximum IOPS measurement - -| VDI -| Mixed small block I/O simulating Virtual Desktop Infrastructure patterns - -| SQL OLTP -| 8K random read/write mix simulating SQL Server OLTP workloads -|=== - -== Running Tests - -=== Single Profile - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Start-VMFleetTest.ps1 ` - -Profile "General" ` - -DurationSeconds 300 ----- - -=== Multiple Profiles (Sweep) - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Start-VMFleetTest.ps1 ` - -Profiles @("General", "Peak", "VDI", "SQL") ` - -DurationSeconds 300 ----- - -== Profile Configuration - -Profiles are defined in `config/profiles/vmfleet/`: - -[source,yaml] ----- -# config/profiles/vmfleet/general.yml -profile: - name: "General" - description: "Balanced read/write workload for general validation" - parameters: - block_size: "8k" - write_ratio: 30 - random_ratio: 70 - outstanding_io: 8 - threads_per_vm: 2 - duration_seconds: 300 - warmup_seconds: 60 ----- - -=== Profile Parameters - -[cols="1,2,1"] -|=== -| Parameter | Description | Example - -| `block_size` -| I/O block size -| `4k`, `8k`, `64k` - -| `write_ratio` -| Percentage of I/O that is writes (0–100) -| `30` for 70/30 read/write - -| `random_ratio` -| Percentage of I/O that is random (0–100) -| `70` for mostly random - -| `outstanding_io` -| I/O queue depth per thread -| `8` - -| `threads_per_vm` -| DiskSpd threads per fleet VM -| `2` - -| `duration_seconds` -| Test duration (excluding warmup) -| `300` - -| `warmup_seconds` -| Warmup before measurement starts -| `60` -|=== - -== Collecting Results - -After tests complete, parse DiskSpd XML output and aggregate metrics: - -[source,powershell] ----- -.\src\solutions\vmfleet\scripts\Collect-VMFleetResults.ps1 ` - -ResultsPath "results/current-run/" ----- - -== Next Steps - -* link:monitoring.adoc[Monitoring] — Metric collection during tests -* link:reporting.adoc[Reporting] — Generate reports from results diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 1b71e79..b43f28f 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -8,7 +8,7 @@ The Azure Local Load Testing Framework is organised into five layers that take a ## Five-Layer Stack -![Five-Layer Architecture](../assets/diagrams/solution-architecture.drawio) +![Solution Architecture](../assets/diagrams/solution-architecture.drawio) ---