Skip to content

Conventions

Adopted July 2026 with the greenfield rebuild. Grounded in: HashiCorp standard module structure & style guide, Google Cloud "Best practices for Terraform", AWS Prescriptive Guidance, Argo CD official bootstrapping guidance, and Microsoft CAF naming.

Placement

See CLAUDE.md for the decision tree ("what applies it?" decides the layer), or invoke the where skill. New directory shapes require an ADR in docs/adr/.

Terraform

  • Modules (terraform/modules/<cloud>/<name>/): README + main/variables/outputs/versions.tf
  • examples/. No provider blocks, no backend, no env assumptions, minimum version constraints (>=). Every variable typed + described; env-specific inputs have no default. Never wrap a single resource in a module.
  • Stacks (terraform/stacks/<cloud>/<system>/<env>/): one root directory per environment, one state per root, thin (locals + module calls). Tight pins (~>), committed .terraform.lock.hcl. No CLI workspaces; environments are directories, never branches.
  • State: azurerm backend, dedicated storage account, use_oidc + use_azuread_auth (Entra RBAC, no access keys). Key mirrors path: <cloud>/<system>/<env>.tfstate.
  • Naming: HCL in snake_case, this for sole instances, never repeat the resource type in its name. Azure resources follow CAF: {abbrev}-{workload}-{env}-{region}.
  • Tags on everything: owner (email), project, environment, expiry (ISO date or none), managed_by = "terraform" — via local.common_tags.

Kubernetes / GitOps

  • Argo CD, pull-based. One manually-applied root Application (kubernetes/bootstrap/); everything else generated by ApplicationSets (kubernetes/appsets/) using git-directory + cluster generators.
  • Apps: kustomize base/ + overlays/<env>/; third-party helm charts inflated via kustomize helmCharts: with pinned versions. Split overlay patches by concern (version / replicas / settings) so promotion = copying a file between env folders.
  • Per-cluster enablement is a directory under kubernetes/clusters/<cluster>/ — a reviewable PR, not a CLI action. The directory name IS the Argo cluster name: cluster-generated ApplicationSets set destination.name from it, every cluster is a cluster Secret of that name (the hub registers itself as aks-dev in kubernetes/appsets/cluster-aks-dev.yaml), clusters are aks-<env>, and a ticket's env is its cluster minus aks-. CI rejects a ticket whose env or cluster does not fit, and any hardcoded remote server URL. vclusters are chart values under kubernetes/vcluster/, registered as Argo destinations via external-secrets.
  • Secrets: External Secrets Operator only. Git holds ExternalSecret references; values live in Azure Key Vault. Never a Secret manifest with a secret value, never sealed blobs. One shape is exempt because it holds no value ESO could fetch: an Argo cluster registration (argocd.argoproj.io/secret-type: cluster) carrying only a name, a server URL and a credential-free config — the hub's own kubernetes/appsets/cluster-aks-dev.yaml (Argo uses its ServiceAccount for the in-cluster address) and remote clusters on the argocd-repos rail via execProviderConfig (workload identity), e.g. kubernetes/infrastructure/argocd-repos/base/cluster-aks-staging.yaml. CI rejects a cluster Secret with a token, password, client key or secret-bearing exec env (destination-contract check in scripts/ci/k8s-validate.sh).

Tenancy — namespaces & ownership (ADR-0004)

Kubernetes namespaces are flat; tenant organization is imposed by three layers:

  • Prefix (human layer): every tenant registers a namespace prefix (screamingface → sf-); every namespace of theirs is <prefix>-*. Owner readable in any kubectl get ns.
  • Labels (machine layer): every tenant namespace carries openmined.org/tenant: <tenant> + openmined.org/managed-by: tenant-construct. Everything scopes on the label, not the name: NetworkPolicy namespaceSelectors, observability leasehold, cost attribution, admission policies.
  • Registry + fence (truth layer): kubernetes/tenants/<t>/namespaces.yaml is the tenant's namespace registry; the AppProject's destinations is its enforcement. A namespace's birth and the permission to use it land in the same PR.

Ownership split — the platform owns the boundaries, the tenant fills them:

Platform-owned (via the tenant-projects carrier, project: default) Tenant-railed (via the tenants ApplicationSet, project: <tenant>)
AppProject (the fence) workloads (Deployments/Services/Jobs…)
Namespaces (explicit manifests in the registry — tenant rails have NO CreateNamespace) NetworkPolicies inside their namespaces
edge/enforcement CRs (HTTPRoute/SecurityPolicy/BTP — never tenant-authored, ADR-0005 §5) ExternalSecret references
cluster-scoped anything (denied to tenants outright) their values/config
  • Namespace creation is platform-gated: the only path to a registered namespace is a reviewed PR touching registry + fence, applied by the carrier. Tenants have no organic creation path at all — the fence denies cluster-scoped kinds and the tenant rails carry no CreateNamespace. The PLATFORM rails (infrastructure, platform-apps) do set CreateNamespace=true, so a namespace can also appear as a side effect of a ticket — bare, off the registry. That is a gap to close, not a second sanctioned path; the carrier below is what closes it.
  • One carrier per cluster, one registry file. tenant-projects carries the fences and the registry to the hub; every remote cluster gets the registry from its own Application (kubernetes/appsets/tenant-namespaces-aks-<env>.yaml, include: "*/namespaces.yaml" — AppProjects are Argo CD CRs and stay on the hub). Without that carrier the cluster's tenant namespaces stay as CreateNamespace=true left them: no labels, so every label-selecting guardrail matches nothing and Pod Security falls back to privileged.
  • Backstop (before a 2nd independently-controlled tenant): the Kyverno admission policy asserts prefix + label + fence-membership (same policy as hostname ownership).
  • Pressure valve: a tenant needing many/self-service namespaces is ADR-0004 §5's vcluster trigger — their sprawl lives inside their vcluster, not our flat list.

CI/CD

  • Workflows are thin triggers; logic lives in scripts/ci/ so humans and CI run the same script. Path-filtered per layer.
  • Terraform: the generic pull-request lane runs credentialless format, validation, and contract checks. This lane does not receive Azure OIDC or run provider-backed plans. Non-production roots plan and apply after merge. Production roots use the two-phase saved-plan dispatch, bound to stack, commit, lock, checksum, state, and plan run (verified live 2026-09-09). Per-stack concurrency prevents overlapping applies. Protected main and approved dispatch jobs use the apply identity.
  • Kubernetes: every kustomize leaf rendered + kubeconform -strict on PR. Deploy is Argo CD syncing main — there is no k8s deploy workflow.
  • Secret scanning: gitleaks on every PR and push.

Security

  • Never commit: secrets, tfstate, tfvars (.tfvars.example only), kubeconfigs.
  • No 0.0.0.0/0 on management ports (SSH/RDP); prefer Azure Bastion.
  • Service principals scoped to a resource group, never subscription Owner. Subscription Owner is for a small human break-glass set only.

Skills

Repeatable procedures are Claude Code skills in .claude/skills/ (committed, shared by everyone incl. CI agents): /new-module, /new-stack, /new-k8s-app (scaffolding — manual-invocation only), /where (placement), /cost-sweep, /access-audit (ops). A procedure done more than twice with consistency requirements becomes a skill; update the skill when a convention changes — skills are the executable form of this doc.

Milestone lifecycle — how big work becomes shipped work

ADR-0009 defines the repository-native lifecycle for registered delivery programs under docs/programs/. Routine fixes, dependency updates, and authorized automation use the normal tracked pull-request path. They do not need a program work package. Human-authored work uses Asana. Authorized automation links its generator run.

docs/programs/GOVERNANCE.md defines the user workflow. Generic record shapes live under docs/programs/_templates/. Agents must use the new-program skill when they classify, create, amend, or audit a program.

A package becomes implementation authority only after its approved record lands on origin/main. CI validation never replaces the owner's approval.

  1. Program — docs/programs/<program>/README.md names one current milestone and one decision route.
  2. Milestone gate — the milestone states its entry criteria, approved scope, exclusions, exit evidence, rollback, and sign-off.
  3. Architecture decision — a new architecture decision requires an ADR. The program links the ADR and cannot override it.
  4. Solidity check — independent review tries to disprove load-bearing claims before implementation. Verified refutations amend the package.
  5. Work packages — one durable package per measurable result, landing, rollback boundary, and evidence set.
  6. Asana mapping — one Asana task per approved package. Asana owns status, assignee, priority, and dependencies.
  7. Implementation — one implementation package per worktree and normally one pull request. Shared states and trust boundaries run in sequence.
  8. Verification — CI and dated post-change evidence prove the package's exact acceptance criteria.
  9. Close — the package links the pull request, commit, tests, runtime proof, rollback result, deviations, and owner acceptance. The ledger records the merged historical result.

The current milestone receives executable work packages.

The immediate next milestone can contain detailed packages at proposed maturity. This supports dependency and rollback review at the current exit gate. Those packages cannot advance beyond proposed before their milestone becomes ready or active.

All later milestones stay as outlines until their prior exit gates pass.

Personal analyses and drafts can support review. They do not authorize work and cannot override repository program records.