# In-cluster conformance Job (L2/L3)

> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
> This document speaks as though no cluster exists and the platform is scaffolding. **A
> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
> describing a **live gap** rather than an expected stage — most importantly, L2/L3
> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
> coverage hole, not a phase.
>
> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
> documentation rather than measurement, and `main` was unprotected with zero runners
> registered the whole time. **Query the live API before asserting platform state.**


Per **ADR-0011** and **docs/14 "Where each layer runs"**: L0/L1 run in CI without a
cluster, but **L2 behavioral and L3 fault-injection run as an in-cluster Chainsaw Job**
on the dev/test cluster that **CI triggers and waits for**. CI holds **no** cluster
credentials — the Job's own scoped ServiceAccount does (R-SEC-02).

## Files
- `rbac.yaml` — the `conformance` namespace, the `conformance-runner` ServiceAccount, and
  a **least-privilege ClusterRole skeleton**. Rules start **empty** and are added — each
  commented with the test/requirement that needs it — only as the matching fault-injection
  test lands. This is a **privileged test identity**: never reused by workloads, its own
  audit item.
- `chainsaw-job.yaml` — the **run template** (not reconciled; the trigger renders it per
  run). Single entrypoint `./run.sh`; a clone init container delivers the suite at the
  commit under test; artifacts leave over stdout. Its header is the authority on the
  substitution tokens and the admission constraints it satisfies, and records the
  `initContainers` hole that was found and closed alongside it — read it before editing
  either file.
- `conformance-clone` — **arrives with PR #18**, not this one. The clone init container's
  entire logic, baked into the runner image at `/usr/local/bin/conformance-clone`. It is a
  file in the image rather than an inline script in the Job precisely so admission can pin
  it: a policy cannot tell the committed script from an attacker's when both are just `args`
  on `/bin/bash -c`. The repository URL and clone target are hardcoded **there** on purpose,
  and `CONFORMANCE_REPO_URL`/`CONFORMANCE_SRC` are hard-failed on a mismatch rather than
  honoured — a URL taken from env would let the trigger choose which repository's code runs
  as `conformance-runner`. This branch's Job depends on that interface:
  `CONFORMANCE_GIT_SHA`, `GITEA_USERNAME`/`GITEA_TOKEN`, a clone target of `/workspace/src`
  (hence `workingDir: /workspace/src/conformance`), and `TMPDIR`/`HOME` under `/workspace`.

## Flow
1. CI (Gitea Actions) renders `chainsaw-job.yaml` — two `@@TOKEN@@` substitutions, the
   runner image digest and the commit SHA — replaces `args` with the invocation shape, and
   `create`s the Job under the narrow `conformance-trigger` identity (create/get jobs, get
   pods + pods/log — *not* a broad kubeconfig, and deliberately **no `pods/exec`**).
2. Admission (`platform/kyverno/admission/conformance-trigger-job-shape.yaml`, Enforce +
   fail-closed) admits only the committed shape. That policy, not the RBAC, is the boundary.
3. The **init container** runs `/usr/local/bin/conformance-clone` with **no args**: it
   shallow-clones the repo into `/workspace/src`, fetches the commit if the shallow tip does
   not already contain it, detaches onto it, and **asserts `HEAD` equals the requested SHA** —
   the suite runs at the commit under test or not at all. The read-only Gitea credential
   reaches `git` as env vars from `secretKeyRef` (secret `conformance-git-readonly`, keys
   `username`/`token`), never as a volume: admission allows no volume but `workspace` and
   `results`.
4. The runner executes `./run.sh` under `conformance-runner`, writing `report.junit.xml` +
   `coverage/` to the `results` volume at `/results` (`CONF_ARTIFACTS`).
5. On exit — green, red or aborted — `run.sh` prints a delimited base64 tar of that tree to
   stdout, carrying `bytes`, `lines` and `sha256` in **both** the BEGIN and END markers. CI
   decodes it from `kubectl logs` and must make all five completeness checks listed above
   `conf_emit_artifacts_tgz()` in `../run.sh`; a partial log then fails collection instead
   of decoding to plausible garbage.

## Prerequisites before this Job can run at all
- **Secret `conformance-git-readonly`** in namespace `conformance`, keys `username` and
  `token`: a **read-only** Gitea token for this repository. Never a write token or a
  push-capable deploy key. **Does not exist** — operator, out of GitOps (plan §3 item 6).
- **The `conformance-runner` image** (plan §5 step 1) — built in **PR #18**, which must merge
  before this template is usable; its digest is what the trigger substitutes. Contract the
  image MUST meet, because the Job and the admission policy both depend on it:
  - bash, git, python3, chainsaw and kubectl on `PATH`;
  - a **uid 65532** non-root user — the Job's `runAsUser`/`fsGroup` pin it, so a different
    uid in the Containerfile means the Job will not start;
  - `conformance-clone` installed at **`/usr/local/bin/conformance-clone`**,
    mode 0755. The policy rule `trigger-initcontainers-must-be-the-committed-clone-step` pins
    that exact path, so an image without it cannot run the clone step and no other path will
    be admitted.

## Phase 0
No cluster exists, so nothing here is applied yet. These manifests are reconciled by Flux
from Phase 1+ and first exercised when L2/L3 can run (T-3.0 onward). In Phase 0 the same
`run.sh` runs in CI's no-cluster stage and emits a **skipped** JUnit + the coverage report.