Adding AGENTS.md #4573
+288
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,288 @@ | ||||||
| # Cloud Agent Instructions for kpt | ||||||
|
|
||||||
| For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or reviewing pull requests in this repository. | ||||||
|
|
||||||
| ## Generic rules | ||||||
|
|
||||||
| ### Coding | ||||||
|
|
||||||
| * Never commit directly to this repository, always aim for a pull request | ||||||
| * Always ask for a final review from a human before committing | ||||||
| * Make sure that AI agent usage is attributed in the correct way | ||||||
|
|
||||||
| ### Reviewing PRs | ||||||
|
|
||||||
| * When committing suggested changes, add a sign-off from the human author and add the `Assisted-by` | ||||||
| tag with the suggesting agent and its used model to the commit message | ||||||
| * If a comment was not accepted and the Conversation was resolved do not make the same comment again | ||||||
|
|
||||||
|
|
||||||
| ## Repository Overview | ||||||
|
|
||||||
| **kpt** is a package-centric toolchain that automates Kubernetes configuration editing and | ||||||
| management. It enables declarative configuration authoring, automation, and delivery at scale | ||||||
| through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven | ||||||
| infrastructure (e.g., Config Connector, Crossplane). | ||||||
|
|
||||||
| - **Language**: Go (version is defined in the [go.mod](./go.mod) file) | ||||||
| - **License**: Apache 2.0 | ||||||
| - **Key Topics**: Kubernetes, configuration management, CLI tooling, GitOps, policy-as-code, KRM (Kubernetes Resource Model) | ||||||
|
|
||||||
| ## Quick Build & Test Commands | ||||||
|
|
||||||
| **Trust these instructions first.** Only perform searches if you find this information incomplete or inaccurate. | ||||||
|
|
||||||
| ### Prerequisites | ||||||
| - Go (version is specified in [go.mod](./go.mod)) | ||||||
| - Git (required and checked at runtime) | ||||||
| - Docker or Podman (for `test-docker` and function runtime tests) | ||||||
| - KinD (CI uses the version defined in `.github/workflows/e2eEnvironment.yml`) | ||||||
|
|
||||||
| ### Build | ||||||
|
|
||||||
| ```bash | ||||||
| make build | ||||||
| ``` | ||||||
| This compiles kpt to `$(go env GOPATH)/bin/kpt` using LDFLAGS with git commit SHA. | ||||||
|
|
||||||
| ### Run All Checks (Build, Test, Lint) | ||||||
|
|
||||||
| ```bash | ||||||
| make all | ||||||
| ``` | ||||||
|
|
||||||
| Runs: `fix vet fmt lint test build tidy` in sequence. *Always* run this before committing. | ||||||
|
|
||||||
| ### Unit Tests | ||||||
|
|
||||||
| ```bash | ||||||
| make test | ||||||
| ``` | ||||||
|
|
||||||
| Runs Go tests with coverage. Set `KRM_FN_RUNTIME` to select function runtime (docker/podman, default uses system default). | ||||||
|
|
||||||
| ### Docker/Podman Runtime Tests | ||||||
|
|
||||||
| ```bash | ||||||
| make test-docker | ||||||
| ``` | ||||||
|
|
||||||
| Requires Docker or Podman. Tests that need container runtime (e.g., pipeline tests). Respects `KRM_FN_RUNTIME` environment variable. | ||||||
|
|
||||||
| ### E2E Function Tests | ||||||
|
|
||||||
| #### Render tests | ||||||
|
|
||||||
| ```bash | ||||||
| make test-fn-render T=".*" | ||||||
| ``` | ||||||
| #### Eval tests | ||||||
|
|
||||||
| ```bash | ||||||
| make test-fn-eval T=".*" | ||||||
| ``` | ||||||
|
|
||||||
| Use `T` parameter to filter tests by regex (e.g., `T=fnconfig` for function config tests). Set `KRM_FN_RUNTIME` to select runtime. | ||||||
|
|
||||||
| ### E2E Live Apply Tests | ||||||
|
|
||||||
| ```bash | ||||||
| make test-live-apply | ||||||
| ``` | ||||||
|
|
||||||
| Requires KinD with Kubernetes 1.33.4 and 1.34.0 (specific SHAs pinned in CI). These tests use Kind internally. Timeout is 20 minutes. | ||||||
|
|
||||||
| ### Linting | ||||||
|
|
||||||
| ```bash | ||||||
| make lint | ||||||
| ``` | ||||||
|
|
||||||
| Runs golangci-lint v2.11.4. If already installed locally with matching version, uses it; otherwise downloads and runs via `go run`. | ||||||
|
|
||||||
| ### Code Generation & Formatting | ||||||
|
|
||||||
| ```bash | ||||||
| make fmt # Run gofmt | ||||||
| make fix # Run go fix | ||||||
| make vet # Run go vet | ||||||
| make tidy # Run go mod tidy | ||||||
| make generate # Generate code from templates (mdtogo, copyright headers) | ||||||
|
liamfallon marked this conversation as resolved.
|
||||||
| make schema # Generate schema | ||||||
| ``` | ||||||
|
|
||||||
| ### Setting Up Git Config (Required for Tests) | ||||||
|
|
||||||
| Many tests require git configuration: | ||||||
|
|
||||||
| ```bash | ||||||
| git config --global user.email "you@example.com" | ||||||
| git config --global user.name "Your Name" | ||||||
| ``` | ||||||
|
|
||||||
| ## Project Layout | ||||||
|
|
||||||
| ### Root Level Files & Directories | ||||||
|
|
||||||
| * **main.go**: CLI entry point; contains //go:generate directives for CLI documentation | ||||||
| * **Makefile**: Primary build orchestration | ||||||
| * **.golangci.yml**: Linting configuration (used golangci-lint version is defined in the `GOLANGCI_LINT_VERSION` variable of the [Makefile](./Makefile)) | ||||||
| * **go.mod / go.sum**: Dependency management | ||||||
| * **CONTRIBUTING.md**: Contribution guidelines and code review requirements | ||||||
| * **CODEOWNERS**: Default reviewers | ||||||
|
|
||||||
| ### Key Source Directories | ||||||
|
|
||||||
| * **commands/**: CLI command implementations using Cobra framework | ||||||
| * **run/**: Main CLI setup; contains GetMain() that initializes Cobra commands with environment setup | ||||||
| * **pkg/**: Core library packages (business logic, utilities) | ||||||
| * **internal/**: Internal packages; includes internal/docs/generated/ (generated from Markdown via mdtogo) | ||||||
| * **mdtogo/**: Code generator tool that converts CLI documentation Markdown files to Go variables | ||||||
|
|
||||||
| ### Build & CI Configuration | ||||||
|
|
||||||
| * **.github/workflows/go.yml**: Main CI workflow | ||||||
| * Runs on Linux (docker/podman matrix) and macOS | ||||||
| * Executes: `make all` + `make test-docker` | ||||||
| * Triggered on PRs (except changes limited to ignored paths like `**.md`) and pushes (pushes exclude dependabot branches) | ||||||
| * **.github/workflows/e2eEnvironment.yml**: KinD-based e2e tests | ||||||
| * Tests Kubernetes 1.33 and 1.34 with KinD v0.30.0 | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| * Runs `./e2e/live/end-to-end-test.sh -k <K8S_VERSION>` | ||||||
| * **.github/workflows/live-e2e.yml**: Live apply e2e tests | ||||||
| * Tests with pinned Kubernetes image SHAs | ||||||
| * Runs `make test-live-apply` with `K8S_VERSION` environment variable | ||||||
|
CsatariGergely marked this conversation as resolved.
|
||||||
| * **.github/workflows/release-api.yml**: Release the kpt API module | ||||||
| * Builds, tests and lints the kpt API module | ||||||
| * Runs `make api` | ||||||
|
|
||||||
| ### Documentation & Tests | ||||||
|
|
||||||
| * **documentation/**: Hugo-based website published to kpt.dev | ||||||
| * Run `make serve` from `documentation/` (serves docs locally) | ||||||
| * Requires `npm install` first (run in `documentation/`) | ||||||
|
|
||||||
| * **e2e/**: End-to-end test suites | ||||||
| * Contains testdata directories for function render/eval tests | ||||||
| * Live tests in `e2e/live/end-to-end-test.sh` | ||||||
|
|
||||||
| ### Other Notable Directories | ||||||
|
|
||||||
| * **release/**: Release automation (GoReleaser config, Homebrew formula generation) | ||||||
| * **hack/**: Miscellaneous development utilities | ||||||
| * **healthcheck/**: Separate module for health checking (Go (Go version is defined in [healthcheck/go.mod](./healthcheck/go.mod)), local Makefile) | ||||||
| * **thirdparty/**: Third-party code (excluded from linting) | ||||||
| * **Formula/**: Homebrew package definition (generated by `go run ./release/formula/main.go VERSION`) | ||||||
|
|
||||||
| ## Linting Rules & Style | ||||||
|
Contributor
There was a problem hiding this comment. should we be linking this to the kpt docs guide https://github.com/kptdev/kpt/tree/main/documentation#style-guide-for-documentation or is this just for code linting? |
||||||
|
|
||||||
| ### Linter Configuration | ||||||
|
|
||||||
| * Linter configuration is defined in the [.golangci.yml](./.golangci.yml) file | ||||||
|
|
||||||
| ### Code Style Requirements (from CONTRIBUTING.md) | ||||||
|
|
||||||
| * **Copyright Headers**: All files must have Apache 2.0 license header | ||||||
| * Use format: // Copyright YEAR The kpt Authors (or year range if modified) | ||||||
| * Year should match creation year, or creation-to-modification year range | ||||||
|
Contributor
There was a problem hiding this comment. It would be good to point out the detailed copyright year update instruction available on porch documentation https://porch.kpt.dev/docs/12_contributing/code-contribution/#update-copyright-on-files" |
||||||
| * **Developer Certificate of Origin (DCO)**: Commits must be signed with -s flag | ||||||
| * **Large Features**: Require reviewed and merged design document (use /docs/design-docs/00-template.md as template) | ||||||
| * **AI Usage**: Must declare AI usage in the PR description; `Assisted-by: AGENT_NAME:MODEL_VERSION` attribution in | ||||||
| commit messages is recommended (see CONTRIBUTING.md). | ||||||
|
|
||||||
| ## Validation Checklist for PRs | ||||||
|
|
||||||
| Before submitting a PR, verify: | ||||||
|
|
||||||
| 1. ✅ All tests pass: make all | ||||||
| 1. ✅ All linting passes: make lint | ||||||
| 1. ✅ Code formatted: make fmt | ||||||
| 1. ✅ Dependencies tidied: make tidy | ||||||
| 1. ✅ Copyright headers added/updated per CONTRIBUTING.md | ||||||
| 1. ✅ DCO sign-off: use git commit -s | ||||||
| 1. ✅ For CLI/API changes: design document reviewed and merged | ||||||
| 1. ✅ AI usage declared in PR description (if applicable) | ||||||
|
|
||||||
| ## Common Build Issues & Workarounds | ||||||
|
|
||||||
| ### Docker/Podman Not Available | ||||||
|
|
||||||
| If `make test-docker` fails due to missing Docker/Podman: | ||||||
|
|
||||||
| * Install Docker Desktop or Podman | ||||||
| * For Podman: ensure it's on PATH and `podman version` runs successfully | ||||||
| * Set `KRM_FN_RUNTIME=podman` if using Podman | ||||||
|
|
||||||
| ### KinD Setup Issues | ||||||
|
|
||||||
| For e2e live tests (`make test-live-apply`): | ||||||
|
|
||||||
| * KinD v0.30.0 is auto-installed by CI workflow | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| * Requires Docker running in background | ||||||
| * Tests use specific Kubernetes image SHAs (see live-e2e.yml matrix) | ||||||
| * Timeout is 20 minutes; allow sufficient time | ||||||
|
|
||||||
| ### Git Configuration | ||||||
|
|
||||||
| Tests fail silently if git user not configured. Always run: | ||||||
|
|
||||||
| ```bash | ||||||
| git config --global user.email "you@example.com" | ||||||
| git config --global user.name "Your Name" | ||||||
| ``` | ||||||
|
|
||||||
| ### Module Generation | ||||||
|
|
||||||
| If changes modify CLI documentation in documentation/content/en/reference/cli/: | ||||||
|
|
||||||
| * Run `make generate` to regenerate `internal/docs/generated/` | ||||||
| * Commit generated files | ||||||
|
|
||||||
| ### Known CI Skips | ||||||
|
|
||||||
| * Windows build currently disabled (see `.github/workflows/go.yml` line 88-104, issue #3463) | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
This can be removed as this gets updated on every change in that file. |
||||||
| * Some linters disabled: `funlen`, `gosec` (marked TODO in `.golangci.yml`) | ||||||
|
|
||||||
| ## Environment Variables | ||||||
|
|
||||||
| * **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl` | ||||||
| * **K8S_VERSION**: Kubernetes version for e2e live tests (used in CI with pinned SHAs) | ||||||
| * **KPT_NO_PAGER_HELP**: Set to 1 to disable pager for help output | ||||||
| * **PAGER**: Custom pager command (default: less -R) | ||||||
| * **KPT_FN_WASM_RUNTIME**: WASM function runtime selection | ||||||
|
CsatariGergely marked this conversation as resolved.
|
||||||
| * **GOPATH**: Go workspace path (used in CI workflows) | ||||||
| * **GOBIN**: Go binary installation directory | ||||||
|
|
||||||
| ## Key Dependencies | ||||||
|
|
||||||
| * **Cobra**: CLI framework | ||||||
| * **Kubernetes libraries (k8s.io/*)**: For Kubernetes resource handling | ||||||
| * **sigs.k8s.io/cli-utils**: CLI utilities | ||||||
| * **sigs.k8s.io/kustomize/kyaml**: YAML handling for Kubernetes | ||||||
| * **sigs.k8s.io/controller-runtime**: Controller and reconciliation patterns | ||||||
| * **wasmtime-go**: WebAssembly function runtime | ||||||
| * **go-containerregistry**: Container image handling | ||||||
|
|
||||||
| ## Testing Strategy | ||||||
|
|
||||||
| * **Unit Tests**: Run with `make test` (standard Go tests) | ||||||
| * **Docker-based Tests**: Run with `make test-docker` (requires container runtime) | ||||||
| * **Function E2E Tests**: Run with `make test-fn-render` / `make test-fn-eval` (testdata-driven) | ||||||
| * **Live Apply E2E**: Run with `make test-live-apply` (KinD-based, 20-minute timeout) | ||||||
| * **Example Verification**: Run with `make site-verify-examples` (verifies CLI examples in docs) | ||||||
|
|
||||||
| ## Implementation Notes for Code Changes | ||||||
|
|
||||||
| * **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/content/en/reference/cli/` for documentation | ||||||
| * **Library Code**: Place in `pkg/` for public APIs; use `internal/` for internal utilities | ||||||
| * **Tests**: Colocate `*_test.go` files with source; use testdata directories for fixtures | ||||||
| * **Generated Code**: Run `make generate` after modifying templates | ||||||
| * **Linting Issues**: Address all `golangci-lint` findings; consult `.golangci.yml` for thresholds | ||||||
| * **Git Flow**: Always create feature branches; use squash-merge preferred per repository settings | ||||||
| * **Documentation**: Update Markdown in documentation/; run `make serve` to make sure that there are no errors | ||||||
|
|
||||||
| Trust these instructions. They have been validated against the Makefile, GitHub workflows, go.mod, | ||||||
| and contributing guidelines. Only search for additional details if: | ||||||
|
|
||||||
| * Build or test commands fail with unexpected errors | ||||||
| * Instructions reference non-existent paths or commands | ||||||
| * New tool versions are released and compatibility is unclear | ||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is there a better way of doing this so we don't have to update the values every time? something to check latest stable kind version & associated k8s version supported by that kind version?