kuma

# AGENTS.md

Kuma - CNCF service mesh (Envoy-based) for K8s/VMs. L4-L7 connectivity, security, observability, multi-zone/multi-mesh.

## Commands

```bash
make install              # Install dev tools (runs: mise install + buf dep update)
make build                # Build all components
make format               # Format and generate code (auto-fix)
make check                # Run format + lint, then verify no files changed
make generate             # Generate code (protobuf, policies, resources)
make test                 # Run tests
make test/e2e             # Run E2E tests (slow, requires cluster setup)

make build/kuma-cp        # Build control plane
make build/kuma-dp        # Build data plane
make build/kumactl        # Build CLI

make test TEST_PKG_LIST=./pkg/xds/...    # Test specific package
UPDATE_GOLDEN_FILES=true make test       # Update golden files
make k3d/cluster/start && skaffold dev   # Dev environment
```

## Workflow

**Code quality principles** (CRITICAL):

1. **Minimal, surgical changes only**
   - Modify ONLY what's necessary; keep PRs small (<10 files)
   - Don't refactor unrelated code "while you're there"

2. **Follow existing patterns**
   - Study surrounding code before making changes
   - Match naming conventions, error handling, structure
   - When in doubt, ask for clarification

3. **No bloated changes**
   - No unnecessary abstractions or `utils.go`/`helpers.go` files
   - No new dependencies without explicit discussion
   - Remove unused code you encounter, but don't hunt for it

4. **Quality gates** (code changes only, skip for docs/config/CI)
   - `make format` to auto-fix, then `make check` to validate (fails if files changed)
   - Fix ALL linting issues (config: `.golangci.yml`, see `.claude/rules/linting.md`)
   - `git diff` to verify changes are focused

### Standard workflow

1. `make check` to ensure clean starting state
2. Read existing code in relevant `pkg/` directory
3. Write tests first (`*_test.go`, Ginkgo/Gomega)
4. Implement minimal, focused changes
5. `make format && make check && make test` to validate

## Git & PRs

```bash
git push --no-verify <remote> branch-name    # ALWAYS use --no-verify
```

- **Commit format**: `type(scope): description`, e.g., `feat(xds):`, `fix(meshtrace):`, `chore(deps):`
- **Commit signing**: use `git commit -s` (DCO `Signed-off-by:` required by CI)
- **Active branches**: see `active-branches.json`
- **Base branch**: `master`
- **PR template**: `.github/PULL_REQUEST_TEMPLATE.md`
- **Issue closure**: Explicitly link resolved issues in **Development** using `gh api graphql` and verify the link. GitHub ignores `Fixes #N` for non-default branches; linking does not guarantee automatic closure when merging into those branches.
  - Using issue/PR node IDs: `gh api graphql -f query='mutation { addCloseIssueReferences(input: {issueId: "ISSUE_NODE_ID", pullRequestIds: ["PR_NODE_ID"]}) { issue { id } } }'`
- **Changelog**: from PR title or `> Changelog: {<desc>,skip}`
- **CI labels**: MUST set with `gh pr create --label "ci/..."`. Most gate on `pull_request` `opened/reopened/synchronize` events, so labels added after creation only take effect on the next new run (usually the next push) — set them at creation time. See label table below
- **MADR**: `docs/madr/decisions/000-template.md` for features/architecture decisions
- **Downstream refs**: say "downstream project" or "enterprise fork". Never mention Kong Mesh in PRs/commits (private repo)

### Behavior-changing CI labels

Set at creation with `--label`. When opening PRs, apply these deliberately:

| Label | Effect | When to use |
|-------|--------|-------------|
| `ci/skip-test` | Skips **all** tests (unit + e2e + container-structure) | Docs-only, comment-only, or non-code PRs where no test can be affected. Never on code changes |
| `ci/skip-e2e-test` | Skips only e2e tests (unit tests still run) | Changes fully covered by unit tests where slow e2e adds no signal (e.g. isolated pkg refactor, config/CLI text). Don't use if touching xDS gen, policies, KDS, or transparent proxy |
| `ci/run-full-matrix` | Runs full OS/arch/k8s test matrix instead of the reduced PR matrix | Changes with cross-platform/version risk: transparent proxy, CNI, install/bootstrap, k8s-version-sensitive code, build/packaging. Costly — don't add by default |
| `ci/verify-stability` | Reruns CI repeatedly to detect flakiness; auto-removed after N consecutive green runs | Suspected flaky test, or a change to e2e/timing-sensitive code where you want confidence it's stable before merge. Add on the PR, let the scheduled stability workflow drive it |

Default (no labels) is correct for most code PRs. Reach for `skip-*` only to save CI on genuinely test-irrelevant changes; reach for `run-full-matrix`/`verify-stability` to add coverage/confidence when the change warrants it.

## Architecture

### Architecture decisions (MADRs)

`docs/madr/decisions/` is the map of why the current design looks the way it does — one decision per file, newest MADRs carrying YAML front matter (`title`, `status`, `date`, `tags`, `summary`, `related`).

There is no maintained index — the front matter IS the map. When building context for a non-trivial change, scan it first and open only the MADRs whose summary or tags match the area you're touching; filenames are descriptive slugs, so older MADRs without front matter are findable by name:

```bash
rg -N '^(status|tags|summary):' docs/madr/decisions/  # the whole map
rg -l 'zone-egress' docs/madr/decisions/              # narrow by tag or slug
./docs/madr/list.sh                                   # same, one line per MADR (human view)
```

A MADR is the design rationale, not the current state — check the code before trusting it, and mind `status: superseded` and the `related` chain (later MADRs often revise earlier ones). Follow `related` when a MADR you read builds on another.

### Components

- `kuma-cp`: control plane, serves xDS configs to data planes, manages mTLS certs, coordinates zones
- `kuma-dp`: data plane proxy (wraps Envoy), connects to `kuma-cp` for bootstrap config
- `kumactl`: CLI for `kuma-cp` REST API
- `kuma-cni`: CNI plugin for transparent proxy setup on K8s

### Key directories

- `pkg/core/`: core resource types and managers
- `pkg/xds/`: Envoy xDS config generation (listeners, clusters, routes, endpoints)
- `pkg/kds/`: Kuma Discovery Service, syncs resources between Global CP and Zone CPs
- `pkg/api-server/`: REST API server (validate external inputs here)
- `pkg/dp-server/`: data plane server (SDS, health checks)
- `pkg/plugins/policies/`: policy plugins; see `.claude/rules/policies.md`
- `pkg/plugins/`: plugin architecture (bootstrap, runtime, CA, resources, policies)
- `pkg/transparentproxy/`: transparent proxy (iptables)
- `pkg/config/`: configuration management
- `pkg/test/`: test utilities, matchers, and resource builders
- `tools/`: code generation tools (policy-gen, resource-gen, openapi)

### Multi-zone

- Global CP coordinates Zone CPs via KDS (`pkg/kds/`)
- Zone ingress/egress proxies (Dataplanes with zone proxy listeners) handle cross-zone traffic
- Supports Kubernetes and Universal (VM/bare metal)
- Upgrade order: global CP first, then zone CPs, and data plane proxies last (by manually restarting them). Design cross-version changes (KDS, schema, validation) for this order only - a newer global must keep older zones working, zone-first is not supported

### Code generation

Run `make generate` after changes to `.proto` files, `pkg/plugins/policies/*/api/` dirs, or resource definitions. Generated files: `zz_generated.*`, `*.pb.go`, `*.pb.validate.go`, `rest.yaml`

### Tool management

Uses `mise` (config: `mise.toml`). Install via `make install`. Includes: buf, ginkgo, helm, kind, kubectl, protoc, golangci-lint, skaffold.

## Testing

- **Framework**: Ginkgo (BDD) + Gomega assertions (`*_test.go`); see `.claude/rules/testing.md`
- **Golden matchers**: `MatchGoldenYAML`, `MatchGoldenJSON`, `MatchGoldenEqual`, `MatchProto`
- **Golden files**: in `testdata/` dirs. Update with `UPDATE_GOLDEN_FILES=true make test`
- **Mocks**: hand-written stubs (no mockgen/counterfeiter). Implement the interface in the test file
- **E2E**: `make test/e2e`. Slow, requires cluster setup

## Gotchas

- **RBAC gate**: if `deployments/` RBAC manifests change, `UPGRADE.md` must also be updated or `make check` fails
- **Import aliases required**: `.golangci.yml` enforces `core_mesh`, `mesh_proto`, `core_model`, `common_api`, etc. See `.claude/rules/linting.md`
- **Cached resources are read-only**: `pkg/core/resources/manager/cache.go` returns shared instances. Never modify them
- **`pkg/` cannot import `app/`**: architectural boundary enforced by depguard linter

## Common issues

- Missing dependencies → `make install`
- Outdated generated code → `make generate`
- Formatting errors → `make format` (auto-fixes), then `make check` (validates)
- Golden file mismatches → `UPDATE_GOLDEN_FILES=true make test`

## Notes

- Versions: `active-branches.json` and `versions.yml` in the repo root
- Docs: `DEVELOPER.md` (setup), `CONTRIBUTING.md` (PR workflow)
- Release process: see `.claude/rules/release.md`
- Local dev and debugging: see `.claude/rules/debug.md`

More agent context in kumahq/kuma

3 other files this repository gives its agents.