|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to coding agents (e.g. Claude Code, claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository purpose |
| 6 | + |
| 7 | +Go module `kubevault.dev/installer` — Helm charts and supporting tooling for installing [KubeVault](https://kubevault.com/). It also exposes a Go API package (`apis/installer/v1alpha1/`) describing chart values so other KubeVault components can consume strongly typed installation parameters. |
| 8 | + |
| 9 | +Charts shipped: |
| 10 | +- `charts/kubevault` — meta chart (operator + webhook + catalog + metrics). |
| 11 | +- `charts/kubevault-operator` — the KubeVault operator (the main controller manager). |
| 12 | +- `charts/kubevault-webhook-server` — admission webhook server. |
| 13 | +- `charts/kubevault-catalog` — `VaultServerVersion` catalog. |
| 14 | +- `charts/kubevault-crds` — CRDs only. |
| 15 | +- `charts/kubevault-metrics` — Prometheus metrics exporter. |
| 16 | +- `charts/kubevault-opscenter` — OpsCenter UI integration. |
| 17 | +- `charts/kubevault-grafana-dashboards` — packaged Grafana dashboards. |
| 18 | +- `charts/kubevault-certified`, `charts/kubevault-certified-crds` — Red Hat-certified packaging. |
| 19 | + |
| 20 | +## Architecture |
| 21 | + |
| 22 | +- `charts/` — one subdirectory per Helm chart. Each has `Chart.yaml`, `values.yaml`, `templates/`, plus generated artifacts `doc.yaml`, `README.md`, and (where applicable) `values.openapiv3_schema.yaml` and `crds/`. |
| 23 | +- `apis/installer/v1alpha1/` — Go types backing chart values. Used for OpenAPI/values-schema generation and as a typed surface for downstream programs. Single API group: `installer:v1alpha1`. |
| 24 | +- `crds/` — top-level CRDs (chart-specific CRDs live under each chart's `crds/`). |
| 25 | +- `catalog/` — image catalog driven by `kmodules.xyz/image-packer`. `imagelist.yaml` is the source of truth. |
| 26 | +- `hack/scripts/` — codegen/release helpers (`update-catalog.sh`, `update-chart-dependencies.sh`, `import-crds.sh`, `ct.sh`, etc.). |
| 27 | +- `tests/` — chart-testing (`ct`) configuration. |
| 28 | +- `lintconf.yaml` — YAML lint config. |
| 29 | +- `third_party/` — vendored third-party assets. |
| 30 | +- `vendor/` — Go vendored deps. |
| 31 | +- `DEVELOPMENT.md` — developer guide. |
| 32 | + |
| 33 | +## Common commands |
| 34 | + |
| 35 | +All Make targets run inside `ghcr.io/appscode/golang-dev` — Docker must be running. |
| 36 | + |
| 37 | +- `make gen` — regenerate everything: clientset + manifests + values schemas + chart docs. Run after any change to `apis/installer/v1alpha1/*_types.go`. |
| 38 | +- `make clientset` — regenerate Go client only. |
| 39 | +- `make manifests` — `gen-crds gen-values-schema gen-chart-doc`. |
| 40 | +- `make gen-values-schema` — regenerate `values.openapiv3_schema.yaml` from the Go types. |
| 41 | +- `make gen-chart-doc` — regenerate per-chart `README.md`. |
| 42 | +- `make update-charts` — refresh chart-level metadata. |
| 43 | +- `make fmt`, `make lint`, `make unit-tests` / `make test` — standard. |
| 44 | +- `make ct` — chart-testing lint+test. |
| 45 | +- `make verify` — `verify-modules`; `go mod tidy && go mod vendor` must leave the tree clean. |
| 46 | +- `make add-license` / `make check-license` — manage license headers. |
| 47 | + |
| 48 | +Auxiliary helpers (invoked outside Make): |
| 49 | + |
| 50 | +- `./hack/scripts/update-catalog.sh` — regenerate `catalog/` from `imagelist.yaml`. |
| 51 | +- `./hack/scripts/import-crds.sh` — pull CRDs from `kubevault.dev/apimachinery` into each chart's `crds/`. |
| 52 | + |
| 53 | +Run a single Go test (requires a local Go toolchain): |
| 54 | + |
| 55 | +``` |
| 56 | +go test ./apis/installer/v1alpha1/... -run TestName -v |
| 57 | +``` |
| 58 | + |
| 59 | +## Conventions |
| 60 | + |
| 61 | +- Module path is `kubevault.dev/installer` (vanity URL). Imports must use that. |
| 62 | +- Edit `apis/installer/v1alpha1/*_types.go` to change a chart's values surface, then run `make gen` so the generated clientset, `values.openapiv3_schema.yaml`, and per-chart `README.md` stay in sync. Do not hand-edit `zz_generated.*.go`, generated chart `README.md` files, `values.openapiv3_schema.yaml`, or anything under `catalog/` except `imagelist.yaml`. |
| 63 | +- License: `LICENSE.md` (AppsCode); use `make add-license` to apply headers to new Go files. |
| 64 | +- Sign off commits (`git commit -s`); contributions follow the DCO. |
| 65 | +- Vendor directory is checked in — `go mod tidy && go mod vendor` must leave the tree clean (enforced by `verify-modules`). |
| 66 | +- CRDs for charts are **imported** from `kubevault.dev/apimachinery` via `import-crds.sh`; do not hand-author `charts/*/crds/*.yaml`. |
| 67 | +- The `-certified` charts mirror the standard charts for Red Hat certification — bumps must apply to both pairs (`kubevault-operator` ↔ `kubevault-certified`, `kubevault-crds` ↔ `kubevault-certified-crds`). |
0 commit comments