Code¶

The code repository xms-cloud-platform-code holds everything that is the same for every customer. This section covers what tools it uses, how it provisions the platform, and how to build and release new functionality.

Page	Covers
This page	What tools we use, and the repository layout
Provisioning	How to provision: infra (job runners), container, layers per environment and region
Releases and upgrades	Release history, upgrade guides per version and the generic update runbook
Deployment layers	The Terraform layers, their order and their state
Spoke canvas	What a spoke deployment creates: resources, groups, service principal credentials, required permissions
Spoke canvas module reference	Inputs, outputs and modules of the spoke Terraform, grouped by purpose
Pipelines and workflows	Every entry pipeline, its parameters, modes and approvals
Building new functionality	Modules, tests, deploying to dev, workflow/pipeline, PR + CI
Releasing	Versions, workflow steps, release notes and upgrade guides

What tools we use¶

Tool	Version (on `main`)	Used for
Terraform	1.14.4 (`src/Dockerfile`)	All hub layers (`infra/`) and the spoke canvas (`src/Xebia.Mcp/Files/terraform/spoke-canvas/`)
azurerm / azapi providers	Exact pins per root module (azurerm 4.60.0 at the time of writing)	Azure resources. Pins are checked by `scripts/Test-TerraformRootProviderPins.ps1`.
PowerShell 7 + module `Xebia.Mcp`	–	All orchestration: config resolution, plan/apply/analyse actions, region matrix, tests (`src/Xebia.Mcp`)
Pester	–	Unit tests (`*.Unit.Tests.ps1` next to each function) and config tests (`src/Xebia.Mcp/Tests/`)
Terraform test	–	Module tests (`infra/modules/<name>/tests/*.tftest.hcl`, with `mock_provider`)
Bicep	–	Job runner infrastructure (`src/Xebia.Mcp/Files/bicep/deploy/initialize/`)
Docker	–	The `mcp` image all pipelines run in (`src/Dockerfile`)
Azure CLI	2.87.0 (dev container)	Login and Azure operations from the module
GitVersion	–	Semantic versions from branches and merge messages (`.GitVersion.yml`)
lefthook	–	Pre-commit hooks: `terraform validate`, `terraform-docs`, `terraform test` for changed modules, provider pin check (`lefthook.yml`)
terraform-docs	–	Generates the README of each layer
Dev container	–	The same toolchain locally (`.devcontainer/devcontainer.json`)
Azure DevOps Pipelines and GitHub Actions	–	CI/CD. Kept functionally identical.
JSON Schema (draft-07)	–	Validation of spoke, firewall, App Gateway and WAF JSON (`src/Xebia.Mcp/Files/json/`)

Repository layout¶

xms-cloud-platform-code/
├── infra/
│   ├── deploy/<layer>/        Terraform root module per deployment layer (foundation, connectivity, firewall, …)
│   ├── templates/<name>/      Compositions of modules used by the layers
│   └── modules/<name>/        Single-purpose Terraform modules (firewall, ip_group, application_gateway, policy, …)
├── src/
│   ├── Xebia.Mcp/             PowerShell module with all orchestration logic
│   │   ├── Functions/Public/  Entry functions (Invoke-XebiaHub, Invoke-XebiaSpoke, Invoke-XebiaInfrastructure, …)
│   │   ├── Functions/Private/ Internal helpers (plan/apply/analyse actions, config resolution, tests)
│   │   ├── Files/json/        JSON schemas: spokeschema, firewallschema, appgwschema, wafpolicyschema
│   │   ├── Files/terraform/spoke-canvas/   Terraform for spokes (deploy/subscription, deploy/spoke, modules)
│   │   ├── Files/bicep/deploy/initialize/  Bicep for the job runner infrastructure
│   │   └── Tests/             Config tests (Config, SpokeConfig, Smoke)
│   └── Dockerfile             The "mcp" container image
├── .azure-devops/pipelines/   Azure DevOps entry pipelines and templates/ (stage-*, job-*, step-*)
├── .github/workflows/         GitHub Actions entry workflows and reusable stage-*/job-*/step-* workflows
├── .github/actions/           Composite actions (checkout-mcp-code, git-version, terraform-plan/apply, …)
├── dev/dev.ps1                Local entry point (same functions the pipelines call)
├── config/Demo/canary/        Demo configuration used to develop and test the code
├── scripts/                   Helper scripts (provider pin check, terraform test runner, version-watcher)
└── docs/                      ADRs, coding standards, how-tos

Points that are not obvious from the layout:

The hub Terraform runs from inside the module. Before a run, infra/ is copied into src/Xebia.Mcp/Files/terraform/cloud-platform/ (Sync-XebiaInfraToMcpModule). The container build and dev/dev.ps1 both do this, and the path is in .gitignore. The plan action runs Terraform from terraform/cloud-platform/deploy/<layer>.
The spoke Terraform lives only in the module (src/Xebia.Mcp/Files/terraform/spoke-canvas/), not in infra/.
YAML stays thin. Pipelines call Invoke-XebiaHub, Invoke-XebiaSpoke, Invoke-XebiaInfrastructure and Invoke-XebiaContainer with an -Action (Prepare, Plan, Analyse, Apply, Clean). See ADR-0011.
Public functions are grouped by domain under Functions/Public/: Actions, AzCli, Config, Invocation, Local, Logging, Terraform, Test, Tools, Workflow. (CONTRIBUTING.md still mentions a Runner/ folder that no longer exists.)