Platform Engineering¶

Platform engineering is the discipline of building the shared foundation that workload teams build on — the management group hierarchy, subscription factory, identity model, and shared services that make it possible for development teams to operate quickly and safely.

Landing Zone: the tenant's foundation

Security Model: the tiering rules and delivery lanes everything else follows

Azure Access Management: who and what gets access

Networking: shared connectivity, addressing, DNS and egress

Governance: policy, standards, logging, evidence and exceptions

Security Operations: detecting, responding to and preventing threats

Operations: keeping the platform running and recoverable

FinOps: budgets, cost allocation and cost control

Infrastructure as Code: how the Terraform is structured and where state lives

Platform Lifecycle: onboarding, identities, decommissioning and upgrades

External and reference

What the platform team owns¶

The platform team is responsible for the infrastructure that every other team depends on. This is not application code — it is the foundation layer that provides governance, security boundaries, networking, and identity to workload teams.

Root of trust & governance

Foundational tenant bootstrap (azure-tenant-bootstrap) establishing the central state backend and root identities
Management group hierarchy aligned to the Microsoft CAF enterprise-scale pattern
Azure Policy assignments at management group scope to enforce organisational standards
Subscription lifecycle — creation, naming, placement, and decommissioning

Identity & access

Central service principal vending (azure-service-principals) operating under Lane A for platform pipelines, tools, and vendors
Entra ID security groups for platform-level human access (engineers, FinOps, read-only)
Tiered reader access patterns (estate-wide, archetype MGs, per-subscription, and JIT PIM)
Per-subscription RBAC groups provisioned automatically as part of subscription vending
Federated OIDC credentials for all Terraform pipelines — no secrets stored anywhere

Shared services (in progress)

Hub networking — VNets, ExpressRoute, DNS, firewalls
Central logging — Log Analytics workspace
Budget alerts per subscription

How it is built: The Dual-Lane Operational Model¶

Everything the platform team manages is defined in code and deployed via GitLab CI/CD pipelines using Terraform. To reconcile automation velocity with the zero standing privilege mandate of Microsoft EAM and NIST SP 800-53, deployments are strictly bifurcated into a dual-lane delivery model:

Lane A (Control Plane / Tier 0): Used for foundational repositories (azure-tenant-bootstrap, azure-service-principals, azure-privileged-access-grants). Automated CI is strictly Plan-Only using a scoped read-only machine identity (sp-pla-tf-*-ro), and saves the plan on main. Automated apply is permanently omitted from pipeline configurations and local plans are blocked. A PIM-elevated engineer applies the merged commit's saved plan with apply-merged — never local files.
Lane B (Management & Workload Planes / Tiers 1 & 2): Standard GitOps Automation. Merge requests run automated validation and plan; merging to main automatically triggers terraform apply via scoped Workload Identity Federation (OIDC) machine identities (sp-*-rw) bounded to specific management groups or workload subscriptions.

flowchart TD
    subgraph LANE_A["Lane A: Control Plane (Tier 0 — Human Gated)"]
        ROOT["azure-tenant-bootstrap<br/>(Bootstrap state & seed identities)"]
        SPV["azure-service-principals<br/>(Vend platform & tool SPs)"]
        PAG["azure-privileged-access-grants<br/>(Persona groups, directory roles, Tier 0 RBAC)"]
        ROOT -->|Central state & seed SP| SPV
    end

    subgraph LANE_B["Lane B: Management & Workloads (Tiers 1 & 2 — Automated GitOps)"]
        MG["azure-management-groups<br/>(Management group hierarchy)"]
        ID["azure-privileged-access-packages<br/>(PIM policies & access packages)"]
        PAG -->|Groups looked up by name| ID
        SUB["subscription-vending-workload / -platform<br/>(Subscription factory)"]
        WL["workload deployments<br/>(App services, databases, networks)"]

        ROOT -->|Scoped Management Groups SP| MG
        SPV -->|Platform Pipeline SPs| SUB
        SUB --> WL
    end

    LANE_A -.->|Vends bounded identities & state backends| LANE_B

Each deployment project has its own service principal with scoped permissions — the platform team's Terraform pipelines can only touch what they need to touch. See the comprehensive Lane A and Lane B Delivery Methodology for full architecture, decision matrices, preflight safeguards, and threat modeling.

IaC Architecture & 3-Tier Module Taxonomy¶

All Terraform code managed by the platform team and consumed by workload teams is structured according to a strict 3-Tier Module Taxonomy:

Tier 1 — Resource Modules (terraform-azure-modules/): Stateless, single-resource wrappers that enforce opinionated security baselines (TLS 1.2+, private endpoints, CAF naming conventions, and ADR-0001 provenance tagging).
Tier 2 — Solutions (terraform-solutions/): Pre-assembled "Golden Paths" that compose multiple Tier 1 modules into business services (e.g., solution-manage-azure-subscription, solution-manage-resource-group). Solutions enforce organizational policy by default (such as non-negotiable delete locks and Defender for Cloud plans) while dramatically reducing cognitive load for developers.
Tier 3 — Deployments (deployments/): Environment- and subscription-specific leaf configurations that map code to dedicated remote state storage. Deployments are operationalized via Lane A (Tier 0 control plane, human PIM gated) or Lane B (automated GitOps via Workload Identity Federation).

See the comprehensive 3-Tier Terraform Module Taxonomy: Architecture & Governance guide for design rules, the "Rule of Two" bypass governance, and declarative refactoring with moved {} blocks.

Design principles¶

Everything in code. No resource exists without a Terraform source. If it cannot be version-controlled, it should not be created.

Least privilege. Every service principal has the minimum permissions needed. Roles are scoped as narrowly as possible — container-level for state, subscription-level for workload deployment, management-group-level for platform governance.

Separation of concerns. Management group hierarchy, subscription vending, and identity management are three separate deployments with three separate service principals. A credential compromise in one cannot affect the others.

Predictable structure. Every subscription gets the same RBAC group structure, the same state storage pattern, and the same pipeline scaffold. Workload teams know what to expect before they write a single line of code.

CAF alignment. The hierarchy, naming conventions, and governance model follow the Microsoft Cloud Adoption Framework enterprise-scale architecture — proven patterns rather than bespoke designs.