Files

290 lines
12 KiB
Markdown

# Spec: Tekton CI/CD for lolympus-tournament-support
This document's original main-to-staging/manual-production contract is specific
to lolympus. Blog follows make-space: source `staging` and `prod` branches each
run a dedicated pipeline and both environments auto-sync. Blog registration is
`argocd/applications/blog-ci.yaml`; its complete delivery/secret contract is in
service-state `ci/blog/README.md` and `apps/blog/README.md`.
## 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.
The `tekton-ci` namespace is shared by all service CI applications. Its
ResourceQuota and LimitRange are owned by the `tekton-config` Argo CD Application
from `platform/tekton/config/ci-resource-policy.yaml`. Their legacy resource name
`lolympus-ci` is retained to transfer ownership without recreating either object;
it does not restrict the policies to the lolympus service. The service `ci`
AppProject does not permit ResourceQuota or LimitRange resources.
The shared quota permits at most 15 PipelineRuns, 15 PVCs requesting a total of
150 GiB, and 150 TaskRuns. The job-based pruner runs at minute 00, 15, 30, and 45
of every hour and retains the newest 10 completed PipelineRuns per namespace,
across pipeline names and success/failure outcomes. Running and pending runs are
protected and are additional to the retained completed history. Child TaskRuns,
Pods, and workspace PVCs follow their owning PipelineRun's deletion; TaskRuns
are not pruned independently. If 15 runs accumulate before pruning frees a slot,
the quota rejects further PipelineRun creation.
### Transferring the shared resource policies
This transfer spans two repositories with independent automatic synchronization.
Do not rely on Application sync waves to order commits across the repositories.
For an existing cluster where `lolympus-tournament-support-ci` owns the policies:
1. Wait for active sync operations to finish. Temporarily disable automated sync
on `platform-root`, `tekton-config`, and `lolympus-tournament-support-ci`,
preserving their existing sync policy for restoration.
2. Record the UID and tracking annotation of both existing `lolympus-ci` objects
in `tekton-ci`. Add the temporary resource annotation
`argocd.argoproj.io/sync-options: Prune=false` to both objects.
3. Publish the service-state removal and platform-state adoption commits. Sync
`lolympus-tournament-support-ci` to the removal commit first. The protected
policies must remain present even though they are no longer desired there.
4. Sync `tekton-config` to the adoption commit. Verify both objects retain their
UIDs and now have tracking IDs beginning with `tekton-config:`. Verify the
quota values and the generated pruner CronJob's schedule and keep arguments.
5. Refresh the old Application and confirm it no longer tracks either policy.
Remove only the temporary `Prune=false` annotation after adoption succeeds.
6. Restore automated sync on the child Applications, then sync `platform-root`
to apply the tightened `ci` AppProject permissions and restore its automation.
Confirm all three Applications are Synced and Healthy.
If adoption fails, leave the existing policies protected and avoid syncing the
new AppProject restrictions until ownership is resolved. Do not delete and
recreate the policies or remove unrelated sync-option annotations.
## Registering Additional Service CI
CI directories in `service-state` are registered explicitly; the service
ApplicationSets discover only `apps/*/overlays/*`.
For URL shortener, `argocd/applications/url-shortener-ci.yaml` reconciles
`service-state/ci/url-shortener` into `tekton-ci` using the `ci` project.
The platform root Application discovers this registration recursively.
Cluster-scoped EventListener RBAC belongs in
`platform/tekton/config/eventlistener-rbac.yaml`. Each listener receives a
dedicated ClusterRole and ClusterRoleBinding allowing only `get`, `list`, and
`watch` on `clusterinterceptors` and `clustertriggerbindings`.
Keep ServiceAccounts, Roles, and RoleBindings in `service-state`; remove the
URL shortener ClusterRoleBinding from its `foundation.yaml` when adopting this
registration. The `ci` project intentionally does not allow cluster resources.
Before the first URL shortener run, configure its Infisical secrets and Gitea
push webhook at `https://tekton-hook.dahyeon.us/url-shortener` as defined in
`service-state/ci/url-shortener`.
## 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
pnpm --filter api test --runInBand
```
Do not use mutable image tags such as `latest`, inline credentials, or direct
`kubectl set image` deployment mutations.
The pinned Node 26 image does not include Corepack. The Tasks bootstrap exactly
`pnpm@10.4.1` into the shared workspace before running package scripts.
## 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.
## External Setup
- Create the Infisical path and all six keys in the Secret Contract before the
first run.
- Point public DNS for `tekton-hook.dahyeon.us` to the same public ingress
endpoint as `tekton.dahyeon.us`.
- In Gitea, add an active push webhook for
`https://tekton-hook.dahyeon.us` with JSON content type and use the exact
`GITEA_WEBHOOK_SECRET` value as its signing secret.
- Protect `https://tekton.dahyeon.us` with an authentication layer such as
Cloudflare Access when build metadata and logs must not be public.
## 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 with read-only mode disabled.
- 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.