jklein
b218f64eac
Closes out the schema programme (#68) by moving what the 18 charts taught into the reference implementation and the binding guidelines. template-chart: - values.schema.json as the reference schema: additionalProperties false on every chart-owned level, pod-spec passthrough left open, and the reasoning inline in the descriptions so a copy carries it along. - defaultedDict and subBlock plus the per-block fallbacks for both security contexts, the three probes and resources, wired into both the Deployment and the StatefulSet. - the reference itself violated guideline 1: its env block reads ingress.domain, so with the Ingress gated off it rendered an empty value. That read is now required(), and the comment says why - the template is what people copy, so it has to teach the guard, not the hole. README, new section "Values that must not lie" with the five rules: 1. a value read outside its obvious template needs its own guard (matrix-synapse published '{"m.server": ":443"}' to federation without it, rendering cleanly and reporting healthy) 2. probes, contexts and resources through the null-safe helper, never behind an "if" - a guard removes the probe instead of showing a null 3. no liveness on an external dependency where a dependency-free path exists, otherwise document why on the helper 4. a fallback reproduces THIS chart's defaults, not the repo standard - calibre's readOnlyRootFilesystem: false is what keeps the runtime uid at 1000 instead of 911 and existing volume data readable 5. a probe default carries its context - port name, Host header, exec command - or the probe vanishes (teamspeak) or gets 403 (patchmon) Plus the two mechanics that are easiest to lose: null reaches schema validation only for keys WITHOUT a chart default (which is why the helper and the ["object","null"] types each cover a case the other cannot), and schemas must be validated against real bundle values - that step caught a draft of mine that would have broken three live paperless releases. CLAUDE.md: the new-chart checklist now names the schema and the adaptation step, since the copied file is chart-specific and wrong until it is adapted. freesailarr is not covered: it is not on main yet (#59).
71 lines
7.5 KiB
Markdown
71 lines
7.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Working on issues — mandatory workflow
|
|
|
|
The main Claude session acts as the **task manager** and does not implement issues itself:
|
|
|
|
1. **Plan first, get approval**: The manager presents a plan for the issue and waits for the user's explicit approval. No implementation before approval.
|
|
2. **Document the final plan on the issue**: Once approved, the plan is posted as a comment on the GitHub issue before implementation starts (skip if the issue body already contains the full plan; later decisions go there as comments too).
|
|
3. **Delegate implementation**: After approval, the manager launches a dedicated **development agent**. The agent implements the issue completely on its own branch and opens a PR.
|
|
4. **PR comment handling by the agent**: After opening the PR, the development agent watches it for review comments. New comments are addressed automatically (code changes, reply on the thread), and addressed threads are marked as **resolved**.
|
|
5. **Agent lifetime**: The development agent terminates itself once its PR has been merged (or closed).
|
|
6. Only after the PR has been **merged by the user** may work on the next issue begin. The user merges; never merge yourself.
|
|
7. **After the merge, verify the linked issue was closed** (auto-close via "Fixes #n"); close it manually if not.
|
|
|
|
Additional rules for all commits, PRs, issues, and comments:
|
|
|
|
- Do **not** add a `Co-Authored-By` trailer and do **not** append "Generated with Claude Code" footers.
|
|
|
|
## Keep the docs current
|
|
|
|
- Changes to this issue workflow always go into this CLAUDE.md file.
|
|
- General repository information (charts, CI pipelines, conventions, tooling) always lives in README.md. Any PR that changes repo-wide behavior must update README.md in the same PR.
|
|
- Runtime verification of chart changes is done in a local, throwaway k3d cluster (k3d is installed on the maintainer's machine): stub CRD for `OnePasswordItem`, dummy secrets, throwaway infrastructure (postgres/redis) where needed.
|
|
|
|
## What this repo is
|
|
|
|
A collection of self-made Helm charts, one directory per chart, published to a private OCI registry via GitHub Actions. Validation happens on three levels: locally with Helm, in the PR pipeline (`validate-charts.yml`: strict lint, package, version-bump check), and in the PR install-test stage (k3d, fixtures under `ci/` — see README):
|
|
|
|
```bash
|
|
helm lint --strict <chart-name>
|
|
helm template <chart-name> --set ingress.domain=example.com --set ingress.clusterIssuer=letsencrypt # render locally; required values vary per chart
|
|
```
|
|
|
|
## Creating a new chart
|
|
|
|
Copy `template-chart/` and replace every `xxx` placeholder — in file names (`templates/xxx.deployment.yaml` → `templates/<app>.deployment.yaml`), in `Chart.yaml`, in the `values.yaml` keys and their `.Values.xxx.*` references inside templates, and in `values.schema.json` (both the values paths and the `xxx.` helper prefixes). The schema and the null-safe fallback helpers come with the template but their content is chart-specific — adapt them along the five points of the README section "Values that must not lie", and validate the result against the chart's real bundle values, not only against its defaults. Then wire up CI:
|
|
|
|
1. Add `.github/workflows/publish-<chart-name>.yml` (copy an existing one, e.g. `publish-outline.yml`) — it triggers on pushes to `main` touching `<chart-name>/**` and calls the reusable `publish-helm-chart.yml`.
|
|
2. Add the chart name to the `chart-name` choice list in `.github/workflows/change-app-version.yml`.
|
|
3. Add install-test fixtures under `ci/<chart-name>/` (`test-values.yaml`, `fixtures.yaml`) or an entry with justification in `ci/excluded-charts.txt` — the PR install-test fails if both are missing.
|
|
|
|
## Versioning scheme
|
|
|
|
`Chart.yaml` versions follow `version: <chart-semver>+up<appVersion>` (e.g. `1.4.0+up1.9.2`), with `appVersion` matching the suffix (dashes in the app version are normalized to dots in the suffix). Any push to `main` touching a chart directory publishes that chart, so the version must be bumped in the same change.
|
|
|
|
Semver conventions for the chart part:
|
|
|
|
- **Patch**: bug fixes without behavior or values-schema change; plain app-version updates.
|
|
- **Minor**: additive, backward-compatible changes (new optional values with unchanged defaults).
|
|
- **Major**: runtime behavior changes or breaking values changes (e.g. probes, security hardening, computed limits, values that become required).
|
|
|
|
App-version updates go through PRs (so the validate and install-test pipelines run), not through the `change-app-version.yml` dispatch workflow (which commits directly to main and bypasses both). For app **major** jumps, update stepwise: first to the last release of the old major line (own PR, merge, publish), then to the newest major.
|
|
|
|
## Chart conventions
|
|
|
|
The binding style guide for all current and future charts lives in **README.md ("Chart style guidelines")**; `template-chart/` is the reference implementation. Compact summary:
|
|
|
|
- Resources named `{{ .Release.Name }}-{{ .Chart.Name }}-<kind>`; template files `<app>.<kind>.yaml`; stateful apps use a StatefulSet (`<app>.sfs.yaml`). Documented exception: historical PVC names stay (renames would orphan data); StatefulSet renames only with a `--cascade=orphan` migration note in a major PR.
|
|
- Main image tag from `{{ .Chart.AppVersion }}`; auxiliary/sidecar/init images pinned via values and reviewed on app-update rounds.
|
|
- Ingress: `ingress.domain` and `ingress.clusterIssuer` `required` **without defaults**; `ingress.className` defaults to `nginx`; optional `ingress.annotations` merged with the cert-manager annotation; TLS secret `tls-<release>-<chart>-ingress`. Documented exception: homeassistant keeps its flexible upstream ingress style (className default `nginx`).
|
|
- Secrets are 1Password `OnePasswordItem` CRs: values expose `secrets.<name>SecretRef` holding an `op://` item path; the operator materializes the Kubernetes Secret.
|
|
- Config changes must restart the workload (#82): every pod template consuming a ConfigMap carries `checksum/config: {{ include (print $.Template.BasePath "/<chart>.configmap.yaml") . | sha256sum }}` (one line per ConfigMap). Without it a changed ConfigMap restarts nothing — `subPath` mounts are never refreshed and apps read config only at start. Adding it to an existing chart is a **major** bump. Secrets from `OnePasswordItem` cannot be hashed (Helm never sees their content); charts mounting them document the limitation in `values.yaml`.
|
|
- Every container offers an additive `env` block rendered through `tpl` with `value`, `secretKeyRef`, and `configMapKeyRef` forms.
|
|
- Hardening: `automountServiceAccountToken: false`, non-root, `readOnlyRootFilesystem: true`, caps dropped, `allowPrivilegeEscalation: false`; contexts values-configurable (`securityContext.pod` / `securityContext.container`); writable paths as emptyDirs; image-forced deviations MUST be documented with a comment in the chart's `values.yaml`.
|
|
- Probes: liveness/readiness/startup on every workload (exception: paperless consume CronJob), values-configurable with calibrated defaults.
|
|
- Resources: requests as values defaults; limits auto-computed by the `_helpers.tpl` helper (`limitFactor` default 3; no CPU limits unless set explicitly).
|
|
- Replicas per workload (explicit `0` allowed) plus a chart-global `scaleDown` flag that overrides them.
|
|
- `icon:` mandatory in every `Chart.yaml`; `helm lint --strict` without findings; CI fixtures under `ci/<chart>/` or a justified exclusion; no chart dependencies (`charts/` directories are empty).
|