kubernetes/AGENTS.md

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.