From 2890a5cb9e664078bd842b1ad12ec08daaab7cc2 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sat, 14 Nov 2026 18:31:55 +0100 Subject: [PATCH 1/3] refactor(deploy): split the scaffold into base, prod and dev overlays New tenants get production and dev from one deploy/ tree (ADR 0016). The root kustomization is the production entry the platform reconciles at `path: .` and includes only ./prod; base holds what both environments run, prod adds the public route, PDB and OpenBao secrets, and dev patches the base down to one replica without any production identity. The production render is byte-identical to main. The rename helper now covers the overlays, tenant CI and the scaffold gate render deploy/dev, the scaffold gate keeps dev free of production-only objects, and the docs teach the layout. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/cd.yaml | 3 +- .github/workflows/ci.yaml | 2 +- .github/workflows/validate-scaffold.yaml | 35 ++++++++-- .gitignore | 2 +- AGENTS.md | 24 +++++-- Dockerfile | 2 +- README.md | 16 +++-- deploy/{ => base}/cluster.yaml | 0 deploy/{ => base}/deployment.yaml | 4 +- deploy/base/kustomization.yaml | 10 +++ deploy/{ => base}/networkpolicy.yaml | 3 +- deploy/{ => base}/service.yaml | 0 deploy/dev/kustomization.yaml | 23 +++++++ deploy/kustomization.yaml | 15 ++-- deploy/{ => prod}/externalsecret.yaml | 3 +- deploy/{ => prod}/httproute.yaml | 0 deploy/prod/kustomization.yaml | 12 ++++ deploy/{ => prod}/poddisruptionbudget.yaml | 0 deploy/{ => prod}/secretstore.yaml | 0 docs/REFERENCE.md | 58 +++++++++++++--- .../platform-tenant-envelope-contract.test.sh | 4 +- scripts/platform-tenant-envelope.test.sh | 14 ++-- scripts/platform-vpa-floor.test.sh | 14 ++-- scripts/rename-placeholders.sh | 13 ++-- scripts/rename-placeholders.test.sh | 68 +++++++++++++------ scripts/tenant-ci-contract.test.sh | 8 ++- 26 files changed, 249 insertions(+), 84 deletions(-) rename deploy/{ => base}/cluster.yaml (100%) rename deploy/{ => base}/deployment.yaml (97%) create mode 100644 deploy/base/kustomization.yaml rename deploy/{ => base}/networkpolicy.yaml (96%) rename deploy/{ => base}/service.yaml (100%) create mode 100644 deploy/dev/kustomization.yaml rename deploy/{ => prod}/externalsecret.yaml (81%) rename deploy/{ => prod}/httproute.yaml (100%) create mode 100644 deploy/prod/kustomization.yaml rename deploy/{ => prod}/poddisruptionbudget.yaml (100%) rename deploy/{ => prod}/secretstore.yaml (100%) diff --git a/.github/workflows/cd.yaml b/.github/workflows/cd.yaml index 41f72b5..cf1ed91 100644 --- a/.github/workflows/cd.yaml +++ b/.github/workflows/cd.yaml @@ -20,7 +20,8 @@ jobs: uses: devantler-tech/.github/.github/workflows/publish-app.yaml@af042c540ce8db4d64add98c34b5c57691e0e812 # v19.0.5 with: # publish-app pins the freshly built image digest into the container with - # this name in deploy/deployment.yaml. Keep that container's name equal to + # this name in deploy/base/deployment.yaml (deploy/deployment.yaml in a + # tenant without deploy/base/). Keep that container's name equal to # the repository name (the platform's signed-publish convention). app-name: ${{ github.event.repository.name }} # The signature this publish mints carries the `uses:` ref above in its diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index b34ab97..ed86932 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -56,7 +56,7 @@ jobs: shell: bash working-directory: . - name: 🧱 Render tenant manifests - run: kubectl kustomize deploy/ >/dev/null + run: kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null shell: bash working-directory: . diff --git a/.github/workflows/validate-scaffold.yaml b/.github/workflows/validate-scaffold.yaml index 741fbfd..bc48c29 100644 --- a/.github/workflows/validate-scaffold.yaml +++ b/.github/workflows/validate-scaffold.yaml @@ -26,7 +26,8 @@ permissions: {} # this template's core deliverable β€” every new tenant inherits them β€” so a PR that # breaks the kustomization (a renamed/removed resource, a YAML error) must not # merge green and ship broken scaffolding downstream. Eight layers run here: -# 1. schema-validate the deploy/ manifests (a typo'd CRD field that renders +# 1. schema-validate the deploy/ production entry and its dev overlay, and +# keep dev free of production-only objects (a typo'd CRD field that renders # without complaint must fail loudly), and # 2. exercise scripts/rename-placeholders.sh β€” the onboarding script every new # tenant runs first; a botched sed address (a missed file, a corrupted label @@ -373,8 +374,9 @@ jobs: key: kubeconform-crds-${{ env.CRDS_CATALOG_REF }} - name: 🧱 Build & schema-validate deploy/ manifests # kubectl (with embedded kustomize) is preinstalled on ubuntu-latest. Render - # the manifests (a broken kustomization fails the render, not silently - # downstream), then schema-validate every rendered resource with kubeconform β€” + # the production entry and the dev overlay (a broken kustomization fails + # the render, not silently downstream), then schema-validate every + # rendered resource with kubeconform β€” # the devantler-tech-standard manifest validator (KSail embeds it; the # platform's gitops-repo-audit skill uses it). Standard Kubernetes kinds # validate against kubeconform's built-in default schemas; the CRD-backed @@ -396,7 +398,32 @@ jobs: echo "${KUBECONFORM_SHA256} kubeconform.tar.gz" | sha256sum -c - tar -xzf kubeconform.tar.gz kubeconform # Render first (broken kustomization fails here), then schema-validate. + # deploy/ is the production entry the platform reconciles at `path: .`; + # it must render exactly deploy/prod. deploy/dev is the dev overlay. kubectl kustomize deploy/ > rendered.yaml + kubectl kustomize deploy/prod > rendered-prod.yaml + kubectl kustomize deploy/dev > rendered-dev.yaml + cmp -s rendered.yaml rendered-prod.yaml || { + echo "::error::deploy/kustomization.yaml must include only ./prod, so deploy/ and deploy/prod render the same objects" + exit 1 + } + # Dev shares the base but none of production's identity: one replica, + # no disruption budget, public route or production secret path. + for kind in PodDisruptionBudget HTTPRoute Gateway Certificate Issuer SecretStore ExternalSecret; do + KIND="${kind}" yq eval-all -e '[.] | map(select(.kind == strenv(KIND))) | length == 0' rendered-dev.yaml >/dev/null || { + echo "::error::deploy/dev renders a ${kind}; keep it in deploy/prod" + exit 1 + } + done + yq eval-all -e '[.] | map(select(.kind == "Deployment")) | [(length == 1), (.[0].spec.replicas == 1)] | all' rendered-dev.yaml >/dev/null || { + echo "::error::deploy/dev must run exactly one replica of the base Deployment" + exit 1 + } + # A hostname, not the platform.devantler.tech/ label prefix. + if grep -Eq '[a-z0-9-]\.platform\.devantler\.tech' rendered-dev.yaml; then + echo "::error::deploy/dev renders a production hostname" + exit 1 + fi # Short retry absorbs a transient catalog blip while (re)populating the cache; # a cache hit needs no network and succeeds on the first attempt. Fold stderr # into the capture (2>&1) so the Skipped:0 assertion below reads kubeconform's @@ -408,7 +435,7 @@ jobs: -cache .kubeconform-cache \ -schema-location default \ -schema-location "https://raw.githubusercontent.com/datreeio/CRDs-catalog/${CRDS_CATALOG_REF}/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json" \ - rendered.yaml 2>&1 | tee kubeconform.out; then + rendered.yaml rendered-dev.yaml 2>&1 | tee kubeconform.out; then ok=1 break fi diff --git a/.gitignore b/.gitignore index 9885f45..9fe2ef2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Never commit plaintext secrets β€” tenant secrets live in OpenBao and are -# delivered into the cluster via External Secrets (see deploy/externalsecret.yaml). +# delivered into the cluster via External Secrets (see deploy/prod/externalsecret.yaml). .env .env.* !.env.example diff --git a/AGENTS.md b/AGENTS.md index fdf72a2..eea4abe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,9 +21,24 @@ platform Kubernetes cluster as an OCI-packaged Kustomize app.> ## Structure -- `deploy/` β€” Kustomize manifests for the platform cluster (Deployment, Service, - HTTPRoute, an optional CNPG Cluster, and β€” when the app needs secrets β€” a - namespaced `SecretStore` + `ExternalSecret` sourcing them from OpenBao). +- `deploy/` β€” Kustomize manifests for the platform cluster, published as one + signed OCI artifact and split so production and dev share one copy of each + manifest: + - `deploy/kustomization.yaml` β€” the production entry the platform reconciles + at `path: .`. It includes only `prod`. + - `deploy/base/` β€” what both environments run: the Deployment (whose app + container receives the published image digest), Service, network policy and + an optional CNPG Cluster. + - `deploy/prod/` β€” `../base` plus what only production runs: the public + HTTPRoute, the PodDisruptionBudget, and β€” when the app needs secrets β€” the + namespaced `SecretStore` + `ExternalSecret` reading production paths in + OpenBao. Anything holding a production hostname, credential, database or + bucket goes here. + - `deploy/dev/` β€” `../base` changed only by kustomize patches (one replica). + Never copy a base manifest into it, and never add a route, PDB or production + secret path: the platform owns dev ingress behind sign-on and reconciles + dev at `path: ./dev` into a `-dev` namespace + ([platform#6126](https://github.com/devantler-tech/platform/issues/6126)). - `.github/workflows/` β€” `ci.yaml` (PR gate), `release.yaml` (semantic-release on `main`), `cd.yaml` (publish the signed OCI artifact on `v*` tags). @@ -31,7 +46,8 @@ platform Kubernetes cluster as an OCI-packaged Kustomize app.> +before merge (the production entry and the `deploy/dev` overlay), then include +every job in `ci-required-checks`.> ## Maintenance (autonomous AI engineer) diff --git a/Dockerfile b/Dockerfile index cb05963..d074a24 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ # # It is deliberately self-consistent with the deploy/ scaffold so a freshly # created tenant deploys cleanly before you swap in your real app: it runs as a -# non-root user and serves HTTP on port 3000, matching deploy/deployment.yaml's +# non-root user and serves HTTP on port 3000, matching deploy/base/deployment.yaml's # securityContext (runAsNonRoot, readOnlyRootFilesystem) and its liveness/readiness # probes. Replace it with your stack's (typically multi-stage) build. FROM python:3.16.0a1-alpine diff --git a/README.md b/README.md index a43b56c..7d6cbe6 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,15 @@ running cluster is needed for this first result: git clone https://github.com/devantler-tech/platform-tenant-template.git cd platform-tenant-template kubectl kustomize deploy/ +kubectl kustomize deploy/dev ``` -Success is exit 0 with the example resources printed as YAML, including the -Deployment, Service and HTTPRoute. Names and image values are placeholders. +Success is exit 0 for both, with the example resources printed as YAML. `deploy/` +renders production, including the Deployment, Service and HTTPRoute. `deploy/dev` +renders the dev overlay: the same Deployment, Service, network policy and +database at one replica, without the public route, disruption budget or +production secrets. [The deploy layout](docs/REFERENCE.md#the-deploy-layout) +explains where each manifest goes. Names and image values are placeholders. Rendering does not validate every CRD field, deploy an app or prove platform registration. Do not apply this unmodified scaffold to a cluster. @@ -55,7 +60,8 @@ the CLI route below. The name must equal the repository name. [What the rename changes](docs/REFERENCE.md#what-the-rename-changes) lists everything it touches. Run it only in your generated app repository, never in an upstream contribution checkout. Review `git diff` and run - `kubectl kustomize deploy/` again; this is still only a local render. + `kubectl kustomize deploy/` and `kubectl kustomize deploy/dev` again; this is + still only a local render. 3. **Replace the example with your app:** application code, `Dockerfile`, the example stack job in `.github/workflows/ci.yaml`, and `AGENTS.md`. 4. **Protect your own files from the weekly sync.** Tailor the supplied @@ -71,8 +77,8 @@ the CLI route below. 5. **Register the tenant on the platform.** Follow [`platform/docs/TENANTS.md`](https://github.com/devantler-tech/platform/blob/main/docs/TENANTS.md). -Default PR CI always builds the tenant image and renders `deploy/` before merge, -using no secrets or write authority. Keep the `delivery-inputs` job and its entry +Default PR CI always builds the tenant image and renders `deploy/` and its +`deploy/dev` overlay before merge, using no secrets or write authority. Keep the `delivery-inputs` job and its entry in `ci-required-checks` when you replace the example job with your stack's lint, test, and build commands. This catches the same image and manifest failures in the pull request that introduced them instead of during release or reconciliation. diff --git a/deploy/cluster.yaml b/deploy/base/cluster.yaml similarity index 100% rename from deploy/cluster.yaml rename to deploy/base/cluster.yaml diff --git a/deploy/deployment.yaml b/deploy/base/deployment.yaml similarity index 97% rename from deploy/deployment.yaml rename to deploy/base/deployment.yaml index aa29736..83ecc43 100644 --- a/deploy/deployment.yaml +++ b/deploy/base/deployment.yaml @@ -6,7 +6,7 @@ metadata: app.kubernetes.io/name: app # The platform's `validate-replica-floor` Kyverno policy (Audit) flags any # Deployment/StatefulSet under 2 replicas β€” the platform HA floor that makes - # the drain-safe `maxUnavailable: 1` PDB (poddisruptionbudget.yaml) actually + # the drain-safe `maxUnavailable: 1` PDB (../prod/poddisruptionbudget.yaml) actually # preserve availability through a node drain (see platform#1882; the paired # `validate-replica-ceiling` policy caps tenants at 3). The scaffold ships a # single replica (a fresh tenant starts small), so it opts out explicitly @@ -56,7 +56,7 @@ spec: type: RuntimeDefault # The app never talks to the Kubernetes API, so don't mount an API token # into the pod (the platform-provisioned tenant ServiceAccount is used by - # External Secrets' Vault auth via secretstore.yaml, not by this pod). + # External Secrets' Vault auth via ../prod/secretstore.yaml, not by this pod). # Remove this only if your app genuinely calls the API. automountServiceAccountToken: false # Spread replicas across nodes so a scale-up to 2-3 replicas is actually diff --git a/deploy/base/kustomization.yaml b/deploy/base/kustomization.yaml new file mode 100644 index 0000000..d3a522c --- /dev/null +++ b/deploy/base/kustomization.yaml @@ -0,0 +1,10 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +# Everything production (../prod) and dev (../dev) share. Put a manifest here +# only when both environments run it unchanged; prod-only objects go in +# ../prod, and dev changes these objects with patches in ../dev. +resources: + - deployment.yaml + - service.yaml + - networkpolicy.yaml # re-opens Gateway ingress + DB/DNS egress under the platform's default-deny + - cluster.yaml # CloudNativePG database β€” delete this line if your tenant has no DB diff --git a/deploy/networkpolicy.yaml b/deploy/base/networkpolicy.yaml similarity index 96% rename from deploy/networkpolicy.yaml rename to deploy/base/networkpolicy.yaml index 12d6143..61ce7b5 100644 --- a/deploy/networkpolicy.yaml +++ b/deploy/base/networkpolicy.yaml @@ -41,7 +41,8 @@ metadata: spec: endpointSelector: {} ingress: - # Platform Gateway β†’ app HTTP (the Gateway routes here via httproute.yaml). + # Platform Gateway β†’ app HTTP (via ../prod/httproute.yaml in production; + # in dev, through the platform's sign-on ingress). # Match the container port in deployment.yaml if you change it from 3000. - fromEntities: - ingress diff --git a/deploy/service.yaml b/deploy/base/service.yaml similarity index 100% rename from deploy/service.yaml rename to deploy/base/service.yaml diff --git a/deploy/dev/kustomization.yaml b/deploy/dev/kustomization.yaml new file mode 100644 index 0000000..41a344f --- /dev/null +++ b/deploy/dev/kustomization.yaml @@ -0,0 +1,23 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +# Dev: the shared base, changed only by the patches below. The platform +# reconciles it at `path: ./dev` into its own `-dev` namespace and owns +# its ingress behind sign-on, so dev carries no public route, disruption +# budget, or production secret path. Change base objects with patches here; +# never copy a manifest. +resources: + - ../base +# One replica, whatever production runs. +replicas: + - name: app + count: 1 +patches: + # Keep the single dev replica clear of the platform's replica-floor audit + # even after you remove this label from the base for production HA. + - target: + kind: Deployment + name: app + patch: |- + - op: add + path: /metadata/labels/platform.devantler.tech~1replica-floor + value: exempt diff --git a/deploy/kustomization.yaml b/deploy/kustomization.yaml index e8152d2..3c60e51 100644 --- a/deploy/kustomization.yaml +++ b/deploy/kustomization.yaml @@ -1,12 +1,9 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization +# Production entry point. The platform reconciles the published manifests +# artifact at `path: .`, which is this file, so it must only include ./prod. +# Shared manifests live in ./base, production-only ones in ./prod, and the dev +# overlay in ./dev (reconciled at `path: ./dev` into the `-dev` +# namespace). resources: - - deployment.yaml - - poddisruptionbudget.yaml # drain-safe maxUnavailable:1 PDB so node drains never deadlock (platform#1882) - - httproute.yaml - - service.yaml - - networkpolicy.yaml # re-opens Gateway ingress + DB/DNS egress under the platform's default-deny - - cluster.yaml # CloudNativePG database β€” delete this line if your tenant has no DB - # OpenBao-backed secrets via External Secrets β€” delete both if you need none: - - secretstore.yaml - - externalsecret.yaml + - prod diff --git a/deploy/externalsecret.yaml b/deploy/prod/externalsecret.yaml similarity index 81% rename from deploy/externalsecret.yaml rename to deploy/prod/externalsecret.yaml index abbd06b..0c575cd 100644 --- a/deploy/externalsecret.yaml +++ b/deploy/prod/externalsecret.yaml @@ -1,7 +1,8 @@ # Materializes a native Kubernetes Secret in this namespace from OpenBao, via the # namespaced SecretStore above. Store the real values in OpenBao under your # tenant prefix (`secret/apps//*`, KV v2) out of band first. Reference the -# resulting Secret from deploy/deployment.yaml with a secretKeyRef. +# resulting Secret with a secretKeyRef from a patch in deploy/prod: the Deployment +# lives in deploy/base, which dev shares, and dev reads no production secret. apiVersion: external-secrets.io/v1 kind: ExternalSecret metadata: diff --git a/deploy/httproute.yaml b/deploy/prod/httproute.yaml similarity index 100% rename from deploy/httproute.yaml rename to deploy/prod/httproute.yaml diff --git a/deploy/prod/kustomization.yaml b/deploy/prod/kustomization.yaml new file mode 100644 index 0000000..788b238 --- /dev/null +++ b/deploy/prod/kustomization.yaml @@ -0,0 +1,12 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +# Production: the shared base plus what only production runs β€” its public +# route, disruption budget, and anything holding a production credential or +# secret path. The platform reconciles this through ../kustomization.yaml. +resources: + - ../base + - poddisruptionbudget.yaml # drain-safe maxUnavailable:1 PDB so node drains never deadlock (platform#1882) + - httproute.yaml + # OpenBao-backed secrets via External Secrets β€” delete both if you need none: + - secretstore.yaml + - externalsecret.yaml diff --git a/deploy/poddisruptionbudget.yaml b/deploy/prod/poddisruptionbudget.yaml similarity index 100% rename from deploy/poddisruptionbudget.yaml rename to deploy/prod/poddisruptionbudget.yaml diff --git a/deploy/secretstore.yaml b/deploy/prod/secretstore.yaml similarity index 100% rename from deploy/secretstore.yaml rename to deploy/prod/secretstore.yaml diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 90aabf9..bcff86f 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,13 +1,14 @@ # Template reference -The detail behind the [README](../README.md): what the placeholder rename changes, which files the -template keeps in sync and which are yours, how publishing works, and how to validate the template -locally. +The detail behind the [README](../README.md): what the placeholder rename changes, how `deploy/` is +laid out, which files the template keeps in sync and which are yours, how publishing works, and how +to validate the template locally. ## What the rename changes `scripts/rename-placeholders.sh` rewrites the `app`, `REPLACE_ME`, and `replace-me` -placeholders in `deploy/` consistently, including the container name, Vault role, +placeholders across `deploy/` and its `base/`, `prod/` and `dev/` overlays +consistently, including the container name, Vault role, and ServiceAccount. Those values **must** equal the repository name (see the convention under [How publishing works](#how-publishing-works)). The helper preserves the `app.kubernetes.io/name` label *keys*, CloudNativePG's literal `-app` @@ -16,7 +17,7 @@ half-wrong. It's a one-shot helper, so delete it once adopted. The example route is renamed for both environments: `.platform.lan` locally and `.platform.devantler.tech` in production, both in -`deploy/httproute.yaml`. Add any custom domains beside them; a tenant that moves +`deploy/prod/httproute.yaml`. Add any custom domains beside them; a tenant that moves to its own canonical domain may drop the `platform.devantler.tech` hostname. Each Platform Gateway attaches only the hostnames its listener serves. @@ -27,6 +28,43 @@ the `platform.devantler.tech` hostname, point the tile's `gethomepage.dev/href` annotation at your canonical domain too, or the tile links to an address the route no longer serves. +## The deploy layout + +Every custom-built app gets a production and a dev environment. Both reconcile +the same signed artifact, which holds the whole `deploy/` tree, so the tree is +split into Kustomize overlays that share one copy of each manifest: + +```text +deploy/ +β”œβ”€β”€ kustomization.yaml # production entry: includes only ./prod +β”œβ”€β”€ base/ # what production and dev both run +β”œβ”€β”€ prod/ # ../base + production-only objects +└── dev/ # ../base + dev patches +``` + +- **`deploy/kustomization.yaml`** is what the platform reconciles for production, + at `path: .`. Keep it to `resources: [prod]`. +- **`deploy/base/`** holds every manifest both environments run unchanged: the + Deployment, whose app container receives the published image digest, the + Service, the network policy and an optional CNPG database. In dev that + database is a separate, empty instance in the dev namespace. +- **`deploy/prod/`** adds what only production runs: public routes and + hostnames, certificates and DNS, PodDisruptionBudgets, backups, and anything + that reads production data or holds a production credential or secret path, + such as the OpenBao `SecretStore` and `ExternalSecret`. +- **`deploy/dev/`** changes base objects only with Kustomize `replicas` and + `patches`, never a copied manifest. It runs one replica and adds no route, + PDB, backup or production secret path: the platform reconciles it at + `path: ./dev` into a `-dev` namespace and owns its ingress behind + sign-on ([platform#6126](https://github.com/devantler-tech/platform/issues/6126)). + Turn on experimental features here only through runtime settings, such as an + environment variable patched onto the Deployment. + +Overlays reference only `../base` and their own files, so every directory builds +under Kustomize's default load restrictions. A secret the app needs in both +environments needs a dev source of its own in `deploy/dev`; reference a +production-only secret from a patch in `deploy/prod`. + ## What the template owns vs. what you own template-sync overwrites the files the template **owns** and never touches the @@ -63,7 +101,7 @@ tenant still carrying these from an older sync can delete them for good):** | File | Purpose | |---|---| -| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only | +| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/` and `deploy/dev`, schema-validates every resource, keeps dev free of production-only objects, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only | | `scripts/rename-placeholders.sh` (+ its test) | One-shot rename of the placeholder app to your tenant name | | `scripts/agent-instructions.test.sh` | Fails closed if the one-time agent scaffold loses its ownership, dependency-bot, external-code, exact-head review, pinned-merge, or user-path evaluation boundaries, or regains a retired rule | | `scripts/workflow-caller-contract.test.sh` | Keeps the portable caller-pin contract wired into tenant CI while validating template-only publisher, release, ownership, and scaffold invariants | @@ -130,8 +168,9 @@ Tenants own both files, so an existing tenant adds the `build(deps)` rule and the `ci` prefix itself. Each tag triggers `cd.yaml`, which calls the platform's [`publish-app.yaml`](https://github.com/devantler-tech/.github/blob/main/.github/workflows/publish-app.yaml) -reusable workflow to build the image, **pin its digest into -`deploy/deployment.yaml`**, push the manifests as an OCI artifact, and +reusable workflow to build the image, **pin its digest into the app container in +`deploy/base/deployment.yaml`** (`deploy/deployment.yaml` in a tenant without +`deploy/base/`), push the whole `deploy/` tree as one OCI artifact, and **cosign-sign** both. The platform's `OCIRepository` verifies that signature, so only artifacts from this trusted workflow are eligible for reconciliation after the platform has registered the tenant and its applicable publisher-approval @@ -187,7 +226,8 @@ required checks for failures that happen after that snapshot. Run these from the repository root. In every tenant, and in this template: ```sh -kubectl kustomize deploy/ # manifests build +kubectl kustomize deploy/ # production manifests build +kubectl kustomize deploy/dev # dev overlay builds (tenants with deploy/dev) sh scripts/workflow-caller-pin-contract.test.sh # portable tenant caller-pin contract (resolves the version-comment tag on github.com and compares it with the pinned commit) sh scripts/publish-pin-approved.test.sh # publish-app pin approval check (reads a local approved set, never the network) actionlint .github/workflows/* # workflows parse diff --git a/scripts/platform-tenant-envelope-contract.test.sh b/scripts/platform-tenant-envelope-contract.test.sh index 4311cb5..9061a2d 100644 --- a/scripts/platform-tenant-envelope-contract.test.sh +++ b/scripts/platform-tenant-envelope-contract.test.sh @@ -71,8 +71,8 @@ validate_contract() { 'resource-graph-definitions/tenant/resource-graph-definition.yaml' \ 'k8s/bases/infrastructure/vault-config/job.yaml' \ 'k8s/bases/apps/ascoachingogvaner' \ - 'deploy/secretstore.yaml' \ - 'deploy/externalsecret.yaml' \ + 'deploy/prod/secretstore.yaml' \ + 'deploy/prod/externalsecret.yaml' \ 'namespace.yaml' \ 'service-account.yaml' \ 'external-secret.yaml' \ diff --git a/scripts/platform-tenant-envelope.test.sh b/scripts/platform-tenant-envelope.test.sh index b19fbc7..42ac181 100644 --- a/scripts/platform-tenant-envelope.test.sh +++ b/scripts/platform-tenant-envelope.test.sh @@ -173,8 +173,8 @@ validate_openbao_authorization() ( for required_file in \ "$vault_config" \ "$rename_script" \ - "$scaffold_root/deploy/secretstore.yaml" \ - "$scaffold_root/deploy/externalsecret.yaml" + "$scaffold_root/deploy/prod/secretstore.yaml" \ + "$scaffold_root/deploy/prod/externalsecret.yaml" do [ -f "$required_file" ] || fail "OpenBao authorization source is missing: $required_file" done @@ -186,8 +186,8 @@ validate_openbao_authorization() ( cp "$rename_script" "$renamed_scaffold/scripts/rename-placeholders.sh" sh "$renamed_scaffold/scripts/rename-placeholders.sh" "$tenant_name" >/dev/null - secret_store=$renamed_scaffold/deploy/secretstore.yaml - external_secret=$renamed_scaffold/deploy/externalsecret.yaml + secret_store=$renamed_scaffold/deploy/prod/secretstore.yaml + external_secret=$renamed_scaffold/deploy/prod/externalsecret.yaml expected_remote_key=apps/$tenant_name/config export tenant_name expected_remote_key @@ -905,11 +905,11 @@ run_vault_duplicate "tenant policy declared twice" \ run_vault_duplicate "tenant Kubernetes-auth role declared twice" \ 'bao write auth/kubernetes/role/ascoachingogvaner' 'ttl=1h' run_vault_prefixed_role_control "another tenant role starts with this tenant name" -run_scaffold_mutation "scaffold OpenBao role changed" deploy/secretstore.yaml \ +run_scaffold_mutation "scaffold OpenBao role changed" deploy/prod/secretstore.yaml \ '.spec.provider.vault.auth.kubernetes.role = "another-tenant"' -run_scaffold_mutation "scaffold OpenBao ServiceAccount changed" deploy/secretstore.yaml \ +run_scaffold_mutation "scaffold OpenBao ServiceAccount changed" deploy/prod/secretstore.yaml \ '.spec.provider.vault.auth.kubernetes.serviceAccountRef.name = "another-tenant"' -run_scaffold_mutation "scaffold OpenBao path crossed into another tenant" deploy/externalsecret.yaml \ +run_scaffold_mutation "scaffold OpenBao path crossed into another tenant" deploy/prod/externalsecret.yaml \ '.spec.data[0].remoteRef.key = "apps/another-tenant/config"' run_mutation "KRO managed-by label removed" "$rgd_path" \ 'del(.spec.resources[] | select(.id == "tenantNamespace").template.metadata.labels."app.kubernetes.io/managed-by")' diff --git a/scripts/platform-vpa-floor.test.sh b/scripts/platform-vpa-floor.test.sh index 4aa1c93..0fde771 100644 --- a/scripts/platform-vpa-floor.test.sh +++ b/scripts/platform-vpa-floor.test.sh @@ -32,7 +32,7 @@ validate_vpa_floor() ( platform_root=$1 scaffold_root=$2 platform_policy=$platform_root/k8s/bases/infrastructure/cluster-policies/best-practices/auto-vpa-deployment.yaml - deployment=$scaffold_root/deploy/deployment.yaml + deployment=$scaffold_root/deploy/base/deployment.yaml [ -f "$platform_policy" ] || fail "Platform auto-vpa policy is missing: $platform_policy" [ -f "$deployment" ] || fail "scaffold Deployment is missing: $deployment" @@ -103,7 +103,7 @@ VALUES scaffold_request_m=$(millicores "$scaffold_requests") [ "$scaffold_request_m" -ge "$platform_floor_m" ] || - fail "scaffold CPU request ${scaffold_requests} is below Platform VPA floor ${platform_floors}; raise deploy/deployment.yaml" + fail "scaffold CPU request ${scaffold_requests} is below Platform VPA floor ${platform_floors}; raise deploy/base/deployment.yaml" printf 'Platform VPA floor contract: request=%s floor=%s\n' "$scaffold_requests" "$platform_floors" ) @@ -121,9 +121,9 @@ mutation_dir=$(mktemp -d) trap 'rm -rf "$mutation_dir"' EXIT platform_policy_rel=k8s/bases/infrastructure/cluster-policies/best-practices/auto-vpa-deployment.yaml -mkdir -p "$mutation_dir/platform/$(dirname -- "$platform_policy_rel")" "$mutation_dir/scaffold/deploy" +mkdir -p "$mutation_dir/platform/$(dirname -- "$platform_policy_rel")" "$mutation_dir/scaffold/deploy/base" cp "$platform_root/$platform_policy_rel" "$mutation_dir/platform/$platform_policy_rel" -cp "$repo_root/deploy/deployment.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" +cp "$repo_root/deploy/base/deployment.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" # Rebuild pristine fixtures, apply one mutation, and require validation to reject it. run_mutation() { @@ -132,15 +132,15 @@ run_mutation() { scaffold_mutation=$3 cp "$platform_root/$platform_policy_rel" "$mutation_dir/platform/$platform_policy_rel" - cp "$repo_root/deploy/deployment.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" + cp "$repo_root/deploy/base/deployment.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" if [ -n "$platform_mutation" ]; then yq eval "$platform_mutation" "$mutation_dir/platform/$platform_policy_rel" > "$mutation_dir/platform-mutant.yaml" mv "$mutation_dir/platform-mutant.yaml" "$mutation_dir/platform/$platform_policy_rel" fi if [ -n "$scaffold_mutation" ]; then - yq eval "$scaffold_mutation" "$mutation_dir/scaffold/deploy/deployment.yaml" > "$mutation_dir/scaffold-mutant.yaml" - mv "$mutation_dir/scaffold-mutant.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" + yq eval "$scaffold_mutation" "$mutation_dir/scaffold/deploy/base/deployment.yaml" > "$mutation_dir/scaffold-mutant.yaml" + mv "$mutation_dir/scaffold-mutant.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" fi if (validate_vpa_floor "$mutation_dir/platform" "$mutation_dir/scaffold") >/dev/null 2>&1; then diff --git a/scripts/rename-placeholders.sh b/scripts/rename-placeholders.sh index f1b68b5..1a4f582 100755 --- a/scripts/rename-placeholders.sh +++ b/scripts/rename-placeholders.sh @@ -1,7 +1,8 @@ #!/usr/bin/env sh # rename-placeholders.sh β€” turn this scaffold into a real tenant in one shot. # -# The deploy/ manifests ship with three placeholder forms that collapse to one +# The deploy/ manifests (the root entry and its base/, prod/ and dev/ +# overlays) ship with three placeholder forms that collapse to one # value β€” your tenant (repository) name: # β€’ `app` β€” the example app/resource name (Deployment, Service, the # `app.kubernetes.io/name` label *value*, HTTPRoute, the CNPG @@ -13,8 +14,8 @@ # repository name β€” see docs/REFERENCE.md β€” so a single name drives everything.) # # Doing this by hand is easy to get half-wrong; this script renames all three -# across deploy/*.yaml in place WITHOUT corrupting the parts that must NOT -# change: +# across deploy/*.yaml and deploy/*/*.yaml in place WITHOUT corrupting the +# parts that must NOT change: # β€’ the `app.kubernetes.io/name` label *key* (only its value is renamed), # β€’ CloudNativePG's literal `-app` suffix on its generated secret, and # β€’ the shared `openbao` SecretStore name. @@ -48,7 +49,8 @@ deploy_dir="$repo_root/deploy" } changed=0 -for f in "$deploy_dir"/*.yaml; do +# The root entry and one level of overlays (base/, prod/, dev/). +for f in "$deploy_dir"/*.yaml "$deploy_dir"/*/*.yaml; do [ -f "$f" ] || continue tmp="$f.rename.$$" # Order matters: the longer CNPG-secret suffix is handled before `app-db`, and @@ -79,4 +81,5 @@ for f in "$deploy_dir"/*.yaml; do done echo "Renamed placeholders to '$name' across $changed file(s) in deploy/." -echo "Next: review with 'git diff', then 'kubectl kustomize deploy/' to confirm it builds." +echo "Next: review with 'git diff', then 'kubectl kustomize deploy/' (production) and" +echo " 'kubectl kustomize deploy/dev' to confirm both build." diff --git a/scripts/rename-placeholders.test.sh b/scripts/rename-placeholders.test.sh index 60d0504..7177ee9 100755 --- a/scripts/rename-placeholders.test.sh +++ b/scripts/rename-placeholders.test.sh @@ -3,7 +3,8 @@ # # rename-placeholders.sh is the first thing a newcomer runs after `Use this # template` β€” it rewrites the `app`, REPLACE_ME, and `replace-me` placeholders -# across deploy/*.yaml into the tenant's real name. A silent regression ships +# across deploy/ (the root entry and its base/, prod/ and dev/ overlays) into +# the tenant's real name. A silent regression ships # broken manifests to every tenant created from this scaffold, and it had no # other coverage. The existing validation gate schema-validates the *unrenamed* # manifests but never runs the rename, so a botched sed address would pass green. @@ -19,7 +20,9 @@ # repointed to the tenant name alongside the uppercase placeholders, # * invalid (non-DNS-1123) names are rejected without mutating anything, # * no stray sed temp files are left behind, and -# * the renamed scaffold still `kubectl kustomize`-builds (CI only). +# * the dev overlay's replica override and patch follow the rename, and +# * the renamed production entry and dev overlay still `kubectl kustomize`-build +# (CI only). # # It runs the script against a throwaway copy so the real working tree is never # mutated. Run locally with `sh scripts/rename-placeholders.test.sh`; CI runs it @@ -35,6 +38,14 @@ fail() { exit 1 } +# Every manifest under a deploy/ tree β€” the root entry and its base/, prod/ and +# dev/ overlays β€” concatenated in a stable order. +deploy_yaml() { + find "$1" -type f -name '*.yaml' | LC_ALL=C sort | while IFS= read -r manifest; do + cat "$manifest" + done +} + # Build a throwaway copy of the working tree so the real tree is never mutated # (the script now targets the scaffold owning it, i.e. this copy). The copy is # its own git repo so check 7's `git status` works. @@ -51,13 +62,13 @@ script="./scripts/rename-placeholders.sh" deploy="deploy" # --- Guardrails: each must reject and exit non-zero, mutating nothing ---------- -snapshot_before="$(cat "$deploy"/*.yaml)" +snapshot_before="$(deploy_yaml "$deploy")" for bad in "My Tenant" "UPPER" "-bad" "bad-" "with_underscore"; do if "$script" "$bad" >/dev/null 2>&1; then fail "expected rejection of invalid DNS-1123 name: '$bad'" fi done -[ "$(cat "$deploy"/*.yaml)" = "$snapshot_before" ] || +[ "$(deploy_yaml "$deploy")" = "$snapshot_before" ] || fail "a rejected invocation modified deploy/ β€” guardrails must bail out first" homepage_route_contract() { @@ -72,7 +83,7 @@ homepage_route_contract() { ' "$1" >/dev/null 2>&1 } -homepage_route_contract "$deploy/httproute.yaml" || +homepage_route_contract "$deploy/prod/httproute.yaml" || fail "scaffold HTTPRoute does not expose the complete Homepage discovery contract" # Publication replaces this explicit placeholder with the built digest. Even the @@ -80,11 +91,11 @@ homepage_route_contract "$deploy/httproute.yaml" || scaffold_image_contract() { yq eval -e '.spec.template.spec.containers[0].image == "ghcr.io/devantler-tech/REPLACE_ME:0.0.0"' "$1" >/dev/null 2>&1 } -scaffold_image_contract "$deploy/deployment.yaml" || +scaffold_image_contract "$deploy/base/deployment.yaml" || fail "scaffold image must use its explicit versioned placeholder" for bad_image in ghcr.io/devantler-tech/REPLACE_ME:latest ghcr.io/devantler-tech/REPLACE_ME ghcr.io/another/REPLACE_ME:0.0.0; do mutant="${work}/image-mutant.yaml" - BAD_IMAGE="$bad_image" yq eval '.spec.template.spec.containers[0].image = strenv(BAD_IMAGE)' "$deploy/deployment.yaml" > "$mutant" + BAD_IMAGE="$bad_image" yq eval '.spec.template.spec.containers[0].image = strenv(BAD_IMAGE)' "$deploy/base/deployment.yaml" > "$mutant" if scaffold_image_contract "$mutant"; then fail "image contract accepted $bad_image" fi @@ -93,7 +104,7 @@ done for annotation in href pod-selector; do mutant="${work}/homepage-${annotation}-mutant.yaml" yq eval "del(.metadata.annotations.\"gethomepage.dev/${annotation}\")" \ - "$deploy/httproute.yaml" > "$mutant" + "$deploy/prod/httproute.yaml" > "$mutant" if homepage_route_contract "$mutant"; then fail "Homepage contract accepted a route without gethomepage.dev/${annotation}" fi @@ -122,13 +133,13 @@ yq eval ".spec.hostnames += [\"${custom_local_hostname}\", \"${custom_prod_hostn .metadata.annotations.\"gethomepage.dev/description\" = \"${custom_description}\" | .metadata.annotations.\"gethomepage.dev/group\" = \"${custom_group}\" | .metadata.annotations.\"gethomepage.dev/icon\" = \"${custom_icon}\"" \ - "$deploy/httproute.yaml" > "$deploy/httproute-with-custom.yaml" -mv "$deploy/httproute-with-custom.yaml" "$deploy/httproute.yaml" + "$deploy/prod/httproute.yaml" > "$deploy/prod/httproute-with-custom.yaml" +mv "$deploy/prod/httproute-with-custom.yaml" "$deploy/prod/httproute.yaml" # --- Happy path --------------------------------------------------------------- "$script" "$NAME" >/dev/null -all="$(cat "$deploy"/*.yaml)" +all="$(deploy_yaml "$deploy")" # 1) REPLACE_ME fully repointed (container image + OpenBao KV path); none remain. printf '%s\n' "$all" | grep -qF "ghcr.io/devantler-tech/${NAME}:0.0.0" || @@ -159,7 +170,7 @@ for field_and_value in \ "icon=${custom_icon}"; do field="${field_and_value%%=*}" expected="${field_and_value#*=}" - actual="$(yq eval ".metadata.annotations.\"gethomepage.dev/${field}\"" "$deploy/httproute.yaml")" + actual="$(yq eval ".metadata.annotations.\"gethomepage.dev/${field}\"" "$deploy/prod/httproute.yaml")" [ "$actual" = "$expected" ] || fail "Homepage ${field} expected '${expected}' after rename, found '${actual}'" done @@ -190,7 +201,7 @@ printf '%s\n' "$all" | grep -qF "name: openbao" || # 6) The lowercase `replace-me` Vault role / ServiceAccount placeholders are # repointed to the tenant name too; no tenant-identity placeholder survives. -grep -qE "^[[:space:]]*role: \"${NAME}\"$" "$deploy/secretstore.yaml" || +grep -qE "^[[:space:]]*role: \"${NAME}\"$" "$deploy/prod/secretstore.yaml" || fail "SecretStore Vault role not renamed to ${NAME}" if ! awk -v expected="name: \"${NAME}\"" ' /^[[:space:]]*serviceAccountRef:[[:space:]]*$/ { in_ref = 1; next } @@ -202,14 +213,21 @@ if ! awk -v expected="name: \"${NAME}\"" ' exit 0 } END { if (!found) exit 1 } -' "$deploy/secretstore.yaml"; then +' "$deploy/prod/secretstore.yaml"; then fail "SecretStore ServiceAccount reference not exactly ${NAME}" fi -grep -qF "replace-me" "$deploy/secretstore.yaml" && +grep -qF "replace-me" "$deploy/prod/secretstore.yaml" && fail "a lowercase 'replace-me' tenant-identity placeholder survived the rename" [ "$(cat "$scope_fixture")" = "$scope_before" ] || fail "rename touched unrelated role/name fields" +# 6b) The dev overlay's targets follow the rename. Kustomize skips a patch whose +# target names no object without any error, so check the names themselves. +[ "$(yq eval '.replicas[0].name' "$deploy/dev/kustomization.yaml")" = "$NAME" ] || + fail "dev overlay replica override does not target the renamed Deployment" +[ "$(yq eval '.patches[0].target.name' "$deploy/dev/kustomization.yaml")" = "$NAME" ] || + fail "dev overlay patch does not target the renamed Deployment" + # 7) No stray temp files left behind by the in-place sed. if git status --porcelain --untracked-files=all | grep -q '\.rename\.'; then fail "stray *.rename.* temp file left behind" @@ -217,7 +235,7 @@ fi # 8) Idempotent: a second run with the same name changes nothing more. "$script" "$NAME" >/dev/null -[ "$(cat "$deploy"/*.yaml)" = "$all" ] || +[ "$(deploy_yaml "$deploy")" = "$all" ] || fail "a second rename mutated deploy/ β€” the script is not idempotent" # 9) Cross-checkout invocation (#61): a path-qualified call from an UNRELATED @@ -229,13 +247,13 @@ rm -rf "$other/.git" git init -q "$other" git init -q "$caller_repo" cp -R "$repo_root/deploy" "$caller_repo/deploy" -caller_before="$(cat "$caller_repo"/deploy/*.yaml)" +caller_before="$(deploy_yaml "$caller_repo/deploy")" (cd "$caller_repo" && "$other/scripts/rename-placeholders.sh" cross-tenant >/dev/null) -[ "$(cat "$caller_repo"/deploy/*.yaml)" = "$caller_before" ] || +[ "$(deploy_yaml "$caller_repo/deploy")" = "$caller_before" ] || fail "cross-checkout invocation mutated the CALLER's deploy/ (#61)" -cat "$other"/deploy/*.yaml | grep -qF "cross-tenant.platform.lan" || +deploy_yaml "$other/deploy" | grep -qF "cross-tenant.platform.lan" || fail "cross-checkout invocation did not rename the scaffold owning the script (#61)" -cat "$other"/deploy/*.yaml | grep -qF "cross-tenant.platform.devantler.tech" || +deploy_yaml "$other/deploy" | grep -qF "cross-tenant.platform.devantler.tech" || fail "cross-checkout invocation did not rename the production hostname (#99)" # 10) The renamed scaffold still builds (CI has kubectl preinstalled; skip locally @@ -243,8 +261,16 @@ cat "$other"/deploy/*.yaml | grep -qF "cross-tenant.platform.devantler.tech" || if command -v kubectl >/dev/null 2>&1; then kubectl kustomize "$deploy" >/dev/null || fail "renamed deploy/ no longer 'kubectl kustomize'-builds" + dev_render=$(kubectl kustomize "$deploy/dev") || + fail "renamed deploy/dev no longer 'kubectl kustomize'-builds" + # shellcheck disable=SC2016 # yq expression, not shell. + printf '%s\n' "$dev_render" | NAME="$NAME" yq eval-all -e ' + [.] | map(select(.kind == "Deployment")) + | [(length == 1), (.[0].metadata.name == strenv(NAME)), (.[0].spec.replicas == 1)] + | all + ' - >/dev/null || fail "renamed dev overlay does not run exactly one replica of ${NAME}" else echo "note: kubectl not found β€” skipping the kustomize-build assertion (CI enforces it)" fi -echo "PASS: rename-placeholders.sh end-to-end (guardrails + placeholder/app rename + label-key/CNPG-suffix/openbao invariants + idempotency + cross-checkout targeting + build)" +echo "PASS: rename-placeholders.sh end-to-end (guardrails + placeholder/app rename + label-key/CNPG-suffix/openbao invariants + idempotency + cross-checkout targeting + dev overlay + build)" diff --git a/scripts/tenant-ci-contract.test.sh b/scripts/tenant-ci-contract.test.sh index 82d4faa..0145708 100755 --- a/scripts/tenant-ci-contract.test.sh +++ b/scripts/tenant-ci-contract.test.sh @@ -88,7 +88,7 @@ validate_contract() { ' assert_ci "manifest-render step must have only audited keys" ' ((.jobs."delivery-inputs".steps[3] | keys | sort | join(",")) == "name,run,shell,working-directory") - and (.jobs."delivery-inputs".steps[3].run == "kubectl kustomize deploy/ >/dev/null") + and (.jobs."delivery-inputs".steps[3].run == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null") and (.jobs."delivery-inputs".steps[3].shell == "bash") and (.jobs."delivery-inputs".steps[3]."working-directory" == ".") ' @@ -125,7 +125,7 @@ validate_contract() { ' assert_ci "tenant manifest render is missing" ' [.jobs."delivery-inputs".steps[] | select( - (.run // "") == "kubectl kustomize deploy/ >/dev/null" + (.run // "") == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null" )] | length == 1 ' assert_ci "required-check aggregate must depend on all four jobs exactly" \ @@ -335,7 +335,7 @@ run_mutation "workflow secret environment added" \ run_mutation "container build removed" \ 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "docker build --tag tenant-delivery-check ."))' run_mutation "manifest render removed" \ - 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "kubectl kustomize deploy/ >/dev/null"))' + 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null"))' run_mutation "checkout credentials retained" \ '.jobs."delivery-inputs".steps[] |= (select(.uses | test("^actions/checkout@[0-9a-f]{40}$")).with."persist-credentials" = true)' run_mutation "second mutable checkout added" \ @@ -360,6 +360,8 @@ run_mutation "image build shell replaced with no-op" \ '.jobs."delivery-inputs".steps[2].shell = "echo {0}"' run_mutation "manifest render redirected to decoy" \ '.jobs."delivery-inputs".steps[3]."working-directory" = "fixtures/valid"' +run_mutation "dev overlay render dropped" \ + '.jobs."delivery-inputs".steps[3].run = "kubectl kustomize deploy/ >/dev/null"' run_mutation "job permissions broadened" \ '.jobs."delivery-inputs".permissions.packages = "write"' run_mutation "delivery dependency removed from aggregate" \ From 23c64640817673118532f170c62eba793fd9b67b Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 15 Nov 2026 08:02:48 +0100 Subject: [PATCH 2/3] fix(release): stage compatible publisher guards before migration --- .github/workflows/cd.yaml | 49 +++---- .github/workflows/ci.yaml | 2 +- .github/workflows/validate-scaffold.yaml | 35 +---- .gitignore | 2 +- AGENTS.md | 23 +-- Dockerfile | 2 +- README.md | 8 +- deploy/base/kustomization.yaml | 10 -- deploy/{base => }/cluster.yaml | 0 deploy/{base => }/deployment.yaml | 4 +- deploy/dev/kustomization.yaml | 23 --- deploy/{prod => }/externalsecret.yaml | 3 +- deploy/{prod => }/httproute.yaml | 0 deploy/kustomization.yaml | 15 +- deploy/{base => }/networkpolicy.yaml | 3 +- deploy/{prod => }/poddisruptionbudget.yaml | 0 deploy/prod/kustomization.yaml | 12 -- deploy/{prod => }/secretstore.yaml | 0 deploy/{base => }/service.yaml | 0 docs/REFERENCE.md | 131 +++++++++--------- scripts/fixtures/own-publisher.yaml | 38 +++++ .../platform-tenant-envelope-contract.test.sh | 4 +- scripts/platform-tenant-envelope.test.sh | 62 ++------- scripts/platform-vpa-floor.test.sh | 14 +- scripts/publish-pin-approved.sh | 10 +- scripts/publish-pin-approved.test.sh | 16 ++- scripts/rename-placeholders.sh | 13 +- scripts/rename-placeholders.test.sh | 74 +++------- scripts/scaffold.test.sh | 6 +- scripts/tenant-ci-contract.test.sh | 8 +- scripts/workflow-caller-contract.test.sh | 47 +++---- scripts/workflow-caller-pin-contract.test.sh | 5 +- 32 files changed, 259 insertions(+), 360 deletions(-) delete mode 100644 deploy/base/kustomization.yaml rename deploy/{base => }/cluster.yaml (100%) rename deploy/{base => }/deployment.yaml (97%) delete mode 100644 deploy/dev/kustomization.yaml rename deploy/{prod => }/externalsecret.yaml (81%) rename deploy/{prod => }/httproute.yaml (100%) rename deploy/{base => }/networkpolicy.yaml (96%) rename deploy/{prod => }/poddisruptionbudget.yaml (100%) delete mode 100644 deploy/prod/kustomization.yaml rename deploy/{prod => }/secretstore.yaml (100%) rename deploy/{base => }/service.yaml (100%) create mode 100644 scripts/fixtures/own-publisher.yaml diff --git a/.github/workflows/cd.yaml b/.github/workflows/cd.yaml index efb4b6d..8bbf349 100644 --- a/.github/workflows/cd.yaml +++ b/.github/workflows/cd.yaml @@ -10,29 +10,30 @@ permissions: {} jobs: publish: name: Publish - # The upstream template has no application to publish; its ID survives renames. + # Skipped in the template repo itself (it ships no app); runs in every tenant + # created from this template. The template is matched by its repository ID, + # which survives the rename from platform-tenant-template to application-template. if: github.repository_id != '1253884448' - runs-on: ubuntu-latest - timeout-minutes: 60 - concurrency: - group: publish-${{ github.repository }} - cancel-in-progress: false permissions: - contents: read - packages: write - id-token: write - steps: - - name: πŸ”’ Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 - with: - egress-policy: audit - - name: πŸ“₯ Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - name: πŸ“¦ Publish signed application - id: publish - uses: devantler-tech/.github/actions/publish-app@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2 - with: - app-name: ${{ github.event.repository.name }} - app-manifest: base/deployment.yaml + contents: read # checkout + packages: write # push image + manifests OCI artifact + id-token: write # keyless cosign signing (via GitHub OIDC) + uses: devantler-tech/.github/.github/workflows/publish-app.yaml@af042c540ce8db4d64add98c34b5c57691e0e812 # v19.0.5 + with: + # publish-app pins the freshly built image digest into the container with + # this name in deploy/deployment.yaml. Keep that container's name equal to + # the repository name (the platform's signed-publish convention). + app-name: ${{ github.event.repository.name }} + # The signature this publish mints carries the `uses:` ref above in its + # certificate. Platform has independently approved this exact maintained + # revision for manifests, admission and node pulls. Other maintained + # revisions, tags and branches fail closed; a full SHA alone does not + # grant approval. The guard below checks only that the ref is a commit + # SHA, so an unapproved SHA still publishes, but its artifact never + # verifies in-cluster and the tenant silently stops reconciling. Get the + # new revision approved in Platform before changing this pin. + # + # Enabling the guard adds the producer-side half: the publish refuses to + # sign at all, before the build, so a tag or branch ref surfaces here as a failed + # release instead of as an artifact the cluster quietly rejects. + enable-caller-pin: true diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 8bcc72e..0df073f 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -74,7 +74,7 @@ jobs: shell: bash working-directory: . - name: 🧱 Render tenant manifests - run: kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null + run: kubectl kustomize deploy/ >/dev/null shell: bash working-directory: . diff --git a/.github/workflows/validate-scaffold.yaml b/.github/workflows/validate-scaffold.yaml index e403b90..59d21be 100644 --- a/.github/workflows/validate-scaffold.yaml +++ b/.github/workflows/validate-scaffold.yaml @@ -26,8 +26,7 @@ permissions: {} # this template's core deliverable β€” every new tenant inherits them β€” so a PR that # breaks the kustomization (a renamed/removed resource, a YAML error) must not # merge green and ship broken scaffolding downstream. Eight layers run here: -# 1. schema-validate the deploy/ production entry and its dev overlay, and -# keep dev free of production-only objects (a typo'd CRD field that renders +# 1. schema-validate the deploy/ manifests (a typo'd CRD field that renders # without complaint must fail loudly), and # 2. exercise scripts/rename-placeholders.sh β€” the onboarding script every new # tenant runs first; a botched sed address (a missed file, a corrupted label @@ -375,9 +374,8 @@ jobs: key: kubeconform-crds-${{ env.CRDS_CATALOG_REF }} - name: 🧱 Build & schema-validate deploy/ manifests # kubectl (with embedded kustomize) is preinstalled on ubuntu-latest. Render - # the production entry and the dev overlay (a broken kustomization fails - # the render, not silently downstream), then schema-validate every - # rendered resource with kubeconform β€” + # the manifests (a broken kustomization fails the render, not silently + # downstream), then schema-validate every rendered resource with kubeconform β€” # the devantler-tech-standard manifest validator (KSail embeds it; the # platform's gitops-repo-audit skill uses it). Standard Kubernetes kinds # validate against kubeconform's built-in default schemas; the CRD-backed @@ -399,32 +397,7 @@ jobs: echo "${KUBECONFORM_SHA256} kubeconform.tar.gz" | sha256sum -c - tar -xzf kubeconform.tar.gz kubeconform # Render first (broken kustomization fails here), then schema-validate. - # deploy/ is the production entry the platform reconciles at `path: .`; - # it must render exactly deploy/prod. deploy/dev is the dev overlay. kubectl kustomize deploy/ > rendered.yaml - kubectl kustomize deploy/prod > rendered-prod.yaml - kubectl kustomize deploy/dev > rendered-dev.yaml - cmp -s rendered.yaml rendered-prod.yaml || { - echo "::error::deploy/kustomization.yaml must include only ./prod, so deploy/ and deploy/prod render the same objects" - exit 1 - } - # Dev shares the base but none of production's identity: one replica, - # no disruption budget, public route or production secret path. - for kind in PodDisruptionBudget HTTPRoute Gateway Certificate Issuer SecretStore ExternalSecret; do - KIND="${kind}" yq eval-all -e '[.] | map(select(.kind == strenv(KIND))) | length == 0' rendered-dev.yaml >/dev/null || { - echo "::error::deploy/dev renders a ${kind}; keep it in deploy/prod" - exit 1 - } - done - yq eval-all -e '[.] | map(select(.kind == "Deployment")) | [(length == 1), (.[0].spec.replicas == 1)] | all' rendered-dev.yaml >/dev/null || { - echo "::error::deploy/dev must run exactly one replica of the base Deployment" - exit 1 - } - # A hostname, not the platform.devantler.tech/ label prefix. - if grep -Eq '[a-z0-9-]\.platform\.devantler\.tech' rendered-dev.yaml; then - echo "::error::deploy/dev renders a production hostname" - exit 1 - fi # Short retry absorbs a transient catalog blip while (re)populating the cache; # a cache hit needs no network and succeeds on the first attempt. Fold stderr # into the capture (2>&1) so the Skipped:0 assertion below reads kubeconform's @@ -436,7 +409,7 @@ jobs: -cache .kubeconform-cache \ -schema-location default \ -schema-location "https://raw.githubusercontent.com/datreeio/CRDs-catalog/${CRDS_CATALOG_REF}/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json" \ - rendered.yaml rendered-dev.yaml 2>&1 | tee kubeconform.out; then + rendered.yaml 2>&1 | tee kubeconform.out; then ok=1 break fi diff --git a/.gitignore b/.gitignore index 9fe2ef2..9885f45 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Never commit plaintext secrets β€” tenant secrets live in OpenBao and are -# delivered into the cluster via External Secrets (see deploy/prod/externalsecret.yaml). +# delivered into the cluster via External Secrets (see deploy/externalsecret.yaml). .env .env.* !.env.example diff --git a/AGENTS.md b/AGENTS.md index f4453a8..c90582c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ Kustomize app (a platform **tenant**). -Keep CI's delivery-input gate: build the tenant image and render `deploy/` before merge; render `deploy/dev` too, +Keep CI's delivery-input gate: build the tenant image and render `deploy/` before merge, then include every job in `ci-required-checks`. @@ -40,24 +40,9 @@ then include every job in `ci-required-checks`. - `.github/workflows/` β€” `ci.yaml` (PR gate) and `release.yaml` (semantic-release on `main`). -- `deploy/` β€” Kustomize manifests for the platform cluster, published as one - signed OCI artifact and split so production and dev share one copy of each - manifest: - - `deploy/kustomization.yaml` β€” the production entry the platform reconciles - at `path: .`. It includes only `prod`. - - `deploy/base/` β€” what both environments run: the Deployment (whose app - container receives the published image digest), Service, network policy and - an optional CNPG Cluster. - - `deploy/prod/` β€” `../base` plus what only production runs: the public - HTTPRoute, the PodDisruptionBudget, and β€” when the app needs secrets β€” the - namespaced `SecretStore` + `ExternalSecret` reading production paths in - OpenBao. Anything holding a production hostname, credential, database or - bucket goes here. - - `deploy/dev/` β€” `../base` changed only by kustomize patches (one replica). - Never copy a base manifest into it, and never add a route, PDB or production - secret path: the platform owns dev ingress behind sign-on and reconciles - dev at `path: ./dev` into a `-dev` namespace - ([platform#6126](https://github.com/devantler-tech/platform/issues/6126)). +- `deploy/` β€” Kustomize manifests for the platform cluster (Deployment, Service, + HTTPRoute, an optional CNPG Cluster, and β€” when the app needs secrets β€” a + namespaced `SecretStore` + `ExternalSecret` sourcing them from OpenBao). - `.github/workflows/cd.yaml` β€” publishes the signed image and manifests artifact on `v*` tags. diff --git a/Dockerfile b/Dockerfile index a054854..aac687d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ # # It is deliberately self-consistent with the deploy/ scaffold so a freshly # created tenant deploys cleanly before you swap in your real app: it runs as a -# non-root user and serves HTTP on port 3000, matching deploy/base/deployment.yaml's +# non-root user and serves HTTP on port 3000, matching deploy/deployment.yaml's # securityContext (runAsNonRoot, readOnlyRootFilesystem) and its liveness/readiness # probes. Replace it with your stack's (typically multi-stage) build. FROM python:3.16.0a1-alpine diff --git a/README.md b/README.md index 9bc38a7..d0e706d 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ flowchart LR | `dotnet` | An ASP.NET Core minimal API on .NET 11 with OpenFeature, xUnit v3 tests and warnings-as-errors analyzers, built and tested in CI | | `svelte` | A SvelteKit 3 and Svelte 5 app on Node 26 with `adapter-node`, OpenFeature, Vitest, svelte-check and ESLint | | `none` | A placeholder CI job for a stack you bring yourself; with `--tenancy` also a placeholder Dockerfile, otherwise you add your own build files | -| `--tenancy` | `deploy/` Kustomize manifests, a signed image and manifests release on every `v*` tag, and CI that builds the image and renders `deploy/` and `deploy/dev` before merge | +| `--tenancy` | `deploy/` Kustomize manifests, a signed image and manifests release on every `v*` tag, and CI that builds the image and renders `deploy/` before merge | Every stack serves a placeholder page at `GET /` on port 3000, which is where the tenant's probes look, so a new tenant deploys before you write any code. @@ -113,9 +113,9 @@ Default PR CI always builds the tenant image and renders `deploy/` before merge, secrets or write authority. Keep the `delivery-inputs` job and its entry in `ci-required-checks` when you change the stack job. This catches the same image and manifest failures in the pull request that introduced them instead of during release or reconciliation. -Keep the `publish-pin-approved` job and its entry too: it verifies the direct publisher’s -minimal signing job and retains the approval checks while an existing tenant uses the shared -reusable publisher. An application scaffolded without +Keep the `publish-pin-approved` job and its entry too: it holds back a dependency update that +moves the publishing workflow to a revision the platform has not yet approved for your tenant, +so the release it would cut does not fail to deploy. An application scaffolded without `--tenancy` has neither job. After authorized App setup and platform registration, eligible Conventional Commits can produce diff --git a/deploy/base/kustomization.yaml b/deploy/base/kustomization.yaml deleted file mode 100644 index d3a522c..0000000 --- a/deploy/base/kustomization.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -# Everything production (../prod) and dev (../dev) share. Put a manifest here -# only when both environments run it unchanged; prod-only objects go in -# ../prod, and dev changes these objects with patches in ../dev. -resources: - - deployment.yaml - - service.yaml - - networkpolicy.yaml # re-opens Gateway ingress + DB/DNS egress under the platform's default-deny - - cluster.yaml # CloudNativePG database β€” delete this line if your tenant has no DB diff --git a/deploy/base/cluster.yaml b/deploy/cluster.yaml similarity index 100% rename from deploy/base/cluster.yaml rename to deploy/cluster.yaml diff --git a/deploy/base/deployment.yaml b/deploy/deployment.yaml similarity index 97% rename from deploy/base/deployment.yaml rename to deploy/deployment.yaml index 83ecc43..aa29736 100644 --- a/deploy/base/deployment.yaml +++ b/deploy/deployment.yaml @@ -6,7 +6,7 @@ metadata: app.kubernetes.io/name: app # The platform's `validate-replica-floor` Kyverno policy (Audit) flags any # Deployment/StatefulSet under 2 replicas β€” the platform HA floor that makes - # the drain-safe `maxUnavailable: 1` PDB (../prod/poddisruptionbudget.yaml) actually + # the drain-safe `maxUnavailable: 1` PDB (poddisruptionbudget.yaml) actually # preserve availability through a node drain (see platform#1882; the paired # `validate-replica-ceiling` policy caps tenants at 3). The scaffold ships a # single replica (a fresh tenant starts small), so it opts out explicitly @@ -56,7 +56,7 @@ spec: type: RuntimeDefault # The app never talks to the Kubernetes API, so don't mount an API token # into the pod (the platform-provisioned tenant ServiceAccount is used by - # External Secrets' Vault auth via ../prod/secretstore.yaml, not by this pod). + # External Secrets' Vault auth via secretstore.yaml, not by this pod). # Remove this only if your app genuinely calls the API. automountServiceAccountToken: false # Spread replicas across nodes so a scale-up to 2-3 replicas is actually diff --git a/deploy/dev/kustomization.yaml b/deploy/dev/kustomization.yaml deleted file mode 100644 index 41a344f..0000000 --- a/deploy/dev/kustomization.yaml +++ /dev/null @@ -1,23 +0,0 @@ -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -# Dev: the shared base, changed only by the patches below. The platform -# reconciles it at `path: ./dev` into its own `-dev` namespace and owns -# its ingress behind sign-on, so dev carries no public route, disruption -# budget, or production secret path. Change base objects with patches here; -# never copy a manifest. -resources: - - ../base -# One replica, whatever production runs. -replicas: - - name: app - count: 1 -patches: - # Keep the single dev replica clear of the platform's replica-floor audit - # even after you remove this label from the base for production HA. - - target: - kind: Deployment - name: app - patch: |- - - op: add - path: /metadata/labels/platform.devantler.tech~1replica-floor - value: exempt diff --git a/deploy/prod/externalsecret.yaml b/deploy/externalsecret.yaml similarity index 81% rename from deploy/prod/externalsecret.yaml rename to deploy/externalsecret.yaml index 0c575cd..abbd06b 100644 --- a/deploy/prod/externalsecret.yaml +++ b/deploy/externalsecret.yaml @@ -1,8 +1,7 @@ # Materializes a native Kubernetes Secret in this namespace from OpenBao, via the # namespaced SecretStore above. Store the real values in OpenBao under your # tenant prefix (`secret/apps//*`, KV v2) out of band first. Reference the -# resulting Secret with a secretKeyRef from a patch in deploy/prod: the Deployment -# lives in deploy/base, which dev shares, and dev reads no production secret. +# resulting Secret from deploy/deployment.yaml with a secretKeyRef. apiVersion: external-secrets.io/v1 kind: ExternalSecret metadata: diff --git a/deploy/prod/httproute.yaml b/deploy/httproute.yaml similarity index 100% rename from deploy/prod/httproute.yaml rename to deploy/httproute.yaml diff --git a/deploy/kustomization.yaml b/deploy/kustomization.yaml index 3c60e51..e8152d2 100644 --- a/deploy/kustomization.yaml +++ b/deploy/kustomization.yaml @@ -1,9 +1,12 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization -# Production entry point. The platform reconciles the published manifests -# artifact at `path: .`, which is this file, so it must only include ./prod. -# Shared manifests live in ./base, production-only ones in ./prod, and the dev -# overlay in ./dev (reconciled at `path: ./dev` into the `-dev` -# namespace). resources: - - prod + - deployment.yaml + - poddisruptionbudget.yaml # drain-safe maxUnavailable:1 PDB so node drains never deadlock (platform#1882) + - httproute.yaml + - service.yaml + - networkpolicy.yaml # re-opens Gateway ingress + DB/DNS egress under the platform's default-deny + - cluster.yaml # CloudNativePG database β€” delete this line if your tenant has no DB + # OpenBao-backed secrets via External Secrets β€” delete both if you need none: + - secretstore.yaml + - externalsecret.yaml diff --git a/deploy/base/networkpolicy.yaml b/deploy/networkpolicy.yaml similarity index 96% rename from deploy/base/networkpolicy.yaml rename to deploy/networkpolicy.yaml index 61ce7b5..12d6143 100644 --- a/deploy/base/networkpolicy.yaml +++ b/deploy/networkpolicy.yaml @@ -41,8 +41,7 @@ metadata: spec: endpointSelector: {} ingress: - # Platform Gateway β†’ app HTTP (via ../prod/httproute.yaml in production; - # in dev, through the platform's sign-on ingress). + # Platform Gateway β†’ app HTTP (the Gateway routes here via httproute.yaml). # Match the container port in deployment.yaml if you change it from 3000. - fromEntities: - ingress diff --git a/deploy/prod/poddisruptionbudget.yaml b/deploy/poddisruptionbudget.yaml similarity index 100% rename from deploy/prod/poddisruptionbudget.yaml rename to deploy/poddisruptionbudget.yaml diff --git a/deploy/prod/kustomization.yaml b/deploy/prod/kustomization.yaml deleted file mode 100644 index 788b238..0000000 --- a/deploy/prod/kustomization.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -# Production: the shared base plus what only production runs β€” its public -# route, disruption budget, and anything holding a production credential or -# secret path. The platform reconciles this through ../kustomization.yaml. -resources: - - ../base - - poddisruptionbudget.yaml # drain-safe maxUnavailable:1 PDB so node drains never deadlock (platform#1882) - - httproute.yaml - # OpenBao-backed secrets via External Secrets β€” delete both if you need none: - - secretstore.yaml - - externalsecret.yaml diff --git a/deploy/prod/secretstore.yaml b/deploy/secretstore.yaml similarity index 100% rename from deploy/prod/secretstore.yaml rename to deploy/secretstore.yaml diff --git a/deploy/base/service.yaml b/deploy/service.yaml similarity index 100% rename from deploy/base/service.yaml rename to deploy/service.yaml diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 8599ab7..e140fd9 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -37,7 +37,7 @@ an invalid name, a second run and the upstream template checkout before it chang ## What the rename changes With `--tenancy`, `scripts/scaffold.sh` runs `scripts/rename-placeholders.sh`, which rewrites the `app`, `REPLACE_ME`, and `replace-me` -placeholders in `deploy/`, `base/`, `prod/` and `dev/` consistently, including the container name, Vault role, +placeholders in `deploy/` consistently, including the container name, Vault role, and ServiceAccount. Those values **must** equal the repository name (see the convention under [How publishing works](#how-publishing-works)). The helper preserves the `app.kubernetes.io/name` label *keys*, CloudNativePG's literal `-app` @@ -46,7 +46,7 @@ half-wrong. It's a one-shot helper: the scaffold removes it once it has run. The example route is renamed for both environments: `.platform.lan` locally and `.platform.devantler.tech` in production, both in -`deploy/prod/httproute.yaml`. Add any custom domains beside them; a tenant that moves +`deploy/httproute.yaml`. Add any custom domains beside them; a tenant that moves to its own canonical domain may drop the `platform.devantler.tech` hostname. Each Platform Gateway attaches only the hostnames its listener serves. @@ -57,43 +57,6 @@ the `platform.devantler.tech` hostname, point the tile's `gethomepage.dev/href` annotation at your canonical domain too, or the tile links to an address the route no longer serves. -## The deploy layout - -Every custom-built app gets a production and a dev environment. Both reconcile -the same signed artifact, which holds the whole `deploy/` tree, so the tree is -split into Kustomize overlays that share one copy of each manifest: - -```text -deploy/ -β”œβ”€β”€ kustomization.yaml # production entry: includes only ./prod -β”œβ”€β”€ base/ # what production and dev both run -β”œβ”€β”€ prod/ # ../base + production-only objects -└── dev/ # ../base + dev patches -``` - -- **`deploy/kustomization.yaml`** is what the platform reconciles for production, - at `path: .`. Keep it to `resources: [prod]`. -- **`deploy/base/`** holds every manifest both environments run unchanged: the - Deployment, whose app container receives the published image digest, the - Service, the network policy and an optional CNPG database. In dev that - database is a separate, empty instance in the dev namespace. -- **`deploy/prod/`** adds what only production runs: public routes and - hostnames, certificates and DNS, PodDisruptionBudgets, backups, and anything - that reads production data or holds a production credential or secret path, - such as the OpenBao `SecretStore` and `ExternalSecret`. -- **`deploy/dev/`** changes base objects only with Kustomize `replicas` and - `patches`, never a copied manifest. It runs one replica and adds no route, - PDB, backup or production secret path: the platform reconciles it at - `path: ./dev` into a `-dev` namespace and owns its ingress behind - sign-on ([platform#6126](https://github.com/devantler-tech/platform/issues/6126)). - Turn on experimental features here only through runtime settings, such as an - environment variable patched onto the Deployment. - -Overlays reference only `../base` and their own files, so every directory builds -under Kustomize's default load restrictions. A secret the app needs in both -environments needs a dev source of its own in `deploy/dev`; reference a -production-only secret from a patch in `deploy/prod`. - ## What the template owns vs. what you own template-sync overwrites the files the template **owns** and never touches the @@ -117,7 +80,7 @@ the template excludes, add the line `!` to your list. | File | Purpose | |---|---| -| `.github/workflows/cd.yaml` (*tenant*) | On a `v*` tag, runs the pinned `actions/publish-app` action to build, digest-pin, push and sign the image and manifests as this repository’s own release workflow | +| `.github/workflows/cd.yaml` (*tenant*) | On a `v*` tag, calls `publish-app.yaml` to build, digest-pin, push, and **cosign-sign** the image + manifests OCI artifact | | `.github/workflows/release.yaml` | semantic-release on `main` (cuts the `v*` tags that drive `cd.yaml`) | | `.github/workflows/codeql.yaml` | Advanced CodeQL for the languages found in the repository, reading `.github/codeql/codeql-config.yml`; off until default setup is off and `CODEQL_SETUP=advanced` | | `.github/workflows/lint.yaml`, `.github/mega-linter.base.yml` | The shared MegaLinter job `ci.yaml` calls, and the base configuration `.mega-linter.yml` extends | @@ -129,7 +92,8 @@ the template excludes, add the line `!` to your list. | `CLAUDE.md` | `@AGENTS.md` shim | | `docs/REFERENCE.md` | This reference | | `scripts/workflow-caller-pin-contract.test.sh` (*tenant*) | Runs in each tenant's required CI and rejects malformed, divergent, or rolled-back reusable-workflow pins, and a version comment that does not name the tag of the pinned commit | -| `scripts/publish-pin-approved.sh`, `scripts/publish-pin-approved.test.sh` (*tenant*) | Checks the minimal direct-action signing job. Existing reusable-workflow callers retain their exact Platform approval checks. The default `ci.yaml` runs the `publish-pin-approved` job and includes it in `ci-required-checks`; this unregistered template runs its tests only. Older tenants that own `ci.yaml` add the job themselves | +| `scripts/fixtures/own-publisher.yaml` (*tenant*) | Direct-action compatibility input used by the portable caller and approval checks; sync it with those checks | +| `scripts/publish-pin-approved.sh`, `scripts/publish-pin-approved.test.sh` (*tenant*) | The check a tenant's required CI runs to refuse a changed publisher identity until Platform approves it for that tenant. Legacy revisions use the existing approved set; maintained publishers require an exact canonical approval. The default `ci.yaml` runs the `publish-pin-approved` job and includes it in `ci-required-checks`; this unregistered template runs its tests only. Older tenants that own `ci.yaml` add the job themselves | | `zizmor.yml` | GitHub Actions pinning policy enforced by the security scan | **Scaffold-time only (arrives when the repo is created, is removed by `scripts/scaffold.sh`, and is @@ -140,7 +104,7 @@ never re-synced, so a tenant still carrying these from an older sync can delete | `stacks/` | The Go and .NET stack sources the scaffold copies once; the copies are then yours | | `scripts/scaffold.sh` (+ its test) | One-shot stack and tenancy scaffold; its test scaffolds every combination and checks what each leaves | | `.github/workflows/validate-stacks.yaml` | Scaffolds each stack as a tenant, then builds, tests, lints, renders `deploy/`, builds the image and checks it serves `GET /` under the restricted container settings | -| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/` and `deploy/dev`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only | +| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only | | `scripts/rename-placeholders.sh` (+ its test) | One-shot rename of the placeholder app to your tenant name | | `scripts/agent-instructions.test.sh` | Fails closed if the one-time agent scaffold loses its ownership, dependency-bot, external-code, exact-head review, pinned-merge, or user-path evaluation boundaries, or regains a retired rule | | `scripts/workflow-caller-contract.test.sh` | Keeps the portable caller-pin contract wired into tenant CI while validating template-only publisher, release, ownership, and scaffold invariants | @@ -218,33 +182,69 @@ image, so their updates reach production on their own. GitHub Actions updates use the `ci` prefix (set in `.github/dependabot.yml`) and release nothing. Tenants own both files, so an existing tenant adds the `build(deps)` rule and the `ci` prefix itself. -Each tag triggers `cd.yaml`, which runs the pinned -[`actions/publish-app`](https://github.com/devantler-tech/.github/tree/main/actions/publish-app) -composite action directly in this repository. It builds the image, pins its digest into -`deploy/base/deployment.yaml`, and publishes the entire `deploy/` tree, including both overlays. -The image and manifests are signed as this repository’s own release workflow on its release tag. -The action refuses a tag outside the default branch, a persisted checkout credential, invalid -inputs, changed deployment sources and an occupied version before publication. It verifies the -signatures before exposing release tags. The upstream template itself never publishes. - -The required caller-pin check binds the action’s immutable commit to its version tag and rejects -versions below the reviewed floor. The signing-job check retains a tag-only trigger, credential-free -checkout, minimal permissions, serialization and an unskippable publisher. Existing reusable-workflow -callers still require their exact Platform publisher approvals; the direct action uses the tenant’s -own release identity instead. Keep the approval job while migrating existing consumers. - -The live envelope check reads Platform’s current KRO and manual tenant definitions. It verifies the -source, namespace, credential, reconciliation and OpenBao boundaries, including a match between the -starter’s own release identity and the generic tenant’s signer rule. Its existing shared-publisher -compatibility cases still reject mutable references, wrong producers, excess or duplicate approvals, -multiple YAML documents and malformed conditional source expressions. New controls also reject a -shared-only rule for the direct publisher and a signer name taken from anywhere except the tenant -name. This source compatibility check establishes no actual publication or deployment. +Each tag triggers `cd.yaml`, which calls the platform's +[`publish-app.yaml`](https://github.com/devantler-tech/.github/blob/main/.github/workflows/publish-app.yaml) +reusable workflow to build the image, **pin its digest into +`deploy/deployment.yaml`**, push the manifests as an OCI artifact, and +**cosign-sign** both. The platform's `OCIRepository` verifies that signature, so +only artifacts from this trusted workflow are eligible for reconciliation after +the platform has registered the tenant and its applicable publisher-approval +checks pass. Workflow configuration alone does not prove that publication or +reconciliation succeeded. + +Before moving a publisher between repositories, merge and template-sync the +approval check first. CI executes the check from the base revision so the +repoint cannot authorize itself. The same commit identifier in another +repository is a changed identity, not an unchanged pin. Maintained publishing +requires the tenant's exact `publish-app` approval in Platform's canonical +record, with at most two distinct reviewed commits during a transition; legacy +approvals do not authorize it. Merge and verify the corresponding Platform +approval and image/manifest verification policy before changing a tenant caller. + +The live envelope check accepts the manual tenant matcher's strict writer forms: +one to three distinct legacy commit IDs, optionally paired with one or two +distinct maintained commit IDs. Both locations must name the same app publisher, +all IDs must be full lowercase commit IDs, and the whole subject must be anchored. +Its controls exercise copies of the Platform envelope and reject mutable refs, +wildcards, wrong producers, duplicate IDs and excess approvals. This checks the +writer's narrow shape; Platform still owns which exact revisions are approved. +The generic KRO rule may retain the existing legacy full-commit pattern, alone +or paired with one or two literal maintained commits. Its rule must also match +the starter's actual pinned publisher identity; recognizing a valid rule shape +does not establish that the producer and consumer agree. Maintained wildcards, +mutable callers, multiple YAML documents and control characters are rejected. +The current conditional TenantSource form is recognized without executing CEL: +the default subject is decoded and checked against the actual caller, while the +explicit arm must retain its exact maintained-publisher path and full-revision +schema. Digest selection must retain the immutable digest schema, and optional +application reconciliation must default on and preserve its deletion guard. +Static OCI references remain supported; conditional application reconciliation +still requires the same source schema and safeguards with that reference form. +The starter uses the maintained publisher at its reviewed minimum version. +Its portable guard rejects a return to the retired catalogue, movable refs, +older versions and version comments that do not match the immutable commit. +The Platform approval and verification policy must be deployed before a live +tenant adopts that caller. This compatibility check does not activate publishing +or authorize a tenant's caller pin. > **Convention:** the Deployment's container `name` MUST equal the repository > name β€” `publish-app` pins the built image digest into the container with that > name (`app-name: ${{ github.event.repository.name }}` in `cd.yaml`). +## Staging a publisher migration + +Existing tenants keep their own `deploy/` tree and CI workflow. Land the updated portable caller +check, approval check, their tests and `scripts/fixtures/own-publisher.yaml` while keeping the +current publisher unchanged. The required approval job executes the checker from its base revision, +so the guard update must merge in the consumer before a later PR changes its publishing job. + +After that consumer’s base contains the updated checks, switch its publisher in a separate PR. +Keep support for both `deploy/deployment.yaml` and `deploy/base/deployment.yaml`: template sync does +not move tenant-owned manifests. The prepared direct-action contract accepts either fixed path or +the exact file-selection expression in the compatibility fixture. The existing reusable-workflow +caller still requires its original Platform approval; the new direct caller retains immutable pins, +a minimal signing job, credential-free checkout and an unskippable publisher. + ## Validate locally Native required CI also inspects workflow startup failures at the pull-request @@ -255,8 +255,7 @@ required checks for failures that happen after that snapshot. Run these from the repository root. In every platform tenant, and in this template: ```sh -kubectl kustomize deploy/ # production manifests build -kubectl kustomize deploy/dev # dev overlay builds (tenants with deploy/dev) +kubectl kustomize deploy/ # manifests build sh scripts/workflow-caller-pin-contract.test.sh # portable tenant caller-pin contract (resolves the version-comment tag on github.com and compares it with the pinned commit) sh scripts/publish-pin-approved.test.sh # publish-app pin approval check (reads a local approved set, never the network) actionlint .github/workflows/* # workflows parse diff --git a/scripts/fixtures/own-publisher.yaml b/scripts/fixtures/own-publisher.yaml new file mode 100644 index 0000000..86b7164 --- /dev/null +++ b/scripts/fixtures/own-publisher.yaml @@ -0,0 +1,38 @@ +name: πŸš€ CD + +on: + push: + tags: + - "v*" + +permissions: {} + +jobs: + publish: + name: Publish + # The upstream template has no application to publish; its ID survives renames. + if: github.repository_id != '1253884448' + runs-on: ubuntu-latest + timeout-minutes: 60 + concurrency: + group: publish-${{ github.repository }} + cancel-in-progress: false + permissions: + contents: read + packages: write + id-token: write + steps: + - name: πŸ”’ Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - name: πŸ“₯ Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: πŸ“¦ Publish signed application + id: publish + uses: devantler-tech/.github/actions/publish-app@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2 + with: + app-name: ${{ github.event.repository.name }} + app-manifest: ${{ hashFiles('deploy/base/deployment.yaml') != '' && 'base/deployment.yaml' || 'deployment.yaml' }} diff --git a/scripts/platform-tenant-envelope-contract.test.sh b/scripts/platform-tenant-envelope-contract.test.sh index 9061a2d..4311cb5 100644 --- a/scripts/platform-tenant-envelope-contract.test.sh +++ b/scripts/platform-tenant-envelope-contract.test.sh @@ -71,8 +71,8 @@ validate_contract() { 'resource-graph-definitions/tenant/resource-graph-definition.yaml' \ 'k8s/bases/infrastructure/vault-config/job.yaml' \ 'k8s/bases/apps/ascoachingogvaner' \ - 'deploy/prod/secretstore.yaml' \ - 'deploy/prod/externalsecret.yaml' \ + 'deploy/secretstore.yaml' \ + 'deploy/externalsecret.yaml' \ 'namespace.yaml' \ 'service-account.yaml' \ 'external-secret.yaml' \ diff --git a/scripts/platform-tenant-envelope.test.sh b/scripts/platform-tenant-envelope.test.sh index 70e43c5..56bd143 100644 --- a/scripts/platform-tenant-envelope.test.sh +++ b/scripts/platform-tenant-envelope.test.sh @@ -151,7 +151,6 @@ generic_default_subject() ( rgd=$2 publisher_revision=${3:-} conditional_subject=0 - own_subject='' # shellcheck disable=SC2016 prefix='${schema.spec.source.publisherRevision == "" ? ' # shellcheck disable=SC2016 @@ -177,7 +176,6 @@ generic_default_subject() ( # The literal after the name is exactly the own-release tail and # the end of the group, so nothing can follow the tenant's tag. [ "$own" = "$own_release_tail)\$" ] || exit 1 - own_subject='^https://github\.com/devantler-tech/app'"$own_release_tail"'$' group_prefix='^https://github\.com/devantler-tech/(' case "$shared" in "$group_prefix"*'|') ;; *) exit 1 ;; esac shared=${shared#"$group_prefix"} @@ -200,10 +198,6 @@ generic_default_subject() ( validate_revision_group "$publisher_revision" 1 || exit 1 subject='^https://github\.com/devantler-tech/\.github/\.github/workflows/publish-app\.yaml@'"$publisher_revision"'$' fi - if [ "${publisher_mode:-shared}" = own ]; then - [ -n "$own_subject" ] && [ -z "$publisher_revision" ] || exit 1 - subject=$own_subject - fi printf '%s\n' "$subject" ) @@ -213,16 +207,6 @@ validate_publish_workflow() { [ -f "$workflow_file" ] || fail "tenant publish workflow is missing: $workflow_file" yq eval-all -e '[.] | length == 1' "$workflow_file" >/dev/null || fail "tenant publish workflow must contain exactly one YAML document" - if yq eval -e '.jobs.publish | has("steps")' "$workflow_file" >/dev/null 2>&1; then - sh "$repo_root/scripts/publish-pin-approved.sh" "$workflow_file" "$workflow_file" >/dev/null || - fail "tenant publish workflow no longer has the minimal own-release signing contract" - publisher_mode=own - # Instantiate the generic tenant rule with a valid example name. The - # parser binds that name's position in the actual CEL expression below. - publisher_identity='https://github.com/devantler-tech/app/.github/workflows/cd.yaml@refs/tags/v1.0.0' - return - fi - publisher_mode=shared # The tag-only tenant job is the producer identity Platform's OCIRepository # accepts. Keep its authority both minimal and immutable. @@ -262,8 +246,8 @@ validate_openbao_authorization() ( for required_file in \ "$vault_config" \ "$rename_script" \ - "$scaffold_root/deploy/prod/secretstore.yaml" \ - "$scaffold_root/deploy/prod/externalsecret.yaml" + "$scaffold_root/deploy/secretstore.yaml" \ + "$scaffold_root/deploy/externalsecret.yaml" do [ -f "$required_file" ] || fail "OpenBao authorization source is missing: $required_file" done @@ -275,8 +259,8 @@ validate_openbao_authorization() ( cp "$rename_script" "$renamed_scaffold/scripts/rename-placeholders.sh" sh "$renamed_scaffold/scripts/rename-placeholders.sh" "$tenant_name" >/dev/null - secret_store=$renamed_scaffold/deploy/prod/secretstore.yaml - external_secret=$renamed_scaffold/deploy/prod/externalsecret.yaml + secret_store=$renamed_scaffold/deploy/secretstore.yaml + external_secret=$renamed_scaffold/deploy/externalsecret.yaml expected_remote_key=apps/$tenant_name/config export tenant_name expected_remote_key @@ -845,17 +829,8 @@ run_producer_control() { '(.spec.resources[] | select(.id == "ociRepository").template.spec.verify.matchOIDCIdentity[0].subject) = strenv(SUBJECT_CONTROL)' \ "$control/k8s/bases/infrastructure/resource-graph-definitions/tenant/resource-graph-definition.yaml" > "$mutation_dir/producer-control.yaml" mv "$mutation_dir/producer-control.yaml" "$control/k8s/bases/infrastructure/resource-graph-definitions/tenant/resource-graph-definition.yaml" - # Keep the existing shared-publisher compatibility and refusal controls - # independent of the starter's new direct-action execution frame. - if [ "${7:-shared}" = own ]; then - cp "$publish_workflow" "$mutation_dir/producer-cd.yaml" - else - CALLER_CONTROL=$control_caller yq eval ' - del(.jobs.publish.steps, .jobs.publish."runs-on", .jobs.publish."timeout-minutes", .jobs.publish.concurrency) - | .jobs.publish.uses = strenv(CALLER_CONTROL) - | .jobs.publish.with = {"app-name": strenv(expected_publish_app_name), "enable-caller-pin": true} - ' "$publish_workflow" > "$mutation_dir/producer-cd.yaml" - fi + CALLER_CONTROL=$control_caller yq eval '.jobs.publish.uses = strenv(CALLER_CONTROL)' \ + "$publish_workflow" > "$mutation_dir/producer-cd.yaml" case "${5:-}" in static-ref) yq eval '(.spec.resources[] | select(.id == "ociRepository").template.spec.ref) = {"semver": ">=1.0.0"}' \ @@ -897,15 +872,6 @@ control_legacy_caller=devantler-tech/actions/.github/workflows/publish-app.yaml@ control_maintained_caller=devantler-tech/.github/.github/workflows/publish-app.yaml@$control_b control_generic_legacy="${control_prefix}${control_legacy}[0-9a-f]{40}\$" control_generic_transition="${control_prefix}(${control_legacy}[0-9a-f]{40}|${control_canonical}${control_b})\$" -control_current_subject=$(yq eval -r '.spec.resources[] | select(.id == "ociRepository").template.spec.verify.matchOIDCIdentity[0].subject' \ - "$baseline/k8s/bases/infrastructure/resource-graph-definitions/tenant/resource-graph-definition.yaml") -run_producer_control 'direct publisher matches the current own-release rule' \ - "$control_current_subject" '' accept '' '' own -run_producer_control 'shared-only rule does not authorize a direct publisher' \ - "$control_generic_transition" '' reject '' '' own -control_wrong_name=$(printf '%s\n' "$control_current_subject" | sed 's/schema\.spec\.name\.replace/schema.spec.other.replace/g') -run_producer_control 'own-release name must come from the tenant name' \ - "$control_wrong_name" '' reject '' '' own run_producer_control 'static OCI ref retains conditional reconciliation safeguards' \ "$control_generic_transition" "$control_maintained_caller" accept static-ref # Literal CEL serialization from Platform's TenantSource publisher contract. @@ -1077,11 +1043,11 @@ run_vault_duplicate "tenant policy declared twice" \ run_vault_duplicate "tenant Kubernetes-auth role declared twice" \ 'bao write auth/kubernetes/role/ascoachingogvaner' 'ttl=1h' run_vault_prefixed_role_control "another tenant role starts with this tenant name" -run_scaffold_mutation "scaffold OpenBao role changed" deploy/prod/secretstore.yaml \ +run_scaffold_mutation "scaffold OpenBao role changed" deploy/secretstore.yaml \ '.spec.provider.vault.auth.kubernetes.role = "another-tenant"' -run_scaffold_mutation "scaffold OpenBao ServiceAccount changed" deploy/prod/secretstore.yaml \ +run_scaffold_mutation "scaffold OpenBao ServiceAccount changed" deploy/secretstore.yaml \ '.spec.provider.vault.auth.kubernetes.serviceAccountRef.name = "another-tenant"' -run_scaffold_mutation "scaffold OpenBao path crossed into another tenant" deploy/prod/externalsecret.yaml \ +run_scaffold_mutation "scaffold OpenBao path crossed into another tenant" deploy/externalsecret.yaml \ '.spec.data[0].remoteRef.key = "apps/another-tenant/config"' run_mutation "KRO managed-by label removed" "$rgd_path" \ 'del(.spec.resources[] | select(.id == "tenantNamespace").template.metadata.labels."app.kubernetes.io/managed-by")' @@ -1220,7 +1186,7 @@ run_publish_mutation "producer workflow unpinned" \ run_publish_mutation "producer workflow changed" \ '.jobs.publish.uses = "devantler-tech/actions/.github/workflows/other.yaml@47f0d9b632581a613963a2d25c243713f24c32a0"' run_publish_mutation "application identity hard-coded" \ - '.jobs.publish.steps[2].with."app-name" = "app"' + '.jobs.publish.with."app-name" = "app"' run_publish_mutation "publisher authority widened" \ '.jobs.publish.permissions.issues = "write"' run_publish_mutation "branch publication enabled" \ @@ -1232,9 +1198,9 @@ run_publish_mutation "second package publisher added" \ # happily accepting an explicit false β€” which is the mutation that silently # restores the unenforced default. Deleting the pair is what would let the # caller-pin requirement decay back to opt-in without a failing test. -run_publish_mutation "credential-free checkout removed" \ - 'del(.jobs.publish.steps[1].with."persist-credentials")' -run_publish_mutation "credential-free checkout disabled" \ - '.jobs.publish.steps[1].with."persist-credentials" = true' +run_publish_mutation "caller SHA-pin enforcement removed" \ + 'del(.jobs.publish.with."enable-caller-pin")' +run_publish_mutation "caller SHA-pin enforcement disabled" \ + '.jobs.publish.with."enable-caller-pin" = false' echo "PASS: signed tenant artifact envelope (KRO + manual + OpenBao + publisher + ${mutations_run} safety mutations + ${subject_controls_run} subject controls + ${producer_controls_run} producer controls)" diff --git a/scripts/platform-vpa-floor.test.sh b/scripts/platform-vpa-floor.test.sh index 0fde771..4aa1c93 100644 --- a/scripts/platform-vpa-floor.test.sh +++ b/scripts/platform-vpa-floor.test.sh @@ -32,7 +32,7 @@ validate_vpa_floor() ( platform_root=$1 scaffold_root=$2 platform_policy=$platform_root/k8s/bases/infrastructure/cluster-policies/best-practices/auto-vpa-deployment.yaml - deployment=$scaffold_root/deploy/base/deployment.yaml + deployment=$scaffold_root/deploy/deployment.yaml [ -f "$platform_policy" ] || fail "Platform auto-vpa policy is missing: $platform_policy" [ -f "$deployment" ] || fail "scaffold Deployment is missing: $deployment" @@ -103,7 +103,7 @@ VALUES scaffold_request_m=$(millicores "$scaffold_requests") [ "$scaffold_request_m" -ge "$platform_floor_m" ] || - fail "scaffold CPU request ${scaffold_requests} is below Platform VPA floor ${platform_floors}; raise deploy/base/deployment.yaml" + fail "scaffold CPU request ${scaffold_requests} is below Platform VPA floor ${platform_floors}; raise deploy/deployment.yaml" printf 'Platform VPA floor contract: request=%s floor=%s\n' "$scaffold_requests" "$platform_floors" ) @@ -121,9 +121,9 @@ mutation_dir=$(mktemp -d) trap 'rm -rf "$mutation_dir"' EXIT platform_policy_rel=k8s/bases/infrastructure/cluster-policies/best-practices/auto-vpa-deployment.yaml -mkdir -p "$mutation_dir/platform/$(dirname -- "$platform_policy_rel")" "$mutation_dir/scaffold/deploy/base" +mkdir -p "$mutation_dir/platform/$(dirname -- "$platform_policy_rel")" "$mutation_dir/scaffold/deploy" cp "$platform_root/$platform_policy_rel" "$mutation_dir/platform/$platform_policy_rel" -cp "$repo_root/deploy/base/deployment.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" +cp "$repo_root/deploy/deployment.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" # Rebuild pristine fixtures, apply one mutation, and require validation to reject it. run_mutation() { @@ -132,15 +132,15 @@ run_mutation() { scaffold_mutation=$3 cp "$platform_root/$platform_policy_rel" "$mutation_dir/platform/$platform_policy_rel" - cp "$repo_root/deploy/base/deployment.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" + cp "$repo_root/deploy/deployment.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" if [ -n "$platform_mutation" ]; then yq eval "$platform_mutation" "$mutation_dir/platform/$platform_policy_rel" > "$mutation_dir/platform-mutant.yaml" mv "$mutation_dir/platform-mutant.yaml" "$mutation_dir/platform/$platform_policy_rel" fi if [ -n "$scaffold_mutation" ]; then - yq eval "$scaffold_mutation" "$mutation_dir/scaffold/deploy/base/deployment.yaml" > "$mutation_dir/scaffold-mutant.yaml" - mv "$mutation_dir/scaffold-mutant.yaml" "$mutation_dir/scaffold/deploy/base/deployment.yaml" + yq eval "$scaffold_mutation" "$mutation_dir/scaffold/deploy/deployment.yaml" > "$mutation_dir/scaffold-mutant.yaml" + mv "$mutation_dir/scaffold-mutant.yaml" "$mutation_dir/scaffold/deploy/deployment.yaml" fi if (validate_vpa_floor "$mutation_dir/platform" "$mutation_dir/scaffold") >/dev/null 2>&1; then diff --git a/scripts/publish-pin-approved.sh b/scripts/publish-pin-approved.sh index b7e3f68..2559947 100644 --- a/scripts/publish-pin-approved.sh +++ b/scripts/publish-pin-approved.sh @@ -32,6 +32,12 @@ fail() { [ "$#" -eq 2 ] || fail 'usage: publish-pin-approved.sh ' # One complete publisher identity, not just a SHA that could belong to another repository. +publish_manifest_choice=$(cat <<'EXPRESSION' +${{ hashFiles('deploy/base/deployment.yaml') != '' && 'base/deployment.yaml' || 'deployment.yaml' }} +EXPRESSION +) +export publish_manifest_choice + publish_identity() { [ -f "$1" ] || fail "no cd.yaml at $1" yq eval-all -e '[.] | length == 1' "$1" >/dev/null || @@ -72,7 +78,9 @@ publish_identity() { and (.jobs.publish.steps[2].uses | test("^devantler-tech/[.]github/actions/publish-app@[0-9a-f]{40}$")) and (.jobs.publish.steps[2].with | keys | sort | join(",")) == "app-manifest,app-name" and .jobs.publish.steps[2].with."app-name" == "${{ github.event.repository.name }}" - and .jobs.publish.steps[2].with."app-manifest" == "base/deployment.yaml" + and (.jobs.publish.steps[2].with."app-manifest" == "base/deployment.yaml" + or .jobs.publish.steps[2].with."app-manifest" == "deployment.yaml" + or .jobs.publish.steps[2].with."app-manifest" == strenv(publish_manifest_choice)) ' "$1" >/dev/null || fail "$1 does not retain the minimal own-release signing contract" yq eval -r '.jobs.publish.steps[2].uses' "$1" return diff --git a/scripts/publish-pin-approved.test.sh b/scripts/publish-pin-approved.test.sh index 8fd9f16..df54958 100644 --- a/scripts/publish-pin-approved.test.sh +++ b/scripts/publish-pin-approved.test.sh @@ -164,9 +164,9 @@ expect 'canonical columns are bound by header, not position' 0 'is approved' "$w rm "$work/canonical.tsv" expect 'an unreadable canonical set fails closed' 1 'could not read' "$work/ok.tsv" "$candidate" example-tenant .github -# Exercise the actual direct caller, including the old-to-own identity transition. +# Exercise the direct caller contract, including the old-to-own identity transition. # Shared-publisher approval records remain mandatory for every legacy case above. -cp "$script_dir/../.github/workflows/cd.yaml" "$work/own.yaml" +cp "$script_dir/fixtures/own-publisher.yaml" "$work/own.yaml" cd_file base.yaml "$main_pin" .github status=0 output=$(PUBLISH_PIN_CONSUMER=example-tenant PUBLISH_PIN_APPROVED_SET="$work/missing.tsv" \ @@ -177,11 +177,23 @@ else printf 'FAIL: direct caller transition (exit %s)\n%s\n' "$status" "$output" >&2 failures=$((failures + 1)) fi +for manifest in deployment.yaml base/deployment.yaml; do + MANIFEST=$manifest yq eval '.jobs.publish.steps[2].with."app-manifest" = strenv(MANIFEST)' \ + "$work/own.yaml" >"$work/fixed-path.yaml" + if sh "$subject" "$work/base.yaml" "$work/fixed-path.yaml" >"$work/result" 2>&1; then + pass=$((pass + 1)) + else + printf 'FAIL: supported manifest path refused: %s\n' "$manifest" >&2 + cat "$work/result" >&2 + failures=$((failures + 1)) + fi +done for mutation in \ '.jobs.publish.steps[2].uses = "other-owner/repo/action@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"' \ '.jobs.publish.steps[2].uses = "devantler-tech/.github/actions/publish-app@main"' \ '.jobs.publish.steps[1].with."persist-credentials" = true' \ '.jobs.publish.steps[2].if = "false"' \ + '.jobs.publish.steps[2].with."app-manifest" = "other/deployment.yaml"' \ '.jobs.publish.permissions.issues = "write"' \ '.jobs.publish.steps += [.jobs.publish.steps[2]]' \ '.jobs.shadow = .jobs.publish' \ diff --git a/scripts/rename-placeholders.sh b/scripts/rename-placeholders.sh index 1a4f582..f1b68b5 100755 --- a/scripts/rename-placeholders.sh +++ b/scripts/rename-placeholders.sh @@ -1,8 +1,7 @@ #!/usr/bin/env sh # rename-placeholders.sh β€” turn this scaffold into a real tenant in one shot. # -# The deploy/ manifests (the root entry and its base/, prod/ and dev/ -# overlays) ship with three placeholder forms that collapse to one +# The deploy/ manifests ship with three placeholder forms that collapse to one # value β€” your tenant (repository) name: # β€’ `app` β€” the example app/resource name (Deployment, Service, the # `app.kubernetes.io/name` label *value*, HTTPRoute, the CNPG @@ -14,8 +13,8 @@ # repository name β€” see docs/REFERENCE.md β€” so a single name drives everything.) # # Doing this by hand is easy to get half-wrong; this script renames all three -# across deploy/*.yaml and deploy/*/*.yaml in place WITHOUT corrupting the -# parts that must NOT change: +# across deploy/*.yaml in place WITHOUT corrupting the parts that must NOT +# change: # β€’ the `app.kubernetes.io/name` label *key* (only its value is renamed), # β€’ CloudNativePG's literal `-app` suffix on its generated secret, and # β€’ the shared `openbao` SecretStore name. @@ -49,8 +48,7 @@ deploy_dir="$repo_root/deploy" } changed=0 -# The root entry and one level of overlays (base/, prod/, dev/). -for f in "$deploy_dir"/*.yaml "$deploy_dir"/*/*.yaml; do +for f in "$deploy_dir"/*.yaml; do [ -f "$f" ] || continue tmp="$f.rename.$$" # Order matters: the longer CNPG-secret suffix is handled before `app-db`, and @@ -81,5 +79,4 @@ for f in "$deploy_dir"/*.yaml "$deploy_dir"/*/*.yaml; do done echo "Renamed placeholders to '$name' across $changed file(s) in deploy/." -echo "Next: review with 'git diff', then 'kubectl kustomize deploy/' (production) and" -echo " 'kubectl kustomize deploy/dev' to confirm both build." +echo "Next: review with 'git diff', then 'kubectl kustomize deploy/' to confirm it builds." diff --git a/scripts/rename-placeholders.test.sh b/scripts/rename-placeholders.test.sh index 6b7ed6a..60d0504 100755 --- a/scripts/rename-placeholders.test.sh +++ b/scripts/rename-placeholders.test.sh @@ -3,8 +3,7 @@ # # rename-placeholders.sh is the first thing a newcomer runs after `Use this # template` β€” it rewrites the `app`, REPLACE_ME, and `replace-me` placeholders -# across deploy/ (the root entry and its base/, prod/ and dev/ overlays) into -# the tenant's real name. A silent regression ships +# across deploy/*.yaml into the tenant's real name. A silent regression ships # broken manifests to every tenant created from this scaffold, and it had no # other coverage. The existing validation gate schema-validates the *unrenamed* # manifests but never runs the rename, so a botched sed address would pass green. @@ -20,9 +19,7 @@ # repointed to the tenant name alongside the uppercase placeholders, # * invalid (non-DNS-1123) names are rejected without mutating anything, # * no stray sed temp files are left behind, and -# * the dev overlay's replica override and patch follow the rename, and -# * the renamed production entry and dev overlay still `kubectl kustomize`-build -# (CI only). +# * the renamed scaffold still `kubectl kustomize`-builds (CI only). # # It runs the script against a throwaway copy so the real working tree is never # mutated. Run locally with `sh scripts/rename-placeholders.test.sh`; CI runs it @@ -38,20 +35,6 @@ fail() { exit 1 } -# The publisher must be able to find the app inside the complete artifact tree. -# A flat-layout default would make every generated tenant's first release fail. -app_manifest=$(yq eval -r '.jobs.publish.steps[] | select(.id == "publish") | .with."app-manifest"' "$repo_root/.github/workflows/cd.yaml") -[ -n "$app_manifest" ] && [ -f "$repo_root/deploy/$app_manifest" ] || - fail "publisher app-manifest does not name an existing deployment manifest" - -# Every manifest under a deploy/ tree β€” the root entry and its base/, prod/ and -# dev/ overlays β€” concatenated in a stable order. -deploy_yaml() { - find "$1" -type f -name '*.yaml' | LC_ALL=C sort | while IFS= read -r manifest; do - cat "$manifest" - done -} - # Build a throwaway copy of the working tree so the real tree is never mutated # (the script now targets the scaffold owning it, i.e. this copy). The copy is # its own git repo so check 7's `git status` works. @@ -68,13 +51,13 @@ script="./scripts/rename-placeholders.sh" deploy="deploy" # --- Guardrails: each must reject and exit non-zero, mutating nothing ---------- -snapshot_before="$(deploy_yaml "$deploy")" +snapshot_before="$(cat "$deploy"/*.yaml)" for bad in "My Tenant" "UPPER" "-bad" "bad-" "with_underscore"; do if "$script" "$bad" >/dev/null 2>&1; then fail "expected rejection of invalid DNS-1123 name: '$bad'" fi done -[ "$(deploy_yaml "$deploy")" = "$snapshot_before" ] || +[ "$(cat "$deploy"/*.yaml)" = "$snapshot_before" ] || fail "a rejected invocation modified deploy/ β€” guardrails must bail out first" homepage_route_contract() { @@ -89,7 +72,7 @@ homepage_route_contract() { ' "$1" >/dev/null 2>&1 } -homepage_route_contract "$deploy/prod/httproute.yaml" || +homepage_route_contract "$deploy/httproute.yaml" || fail "scaffold HTTPRoute does not expose the complete Homepage discovery contract" # Publication replaces this explicit placeholder with the built digest. Even the @@ -97,11 +80,11 @@ homepage_route_contract "$deploy/prod/httproute.yaml" || scaffold_image_contract() { yq eval -e '.spec.template.spec.containers[0].image == "ghcr.io/devantler-tech/REPLACE_ME:0.0.0"' "$1" >/dev/null 2>&1 } -scaffold_image_contract "$deploy/base/deployment.yaml" || +scaffold_image_contract "$deploy/deployment.yaml" || fail "scaffold image must use its explicit versioned placeholder" for bad_image in ghcr.io/devantler-tech/REPLACE_ME:latest ghcr.io/devantler-tech/REPLACE_ME ghcr.io/another/REPLACE_ME:0.0.0; do mutant="${work}/image-mutant.yaml" - BAD_IMAGE="$bad_image" yq eval '.spec.template.spec.containers[0].image = strenv(BAD_IMAGE)' "$deploy/base/deployment.yaml" > "$mutant" + BAD_IMAGE="$bad_image" yq eval '.spec.template.spec.containers[0].image = strenv(BAD_IMAGE)' "$deploy/deployment.yaml" > "$mutant" if scaffold_image_contract "$mutant"; then fail "image contract accepted $bad_image" fi @@ -110,7 +93,7 @@ done for annotation in href pod-selector; do mutant="${work}/homepage-${annotation}-mutant.yaml" yq eval "del(.metadata.annotations.\"gethomepage.dev/${annotation}\")" \ - "$deploy/prod/httproute.yaml" > "$mutant" + "$deploy/httproute.yaml" > "$mutant" if homepage_route_contract "$mutant"; then fail "Homepage contract accepted a route without gethomepage.dev/${annotation}" fi @@ -139,13 +122,13 @@ yq eval ".spec.hostnames += [\"${custom_local_hostname}\", \"${custom_prod_hostn .metadata.annotations.\"gethomepage.dev/description\" = \"${custom_description}\" | .metadata.annotations.\"gethomepage.dev/group\" = \"${custom_group}\" | .metadata.annotations.\"gethomepage.dev/icon\" = \"${custom_icon}\"" \ - "$deploy/prod/httproute.yaml" > "$deploy/prod/httproute-with-custom.yaml" -mv "$deploy/prod/httproute-with-custom.yaml" "$deploy/prod/httproute.yaml" + "$deploy/httproute.yaml" > "$deploy/httproute-with-custom.yaml" +mv "$deploy/httproute-with-custom.yaml" "$deploy/httproute.yaml" # --- Happy path --------------------------------------------------------------- "$script" "$NAME" >/dev/null -all="$(deploy_yaml "$deploy")" +all="$(cat "$deploy"/*.yaml)" # 1) REPLACE_ME fully repointed (container image + OpenBao KV path); none remain. printf '%s\n' "$all" | grep -qF "ghcr.io/devantler-tech/${NAME}:0.0.0" || @@ -176,7 +159,7 @@ for field_and_value in \ "icon=${custom_icon}"; do field="${field_and_value%%=*}" expected="${field_and_value#*=}" - actual="$(yq eval ".metadata.annotations.\"gethomepage.dev/${field}\"" "$deploy/prod/httproute.yaml")" + actual="$(yq eval ".metadata.annotations.\"gethomepage.dev/${field}\"" "$deploy/httproute.yaml")" [ "$actual" = "$expected" ] || fail "Homepage ${field} expected '${expected}' after rename, found '${actual}'" done @@ -207,7 +190,7 @@ printf '%s\n' "$all" | grep -qF "name: openbao" || # 6) The lowercase `replace-me` Vault role / ServiceAccount placeholders are # repointed to the tenant name too; no tenant-identity placeholder survives. -grep -qE "^[[:space:]]*role: \"${NAME}\"$" "$deploy/prod/secretstore.yaml" || +grep -qE "^[[:space:]]*role: \"${NAME}\"$" "$deploy/secretstore.yaml" || fail "SecretStore Vault role not renamed to ${NAME}" if ! awk -v expected="name: \"${NAME}\"" ' /^[[:space:]]*serviceAccountRef:[[:space:]]*$/ { in_ref = 1; next } @@ -219,21 +202,14 @@ if ! awk -v expected="name: \"${NAME}\"" ' exit 0 } END { if (!found) exit 1 } -' "$deploy/prod/secretstore.yaml"; then +' "$deploy/secretstore.yaml"; then fail "SecretStore ServiceAccount reference not exactly ${NAME}" fi -grep -qF "replace-me" "$deploy/prod/secretstore.yaml" && +grep -qF "replace-me" "$deploy/secretstore.yaml" && fail "a lowercase 'replace-me' tenant-identity placeholder survived the rename" [ "$(cat "$scope_fixture")" = "$scope_before" ] || fail "rename touched unrelated role/name fields" -# 6b) The dev overlay's targets follow the rename. Kustomize skips a patch whose -# target names no object without any error, so check the names themselves. -[ "$(yq eval '.replicas[0].name' "$deploy/dev/kustomization.yaml")" = "$NAME" ] || - fail "dev overlay replica override does not target the renamed Deployment" -[ "$(yq eval '.patches[0].target.name' "$deploy/dev/kustomization.yaml")" = "$NAME" ] || - fail "dev overlay patch does not target the renamed Deployment" - # 7) No stray temp files left behind by the in-place sed. if git status --porcelain --untracked-files=all | grep -q '\.rename\.'; then fail "stray *.rename.* temp file left behind" @@ -241,7 +217,7 @@ fi # 8) Idempotent: a second run with the same name changes nothing more. "$script" "$NAME" >/dev/null -[ "$(deploy_yaml "$deploy")" = "$all" ] || +[ "$(cat "$deploy"/*.yaml)" = "$all" ] || fail "a second rename mutated deploy/ β€” the script is not idempotent" # 9) Cross-checkout invocation (#61): a path-qualified call from an UNRELATED @@ -253,13 +229,13 @@ rm -rf "$other/.git" git init -q "$other" git init -q "$caller_repo" cp -R "$repo_root/deploy" "$caller_repo/deploy" -caller_before="$(deploy_yaml "$caller_repo/deploy")" +caller_before="$(cat "$caller_repo"/deploy/*.yaml)" (cd "$caller_repo" && "$other/scripts/rename-placeholders.sh" cross-tenant >/dev/null) -[ "$(deploy_yaml "$caller_repo/deploy")" = "$caller_before" ] || +[ "$(cat "$caller_repo"/deploy/*.yaml)" = "$caller_before" ] || fail "cross-checkout invocation mutated the CALLER's deploy/ (#61)" -deploy_yaml "$other/deploy" | grep -qF "cross-tenant.platform.lan" || +cat "$other"/deploy/*.yaml | grep -qF "cross-tenant.platform.lan" || fail "cross-checkout invocation did not rename the scaffold owning the script (#61)" -deploy_yaml "$other/deploy" | grep -qF "cross-tenant.platform.devantler.tech" || +cat "$other"/deploy/*.yaml | grep -qF "cross-tenant.platform.devantler.tech" || fail "cross-checkout invocation did not rename the production hostname (#99)" # 10) The renamed scaffold still builds (CI has kubectl preinstalled; skip locally @@ -267,16 +243,8 @@ deploy_yaml "$other/deploy" | grep -qF "cross-tenant.platform.devantler.tech" || if command -v kubectl >/dev/null 2>&1; then kubectl kustomize "$deploy" >/dev/null || fail "renamed deploy/ no longer 'kubectl kustomize'-builds" - dev_render=$(kubectl kustomize "$deploy/dev") || - fail "renamed deploy/dev no longer 'kubectl kustomize'-builds" - # shellcheck disable=SC2016 # yq expression, not shell. - printf '%s\n' "$dev_render" | NAME="$NAME" yq eval-all -e ' - [.] | map(select(.kind == "Deployment")) - | [(length == 1), (.[0].metadata.name == strenv(NAME)), (.[0].spec.replicas == 1)] - | all - ' - >/dev/null || fail "renamed dev overlay does not run exactly one replica of ${NAME}" else echo "note: kubectl not found β€” skipping the kustomize-build assertion (CI enforces it)" fi -echo "PASS: rename-placeholders.sh end-to-end (guardrails + placeholder/app rename + label-key/CNPG-suffix/openbao invariants + idempotency + cross-checkout targeting + dev overlay + build)" +echo "PASS: rename-placeholders.sh end-to-end (guardrails + placeholder/app rename + label-key/CNPG-suffix/openbao invariants + idempotency + cross-checkout targeting + build)" diff --git a/scripts/scaffold.test.sh b/scripts/scaffold.test.sh index 947e00c..9139863 100755 --- a/scripts/scaffold.test.sh +++ b/scripts/scaffold.test.sh @@ -114,9 +114,9 @@ check_tenancy() { # shellcheck disable=SC2016 grep -Fq 'build the tenant image and render `deploy/` before merge' "$dir/AGENTS.md" || fail "$label: AGENTS.md lost the delivery-input invariant" - grep -q "name: demo-app$" "$dir/deploy/base/deployment.yaml" || + grep -q "name: demo-app$" "$dir/deploy/deployment.yaml" || fail "$label: deploy/ was not renamed to the application" - grep -q 'REPLACE_ME' "$dir/deploy/base/deployment.yaml" && + grep -q 'REPLACE_ME' "$dir/deploy/deployment.yaml" && fail "$label: deploy/ still carries a placeholder image" # The scaffolded gate must satisfy the same contract as the template's own. sh "$repo_root/scripts/tenant-ci-contract.test.sh" --validate \ @@ -229,7 +229,7 @@ dir=$work/named/checkout copy_template "$dir" sh "$dir/scripts/scaffold.sh" go --tenancy widget >/dev/null grep -qx 'module github.com/devantler-tech/widget' "$dir/go.mod" || fail "explicit name: go.mod not renamed" -grep -q 'name: widget$' "$dir/deploy/base/deployment.yaml" || fail "explicit name: deploy/ not renamed" +grep -q 'name: widget$' "$dir/deploy/deployment.yaml" || fail "explicit name: deploy/ not renamed" echo "ok: explicit name" # The name `example` already matches the .NET placeholder project, so nothing moves. diff --git a/scripts/tenant-ci-contract.test.sh b/scripts/tenant-ci-contract.test.sh index 21c6f55..7b70f6f 100755 --- a/scripts/tenant-ci-contract.test.sh +++ b/scripts/tenant-ci-contract.test.sh @@ -88,7 +88,7 @@ validate_contract() { ' assert_ci "manifest-render step must have only audited keys" ' ((.jobs."delivery-inputs".steps[3] | keys | sort | join(",")) == "name,run,shell,working-directory") - and (.jobs."delivery-inputs".steps[3].run == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null") + and (.jobs."delivery-inputs".steps[3].run == "kubectl kustomize deploy/ >/dev/null") and (.jobs."delivery-inputs".steps[3].shell == "bash") and (.jobs."delivery-inputs".steps[3]."working-directory" == ".") ' @@ -125,7 +125,7 @@ validate_contract() { ' assert_ci "tenant manifest render is missing" ' [.jobs."delivery-inputs".steps[] | select( - (.run // "") == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null" + (.run // "") == "kubectl kustomize deploy/ >/dev/null" )] | length == 1 ' # The aggregate consumes `needs.*.result`, so `needs` alone decides what is checked: it must @@ -343,7 +343,7 @@ run_mutation "workflow secret environment added" \ run_mutation "container build removed" \ 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "docker build --tag tenant-delivery-check ."))' run_mutation "manifest render removed" \ - 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "kubectl kustomize deploy/ >/dev/null && kubectl kustomize deploy/dev >/dev/null"))' + 'del(.jobs."delivery-inputs".steps[] | select((.run // "") == "kubectl kustomize deploy/ >/dev/null"))' run_mutation "checkout credentials retained" \ '.jobs."delivery-inputs".steps[] |= (select(.uses | test("^actions/checkout@[0-9a-f]{40}$")).with."persist-credentials" = true)' run_mutation "second mutable checkout added" \ @@ -368,8 +368,6 @@ run_mutation "image build shell replaced with no-op" \ '.jobs."delivery-inputs".steps[2].shell = "echo {0}"' run_mutation "manifest render redirected to decoy" \ '.jobs."delivery-inputs".steps[3]."working-directory" = "fixtures/valid"' -run_mutation "dev overlay render dropped" \ - '.jobs."delivery-inputs".steps[3].run = "kubectl kustomize deploy/ >/dev/null"' run_mutation "job permissions broadened" \ '.jobs."delivery-inputs".permissions.packages = "write"' run_mutation "delivery dependency removed from aggregate" \ diff --git a/scripts/workflow-caller-contract.test.sh b/scripts/workflow-caller-contract.test.sh index d248e29..271c5dc 100644 --- a/scripts/workflow-caller-contract.test.sh +++ b/scripts/workflow-caller-contract.test.sh @@ -46,6 +46,8 @@ tenant_ignored() { [ -f "$portable_contract" ] || fail 'the portable workflow-caller pin contract is missing' +[ -f "$repo_root/scripts/fixtures/own-publisher.yaml" ] || + fail 'the direct publisher compatibility fixture is missing' grep -Fqx 'scripts/workflow-caller-contract.test.sh' "$template_sync_ignore" || fail 'the scaffold-only workflow-caller contract must stay tenant-ignored' if grep -Fqx 'scripts/workflow-caller-pin-contract.test.sh' "$template_sync_ignore"; then @@ -77,25 +79,20 @@ validate_contract() { reference_file=$5 ignore_file=$6 dependabot_file=$7 + if tenant_ignored "$ignore_file" scripts/fixtures/own-publisher.yaml; then + fail 'the portable caller fixture must reach tenants through template sync' + fi - yq eval -e '.jobs.publish.steps[2].uses | test("^devantler-tech/[.]github/actions/publish-app@[0-9a-f]{40}$")' \ + yq eval -e '.jobs.publish.uses | test("^devantler-tech/[.]github/[.]github/workflows/publish-app[.]yaml@[0-9a-f]{40}$")' \ "$cd_file" >/dev/null || fail 'the starter must ship the maintained application publisher' sh "$portable_contract" --validate "$cd_file" "$release_file" "$template_sync_file" || fail 'the portable workflow-caller pin contract rejected the caller set' - yq eval -e ' - (.jobs.publish | has("uses") | not) - and (.jobs.publish | has("with") | not) - and .jobs.publish.steps[1].with."persist-credentials" == false - and .jobs.publish.steps[2].id == "publish" - and (.jobs.publish.steps[2] | has("if") | not) - and (.jobs.publish.steps[2] | has("continue-on-error") | not) - and .jobs.publish.steps[2].with."app-manifest" == "base/deployment.yaml" - ' \ + yq eval -e '.jobs.publish.with."enable-caller-pin" == true' \ "$cd_file" >/dev/null || - fail 'the publish caller must keep credential-free checkout and mandatory publication' + fail 'the publish caller must keep the producer-side ref guard enabled' # Canonical release and sync callers move together within their own catalogue. # The maintained publisher has an independent, explicitly approved version. Dependabot treats @@ -267,11 +264,11 @@ run_mutation() { } run_mutation 'publish caller SHA pin removed' cd \ - '.jobs.publish.steps[2].uses = "devantler-tech/.github/actions/publish-app@main"' + '.jobs.publish.uses = "devantler-tech/.github/.github/workflows/publish-app.yaml@main"' run_mutation 'legacy publisher restored' cd \ - '.jobs.publish.steps[2].uses = "devantler-tech/actions/.github/workflows/publish-app.yaml@ea4df9004d4ab43b6c9af5b0c5f55712f7211328"' + '.jobs.publish.uses = "devantler-tech/actions/.github/workflows/publish-app.yaml@ea4df9004d4ab43b6c9af5b0c5f55712f7211328"' run_mutation 'publisher-side caller pin disabled' cd \ - '.jobs.publish.steps[2].if = "false"' + '.jobs.publish.with."enable-caller-pin" = false' run_mutation 'release caller SHA pin removed' release \ '.jobs.release.uses = "devantler-tech/.github/.github/workflows/create-release.yaml@main"' run_mutation 'release issue isolation disabled' release \ @@ -288,6 +285,11 @@ run_mutation 'template-sync ignore-entry merge disabled' template-sync \ '.jobs."template-sync".with."merge-template-ignore-entries" = false' run_mutation 'template-sync ignore-entry merge removed' template-sync \ 'del(.jobs."template-sync".with."merge-template-ignore-entries")' +# The sed append address is literal; it must not expand as a shell variable. +# shellcheck disable=SC2016 +run_mutation 'portable caller fixture excluded from template sync' ignore \ + '$a\ +scripts/fixtures/own-publisher.yaml' run_mutation 'required scaffold invocation removed' validation \ 'del(.jobs."validate-scaffold".steps[] | select(.run == "sh scripts/workflow-caller-contract.test.sh"))' run_mutation 'reference ownership table marker removed' reference \ @@ -352,25 +354,20 @@ run_fleet_mutation() { cp "$dependabot_config" "$mutation_dir/dependabot.yml" for pair in \ - "cd.yaml|.jobs.publish.steps[2].uses|publish-app" \ + "cd.yaml|.jobs.publish.uses|publish-app" \ "release.yaml|.jobs.release.uses|create-release" \ "template-sync.yaml|.jobs.\"template-sync\".uses|template-sync"; do mutant_file=${pair%%|*} rest=${pair#*|} mutant_path=${rest%%|*} mutant_workflow=${rest##*|} - if [ "$mutant_workflow" = publish-app ]; then - mutant_workflow=actions/publish-app - else - mutant_workflow=.github/workflows/$mutant_workflow.yaml - fi if [ "$family" = publish ]; then - [ "$mutant_workflow" = actions/publish-app ] || continue + [ "$mutant_workflow" = publish-app ] || continue else - [ "$mutant_workflow" != actions/publish-app ] || continue + [ "$mutant_workflow" != publish-app ] || continue fi yq eval \ - "${mutant_path} = \"devantler-tech/.github/${mutant_workflow}@${ref}\" | + "${mutant_path} = \"devantler-tech/.github/.github/workflows/${mutant_workflow}.yaml@${ref}\" | ${mutant_path} line_comment = \"${version}\"" \ "$mutation_dir/$mutant_file" > "$mutation_dir/mutant.yaml" mv "$mutation_dir/mutant.yaml" "$mutation_dir/$mutant_file" @@ -391,7 +388,7 @@ run_fleet_mutation() { } run_mutation 'publish caller rolled back while the others stay current' cd \ - '.jobs.publish.steps[2].uses = "devantler-tech/.github/actions/publish-app@77cfa9cfc5514ebe1429f64e681afd181cf4515d"' + '.jobs.publish.uses = "devantler-tech/.github/.github/workflows/publish-app.yaml@77cfa9cfc5514ebe1429f64e681afd181cf4515d"' run_mutation 'release caller rolled back while the others stay current' release \ '.jobs.release.uses = "devantler-tech/.github/.github/workflows/create-release.yaml@4b00bd6698af033dc472b39a7e609173fe38dfb1"' run_fleet_mutation 'publisher below reviewed floor' \ @@ -399,7 +396,7 @@ run_fleet_mutation 'publisher below reviewed floor' \ run_fleet_mutation 'publisher at historical maintained v6.1.0' \ 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' 'v6.1.0' publish 'older than the reviewed floor' run_fleet_mutation 'publisher version comment stripped' \ - '3cab796adef97dcde0c55724866a0b19397aba39' '' publish 'version comment of the form' + '0c7b6c3509b73adbc7537e030935bb01987e625b' '' publish 'version comment of the form' run_fleet_mutation 'publisher version comment unparseable' \ '0c7b6c3509b73adbc7537e030935bb01987e625b' 'vLATEST.x.y' publish 'version comment of the form' run_fleet_mutation 'publisher version comment carrying a fourth component' \ diff --git a/scripts/workflow-caller-pin-contract.test.sh b/scripts/workflow-caller-pin-contract.test.sh index a9a3423..d5f5cba 100644 --- a/scripts/workflow-caller-pin-contract.test.sh +++ b/scripts/workflow-caller-pin-contract.test.sh @@ -100,9 +100,9 @@ validate_pins "$cd_workflow" "$release_workflow" "$template_sync_workflow" mutation_dir=$(mktemp -d) trap 'rm -rf "$mutation_dir"' EXIT mutations_run=0 -# Start each negative control with independent copies of the real callers. +# Start each control with the direct-caller fixture and real release/sync callers. reset_mutation() { - cp "$cd_workflow" "$mutation_dir/cd.yaml" + cp "$script_dir/fixtures/own-publisher.yaml" "$mutation_dir/cd.yaml" cp "$release_workflow" "$mutation_dir/release.yaml" cp "$template_sync_workflow" "$mutation_dir/template-sync.yaml" } @@ -128,6 +128,7 @@ single_mutation() { # Existing tenants can receive the portable check before changing their caller. # Verify that the retained legacy arm still checks a real, tagged publisher. reset_mutation +validate_pins "$mutation_dir/cd.yaml" "$mutation_dir/release.yaml" "$mutation_dir/template-sync.yaml" yq eval ' del(.jobs.publish.steps, .jobs.publish."runs-on", .jobs.publish."timeout-minutes", .jobs.publish.concurrency) | .jobs.publish.uses = "devantler-tech/.github/.github/workflows/publish-app.yaml@af042c540ce8db4d64add98c34b5c57691e0e812" From 8c55e8c7e1e330f7cfba23198680616ee5ed4ca7 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 15 Nov 2026 10:06:20 +0100 Subject: [PATCH 3/3] fix(release): reject workflow-level publisher overrides Limit the own-release signing frame to its supported workflow keys. Cover inherited environment and shell defaults with native admission regressions. Part of #289 --- scripts/publish-pin-approved.sh | 4 +++- scripts/publish-pin-approved.test.sh | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/publish-pin-approved.sh b/scripts/publish-pin-approved.sh index 2559947..93d77cf 100644 --- a/scripts/publish-pin-approved.sh +++ b/scripts/publish-pin-approved.sh @@ -46,9 +46,11 @@ publish_identity() { # A direct action signs as this repository, independently of the action's # revision. Retain a minimal, tag-only, credential-free execution frame; # the required caller-pin check binds its SHA to the catalogue release. + # Workflow-level env and defaults can also change the action's execution. # shellcheck disable=SC2016 yq eval -e ' - (.permissions | length) == 0 + (keys - ["name", "on", "permissions", "jobs"] | length) == 0 + and (.permissions | length) == 0 and (.["on"] | keys | join(",")) == "push" and (.["on"].push | keys | join(",")) == "tags" and (.["on"].push.tags | length) == 1 diff --git a/scripts/publish-pin-approved.test.sh b/scripts/publish-pin-approved.test.sh index df54958..c472b05 100644 --- a/scripts/publish-pin-approved.test.sh +++ b/scripts/publish-pin-approved.test.sh @@ -189,6 +189,8 @@ for manifest in deployment.yaml base/deployment.yaml; do fi done for mutation in \ + '.env.BASH_ENV = "publisher-hook.sh"' \ + '.defaults.run.shell = "bash -e {0}"' \ '.jobs.publish.steps[2].uses = "other-owner/repo/action@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"' \ '.jobs.publish.steps[2].uses = "devantler-tech/.github/actions/publish-app@main"' \ '.jobs.publish.steps[1].with."persist-credentials" = true' \