Documentation
About
Architecture

Architecture

Learn more about the components that make up kgateway. These components work together to provide traffic management, security, and resiliency for your apps.

Component architecture

The following image shows the different components that make up the kgateway control and data plane. These components work together to translate gateway custom resources into gateway proxy configuration. The gateway proxy configuration controls the behavior of the gateway proxies that serve your apps. Kgateway supports the Envoy-based kgateway proxy and the agentgateway proxy.

Component architecture
Component architecture

  1. The config and secret watcher components in the kgateway pod watch the cluster for new Kubernetes Gateway API and kgateway resources, such as Gateways, HTTPRoutes, or TrafficPolicies.
  2. When the config or secret watcher detect new or updated resources, it sends the resource configuration to the kgateway translation engine.
  3. The translation engine translates Kubernetes Gateway API and kgateway resources into gateway proxy configuration. All gateway proxy configuration is consolidated into an xDS snapshot.
  4. The reporter receives a status report for every resource that is processed by the translator.
  5. The reporter writes the resource status back to the etcd data store.
  6. The xDS snapshot is provided to the kgateway xDS server component in the kgateway pod.
  7. Gateway proxies in the cluster pull the latest gateway proxy configuration from the kgateway xDS server.
  8. Clients send a request to the IP address or hostname that the gateway proxy is exposed on.
  9. The gateway proxy uses the listener and route-specific configuration that was provided in the xDS snapshot to perform routing decisions and forward requests to destinations in the cluster.

Config watcher

The config watcher component is part of the kgateway control plane and watches the cluster for new or updated Kubernetes Gateway API and kgateway resources, such as Gateways, HTTPRoutes, and Backends. When the config watcher detects new or updated resources, it sends the Kubernetes configuration to the kgateway translation engine.

Secret watcher

The secret watcher component is part of the kgateway control plane and watches a secret store for updates to secrets. For example, you might use a Kubernetes Secret to store the AWS access key and secret key credentials for a Backend to access an AWS Lambda. However, you can configure kgateway to also watch other secret stores.

Translation engine

The kgateway translator receives snapshots of all the Kubernetes Gateway API, Kubernetes API, and kgateway resources that you create or update. The translator starts a new translation loop for each update to translate these resources into valid gateway proxy configuration. The gateway proxy configuration is stored in an xDS snapshot.

The following image shows the different stages of a translation cycle for the different gateway proxies.

Kgateway translation cycle
Kgateway translation cycle

  1. The translation cycle starts by defining Envoy clusters from all configured Backend and Kubernetes service resources. Clusters in this context are groups of similar hosts. Each Backend has a type that determines how the Backend is processed. Correctly configured Backends and Kubernetes services are converted into Envoy clusters that match their type, including information like cluster metadata.

  2. The next step in the translation cycle is to process all the functions on each Backend. Function-specific cluster metadata is added and is later processed by function-specific Envoy filters.

  3. In the next step, all Envoy routes are generated. Routes are generated for each route rule that is defined on the HTTPRoute and TrafficPolicy resources. When all of the routes are created, the translator processes and aggregates HTTPListenerPolicy resources into Envoy virtual hosts, and adds them to a new Envoy HTTP Connection Manager configuration.

  4. Filter plug-ins are queried for their filter configurations, generating the list of HTTP and TCP Filters that are added to the Envoy listeners.

  5. Finally, an xDS snapshot is composed of the all the valid endpoints (EDS), clusters (CDS), route configs (RDS), and listeners (LDS). The snapshot is sent to the kgateway xDS server. Gateway proxies in your cluster watch the xDS server for new config. When new config is detected, the config is pulled into the gateway proxy.

Agentgateway translation cycle
Agentgateway translation cycle

  1. When the agentgateway feature is enabled for kgateway, the agentgateway syncer component is created as part of the control plane.

  2. The agentgateway syncer sets up the initial configuration, including the agentgateway GatewayClass name that Gateways can use to automatically create agentgateway proxies. The agentgateway syncer also builds the initial krt collections based on the Gateway API and kgateway resources in the cluster.

  3. The translation cycle starts by collecting all of the resources that are needed to create agentgateway proxy config. These various collections include:

    • Core collections of the Kubernetes, Gateway API, and kgateway resources that are defined in the cluster, such as namespaces, services, gateways, routes, policies, backends, and plugins for AI, MCP, and A2A-specific backends.
    • Agentgateway data plane resource building that consist of information translated from the core collection into the format that agentgateway expects, such as bind, port, listener, route, backend, target, and policy configuration for agentgateway. For more information, see the agentgateway about topic.
    • Address collections of the service and workloads that are included in service discovery and endpoint resolution.
    • The translation order ensures that dependencies are resolved correctly: binds → listeners → routes → policies, with backends and addresses processed separately and added to the final configuration.

  4. The next step in the translation process is to build the xDS collection. This step merges all of the resource config of agentgateway data plane resources together with the address collections to create the config for each agentgateway proxy. It also builds status reports for the resources, tracks attached routes, and determines attached policies.

  5. Finally, the information from the resource and xDS collections are turned into an xDS snapshot of the agentgateway proxy config. The snapshot is sent to the xDS server. The agentgateway proxies in your cluster watch the xDS server for new config. When new config is detected, the config is pulled into the agentgateway proxy via gRPC.

Reporter

The reporter component receives a validation report for every kgateway resource that was processed by the translator. Any invalid configuration is reported back to the user through the Kubernetes storage layer. Invalid resources are marked as rejected and an error message is captured in the resource configuration.

xDS server

The xDS server sends the xDS snapshot to the gateway proxies in the data plane.

  • Envoy-based kgateway proxy: Updates the Envoy cluster with a new configuration of Envoy EDS, CDS, RDS, and LDS resources to match the desired state.

  • Agentgateway proxy: Updates the agentgateway proxy with agentgateway-specific configuration, including MCP and A2A protocol support, to match the desired state.

OverviewDeployment patterns