kupra's design is described in its ADRs, starting with ADR 1.
Tools are pinned with mise. After mise install:
mise run checklints and runs the unit tests.mise run generategenerates deepcopy code, CRDs and RBAC from the API types and+kubebuildermarkers. CI fails if generated files are out of date, or ifgo mod tidywould changego.modorgo.sum. The operator's RBAC goes tocharts/kupra/files/role.yaml, and the chart puts its Role in the release's namespace, sonamespace=kupra-systemin markers means the namespace kupra is installed in.- The dashboard's frontend is a SvelteKit app in
web, built on @immich/ui.mise run web:checktype-checks, lints and checks its formatting,mise run web:testruns its unit tests, andmise run web:buildbuilds it intointernal/dashboard/page, which the dashboard's binary embeds, so build it before the binary.mise run web:generategenerates its TypeScript types from the CRDs, so run it aftermise run generatechanges them. CI fails if they're out of date.mise run dashboard:devserves the built dashboard athttp://localhost:8080against envtest's API server, with sample data and a stand-in identity provider that signs you in asoidc:alice; the provider's certificate is self-signed, so accept it once.mise run web:devruns a dev server with hot reload that passes/apiand/authto it, andpnpm --dir web run screenshots <dir>takes screenshots of its pages in light and dark mode. mise run test:integrationruns the controller tests against a local API server, with envtest.mise run chart:diffdiffs the rendered chart, CRDs included, against where the branch leftmain. CI comments it on pull requests that change the chart.mise run e2e:upcreates a kind cluster with the CSI snapshot controller, the CSI hostpath driver and CloudNativePG. It also installs the chart, with operator and dashboard images built by ko from the working tree, and Dex as the identity provider that the API server and the dashboard trust. The dashboard is athttp://localhost:8090, wherecreator@example.comandviewer@example.comsign in with the passwordpassword.mise run test:smokechecks that the installed operator reconciles a Preview.mise run test:e2escales the operator down and runs the end-to-end tests on the cluster, including the dashboard's with Playwright, andmise run e2e:downdeletes it.
There are three layers of tests:
- Unit tests cover rendering and anything else written as pure functions, which is where most behaviour should be tested.
- Integration tests run against envtest, which is a real API server without Kubernetes' controllers. Namespaces never finish deleting there, and ClusterRoles aren't aggregated.
- End-to-end tests run the operator in the test process, but with its own service account's token, so its RBAC is tested too.
- Where Kubernetes has a standard shape for something, the API uses it, such as discriminated unions,
corev1reference types andrbacv1.Subject. - Before writing a type or helper, check whether Kubernetes, controller-runtime, apiserver or Flux's libraries already have one. If none fits, say why in a comment.
kupra's prose reads like Kubernetes' own. When in doubt, find how Kubernetes, controller-runtime or Flux words the same thing, and copy it.
- Errors and messages, such as field errors, condition messages and events, are terse: lowercase, no trailing period, one clause. They say what's wrong, not why or how to fix it, in the wording of apimachinery's field errors:
is required,must be ...,may not be set,not found. For example:spec.dataSourceRef: Forbidden: may not be set on a claim with managed state. - Doc comments start with the name and say what it is or does, in one sentence. A second sentence is only for what a caller can't tell from the signature.
- Comments say why, where the code can't. They don't narrate what the code does, compare it with earlier versions, or argue for the design: that belongs in the ADRs.
- CRD descriptions and flag help are one short sentence, like those of Kubernetes' own types.
- No filler, such as "note that", "simply" or "just", and no hedging.
- Commit messages are conventional commits, one line, with no body.
- PRs are squash-merged under their title, which is a conventional commit too.
- Larger work is a stack of PRs, managed with
gh stack. Each commit in a PR builds and passes the tests on its own. - Kritika, the org's review bot, reviews every PR. Once it's happy, a maintainer reviews. From then on, fixes go in as new commits instead of rewriting the PR's history.
An ADR stays Proposed until it's implemented. The PR that finishes the last part of an ADR marks it Accepted, and updates it if the implementation turned out differently.
release-please opens a release PR from the conventional commits on main. Merging it tags the release, and publishes the operator's image to ghcr.io/futo-org/kupra-operator and the chart to oci://ghcr.io/futo-org/charts/kupra, all with the same version. Installing kupra covers installs and upgrades.