DOCSEARCHbyAlgolia
Submit Docs

kgateway Documentation

repository·main·Indexed 26 days ago

https://github.com/kgateway-dev/kgateway

A Kubernetes-native API Gateway control plane that implements the Kubernetes Gateway API for the Envoy proxy. It manages API connectivity, security policies, and traffic routing for microservices, serverless, and legacy applications. The project includes tools for API development, a mock OAuth2 Identity Provider (dummy-idp), an applier utility for YAML templates, and Envoy dynamic module filters such as http-acl and Rustformation.

Tokens
60K
Snippets
137
Records
264
Agent score
91%

What's inside kgateway

  2. Overview of kgateway

    main

    kgateway is a resilient, performance-oriented control plane for Kubernetes that implements the Kubernetes Gateway API for Envoy. It is designed to scale from lightweight microgateway deployments between services to large-scale centralized gateways.

    Key Use Cases:

    • Next-Gen API Gateway: Expose APIs and apply policies such as authentication, authorization, and rate limiting using Envoy and the Gateway API.
    • Hybrid Application Migration: Route traffic to backends including microservices, serverless functions, or legacy applications to facilitate gradual migration.
    • Complex Tenancy Environments: Support multiple teams and personas through route delegation and composable policies.

    Note on agentgateway: As of version 2.3.0, the control plane for agentgateway has been migrated to the agentgateway repository. kgateway now focuses exclusively on being a stable API Gateway powered by Envoy.

  3. Overview of Route Delegation in kgateway

    main
    Route delegation allows HTTPRoute resources to delegate routing configuration to other HTTPRoute resources. This feature is designed to improve maintainability by splitting large routing configurations into smaller, manageable objects, allowing different teams to manage their own routing decisions and policies independently without impacting others. It also enables the reuse of routing configurations across multiple locations.

  4. Overview of Fault Injection Support

    main
    kgateway supports fault injection via the TrafficPolicy CRD to enable chaos engineering and resiliency testing. This feature allows users to simulate failure conditions such as latency (delay injection), aborts (HTTP/gRPC errors), and response rate limiting. It is designed to help validate retry policies, timeout configurations, and fallback behaviors at the gateway layer without modifying application code.

  5. Overview of Rustformation Envoy Module

    main

    Rustformation is an Envoy dynamic module filter that performs request and response transformations using MiniJinja templates. It implements the TransformationPolicy CRD spec and is attached to routes as a per-route configuration.

    Capabilities:

    • Headers: Set, add, or remove request and response headers.
    • Bodies: Rewrite request or response bodies using templates.
    • Metadata: Create Envoy dynamic metadata for consumption by downstream filters or access logs.

    Buffering Behavior:

    • The filter buffers the full body before applying transformations unless parseAs: None is specified.
    • WebSocket upgrade requests and HTTP CONNECT tunnels are never buffered; only header transformations are applied to these requests.

  6. Understand Orphaned Resource Status Reporting

    main

    kgateway implements a status clearing mechanism to ensure that when a resource (like an HTTPRoute or TrafficPolicy) loses its valid references (e.g., a parentRef is changed to a non-existent Gateway), its stale status conditions are cleared.

    Instead of simply ignoring resources with invalid references during the translation phase, kgateway now uses a status collection pattern during the Intermediate Representation (IR) construction phase. This marks resources as "dirty" with an empty status entry. If the translation phase does not find valid references for that resource, the empty status is merged into the final report, effectively clearing the stale parents list in the Kubernetes CRD status.

  7. Understand Orphaned Resource Status Reporting in kgateway

    main

    kgateway implements status reporting for 'orphaned' resources to prevent stale configuration data from misleading users. An orphaned resource is a Custom Resource (CRD) such as an HTTPRoute or TrafficPolicy that contains invalid or non-existent parentRefs or targetRefs.

    Previously, these resources were not picked up during the translation phase, causing their status to remain stuck on the last valid configuration. The current implementation ensures that when a resource becomes orphaned, its stale status is cleared, aligning with Kubernetes best practices and improving troubleshooting visibility.

  8. Understand the current kgateway E2E testing framework

    main

    The existing end-to-end (E2E) testing framework is a custom implementation located in test/e2e/. It is designed specifically for kgateway's lifecycle and uses three core abstractions:

    • TestInstallation: Bundles the runtime context, cluster context, install context, an Actions provider (wrappers for Helm, kubectl, curl), an Assertions provider (Gomega-based helpers), and a per-test failure dump directory.
    • BaseTestingSuite: A suite that embeds testify/suite.Suite and manages the test lifecycle (Setup, Before/After Test, Teardown) including manifest application, image pre-pulling, and Gateway API version gating.
    • SuiteRunner: Registers and executes testify suites against a single TestInstallation.

    Tests are organized as features/<area>/suite.go and registered in tests/<entrypoint>_tests.go. Each test method on a suite struct is treated as a Go subtest.

  9. Understand Orphaned Resource Status Reporting behavior

    main

    kgateway implements a mechanism to handle 'orphaned' resources—Kubernetes resources that previously had a status reported by kgateway but are no longer present in the current translation phase (e.g., due to a change in parentRef or deletion).

    To prevent stale status information from persisting in Kubernetes, the controller identifies resources that have an existing status but are missing from the current ReportMap. For these orphaned resources, the controller adds an empty status entry to the ReportMap, which triggers the status syncer to clear the stale status in Kubernetes.

  10. Understand the xDS Translation Lifecycle

    main

    kgateway translates Kubernetes objects (Gateways, HTTPRoutes, Services, etc.) into Envoy configuration through a multi-phase process:

    1. Policy -> IR Translation: Plugins translate CRDs into ir.PolicyWrapper objects. This happens early so errors can be reported on the CRD status immediately.
    2. Policy Attachment: kgateway uses TargetRefs to attach these policy IRs to the AttachedPolicies struct within the Gateway and HTTPRoute IRs.
    3. xDS Translation Phase 1 (Aggregation): kgateway aggregates all HTTPRoutes for a single Gateway into one Gateway IR object. This phase resolves delegation and merges routes based on the Gateway API spec using KRT to track dependencies.
    4. xDS Translation Phase 2 (Envoy Config Generation): The Gateway IR is translated into Envoy protobufs. During this phase, kgateway invokes the NewGatewayTranslationPass provided by your plugins. The plugin's ProxyTranslationPass is called with the AttachedPolicies to modify Envoy routes or listeners (e.g., adding HTTP filters).

  11. Understand kgateway security architecture and components

    main

    kgateway is an Envoy-powered, Kubernetes-native API Gateway. Its security and traffic handling are distributed across several specialized components:

    • kgateway-proxy: A wrapper around the Envoy proxy that handles downstream traffic, executes encoding/decoding filters, and manages routing logic. It runs in its own Pod.
    • kgateway: The controller that processes Kubernetes Gateway API resources and kgateway CRDs to produce xDS snapshots for the proxy. It runs in its own Pod.
    • sds (Secret Discovery Service): A sidecar to kgateway-proxy that implements the SDS protocol, allowing certificates to be distributed to the proxy dynamically without mounting them directly into the container.
    • kgateway-ai-extension: A sidecar to kgateway-proxy that enables routing traffic to LLMs.
    • kgwctl: A standalone CLI binary used to inspect the runtime state of a kgateway installation.

  12. Understand TLS configuration conflicts and ordering

    main

    In kgateway, TLS configuration is applied via different plugins that target different Envoy fields. Because plugin application uses Go map iteration, the order is non-deterministic.

    Field Mapping

    • BackendTLSPolicy and BackendConfigPolicy: Set TransportSocket on the cluster.
    • Istio plugin: Sets TransportSocketMatches on the cluster.

    Conflict Scenarios

    1. Istio Auto-mTLS Enabled (Default): Istio sets TransportSocketMatches. If you also use BackendTLSPolicy or BackendConfigPolicy, they set TransportSocket. These are different fields, so they do not overwrite each other, but they can cause functional conflicts in how traffic is handled.
    2. Istio Auto-mTLS Disabled: By using the kgateway.dev/disable-istio-auto-mtls: "true" annotation, Istio does not set TransportSocketMatches. This allows BackendConfigPolicy and BackendTLSPolicy to configure TransportSocket without conflict.
    3. Multiple Backend Plugins: If both BackendConfigPolicy and BackendTLSPolicy are used, they both target TransportSocket. Since the order is random, the 'winner' is unpredictable, though BackendConfigPolicy is designed to overwrite existing TransportSocket configurations.