Azure From Zero To Hero Architecture Plan¶
This plan describes how the repository is organized today and how improvements should preserve the learning path while strengthening quality, security, and validation.
Current Architecture¶
Azure From Zero To Hero is a folder-per-lesson Terraform curriculum. Each
CLZ-* folder has focused configuration, inputs, outputs, example values, and a
README. Local-only and readiness lessons declare no Azure provider/resources;
deployable lessons normally own their Azure lifecycle. CLZ-320 intentionally
consumes the backend outputs produced by CLZ-310.
| Layer | Current role |
|---|---|
| Root README and book PDF | Entry point for learners and the free companion book |
CLZ-* lesson folders |
Hands-on Terraform labs in curriculum order |
modules/ |
Small reusable modules introduced late in the path |
scripts/ |
Windows/PowerShell validation and setup helpers |
.github/workflows/ |
Validation-only CI for Terraform and repository quality |
wiki/ |
Reference material for concepts, security, state, tooling, and troubleshooting |
Target Architecture¶
The target architecture keeps early lessons explicit so beginners can see every resource relationship. Reuse increases only after the learner has seen the pattern directly.
| Curriculum phase | Architecture intent |
|---|---|
| CLZ-090 to CLZ-160 | Tooling, Terraform workflow, variables, tags, and state basics stay direct and readable |
| CLZ-170 to CLZ-250 | Network, NSG, Windows VM, IIS, Bastion, Load Balancer, count, and for_each stay mostly explicit |
| CLZ-260 to CLZ-270 | VMSS and Load Balancer patterns can use modules/windows-iis-vmss while lesson-specific scaling logic remains visible |
| CLZ-280 to CLZ-380 | Platform services stay direct unless a repeated pattern becomes distracting |
| CLZ-390 | Capstone composes stable modules and final reference architecture resources |
Module boundaries should stay small. A module is acceptable only when it removes repeated infrastructure code without hiding the concept being taught in that lesson.
Validation Architecture¶
The repository has two validation paths:
| Path | Purpose |
|---|---|
| Local script | scripts/Test-AzureFromZeroToHeroTerraform.ps1 runs formatting, readonly initialization, validation, and mock-provider tests with JSON report output |
| CI workflow | .github/workflows/terraform-validate.yml runs credential-free Terraform validation/tests and repository quality checks on pull requests and main |
The default CI path remains credential-free and never runs Azure plans or applies. Cloud planning is a deliberate local action with Azure CLI and an explicit subscription ID, or the separately documented manual OIDC example in CLZ-370. Owned public DNS and remote-state consumers require their documented targeted context rather than generic CI assumptions.
Security Architecture¶
Security is taught as a progression:
| Stage | Pattern |
|---|---|
| Early Windows lessons | Direct access is temporary and scoped with admin_cidr |
| Bastion lesson and later | RDP moves to private management through Azure Bastion |
| Key Vault lesson | Generated credentials move into central secret storage |
| Private endpoint lessons | Storage and SQL move away from public service access |
| CI | Validation-only workflow avoids apply credentials by default |
Direct RDP examples exist to teach the resource model. They are not the mature end state. The preferred final pattern is private administration through Bastion, private endpoints for data services, narrow input values, protected Terraform state, and cleanup after every lab.
Reproducibility Architecture¶
Every lesson remains independently readable from its own folder. Azure deployments are self-contained except for explicit cataloged dependencies such as the CLZ-310 backend and CLZ-320 consumer. Runtime Terraform files stay local and ignored:
| File or folder | Policy |
|---|---|
.terraform/ |
Generated locally or in CI, not committed |
.terraform.lock.hcl |
Committed for every Terraform root with Windows and Linux AMD64 checksums |
terraform.tfvars |
Local-only user values, not committed |
terraform.tfvars.example |
Safe committed defaults |
*.tfplan and state files |
Local runtime data, not committed |
This keeps the repository clean for learners while allowing CI and local runs to reinitialize each lesson as needed.
Learner Flow¶
- Read the free companion book for the conceptual path.
- Start at the root README and confirm workstation readiness.
- Run lessons in CLZ order.
- Review each lesson README, variables, and plan before apply.
- Capture outputs only when needed for validation or the next lesson.
- Destroy lab resources after validation.
- Use the wiki pages for deeper reference and troubleshooting.
The architecture goal is not maximum abstraction. The goal is a repeatable Windows-first Azure Terraform learning path that becomes more modular, private, and operationally disciplined as the learner advances.
For the capstone deployment design, see the Final Reference Architecture Plan.