agentleFS
enixenix/kube-image-keeper/.claude/skills/e2e-spec/SKILL.md

e2e-spec

Skill759 starsChanged 21 days agoMITView on GitHub

Use when adding, changing or fixing e2e specs under test/e2e/ in kuik (the Kind suite run by task test-e2e), or when deciding what a PR should check end to end.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. Mr-Quin/danmaku-anywhere★ 550same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run: only through task test-e2e, on an isolated Kind cluster, never against a real cluster.

    line 40

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

e2e specs

An e2e spec checks what only a real cluster can answer: the API server, admission, the kubelet, the chart as deployed. Everything else belongs to a unit or envtest spec. Target: $ARGUMENTS.

When

e2e specs come last in a PR (0012): once the PR is otherwise ready (automated review addressed, unit and envtest specs green, the feature believed to work), one final test commit adds them. A failure is fixed by fixup! commits, autosquashed once like review fixes. This is the one exception to "a test commit before each feat commit" of tests.md; unit and envtest specs keep that order. The reason: a Kind run takes minutes.

A PR that emits events, reads Secrets or writes a status adds at least one e2e spec that runs the call through the chart's RBAC: envtest's admin client hides a missing grant.

On a PR, the suite runs only under the e2e-ready label (0013): once the PR is reviewed, its e2e specs are pushed and its fixup! commits are autosquashed, ask the user to add it. The required E2E check fails until then, unless the PR changes no path the suite depends on.

Workflow

  1. Outline first. REQUIRED SUB-SKILL: follow test-outline: the It / Entry strings are drafted as PIt / PEntry, shown with task test-outline -- ./test/e2e/, checked by spec-reviewer and reported before any body.
  2. One spec per rule, never one per verb, kind or field (tests.md). Drop a case a unit or envtest spec already proves.
  3. Bodies, with the patterns below, in the final test commit.
  4. Run only through task test-e2e, on an isolated Kind cluster, never against a real cluster. The task creates KIND_CLUSTER when it is missing and deletes it afterwards only in that case. An existing Kind cluster of that name is reused as is, with the Kind configuration it was created with (after a change to test/e2e/kind-config.yaml, delete it with task cleanup-test-e2e), and the suite installs and uninstalls kuik on it, so never point KIND_CLUSTER at a cluster used for anything else. Give the run a dedicated kubeconfig:

    KUBECONFIG=<tmp>/e2e-kubeconfig task test-e2e

    kind create cluster switches the current context of the kubeconfig it writes to, and the suite uninstalls the CRDs at the end: on a shared kubeconfig, a later kubectl could hit the wrong cluster. The e2e tasks are outbound for the confirm-outbound hook: the user approves each run.

Patterns

NeedDo
An origin that is unavailableA .invalid host (kuik-e2e.invalid/...): it fails fast, at DNS
A slow or blackholed candidateA documentation address (192.0.2.1, TEST-NET-1, never routed): the connection hangs until the timeout
A registry that answersregistry.k8s.io/pause:3.10: HTTPS, non-root, fits the restricted Pod Security profile
An image an ImageMirror copiesPin one single-platform Linux manifest by digest, chosen by the node architecture: a mirror copies an index whole, and the Windows layers of pause:3.10 weigh some 570 MB
Every webhook replica has seen a new CR or configEach replica has its own informers and config: poll replicasRouting until each replica answers as expected. It sends an AdmissionReview to each pod through kubectl proxy. Admission through the API server, a server-side dry run included, reaches one replica only
A rewrite happenedAssert the rewritten image and the kuik.enix.io/rewrites annotation (kuik.enix.io/no-alternatives when every candidate failed)
A counter movedThe kuik counters are per replica: webhookMetric reads one on each webhook pod (kubectl get --raw /api/v1/namespaces/<ns>/pods/<pod>:8080/proxy/metrics). Compare pod by pod when every replica must move, as after a config reload; sum when any replica may serve the admission
kuik left a pod untouchedProves nothing alone. Order the specs so that a rewrite proves the webhook is called before any "untouched" spec
A config changesetConfig(mergeConfig(original, fragment)): a YAML deep merge of the fragment onto the release's config, written with kubectl patch of the ConfigMap, never helm upgrade. On the e2e cluster the kubelet syncs it into the pods in about 10 to 15s; 3m stays the upper bound. Prove it loaded through behaviour: webhook.availabilityCheck.timeout: 1ms fails every probe, so a replica that loaded it stops rewriting
Any waitOn behaviour (replicasRouting, an observed status), never on a period: the e2e cluster syncs ConfigMaps every 10s and the e2e release checks registries every 10s, while real clusters keep 1m, so a wait sized on those periods hides one that is too short

The suite needs internet access: images come from public registries. Kind gets test/e2e/kind-config.yaml only (the kubelet syncFrequency set to 10s) and containerd no configuration, so the kubelet never pulls from an in-cluster registry (a plain HTTP registry does not work: the webhook probes an original over HTTPS even when it matches an insecure: true entry). cert-manager is pulled the same way. The one in-cluster registry is the ImageMirror destination of mirror_test.go: kuik writes to it, no pod pulls from it, so its mirrors use rewritePolicy: None.

The chart is deployed once per suite, in BeforeSuite / AfterSuite, and never a second time: Ginkgo shuffles the top-level containers, so one container's BeforeAll would not cover the others. A top-level AfterEach dumps logs, events and pod descriptions on failure.

Fixtures and helpers

  • e2e_suite_test.go: BeforeSuite builds the manager image, loads it into Kind, installs cert-manager unless present (CERT_MANAGER_INSTALL_SKIP=true skips it) and runs deployChart (the kuik-system namespace under the restricted Pod Security profile, make install, make deploy with test/e2e/values.yaml, which sets registries.default.check.interval: 10s). KUIK_E2E_SKIP_IMAGE_BUILD=true loads an image built beforehand instead of building it (CI sets it after a cached buildx build). AfterSuite runs undeployChart and removes cert-manager if the suite installed it, unless KUIK_E2E_DISPOSABLE_CLUSTER=true, which task test-e2e sets when it created the cluster and deletes it after the run. The top-level AfterEach dumps logs, events and pod descriptions on failure. The default Eventually timeout is 2m. Every command is bounded: kubectl (1m), makeTarget (10m), runBounded for any other command, and kubectlCommand for a caller that builds the command before utils.Run.
  • e2e_test.go: the chart's names as constants (namespace, deploymentName, processSelector, metricsPort...) and the Manager container. Its specs: the 3 Deployments are available, each process runs under its own ServiceAccount, the RBAC table of docs/v3/architecture.md (canI, over kubectl auth can-i --as), the webhook metrics endpoint (a curl-metrics pod, getMetricsOutput), the cert-manager Secret and the CA injection.
  • routing_test.go: the Pod routing container. Its pods run in kuik-e2e-routing, a namespace labelled kuik.enix.io/e2e=true that its ImageAlternatives select. Helpers:
    • podManifest, createPod: a restricted-compatible pause pod, created through admission once.
    • podImage, podPhase, kuikAnnotations: the admitted image, the phase, and only the kuik.enix.io/* annotations.
    • replicasRouting, everyReplica: whether each webhook pod rewrites an unreachable origin, asked directly through kubectl proxy (startAPIProxy, in BeforeAll).
    • webhookMetric: a counter on each webhook pod.
    • setConfig, mergeConfig: replace the global config file in its ConfigMap; a fragment is deep merged onto the release's config first, never appended.
    • scaleWebhook, webhookPods, webhookRestarts, deploymentAvailable: the webhook Deployment and its pods; webhookRestarts is what a "without a restart" spec compares.
    • kubectlStdin: kubectl with a manifest on stdin.
  • mirror_test.go: the Image mirroring container. A distribution v3 registry in kuik-e2e-registry (htpasswd, tag deletion on), addressed by its DNS name so that destination.insecure matters, and pods in kuik-e2e-mirror. registryTags reads the tags of a repository from the registry's storage.
  • test/utils: Run (runs a command from the project directory), LoadImageToKindClusterWithName, GetNonEmptyLines, the cert-manager install helpers.

Common mistakes

MistakeFix
e2e specs written with the first test commitAdd them in the last commit, once the PR is ready
A new file under test/e2e/ without //go:build e2eStart every file with it: task test skips test/e2e/, so the miss passes locally
Running the suite on the current kubeconfig, or on a real clusterKUBECONFIG=<tmp>/e2e-kubeconfig task test-e2e, Kind only
Creating the pod right after the CRPoll replicasRouting until every replica sees the CR
Waiting on a server-side dry runIt reaches one replica only: ask each pod with replicasRouting
Reading the metrics of one webhook podRead every replica with webhookMetric
Proving a config reload from a log lineProve it through routing, with a config that changes it
kubectl create --raw to a webhook podIt sends no Content-Type, which the webhook refuses: POST through kubectl proxy
An HTTP call without a timeout inside EventuallyEventually never interrupts a hung poll: bound the client
An assertion on a cluster-wide list or count (driftedImages empty)Assert only on the objects the spec creates: other specs and the platform's own images add entries, in random order
A one-shot Expect on something that makes the webhook or a loop reach a real registryEventually with a bounded timeout: the first probe of a cold host (TLS, token, redirect) can exceed availabilityCheck.timeout
A bare exec.Commandutils.Run waits for the process with no deadline: use kubectl, makeTarget or runBounded
An "untouched" spec with nothing proving the webhook ranOrder it after a spec that shows a rewrite
An in-cluster plain HTTP registry for an image a pod pulls or the webhook probesregistry.k8s.io for an answer, .invalid for a failure; the ImageMirror destination is the one exception
helm upgrade to change the configsetConfig(mergeConfig(original, fragment)), then wait on behaviour (3m at most)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.