Kuma - CNCF service mesh (Envoy-based) for K8s/VMs. L4-L7 connectivity, security, observability, multi-zone/multi-mesh.
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 environmentCode quality principles (CRITICAL):
-
Minimal, surgical changes only
- Modify ONLY what's necessary; keep PRs small (<10 files)
- Don't refactor unrelated code "while you're there"
-
Follow existing patterns
- Study surrounding code before making changes
- Match naming conventions, error handling, structure
- When in doubt, ask for clarification
-
No bloated changes
- No unnecessary abstractions or
utils.go/helpers.gofiles - No new dependencies without explicit discussion
- Remove unused code you encounter, but don't hunt for it
- No unnecessary abstractions or
-
Quality gates (code changes only, skip for docs/config/CI)
make formatto auto-fix, thenmake checkto validate (fails if files changed)- Fix ALL linting issues (config:
.golangci.yml, see.claude/rules/linting.md) git diffto verify changes are focused
make checkto ensure clean starting state- Read existing code in relevant
pkg/directory - Write tests first (
*_test.go, Ginkgo/Gomega) - Implement minimal, focused changes
make format && make check && make testto validate
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(DCOSigned-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 graphqland verify the link. GitHub ignoresFixes #Nfor 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 } } }'
- Using issue/PR node IDs:
- Changelog: from PR title or
> Changelog: {<desc>,skip} - CI labels: MUST set with
gh pr create --label "ci/...". Most gate onpull_requestopened/reopened/synchronizeevents, 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.mdfor features/architecture decisions - Downstream refs: say "downstream project" or "enterprise fork". Never mention Kong Mesh in PRs/commits (private repo)
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.
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:
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.
kuma-cp: control plane, serves xDS configs to data planes, manages mTLS certs, coordinates zoneskuma-dp: data plane proxy (wraps Envoy), connects tokuma-cpfor bootstrap configkumactl: CLI forkuma-cpREST APIkuma-cni: CNI plugin for transparent proxy setup on K8s
pkg/core/: core resource types and managerspkg/xds/: Envoy xDS config generation (listeners, clusters, routes, endpoints)pkg/kds/: Kuma Discovery Service, syncs resources between Global CP and Zone CPspkg/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.mdpkg/plugins/: plugin architecture (bootstrap, runtime, CA, resources, policies)pkg/transparentproxy/: transparent proxy (iptables)pkg/config/: configuration managementpkg/test/: test utilities, matchers, and resource builderstools/: code generation tools (policy-gen, resource-gen, openapi)
- 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
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
Uses mise (config: mise.toml). Install via make install. Includes: buf, ginkgo, helm, kind, kubectl, protoc, golangci-lint, skaffold.
- Framework: Ginkgo (BDD) + Gomega assertions (
*_test.go); see.claude/rules/testing.md - Golden matchers:
MatchGoldenYAML,MatchGoldenJSON,MatchGoldenEqual,MatchProto - Golden files: in
testdata/dirs. Update withUPDATE_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
- RBAC gate: if
deployments/RBAC manifests change,UPGRADE.mdmust also be updated ormake checkfails - Import aliases required:
.golangci.ymlenforcescore_mesh,mesh_proto,core_model,common_api, etc. See.claude/rules/linting.md - Cached resources are read-only:
pkg/core/resources/manager/cache.goreturns shared instances. Never modify them pkg/cannot importapp/: architectural boundary enforced by depguard linter
- Missing dependencies →
make install - Outdated generated code →
make generate - Formatting errors →
make format(auto-fixes), thenmake check(validates) - Golden file mismatches →
UPDATE_GOLDEN_FILES=true make test
- Versions:
active-branches.jsonandversions.ymlin 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