Architecture

Learn more about the components that make up the kgateway control plane. 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 plane Control Plane Components that manage and distribute configuration and policies to the data plane. and data plane Data Plane Proxies (Envoy or agentgateway) that process live network traffic per configuration from the control plane. . These components work together to translate gateway custom resources into gateway proxy Proxy Envoy- or agentgateway-based data plane process that terminates and forwards traffic. 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.

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 Translation Conversion of Gateway API and CRDs into xDS config for the data plane. 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 gateway proxy.

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.

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