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,
thisfor 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 ornone),managed_by = "terraform"— vialocal.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 kustomizehelmCharts: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 setdestination.namefrom it, every cluster is a cluster Secret of that name (the hub registers itself asaks-devinkubernetes/appsets/cluster-aks-dev.yaml), clusters areaks-<env>, and a ticket'senvis its cluster minusaks-. CI rejects a ticket whose env or cluster does not fit, and any hardcoded remote server URL. vclusters are chart values underkubernetes/vcluster/, registered as Argo destinations via external-secrets. - Secrets: External Secrets Operator only. Git holds
ExternalSecretreferences; 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 ownkubernetes/appsets/cluster-aks-dev.yaml(Argo uses its ServiceAccount for the in-cluster address) and remote clusters on theargocd-reposrail viaexecProviderConfig(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 inscripts/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 anykubectl 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: NetworkPolicynamespaceSelectors, observability leasehold, cost attribution, admission policies. - Registry + fence (truth layer):
kubernetes/tenants/<t>/namespaces.yamlis the tenant's namespace registry; the AppProject'sdestinationsis 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 setCreateNamespace=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-projectscarries 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 asCreateNamespace=trueleft them: no labels, so every label-selecting guardrail matches nothing and Pod Security falls back toprivileged. - 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
mainand approved dispatch jobs use the apply identity. - Kubernetes: every kustomize leaf rendered +
kubeconform -stricton PR. Deploy is Argo CD syncingmain— there is no k8s deploy workflow. - Secret scanning: gitleaks on every PR and push.
Security
- Never commit: secrets, tfstate, tfvars (
.tfvars.exampleonly), kubeconfigs. - No
0.0.0.0/0on 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.
- Program —
docs/programs/<program>/README.mdnames one current milestone and one decision route. - Milestone gate — the milestone states its entry criteria, approved scope, exclusions, exit evidence, rollback, and sign-off.
- Architecture decision — a new architecture decision requires an ADR. The program links the ADR and cannot override it.
- Solidity check — independent review tries to disprove load-bearing claims before implementation. Verified refutations amend the package.
- Work packages — one durable package per measurable result, landing, rollback boundary, and evidence set.
- Asana mapping — one Asana task per approved package. Asana owns status, assignee, priority, and dependencies.
- Implementation — one implementation package per worktree and normally one pull request. Shared states and trust boundaries run in sequence.
- Verification — CI and dated post-change evidence prove the package's exact acceptance criteria.
- 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.