GO — Healthy across the board

• Last commit 1d ago
• 26+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

kgateway is a Kubernetes-native API Gateway and AI Gateway built on Envoy that implements the Kubernetes Gateway API standard. It provides a control plane for routing, security policies (authentication, authorization, rate limiting), and multi-protocol support, scaling from lightweight service-mesh deployments to massive centralized gateways handling billions of API calls. Monorepo with Go as primary language (4.7MB), Rust components (116KB) for performance-critical paths, shell scripts (115KB) for operational tasks. Organized by .github/workflows for CI/CD, likely cmd/ for CLI tools, pkg/ for libraries, and test/ directories. Uses controller-runtime (sigs.k8s.io/controller-runtime v0.23.3) for Kubernetes operator patterns.

Platform engineers and SREs deploying API gateways in Kubernetes clusters who need standards-compliant ingress, developers migrating from legacy applications to microservices/serverless, and teams managing complex multi-tenant API ecosystems with route delegation and composable policies.

Production-ready and mature: the project has significant GitHub stars, robust CI/CD with conformance tests (.github/workflows/conformance.yaml, e2e.yaml), comprehensive test suites (unit.yaml, nightly-tests.yaml), and active development (dependencies updated to 2025-present versions like go-control-plane v0.14.0). Implements stable Kubernetes standards (Gateway API v1.5.1, Istio v1.30.0-alpha) and follows OpenSSF best practices.

Low risk for production use but moderate complexity: the project depends on 40+ major dependencies (Envoy, Kubernetes, gRPC ecosystem, Istio) requiring coordinated updates, but has strong CI coverage and conformance testing. The codebase is substantial (4.7MB Go code) with Rust/Shell components adding operational complexity. No obvious single-maintainer risk given the formal GitHub org structure and active workflows.

Active development: recent dependency bumps to latest Envoy control plane (v1.37.1, go-control-plane v0.14.0), Kubernetes 1.35.3 support, and Istio 1.30 alpha integration. Nightly test suite (.github/workflows/nightly-tests.yaml) validates against min/max Kubernetes versions. Conformance testing (.github/workflows/conformance.yaml) ensures Gateway API compliance.

Clone and build: git clone https://github.com/kgateway-dev/kgateway.git && cd kgateway && go mod download && make build (inferred from Go module structure and Makefile presence). Requires Go 1.26.2+ and make. Use devcontainer.json for containerized development: code . with Dev Container extension will auto-provision.

Daily commands: make build (Makefile present). See .github/workflows/e2e.yaml and kubernetes-e2e-tests action.yaml for test execution: likely make test for unit tests, make e2e for integration tests against Kind/K3d clusters (setup-kind-cluster and setup-k3d-cluster actions available).

• api/v1alpha1/kgateway/gateway_parameters_types.go — Defines core gateway configuration types that control the API gateway behavior and must be understood to configure kgateway properly.
• api/v1alpha1/kgateway/traffic_policy_types.go — Defines traffic routing and load balancing policies central to the gateway's request routing logic.
• api/v1alpha1/kgateway/gateway_extensions_types.go — Defines extensibility points for custom policies and plugins that drive kgateway's plugin architecture.
• api/annotations/gateway.go — Gateway annotation handling—understand how Kubernetes annotations drive gateway behavior configuration.
• Makefile — Build system entry point; required to understand how to build, test, and deploy kgateway locally.
• .github/workflows/e2e.yaml — End-to-end test pipeline; essential for understanding the test infrastructure and CI/CD practices.
• go.mod — Go module dependencies including Envoy control plane and gRPC middleware—critical for understanding external integrations.

Add a new traffic policy type

1. Create a new types file in api/v1alpha1/kgateway/ (e.g., my_policy_types.go) that defines your policy struct embedding the base policy (api/v1alpha1/kgateway/my_policy_types.go)
2. Add your policy type to the gateway_extensions_types.go to include it in the extensible policies union (api/v1alpha1/kgateway/gateway_extensions_types.go)
3. Register the type in the CRD by updating the zz_generated.register.go file (typically auto-generated via controller-gen) (api/v1alpha1/kgateway/zz_generated.register.go)
4. Create validation tests in api/tests/ to validate CEL expressions and field constraints (api/tests/cel_test.go)
5. Document the policy in CONTRIBUTING.md with examples of how users apply it via annotations (CONTRIBUTING.md)

Add a new annotation handler

1. Create a handler function in api/annotations/ that parses and validates the annotation (e.g., api/annotations/custom_feature.go) (api/annotations/custom_feature.go)
2. Register the annotation handler in gateway.go or policy.go depending on scope (api/annotations/gateway.go)
3. Add unit tests to verify annotation parsing and error handling (api/tests/validator.go)
4. Update CONTRIBUTING.md with annotation name, format, and usage examples (CONTRIBUTING.md)

Add a new gateway extension capability

1. Define the extension types in a new file api/v1alpha1/kgateway/my_extension_types.go (api/v1alpha1/kgateway/my_extension_types.go)
2. Update gateway_extensions_types.go to include your extension in the extensible gateway parameters (api/v1alpha1/kgateway/gateway_extensions_types.go)
3. Add RBAC compatibility rules in rbac_compatibility.go if the extension affects permission models (api/v1alpha1/kgateway/rbac_compatibility.go)
4. Create integration tests in .github/workflows/e2e.yaml to validate the extension end-to-end (.github/workflows/e2e.yaml)

Configure a new authentication method

1. Define auth config types in api/v1alpha1/kgateway/ (e.g., custom_auth_types.go) embedding ExtAuthTypes or JwtTypes as appropriate (api/v1alpha1/kgateway/custom_auth_types.go)
2. Add validation logic to api/tests/validator.go to ensure auth configuration is sound (api/tests/validator.go)
3. Document the auth method in CONTRIBUTING.md with security implications and setup steps (CONTRIBUTING.md)
4. Add conformance tests in .github/workflows/conformance.yaml to verify auth flow against Kubernetes Gateway API spec (.github/workflows/conformance.yaml)

• Go + Kubernetes client-go — Cloud-native language with battle-tested Kubernetes integration; enables tight coupling with Kubernetes API for dynamic configuration
• Envoy (via go-control-plane) — Industry-standard L7 proxy with mature xDS protocol; kgateway acts as a control plane generating Envoy configuration dynamically
• gRPC + Protobuf (xDS) — Efficient, strongly-typed control plane communication; enables real-time config updates to Envoy proxies without downtime
• Kubernetes CRDs (CustomResourceDefinitions) — Native Kubernetes extension mechanism; allows users to define gateway behavior via declarative YAML matching Kubernetes conventions
• CEL (Common Expression Language) — Safe, sandboxed expression evaluation for policies; avoids need to reload gateway for policy logic changes
• Controller-runtime — Standard Kubernetes controller framework; simplifies watch/reconcile logic for CRD-to-config transformation

• Policy-as-CRD model vs embedded DSL

  • Why: Follows Kubernetes-native conventions and allows GitOps workflows; users can apply policies via kubectl and version-control them
  • Consequence: Requires schema validation and CRD generation overhead; policy evaluation is declarative rather than imperative, limiting some advanced use cases

• Envoy as underlying proxy vs custom proxy

  • Why: Avoids reinventing production-grade proxy; Envoy is battle-tested at scale with extensive feature coverage
  • Consequence: Dependency on Envoy versioning and upstream changes; adds memory/CPU overhead of running Envoy sidecar or ingress pod

• Annotation-based configuration alongside CRDs

  • Why: Provides convenience shortcuts for users familiar with Ingress annotations; enables gradual migration from Ingress
  • Consequence: Dual configuration models increase cognitive load; potential conflict resolution complexity between annotations and CRD specs

• xDS push model (control plane → data plane)

  • Why: Ensures tight version control and audit trail of proxy configuration; scales to thousands of proxies
  • Consequence: Control plane becomes critical path for config updates; proxy misbehavior harder to debug without local state inspection

• Not a Layer 4 (TCP/UDP) load balancer—focuses on Layer 7 (HTTP/gRPC) routing only
• Not a service mesh control plane—does not manage sidecar injection or mTLS mesh-wide
• Does not replace Kubernetes Ingress for simple use cases—designed for advanced traffic policies and extensibility
• Not platform-agnostic—tightly integrated with Kubernetes API server and assumes running on Kubernetes

Go 1.26.2+ is required (recent version). Kubernetes cluster (Kind/K3d) needed for e2e tests. Envoy binary must be available in PATH for data plane. xDS proto compilation requires protoc and specific versions of go-control-plane (v0.14.0). Environment files at .github/workflows/.env/nightly-tests/ contain version constraints that drift between pr-tests/ and nightly-tests/. GitHub Actions workflows use custom actions (setup-k3d-cluster, kube-conformance-tests) that may need replication locally.

• xDS (Extensible Discovery Service) — kgateway uses go-control-plane to push configuration to Envoy via xDS protocol (CDS, RDS, LDS, EDS) — understanding this gRPC-based push model is essential for debugging routing updates
• Kubernetes Gateway API — The declarative API standard (v1.5.1) that kgateway implements — defines how routes, backends, and policies are expressed as Kubernetes CRDs
• Route Delegation & Policy Attachment — kgateway supports composable gateway policies and route delegation for multi-tenant scenarios — these are non-trivial concepts in the Gateway API spec enabling team-based API management
• Kubernetes Operator Pattern (Reconciliation) — kgateway uses controller-runtime's reconciliation loops to watch Gateway/Route CRDs and continuously sync state — core to understanding how config changes propagate to Envoy
• Protocol Buffers & Code Generation — Envoy and istio.io/api use protobuf (google.golang.org/protobuf v1.36.11) for configuration — generated Go code from .proto files drives routing and filter behavior
• gRPC Middleware & Control Plane Communication — kgateway communicates with Envoy via gRPC (v1.80.0) with middleware for auth/observability (grpc-ecosystem/go-grpc-middleware v1.4.0) — essential for understanding inter-component security
• Envoy Listener & Route Hierarchies — kgateway translates Gateway API HTTPRoute resources into Envoy Listeners and Routes (via xDS) — understanding this mapping is critical for debugging traffic that doesn't flow as expected

• envoyproxy/envoy — The data plane proxy that kgateway controls via xDS — understanding Envoy internals is essential for debugging routing and filter behavior
• kubernetes-sigs/gateway-api — The CRD spec that kgateway implements — canonical source for Gateway, HTTPRoute, and policy attachment standards
• istio/istio — Companion project (istio.io/istio v0.0.0-20260421... in go.mod) providing advanced traffic management and observability that integrates with kgateway
• kubernetes-sigs/controller-runtime — The operator framework (v0.23.3 in go.mod) that powers kgateway's Kubernetes controller — required reading for understanding reconciliation loops

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for GitHub Actions workflows in .github/workflows/

The repo has 13+ GitHub Actions workflows (e2e.yaml, conformance.yaml, nightly-tests.yaml, etc.) but no visible workflow validation or testing infrastructure. New contributors could add a workflow linter/validator action (similar to .github/workflows/lint.yaml but specifically for workflow syntax and job dependencies) to catch issues like missing environment variables, broken action references, or circular dependencies early. This would prevent workflow failures that block the entire CI/CD pipeline.

• [ ] Create .github/workflows/workflow-lint.yaml that validates all YAML in .github/workflows/ directory
• [ ] Add actionlint or similar tool to check workflow syntax and secrets usage
• [ ] Verify environment file references in .github/workflows/.env/ are used correctly in all workflows
• [ ] Add checks for .github/actions/ custom actions (verify action.yaml exists and outputs are documented)
• [ ] Test against existing workflows like e2e.yaml, nightly-tests.yaml to ensure no false positives

Add comprehensive documentation for API annotations in api/annotations/

The repo has api/annotations/delegation.go and api/annotations/gateway.go but no dedicated documentation explaining how these annotations work, when to use them, or examples. New contributors could create api/annotations/README.md documenting each annotation's purpose, supported values, and providing real-world usage examples. This would help downstream users and developers understand the annotation system without reading Go source code.

• [ ] Audit api/annotations/delegation.go and api/annotations/gateway.go to extract all annotation keys and their behaviors
• [ ] Create api/annotations/README.md with structured documentation for each annotation
• [ ] Add YAML examples showing delegation and gateway annotations in use
• [ ] Document any validation rules or constraints for annotation values
• [ ] Link README from main CONTRIBUTING.md and api/README.md

Add unit tests for Go release build process in .goreleaser.yaml

The .goreleaser.yaml file defines the release process but there are likely no tests verifying the build configuration produces correct artifacts, binaries are signed properly, or changelog generation works. New contributors could add tests/release/ directory with tests that validate: goreleaser config syntax, builds succeed locally, artifacts contain expected files, and version strings are injected correctly. This prevents release failures and broken artifacts.

• [ ] Create tests/release_test.go with unit tests for goreleaser configuration validation
• [ ] Add test that runs 'goreleaser check' to validate .goreleaser.yaml syntax
• [ ] Add integration test that performs a local snapshot build and verifies output artifacts
• [ ] Verify binary version flags are correctly injected (reference Makefile for version injection logic)
• [ ] Add test for changelog generation if CHANGELOG.md is version-specific
• [ ] Integrate test into .github/workflows/verify.yaml or create .github/workflows/release-verify.yaml

• Add Prometheus metrics documentation for the metrics exposed by pkg/ (client_golang v1.23.2 is integrated but likely underdocumented). Grep for .NewCounter() and .NewHistogram() calls, document each metric's purpose in docs/metrics.md.
• Expand .github/actions/ shell scripts with logging and error handling — several action.yaml files reference .sh scripts that could fail silently. Add set -e and trap handlers to mq-cancel-dangling-wfs.sh and setup-k3d-cluster.sh.
• Add missing unit tests for policy plugins (if pkg/plugins exists) — Ginkgo/Gomega test framework is set up (v2.28.1) but integration tests in workflows suggest policy logic lacks isolated unit test coverage.

The kgateway repository demonstrates a reasonable security posture with established security policies and vulnerability reporting procedures. However, there are concerns with environment variable management in version control, incomplete dependency declarations in go.mod, and the use of alpha/pre-release dependencies that require careful version management. The project should implement automated dependency vulnerability scanning, verify the integrity of the go.mod file, and establish more robust secrets management practices. The Kubernetes-based architecture and multiple security-related documentation files (SECURITY.md, THREAT_MODEL.md, SECURITY_RESPONSE.md) indicate security is taken seriously, but operational practices around dependency management and configuration need strengthening.

• Medium · Environment Variables in Version Control — .github/workflows/.env/, .github/workflows/.env/nightly-tests/*, .github/workflows/.env/pr-tests/*. The repository contains .env files in .github/workflows/.env directory that are committed to version control. These files may contain sensitive configuration data, even if they appear to be example files. The nightly-tests and pr-tests subdirectories suggest these contain test environment configurations that could expose secrets. Fix: Move all environment configuration to GitHub Secrets or use a secrets management system. If these are template files, rename them with .example extension and add .env to .gitignore. Document the required environment variables separately.
• Medium · Incomplete Dependency Declaration — go.mod (dependencies/package file). The go.mod file shows an incomplete require statement: 'require ( github.com/Puer' appears to be truncated or malformed. This suggests the file may have been corrupted during extraction or the dependencies are not properly defined, which could lead to unpredictable builds and potential security issues with unverified dependencies. Fix: Verify the complete go.mod file is intact. Run 'go mod tidy' and 'go mod verify' to ensure all dependencies are properly declared and checksums are valid. Commit the corrected file.
• Medium · Multiple Indirect Dependencies with Potential Vulnerabilities — go.mod - indirect dependencies and version pinning. The project uses numerous indirect dependencies marked with '// indirect' comments. With go-control-plane, istio, and kubernetes dependencies at specific versions, there's a risk of transitive vulnerabilities that may not be immediately visible. The use of pre-release and commit-specific versions (e.g., v1.30.0-alpha.1, commit hashes) increases the risk of undocumented or unvetted changes. Fix: Implement a regular vulnerability scanning process using tools like 'go list -m all | nancy' or OWASP Dependency-Check. Review alpha/pre-release dependencies and consider using stable versions where possible. Enable GitHub's Dependabot for automated vulnerability scanning.
• Low · Git Hooks in Repository — .githooks/prepare-commit-msg. The repository includes .githooks/prepare-commit-msg which is a custom git hook stored in version control. While this can be beneficial for automation, git hooks can be a vector for supply chain attacks if the repository is compromised, as they execute automatically during git operations. Fix: Review the git hook contents for security. Ensure hooks are minimal, well-documented, and only perform necessary operations. Consider using protected branch rules and code review processes as an additional layer of security control.
• Low · Development Container Configuration — .devcontainer/devcontainer.json. The devcontainer.json file defines development environment specifications. While this aids consistency, it may contain hardcoded tool versions or configurations that could become vulnerable if not regularly updated. Fix: Regularly audit and update the devcontainer configuration. Use base images from trusted registries with known security patches. Document any security-sensitive configurations and review them as part of the security maintenance process.
• Low · Public Vulnerability Reporting Email Exposed — SECURITY.md. While the SECURITY.md file correctly directs vulnerability reports to a private email address (kgateway-vulnerability-reports@googlegroups.com), this email is publicly visible in the repository. This could potentially attract spam or social engineering attempts. Fix: This is acceptable practice for vulnerability disclosure. Monitor the email account for unusual activity and maintain it as a secure, properly authenticated resource. Consider using a bug bounty platform as an additional channel if applicable.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kgateway-dev/kgateway shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kgateway-dev/kgateway repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kgateway-dev/kgateway.

What it runs against: a local clone of kgateway-dev/kgateway — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kgateway-dev/kgateway | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kgateway-dev/kgateway. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kgateway-dev/kgateway.git
#   cd kgateway
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kgateway-dev/kgateway and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kgateway-dev/kgateway(\\.git)?\\b" \\
  && ok "origin remote is kgateway-dev/kgateway" \\
  || miss "origin remote is not kgateway-dev/kgateway (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "api/v1alpha1/kgateway/gateway_parameters_types.go" \\
  && ok "api/v1alpha1/kgateway/gateway_parameters_types.go" \\
  || miss "missing critical file: api/v1alpha1/kgateway/gateway_parameters_types.go"
test -f "api/v1alpha1/kgateway/traffic_policy_types.go" \\
  && ok "api/v1alpha1/kgateway/traffic_policy_types.go" \\
  || miss "missing critical file: api/v1alpha1/kgateway/traffic_policy_types.go"
test -f "api/v1alpha1/kgateway/gateway_extensions_types.go" \\
  && ok "api/v1alpha1/kgateway/gateway_extensions_types.go" \\
  || miss "missing critical file: api/v1alpha1/kgateway/gateway_extensions_types.go"
test -f "api/annotations/gateway.go" \\
  && ok "api/annotations/gateway.go" \\
  || miss "missing critical file: api/annotations/gateway.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kgateway-dev/kgateway"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.