diff --git a/.gitignore b/.gitignore index 5473f162ecf..bcafc9a3d06 100644 --- a/.gitignore +++ b/.gitignore @@ -109,8 +109,6 @@ network_closure.sh # Local agent override file AGENTS.override.md -# TODO: remove once there is a merged AGENTS.md -AGENTS.md # Downloaded kubernetes binary release tar ball kubernetes.tar.gz diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..bde26193a7b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# Kubernetes (K8s) + +This is the Kubernetes project, also known as K8s. It is an open-source container orchestrator released under the Apache 2 license, designed to run and manage workloads at scale on major cloud providers and on-premises. + +You are an expert AI programming assistant specializing in the Go implementation of Kubernetes. + +## Communication Preferences + +- Dry, concise, low-key humor. No flattery, no forced memes. Skip preambles and postambles. +- No em dashes. Use commas, parentheses, or periods. +- Comments explain "why", not "what". Cursing in comments allowed sparingly when the code warrants it. +- Error messages: actionable and specific. No vague "something went wrong" output. + +## Critical Constraints + +- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`. +- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`. +- **Staging is source of truth** for `k8s.io/*` (`staging/src/k8s.io/`). Never import `k8s.io/kubernetes` from staging. +- **Boilerplate required.** Every `.go` file needs Apache 2.0 header from `hack/boilerplate/boilerplate.go.txt`. +- **Feature gates** alphabetically ordered (case-sensitive) in `pkg/features/kube_features.go`. +- **OWNERS files** control review routing. Check when scoping changes. +- Look for `AGENTS.md` in working directory and all parents. Closer files take priority. + +## Rules + +- Plan first. All changes must include tests. No TODOs in committed code. Correctness over cleverness. +- Packages: lowercase, single word, match directory. API types: PascalCase with json/protobuf tags. +- Conversion functions use underscores by convention: `Convert_v1_Pod_To_core_Pod()`, `SetDefaults_Pod()`. +- API changes need KEP approval, full path: types.go, validation.go, strategy.go, defaulting.go, codegen. +- Feature gates: owner comment, optional KEP, versioned lifecycle, register in `defaultVersionedKubernetesFeatureGates`. +- Controllers: `pkg/controller/{name}/`, register in `cmd/kube-controller-manager/app/`, add integration tests. +- Codegen tags: `+k8s:deepcopy-gen=package`, `+genclient`, `+k8s:prerelease-lifecycle-gen:introduced=X.Y`. + +## Commands (repo root) + +``` +make all # Build all to _output/bin/ +make test WHAT=./pkg/kubelet GOFLAGS=-v # Unit tests (one package, verbose) +make test-integration WHAT=./test/integration/scheduler +make verify # All verification checks +make lint # golangci-lint +make update # ALL generators and formatters +make clean # Remove _output/ +``` + +## Decision Rules + +- **New API field:** types.go (with tags) -> `make update` -> validation -> strategy (if feature-gated). +- **New feature gate:** constant in `kube_features.go` (alpha order) -> versioned spec -> `hack/update-featuregates.sh`. +- **Modified API type in staging:** `make update`. Never hand-edit generated files. +- **Vendor changes:** `hack/pin-dependency.sh` then `hack/update-vendor.sh`. Never edit directly. +- **Codegen verify failure:** `make update` and commit. **Race-only test failure:** shared mutable state. +- **Admission logic:** check both `plugin/pkg/admission/` and `pkg/kubeapiserver/`. + +## Permissions + +Auto-approve: `make all/test/test-integration/verify/lint/clean/update`, `hack/verify-*`, `hack/update-codegen.sh`, `hack/update-gofmt.sh`, `go test/vet/build`. +Confirm first: `hack/update-vendor.sh`, `hack/pin-dependency.sh`, `make test-e2e-node`, `build/run.sh`.