From 3bcac320721c4b4f53eeba3b7d444f3ea576d5e5 Mon Sep 17 00:00:00 2001 From: eding Date: Wed, 16 Sep 2026 18:57:47 +0200 Subject: [PATCH] docs: define central delivery ownership --- AGENTS.md | 9 +++ README.md | 21 ++--- docs/architecture/delivery-ownership.md | 103 ++++++++++++++++++++++++ docs/delivery-feedback.md | 16 ++-- docs/e2e.md | 7 ++ docs/operations.md | 41 +++++----- 6 files changed, 153 insertions(+), 44 deletions(-) create mode 100644 docs/architecture/delivery-ownership.md diff --git a/AGENTS.md b/AGENTS.md index 2fe8ab9..694e9f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,15 @@ - The testing suite, onboarding, and mutation E2E commands must target `Maidn` fixture sources. - `test-org-2` is disposable execution state only. It may host temporary delivery branches and resources, but it is never a fixture source or test-suite owner. +## Delivery Ownership + +- Application repositories are build inputs only; do not add or update active + `.tekton/` or `.maidn/` delivery resources in them. +- The cluster repository owns Pipelines, Tasks, triggers, and runtime secret + access. The manifests repository owns image tags and promotion state. +- Flux chart sources must use only the protected `maidn/platform-` branch, + never an application `main` or `maidn/delivery-*` branch. + ## Required Checks - Before each commit: inspect `git status --short`, `git diff --check`, and `git log --oneline -10`. diff --git a/README.md b/README.md index be2ee5d..3fba6f4 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,15 @@ ## Commands -go mod init github.com/Pingu-Studio/MaidnCLI -go get -u github.com/spf13/cobra@latest -go get golang.org/x/term -go mod tidy -go get gopkg.in/yaml.v3 - -in powershell run -```powershell -go install github.com/go-delve/delve/cmd/dlv@latest -dlv version -``` -## Commands - -- `cicd-tool repo init --org --flux-repo ` creates the manifests and Flux repos +- `cicd-tool repo init` is a legacy GitHub workflow and is not used for new Forgejo/GitOps platform onboarding. - `cicd-tool bootstrap` runs a shorter Forgejo-first wizard, asks for a Forgejo PAT, asks where local repos should be cloned, discovers Proxmox nodes/storage/networks, retries without losing entered answers when discovery fails, shows the latest Talos version, derives the standardized Talos factory URL, schematic, and required extensions automatically from the chosen version, writes `terraform.tfvars`, stages Talos images on Proxmox, and can execute Terraform, Talos bootstrap, and Flux bootstrap - `cicd-tool bootstrap --config maidn-bootstrap.yaml` skips the wizard and uses the saved config -- `maidn bootstrap init --config --organization --create-organization --enable-delivery` locks an isolated workspace, initializes the Forgejo repositories, then runs the non-destructive bootstrap reconcile lifecycle; use `--mode=rebuild --yes` for an authorized rebuild. Delivery scaffolding requires `--enable-delivery`. -- `maidn app onboard --config --from ` opens reviewed source-delivery and cluster-registration PRs; see `docs/operations.md`. +- `cicd-tool bootstrap init --config --organization --create-organization` locks an isolated workspace, initializes Forgejo repositories, then runs the non-destructive bootstrap reconcile lifecycle. Use `--mode=rebuild --yes` only for an authorized rebuild. +- `cicd-tool app onboard --config --from ` is being migrated to central delivery ownership. Do not use the source-owned implementation for new applications; see `docs/architecture/delivery-ownership.md`. - `cicd-tool e2e` runs bounded, read-only Flux, ExternalSecret, PipelineRun, preview, and promotion-PR checks with JSON output. See `docs/e2e.md`. See `docs/operations.md` for the authorized operating and verification runbook. +See `docs/architecture/delivery-ownership.md` for the developer and platform +ownership boundary. App authors: see `docs/delivery-feedback.md` for preview feedback and the scoped Forgejo token contract. ## Forgejo setup diff --git a/docs/architecture/delivery-ownership.md b/docs/architecture/delivery-ownership.md new file mode 100644 index 0000000..dbd9989 --- /dev/null +++ b/docs/architecture/delivery-ownership.md @@ -0,0 +1,103 @@ +# Delivery Ownership + +## Status + +This is the approved target architecture. The current source-owned onboarding +implementation is being migrated and must not be used for new applications. + +## Trust Boundary + +Application repositories are build inputs, not GitOps inputs. A developer can +change application code on `main`, but cannot change an active Pipeline, Task, +runtime secret reference, Helm chart, environment value, or promotion policy. + +| Concern | Owner | Location | +| --- | --- | --- | +| Application code, tests, Dockerfile | Developers | `Maidn/` `main` | +| Approved charts and environment values | Platform | `Maidn/` `maidn/platform-` | +| Pipeline, Tasks, triggers, runtime access | Platform | Cluster repository | +| Image tags, preview ownership, promotion PRs | Platform | Deployment manifests repository | +| Secret values and policies | Platform | Private config, SOPS operational state, OpenBao | + +The protected platform branch may be readable by developers, but only platform +operators and approved automation may push or merge into it. Flux must track +only that branch for chart content. Flux must never track an application `main` +branch or `maidn/delivery-*` branch. + +## Resource Flow + +```mermaid +flowchart LR + App[Application main branch\ncode only] + Platform[Protected platform branch\nchart and values] + Cluster[Cluster repository\nPipeline, Tasks, secret access] + Manifests[Manifests repository\nimage tags and promotion] + Flux[Flux] + Workload[Preview, staging, production] + + App -->|exact source SHA| Cluster + Cluster --> Manifests + Platform --> Flux + Manifests --> Flux + Flux --> Workload +``` + +The central Pipeline clones the application repository at the event SHA only to +build an image. It obtains chart content from the protected platform branch and +writes only image-tag and promotion state to the manifests repository. + +## Prohibited Application Content + +Application repositories must not contain active delivery control-plane +resources: + +- `.tekton/` Pipeline or Task resources +- `.maidn/` Flux, RBAC, SecretStore, or ExternalSecret resources +- Flux Kustomizations or GitRepositories +- Kubernetes Secret values, SOPS identities, OpenBao tokens, or kubeconfigs + +An application `main` branch may retain a chart as a developer proposal, but it +has no delivery effect. A platform operator explicitly reviews and copies an +approved chart and environment values to `maidn/platform-`. + +## Approval Sequence + +1. A platform operator creates or updates the protected platform branch through + a reviewed platform PR. +2. A platform operator reviews and merges the central cluster registration that + renders the Pipeline, Tasks, protected chart source, and runtime references. +3. Flux applies only the central cluster resources and protected chart branch. +4. Developers use Forgejo pull requests and pushes to trigger builds; they do + not edit deployment control-plane resources. +5. Production promotion remains a reviewed PR in the manifests repository. + +## Migration Rules + +Existing source-owned registrations are migrated one application at a time. +First establish the protected platform package, then merge the central cluster +registration, then verify Flux and delivery. Remove the legacy source +GitRepository, Kustomizations, and delivery branch only after the replacement +is Ready. + +The canonical fixtures are migration pilots. `Maidn/maidn-e2e-secret` remains +disabled until its central replacement is reviewed. Angular and web legacy +registrations must follow the same migration path. + +## Command Status + +`cicd-tool bootstrap`, `cicd-tool app`, and `cicd-tool e2e` are the current +Forgejo and GitOps command families. `cicd-tool repo init` and `cicd-tool vault +create-*` are legacy GitHub/direct-apply paths and are not part of new platform +onboarding. They will be deprecated or removed after the central delivery +migration. + +## Acceptance + +The architecture is accepted only after a canonical fixture proves all of the +following with a real Forgejo event: + +- pull request preview build, route, and delivery feedback +- main-to-staging deployment at an immutable image SHA +- reviewed production promotion PR +- runtime secret and shared database projection without preview credentials +- closed-preview cleanup and orphan-cleaner recovery diff --git a/docs/delivery-feedback.md b/docs/delivery-feedback.md index e7b7e94..7d03fde 100644 --- a/docs/delivery-feedback.md +++ b/docs/delivery-feedback.md @@ -1,10 +1,11 @@ # Delivery feedback -`maidn app onboard` adds source-owned Tekton tasks that update one marked -Forgejo pull-request comment. The comment contains only the verified preview -URL, a redacted task-status summary, and the PipelineRun name. Set the optional -`delivery.tektonDashboardUrl` to a credential-free HTTPS Tekton Dashboard -origin to add a PipelineRun link. +The central cluster registration owns the Tekton tasks that update one marked +Forgejo pull-request comment. Application repositories do not carry active +delivery Tasks. The comment contains only the verified preview URL, a redacted +task-status summary, and the PipelineRun name. Set the optional +`delivery.tektonDashboardUrl` to a credential-free HTTPS Tekton Dashboard origin +to add a PipelineRun link. Before enabling delivery feedback, create the separate Forgejo token with `bootstrap --config --create-forgejo-delivery-status-token`. @@ -17,5 +18,6 @@ Forgejo API responses. Preview and staging feedback waits up to ten minutes for the app Deployment and HTTPRoute, then performs a bounded HTTPS check. A production event reports the manifest-repository promotion PR; it does not claim a production deploy. -The chart must name both resources after `delivery.appName`; the HTTPRoute's -first hostname must be the public HTTPS preview/staging URL. +The protected `maidn/platform-` chart must name both resources after +`delivery.appName`; the HTTPRoute's first hostname must be the public HTTPS +preview/staging URL. diff --git a/docs/e2e.md b/docs/e2e.md index 61ac56d..0416e1f 100644 --- a/docs/e2e.md +++ b/docs/e2e.md @@ -29,3 +29,10 @@ Build the portable OCI runner with `docker build -t maidn-e2e-runner .`. Mount the kubeconfig and optional token file read-only; ensure they are readable by the image's non-root user. The build context excludes known secret-bearing bootstrap inputs. + +## Fixture Boundary + +Use `cicd-tool e2e-mutate` only with canonical `Maidn/maidn-e2e-*` fixtures. +The test runner must prove preview, staging, production promotion, runtime +secret/database access, preview cleanup, and orphan cleanup against central +delivery resources. It must not mutate `test-org-2` as a fixture source. diff --git a/docs/operations.md b/docs/operations.md index eef58cf..ef18b36 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -43,10 +43,15 @@ creates the Gateway, Tekton, and Tekton Triggers platform resources using go run . bootstrap init --config --organization --create-organization ``` -Use a clean checkout on `delivery.appRepoRef`. The app repository URL must be -the canonical source owner, such as `Maidn/.git`; `test-org-2` is only the -execution owner. Set per-app static build values with command-line overrides, -not by rewriting the private default: +The source-owned onboarding implementation is being retired. Do not onboard a +new application until the central delivery renderer is available. See +[Delivery Ownership](architecture/delivery-ownership.md) for the approved +architecture and migration rules. + +The future onboarding command uses a clean checkout on `delivery.appRepoRef`. +The app repository URL must be the canonical source owner, such as +`Maidn/.git`; `test-org-2` is execution state only. Per-app static build +values remain command-line overrides rather than private defaults: ```powershell go run . app onboard --config --from ` @@ -56,16 +61,13 @@ go run . app onboard --config --from ``` For a runtime build, set `--build-strategy runtime`; static-only output options -remain harmless. Onboarding opens, but never merges, a source delivery PR and a -cluster registration PR. It registers the Forgejo hook but does not emit a test -delivery. Review and merge the source delivery PR first, then the cluster -registration PR. The registration is stored in -`base/tekton/apps/.yaml`; Flux loads the source-owned `.tekton` path and -the generic EventListener dispatches by Forgejo repository name. +remain harmless. Central onboarding will create reviewed platform-branch and +cluster-registration changes. The cluster repository will own +`base/tekton/apps/.yaml`; the application repository will remain a build +input only. The generic EventListener dispatches by Forgejo repository name. -Existing registrations are never overwritten. Move a legacy source registration -to its canonical source in a separate reviewed cluster-repository PR before -onboarding that application. +Existing source-owned registrations are migrated in separate reviewed cluster +repository PRs. Never overwrite an unmanaged registration. After Flux reports the app Kustomization Ready, use Forgejo's hook test endpoint against a non-`main` ref and inspect the resulting PipelineRun. The command and @@ -80,14 +82,11 @@ by default. Shared credentials are appropriate only for the shared environment database. Use a dedicated service only when isolation, lifecycle, or storage requirements demand it. -An application can carry reviewed dedicated resources in -`.maidn/kustomization.yaml`. Onboarding registers that path as the app's -`-addons` Flux Kustomization without changing the generated `.tekton` -files. Runtime secret grants also generate the app's `.maidn/secret-access.yaml` -there. Add-ons must declare their namespace explicitly and contain references, -never credential values. Preview namespaces do not receive staging or production -runtime credentials; preview-safe configuration is the application chart's -responsibility. +The cluster repository owns reviewed dedicated resources and runtime secret +access. Application repositories must not carry active `.maidn` resources. +Runtime references never contain credential values. Preview namespaces do not +receive staging or production runtime credentials; preview-safe configuration is +defined in the protected platform chart branch. Declare runtime secret access in the private configuration and run normal bootstrap reconciliation to create its policy and role. Set values only with