From 63fb4dbc78cf9ff18b276aa9ea623a83fc0daa7c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Steenis Date: Mon, 19 Oct 2026 20:19:23 +0200 Subject: [PATCH 1/2] Add AGENTS.md --- AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0f1e1a6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# kubernetes-api + +Go types and generated CRDs for Qdrant's Kubernetes resources. This repository defines the +contract only; it contains no controllers. + +## Layout + +Three API groups, each with its own Helm chart toggle: + +| Package | API group | Chart directory (value) | +|---|---|---| +| `api/v1` | `qdrant.io/v1` | `region-crds` (`includeRegionCRDs`); `QdrantRelease` goes to `management-crds` (`includeManagementCRDs`) | +| `api/auth/v1alpha1` | `auth.qdrant.io/v1alpha1` | `auth-crds` (`includeAuthCRDs`) | +| `api/routing/v1alpha1` | `routing.qdrant.io/v1alpha1` | `routing-crds` (`includeRoutingCRDs`) | + +The `manifests` target in the `Makefile` decides which chart directory each CRD lands in; +see `docs/api.md` for all resources. + +- `api/**/*_types.go`: the types and kubebuilder markers. In `api/`, edit only these, the + tests and `groupversion_info.go` (for a new group) by hand. +- Generated, never edit by hand: `api/**/zz_generated.deepcopy.go`, `crds/`, + `charts/qdrant-kubernetes-api/templates/*-crds/`, `docs/api.md`. +- A new resource in `qdrant.io` lands in `region-crds` unless the `manifests` target moves it + elsewhere. + +## Changing types + +- After any change under `api/`, run `make gen` and commit all generated files. +- New API group: create `charts/qdrant-kubernetes-api/templates/-crds/`, add the `rm`, + `mv` and template loop lines to the `manifests` target, add `includeCRDs` to + `values.yaml`, add the helm lint lines to both the `lint` target and + `.github/workflows/pr-workflow.yaml`, and update the Layout table above. Otherwise its CRD + stays in `crds/` and never reaches the chart. +- New optional fields: pointer type, `+optional`, `omitempty`, and no `+kubebuilder:default` + unless explicitly required. A default changes every existing CR. +- Fields under `spec.config` that map directly to a Qdrant config key use Qdrant's snake_case + name (`max_log_files`). Kubernetes references such as secrets use camelCase. `maxCollections` + is an existing exception; don't copy it. Fields outside `spec.config` use camelCase. +- Restrict enums with `+kubebuilder:validation:Enum=`, using Qdrant's exact values. +- If a field needs a minimum Qdrant version, say so in the field comment ("Requires Qdrant + v1.x.y or later"). +- Every field except `Spec`, `Status` and `Items` gets a doc comment; it becomes the CRD + description, and non-status comments also end up in `docs/api.md`. +- Additions only. Removing or renaming a field breaks existing CRs. To retire a field, keep it + and add a `// Deprecated: Use X instead` comment. +- Don't reorder imports by hand; `make gen` runs `gci` with a `github.com/qdrant` group. + +## Validate + +- `make gen` leaves no uncommitted changes. +- `make lint` (gofmt, golangci-lint, helm lint for the chart flag combinations). CI also runs + `kubeconform` on `helm template` output, which `make lint` does not. +- `make test` (unit tests in `api/v1` and `api/routing/v1alpha1`, envtest integration tests + in `api/v1`). It runs `manifests`, `generate`, `fmt` and `vet` first, and downloads envtest + assets, so it needs network access. Add a case to the table tests in `*_types_test.go` for + new validation logic. + +## Branches and release + +- Name branches `feature/...` (or `feat/...`), `fix/...` or `chore/...`. The PR label is set from the branch + name, and release notes are grouped by that label. +- A release is a push to a `releases/vX.Y.Z` branch; CI creates the tag and GitHub release. From 201d0841122c41aeebdd6eda2a8473a1fb1c5608 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Steenis Date: Tue, 20 Oct 2026 14:04:12 +0200 Subject: [PATCH 2/2] README correction --- AGENTS.md | 4 +++- README.md | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f1e1a6..7b6ed73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,4 +59,6 @@ see `docs/api.md` for all resources. - Name branches `feature/...` (or `feat/...`), `fix/...` or `chore/...`. The PR label is set from the branch name, and release notes are grouped by that label. -- A release is a push to a `releases/vX.Y.Z` branch; CI creates the tag and GitHub release. +- A release needs a `vX.Y.Z` tag pushed by a cloud-admin, then a push to a `releases/vX.Y.Z` + branch on the same commit. CI publishes the GitHub release and the chart. Steps are in + `README.md`. diff --git a/README.md b/README.md index 78cdc02..1a94ab8 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,6 @@ Only members of `cloud-admins` can create `v*` tags (SEC-41 tag ruleset), so the git push origin releases/v1.2.3 ``` -The release workflow finds the tag on the branch head and skips tag creation, then publishes the release notes, the Helm chart and the image. If the branch was pushed before the tag, the run fails at the tag step; push the tag and re-run the failed job. A tag that exists on a different commit fails the release. +The release workflow finds the tag on the branch head and skips tag creation, then publishes the release notes and the Helm chart. If the branch was pushed before the tag, the run fails at the tag step; push the tag and re-run the failed job. A tag that exists on a different commit fails the release. Deployment to different environments is coupled with operator release, please see [qdrant/operator: Release process](https://github.com/qdrant/operator?tab=readme-ov-file#release-process) for details.