From dc76a7c0b409870ca6af1c255980fd586c050034 Mon Sep 17 00:00:00 2001 From: Francesco Pantano Date: Wed, 6 May 2026 12:03:32 +0200 Subject: [PATCH] Add AGENTS.md This patch adds AGENTS.md to the repo to ensure any AI agent can follow the conventions defined for this operator. At the same time, it allows to not waste time navigating the repo to find initial information and save tokens. Signed-off-by: Francesco Pantano --- 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 000000000..bddcfe4b2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md - nova-operator + +## Project overview + +nova-operator is a Kubernetes operator that manages +[OpenStack Nova](https://docs.openstack.org/nova/latest/) (the compute +service: VM lifecycle, scheduling, cells, live migration, VNC console, and +metadata) on OpenShift/Kubernetes. It is part of the +[openstack-k8s-operators](https://github.com/openstack-k8s-operators) project. + +## Tech stack + +| Layer | Technology | +|-------|------------| +| Language | Go (modules, multi-module workspace via `go.work`) | +| Scaffolding | [Kubebuilder v4](https://book.kubebuilder.io/) + [Operator SDK](https://sdk.operatorframework.io/) | +| CRD generation | controller-gen (DeepCopy, CRDs, RBAC, webhooks) | +| Config management | Kustomize | +| Packaging | OLM bundle | +| Testing | Ginkgo/Gomega + envtest (functional), KUTTL (integration) | +| Linting | golangci-lint (`.golangci.yaml`) | +| CI | Zuul (`zuul.d/`), Prow (`.ci-operator.yaml`), GitHub Actions | + +## Directory structure and Custom Resources + +The project directory structure and design choices are documented in +[doc/design.md](doc/design.md). + +## Build commands + +After modifying Go code, always run: `make generate manifests fmt vet`. + +## Code style guidelines + +- Follow standard openstack-k8s-operators conventions and lib-common patterns. +- Use `lib-common` modules for conditions, endpoints, TLS, storage, and other + cross-cutting concerns rather than re-implementing them. +- CRD types go in `api/v1beta1/`. Controller logic goes in + `internal/controller/`. Resource-building helpers go in `internal/nova*` + packages matching the CR they support. +- Config templates are plain files in `templates/` -- they are mounted at + runtime via the `OPERATOR_TEMPLATES` environment variable. +- Webhook logic is split between the kubebuilder markers in `api/v1beta1/` and + the implementation in `internal/webhook/`. + +## Testing + +- Functional tests use the envtest framework with Ginkgo/Gomega and live in + `test/functional/`. +- KUTTL integration tests live in `test/kuttl/`. +- Run all functional tests: `make test`. +- When adding a new field or feature, add corresponding test cases in + `test/functional/` and update fixture data accordingly. + +## Key dependencies + +- [lib-common](https://github.com/openstack-k8s-operators/lib-common): shared modules for conditions, endpoints, database, TLS, secrets, etc. +- [infra-operator](https://github.com/openstack-k8s-operators/infra-operator): RabbitMQ and topology APIs. +- [mariadb-operator](https://github.com/openstack-k8s-operators/mariadb-operator): database provisioning. +- [keystone-operator](https://github.com/openstack-k8s-operators/keystone-operator): identity service registration. +- [gophercloud](https://github.com/gophercloud/gophercloud): Go OpenStack SDK. +- [Developer guide](https://github.com/openstack-k8s-operators/nova-operator/blob/main/doc/developer.md): local development setup, building, running, and debugging the operator.