How sathishkst82/sathish-az-_trrafom-demo works
1. What this repo is
- This is a Terraform-based Azure platform repository, not an application repo.
- It provisions three Azure environments — dev, uat, and prod — using reusable Terraform modules and GitHub Actions-driven delivery.
2. Top-level architecture boundary
- The repository has two main layers:
- Reusable modules in modules/ for network, VM, storage, and governance.
- Environment stacks in environments/dev, environments/uat, and environments/prod that compose those modules into deployable environments.
- The root also contains shared provider/version config and CI/CD workflows.
3. Environment stacks as deployment units
- Each environment directory is a separate Terraform root module with its own backend, provider config, variables, and outputs.
- These stacks are the actual deployment boundary for Azure state: each environment has its own remote state key and its own resource group, network, compute, storage, and policy assignment footprint.
4. Shared infrastructure modules
- modules/vnet creates the segmented network core: VNET, multiple subnets, NSGs, route tables, and private DNS/VNET link wiring.
- modules/vm provisions Windows compute with private access patterns and managed identity.
- modules/storage provisions hardened storage accounts and containers, with private endpoint/private access support.
- modules/governance creates Azure Policy definitions, initiatives, and assignments.
5. Primary data/infrastructure flow
- The central flow is: environment stack → resource group → platform modules → Azure resources.
- Network is the first dependency because VM and storage modules attach into the environment VNET and subnets.
- Governance is then assigned at the environment resource group level so policy applies across the environment’s resources.
6. Network and segmentation model
- The architecture is private-first and segmented by subnet function.
- Each environment uses a non-overlapping /16 CIDR, with subnet boundaries reserved for management, application, data, private endpoint, and future expansion.
- This layout is intended to support predictable routing, hub/spoke readiness, and private endpoint patterns.
7. Security and governance boundary
- Azure Policy is the governance layer, with custom policies for required tags, allowed regions, and denying public IPs.
- Policies are grouped into a baseline initiative and assigned per environment.
- DEV and UAT are configured for softer adoption, while PROD is enforced more strictly.
- Security controls are also embedded in the platform modules: no public IPs by default, private storage access, TLS/HTTPS protections, and managed identity on VMs.
8. Identity and deployment authentication
- The repo uses GitHub OIDC federation to Azure; there are no long-lived Azure client secrets in the repo.
- GitHub Environments supply Azure client/tenant/subscription context and sensitive inputs like the Windows admin password.
- This makes GitHub Actions the deployment control plane and Azure the target runtime.
9. CI/CD orchestration
- The key workflow is .github/workflows/iac-dispatch.yml, which acts as the entrypoint and dispatches to reusable Terraform workflows.
- The pipeline stages are:
- validation: fmt, init, validate, terraform-docs checks, TFLint
- plan: includes Wiz IaC scanning and plan artifact creation
- apply: reuses the saved plan for deterministic deployment
- destroy-plan / destroy-apply: separate reviewable destroy lifecycle
- PROD apply/destroy is gated by GitHub Environment approval.
10. State and backend architecture
- Every environment uses the AzureRM backend, but backend settings are injected at runtime by the workflow.
- State is therefore externalized to a dedicated Azure storage backend and separated per environment via backend keying.
- This creates a hard boundary between local code and persisted infrastructure state.
11. Testing and quality gates
- The tests/ directory contains Terratest-based validation for at least the VNET module using fixtures.
- The repo also enforces static and policy checks with TFLint, terraform-docs validation, policy JSON checks, and IaC scanning.
- This makes the module boundary testable independently from full environment deployments.
12. Operational documentation and design intent
- The docs/ folder contains architecture, network, OIDC, environment setup, and governance guidance.
- The architecture documentation is not decorative; it reflects the implementation layout and helps explain intended subnetting, policy posture, and deployment workflow.
- The overall design is enterprise platform infrastructure: reusable, environment-scoped, private-by-default, and governed at the Azure control plane.
Main entry points: dev/main.tf Dev stack · uat/main.tf UAT stack · prod/main.tf Prod stack · governance/main.tf Governance module
Components 20
Root
Shared Terraform, providers, and repo entrypoints
- Root config · Shared Terraform provider and version configuration at repository root
providers.tf - Versions · Common Terraform and provider version constraints
versions.tf
Environments
Separate Terraform root modules for dev, uat, and prod
- Dev stack · Terraform root module for the dev environment
environments/dev/main.tf - UAT stack · Terraform root module for the uat environment
environments/uat/main.tf - Prod stack · Terraform root module for the prod environment
environments/prod/main.tf
Modules
Reusable platform modules
- VNet module · Creates segmented private networking, subnets, NSGs, routing, and DNS links
modules/vnet/main.tf - VM module · Provisions Windows virtual machines with managed identity and private access patterns
modules/vm/main.tf - Storage module · Creates hardened storage accounts and containers with private access support
modules/storage/main.tf - Governance module · Creates policy definitions, initiatives, and assignments
modules/governance/main.tf
Governance
Policy definitions used by the governance module
- Tags policy · Custom policy requiring resource tags
governance/require-tags-policy.json - Regions policy · Custom policy restricting allowed Azure regions
governance/allowed-regions-policy.json - Deny IP policy · Custom policy denying public IP usage
governance/deny-public-ip-policy.json
CI/CD
GitHub Actions workflows for validation, planning, and deployment
- Dispatch · Entry workflow that routes infrastructure actions into reusable Terraform workflows
.github/workflows/iac-dispatch.yml - Validate · Runs fmt, init, validate, docs checks, and linting
.github/workflows/terraform-validate.yml - Plan · Creates reviewed Terraform plans and runs IaC scanning
.github/workflows/terraform-plan.yml - Apply · Applies saved plans for deterministic deployment
.github/workflows/terraform-apply.yml - Destroy · Reviewable destroy planning and application flow
.github/workflows/terraform-destroy-plan.yml
Docs & Tests
Architecture docs and module validation tests
- VNet tests · Terratest coverage for the VNet module using fixtures
tests/vnet_test.go - Network docs · Architecture guidance for subnetting, private access, and segmentation
docs/network-architecture.md - OIDC docs · Documentation for GitHub OIDC federation to Azure
docs/oidc-setup.md
Connections 29
- Root config → Dev stack: shared provider · Environment stacks inherit common provider configuration
- Root config → UAT stack: shared provider · Environment stacks inherit common provider configuration
- Root config → Prod stack: shared provider · Environment stacks inherit common provider configuration
- Versions → Dev stack: constraints · Version constraints apply to environment roots
- Versions → UAT stack: constraints · Version constraints apply to environment roots
- Versions → Prod stack: constraints · Version constraints apply to environment roots
- Dev stack → VNet module: uses · Dev composes the shared network module
- Dev stack → VM module: uses · Dev composes the shared compute module
- Dev stack → Storage module: uses · Dev composes the shared storage module
- Dev stack → Governance module: assigns · Dev assigns baseline governance to the environment
- UAT stack → VNet module: uses · UAT composes the shared network module
- UAT stack → VM module: uses · UAT composes the shared compute module
- UAT stack → Storage module: uses · UAT composes the shared storage module
- UAT stack → Governance module: assigns · UAT assigns baseline governance to the environment
- Prod stack → VNet module: uses · Prod composes the shared network module
- Prod stack → VM module: uses · Prod composes the shared compute module
- Prod stack → Storage module: uses · Prod composes the shared storage module
- Prod stack → Governance module: assigns · Prod assigns baseline governance to the environment
- Governance module → Tags policy: loads · Governance module consumes custom policy definitions
- Governance module → Regions policy: loads · Governance module consumes custom policy definitions
- Governance module → Deny IP policy: loads · Governance module consumes custom policy definitions
- Dispatch → Validate: dispatches · Workflow entrypoint sends runs to validation
- Dispatch → Plan: dispatches · Workflow entrypoint sends runs to planning
- Dispatch → Apply: dispatches · Workflow entrypoint sends runs to apply
- Dispatch → Destroy: dispatches · Workflow entrypoint sends runs to destroy lifecycle
- Plan → Apply: saves plan · Apply reuses the reviewed plan artifact
- VNet tests → VNet module: tests · Terratest validates the network module behavior
- Network docs → VNet module: describes · Docs explain the network architecture embodied by the module
- OIDC docs → Dispatch: describes · Docs explain GitHub OIDC-based deployment authentication