docs: define Tekton staging delivery contract
Document repository ownership, credential boundaries, quality gates, immutable release identifiers, and the GitOps verification plan before adding CI resources.
This commit is contained in:
1 parent
cc57cc0bd4
commit
79268872f6
1 file changed
+203
@@ -0,0 +1,203 @@
|
|||||||
|
# Spec: Tekton CI/CD for lolympus-tournament-support
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
|
||||||
|
Build a GitOps-native staging delivery path for the lolympus monorepo on the
|
||||||
|
existing k3s cluster.
|
||||||
|
|
||||||
|
A push to the source repository's `main` branch must:
|
||||||
|
|
||||||
|
1. validate the API and web applications;
|
||||||
|
2. build and push an immutable API image to Harbor;
|
||||||
|
3. deploy the web application to the Cloudflare Pages `staging` branch; and
|
||||||
|
4. update only the staging image tag in `service-state`.
|
||||||
|
|
||||||
|
Argo CD remains the only component that deploys Kubernetes workloads.
|
||||||
|
Production promotion remains a separate PR/manual operation.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- Kubernetes: k3s v1.35.5+k3s1, amd64, containerd
|
||||||
|
- GitOps: Argo CD with Kustomize
|
||||||
|
- CI: Tekton Operator v0.79.1, Pipelines v1.9.3, Triggers v0.35.0
|
||||||
|
- Image builder: BuildKit v0.31.1 rootless, pinned by digest
|
||||||
|
- Source and GitOps hosting: Gitea at `git.dahyeon.us`
|
||||||
|
- Image registry: `registry.dahyeon.us/lolympus/lolympus-tournament-support`
|
||||||
|
- Web hosting: Cloudflare Pages project `lolympus`
|
||||||
|
- Secret management: Infisical Secrets Operator
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
Render platform state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl kustomize clusters/main
|
||||||
|
kubectl kustomize platform/tekton/config
|
||||||
|
```
|
||||||
|
|
||||||
|
Render and validate CI state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl kustomize ci/lolympus-tournament-support
|
||||||
|
kubectl apply --dry-run=server -k ci/lolympus-tournament-support
|
||||||
|
```
|
||||||
|
|
||||||
|
Application quality gates:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
corepack pnpm install --frozen-lockfile
|
||||||
|
corepack pnpm --filter api exec eslint "{src,apps,libs,test}/**/*.ts" --max-warnings=0
|
||||||
|
corepack pnpm --filter web lint
|
||||||
|
corepack pnpm --filter api test -- --runInBand
|
||||||
|
corepack pnpm --filter web test
|
||||||
|
node --test scripts/deploy-cloudflare-pages.test.mjs
|
||||||
|
corepack pnpm --filter api build
|
||||||
|
corepack pnpm --filter web build:staging
|
||||||
|
corepack pnpm audit --prod --audit-level high
|
||||||
|
```
|
||||||
|
|
||||||
|
Runtime verification:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl get tektonconfig,tektondashboard
|
||||||
|
kubectl get pipelinerun,taskrun -n tekton-ci
|
||||||
|
kubectl logs -n tekton-ci -l tekton.dev/pipelineRun=<run-name> --all-containers
|
||||||
|
```
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
platform-state/
|
||||||
|
docs/tekton-ci-cd.md
|
||||||
|
clusters/main/namespaces.yaml
|
||||||
|
argocd/projects/ci.yaml
|
||||||
|
argocd/applications/lolympus-tournament-support-ci.yaml
|
||||||
|
|
||||||
|
service-state/
|
||||||
|
ci/lolympus-tournament-support/
|
||||||
|
kustomization.yaml
|
||||||
|
foundation.yaml
|
||||||
|
infisical-secret.yaml
|
||||||
|
tasks.yaml
|
||||||
|
pipeline.yaml
|
||||||
|
trigger.yaml
|
||||||
|
ingress.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Tekton controllers stay in `tekton-pipelines`. Application PipelineRuns and
|
||||||
|
their credentials run in the isolated `tekton-ci` namespace.
|
||||||
|
|
||||||
|
## Code Style
|
||||||
|
|
||||||
|
Use stable Tekton APIs, explicit names, immutable image references, bounded
|
||||||
|
resources, and namespace-scoped RBAC.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: tekton.dev/v1
|
||||||
|
kind: Task
|
||||||
|
metadata:
|
||||||
|
name: lolympus-quality
|
||||||
|
spec:
|
||||||
|
workspaces:
|
||||||
|
- name: source
|
||||||
|
steps:
|
||||||
|
- name: test-api
|
||||||
|
image: node:26-bookworm-slim@sha256:<pinned-digest>
|
||||||
|
workingDir: $(workspaces.source.path)
|
||||||
|
script: |
|
||||||
|
#!/bin/sh
|
||||||
|
set -eu
|
||||||
|
corepack pnpm --filter api test -- --runInBand
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not use mutable image tags such as `latest`, inline credentials, or direct
|
||||||
|
`kubectl set image` deployment mutations.
|
||||||
|
|
||||||
|
## Secret Contract
|
||||||
|
|
||||||
|
Infisical project `8520b8c0-3796-4fd6-a03c-6f0508c8c42c`, environment
|
||||||
|
`prod`, path `/platform/tekton/lolympus-tournament-support` must contain:
|
||||||
|
|
||||||
|
- `GITEA_USERNAME`: bot account with source read and service-state write access
|
||||||
|
- `GITEA_TOKEN`: token for that bot account
|
||||||
|
- `HARBOR_DOCKER_CONFIG_JSON`: Docker config JSON for a project-scoped robot
|
||||||
|
- `CLOUDFLARE_API_TOKEN`: token scoped to Pages deployments
|
||||||
|
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare account identifier
|
||||||
|
- `GITEA_WEBHOOK_SECRET`: high-entropy webhook signing secret
|
||||||
|
|
||||||
|
The source test/build Tasks do not receive Gitea, Harbor, or Cloudflare
|
||||||
|
credentials. Credential Secrets are mounted only into the Tasks that require
|
||||||
|
them.
|
||||||
|
|
||||||
|
## Pipeline Contract
|
||||||
|
|
||||||
|
- Trigger: signed Gitea push event for exactly
|
||||||
|
`dahyeon/lolympus-tournament-support` and `refs/heads/main`
|
||||||
|
- Source revision: the full 40-character commit SHA from the webhook
|
||||||
|
- Image tag: `sha-<full-commit-sha>`
|
||||||
|
- Cloudflare Pages branch: `staging`
|
||||||
|
- GitOps target:
|
||||||
|
`apps/lolympus-tournament-support/overlays/staging/kustomization.yaml`
|
||||||
|
- Superseded runs must not update `service-state`
|
||||||
|
- A failure in any quality, image, or Cloudflare step must prevent GitOps update
|
||||||
|
- Pipeline timeout: 45 minutes
|
||||||
|
- Workspace: 10 GiB `local-path` volume claim per PipelineRun
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
|
||||||
|
- Static: `git diff --check` and Kustomize rendering for every state repo
|
||||||
|
- Schema: client dry-run before namespace creation, server dry-run afterwards
|
||||||
|
- Application: run every command listed under Application quality gates
|
||||||
|
- Integration: send a signed test webhook and verify one PipelineRun is created
|
||||||
|
- End-to-end: verify Harbor tag, Cloudflare staging deployment, service-state
|
||||||
|
commit, and Argo CD staging sync all refer to the same source SHA
|
||||||
|
- Rollback: revert the service-state tag commit and manually redeploy the prior
|
||||||
|
Cloudflare source revision if required
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
Always:
|
||||||
|
|
||||||
|
- use Argo CD for persistent cluster resources;
|
||||||
|
- use immutable source and image revisions;
|
||||||
|
- validate webhook signatures and repository/branch fields;
|
||||||
|
- keep RBAC namespace-scoped and resource-limited;
|
||||||
|
- keep production promotion manual.
|
||||||
|
|
||||||
|
Ask first:
|
||||||
|
|
||||||
|
- enabling automatic production sync;
|
||||||
|
- changing the Harbor repository or Cloudflare project;
|
||||||
|
- granting CI credentials access to additional repositories;
|
||||||
|
- enabling privileged image builds.
|
||||||
|
|
||||||
|
Never:
|
||||||
|
|
||||||
|
- store secret values in Git;
|
||||||
|
- pass a repository URL from an untrusted webhook directly to a clone Task;
|
||||||
|
- expose credentials to application test or build steps;
|
||||||
|
- mutate staging Deployments directly with kubectl;
|
||||||
|
- deploy an unverified pull request with production-capable credentials.
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
- `TektonConfig` and all required controllers are Ready.
|
||||||
|
- `https://tekton.dahyeon.us` returns HTTP 200 in read-only mode.
|
||||||
|
- A valid main push creates exactly one staging PipelineRun.
|
||||||
|
- Invalid signatures, repositories, branches, and malformed SHAs are rejected.
|
||||||
|
- Quality gates complete before side effects.
|
||||||
|
- The Harbor tag, Cloudflare staging deployment, and service-state staging tag
|
||||||
|
identify the same source commit.
|
||||||
|
- Argo CD automatically deploys staging and leaves production unchanged.
|
||||||
|
- Finished runs and their PVCs are pruned according to the configured policy.
|
||||||
|
|
||||||
|
## Implementation Plan
|
||||||
|
|
||||||
|
1. Add `tekton-ci` namespace and bounded namespace resources.
|
||||||
|
2. Add Infisical-backed, purpose-specific CI Secrets.
|
||||||
|
3. Add clone, quality, BuildKit, latest-revision, Cloudflare, and GitOps Tasks.
|
||||||
|
4. Compose the staging Pipeline and signed Gitea Trigger.
|
||||||
|
5. Add a TLS Ingress at `tekton-hook.dahyeon.us`.
|
||||||
|
6. Add the restricted Argo CD project and Application.
|
||||||
|
7. Validate a signed webhook end to end after the Infisical values exist.
|
||||||
|
|
||||||
Reference in new issue
Block a user