Skip to content

Commit 321baf5

Browse files
committed
docs(agents): narrow lookup rule to copied state
The staleness problem is specific to a lookup that carries another object's content into the rendered output; a lookup whose repeated render is identical, such as a guard or keeping a generated Secret, cannot go stale, and banning it pushed agents toward nothing better. The testing caveat held only for runs without a kubernetesProvider mock, and the alternatives now name the mechanisms the tree already has, so an agent can reach for them instead of a new lookup. Assisted-by: LLM Signed-off-by: Timofei Larkin <[email protected]>
1 parent 648dcd2 commit 321baf5

2 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ This file provides structured guidance for AI coding assistants and agents worki
2828

2929
- **Go code, Helm charts, build and test commands, project structure** (e.g., "add a field to this CRD", "fix this controller", "add a value to the postgres chart", "regenerate the values schema", "how do I build/test this", "where should I put X", "what's the convention for Y", "how is the project organized")
3030
- Read: [`overview.md`](./docs/agents/overview.md)
31-
- Action: Read the section that matches — `Go Code` (controller-runtime patterns, kubebuilder markers), `Helm Charts` (umbrella pattern, vendored upstream charts, no new `lookup`), `Values schema generation`, `Build and Development Commands`, `Testing`, `Package Structure`
31+
- Action: Read the section that matches — `Go Code` (controller-runtime patterns, kubebuilder markers), `Helm Charts` (umbrella pattern, vendored upstream charts, which `lookup` is allowed), `Values schema generation`, `Build and Development Commands`, `Testing`, `Package Structure`
3232

3333
- **E2E tests and E2E CI** (e.g., "write/fix an e2e test", "stabilize a flaky test", "add a bats test", "change the e2e workflow", "why did e2e fail")
3434
- Read: [`e2e-testing.md`](./docs/agents/e2e-testing.md)

‎docs/agents/overview.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -118,11 +118,11 @@ A chart also declares the limits on its own resource name there, with `## @name
118118
- Override configuration in root `values.yaml`
119119
- Use `values.schema.json` for input validation and dashboard UI rendering
120120

121-
**No new `lookup`.** Do not add a `lookup` to a chart template unless the operator or a maintainer has authorized that specific one. A lookup reads cluster state at render time, and nothing triggers a reconcile of the HelmRelease when the object it reads changes, so the release keeps the stale answer until something unrelated upgrades it. `helm template` and helm-unittest see only the empty branch of a lookup, so the other branch goes untested.
121+
**No `lookup` that copies another object into the render.** A `lookup` reads cluster state at render time, and nothing re-renders the HelmRelease when that state changes, so whatever it copied into the output (a bucket name, an endpoint, a CA, a list of StorageClasses) stays stale until something unrelated upgrades the release. Lookups of this kind already in the charts have caused failures, and several have since been moved to values, so they are not precedent: do not add one of this kind unless a maintainer has authorized that specific one.
122122

123-
The lookups already in the charts are not precedent: the project has worked to remove them, and they spread because agents copied them. The accepted exception is a check that an object, such as a Secret, exists, where the render converges on the same output however often it runs.
123+
A `lookup` is fine when a repeated render gives the same output and carries nothing from another object into it: checking that an object exists, keeping a generated Secret's value, keeping an immutable field of the chart's own live object, or a guard that `fail`s on an unsafe change. Keep its empty branch rendering, because offline `helm template` and helm-unittest without a `kubernetesProvider` mock see only that branch; test the other branch with such a mock.
124124

125-
To use a fact about the cluster instead, have the Cozystack API or a controller write it into the release's values, read the state at run time in a hook or Job, or move the logic into a controller.
125+
To use a fact about the cluster instead, read it from values: `_cluster` and `_namespace` in the `cozystack-values` Secret, or `valuesFrom` on a specific Secret, whose content change is a values change and so upgrades the release. Ask whether an API is served with `.Capabilities.APIVersions.Has`, since a `lookup` on an unserved group aborts the whole render. Otherwise check at run time in a hook or Job, or let a controller own the object.
126126

127127
### Go Code
128128
- Follow standard **Go conventions** and idioms

0 commit comments

Comments
 (0)