# envoyproxy/gateway architecture

> Architecture diagram of the GitHub repository envoyproxy/gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/envoyproxy/gateway
- Repository: https://github.com/envoyproxy/gateway

## Overview

Envoy Gateway manages standalone or Kubernetes-based Envoy Proxy deployments. The principal workflow is: an operator submits Gateway API resources; a provider watches and assembles them; the Gateway API translator produces intermediate representations; xDS translation and infrastructure runners configure and provision Envoy; status is reported back. Configuration loading, extension hooks, global rate limiting, administration, and shutdown are supporting capabilities. The sampled excerpts directly establish runner orchestration and provider-to-translator channels; some downstream connections are inferred only where package responsibilities and comments explicitly support them.

Main entry points: [`internal/cmd/server.go`](https://github.com/envoyproxy/gateway/blob/main/internal/cmd/server.go) (Gateway Server), [`internal/provider/kubernetes/controller.go`](https://github.com/envoyproxy/gateway/blob/main/internal/provider/kubernetes/controller.go) (Kubernetes Provider), [`internal/gatewayapi/translator.go`](https://github.com/envoyproxy/gateway/blob/main/internal/gatewayapi/translator.go) (Gateway Translator), [`internal/ir/xds.go`](https://github.com/envoyproxy/gateway/blob/main/internal/ir/xds.go) (xDS IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime Orchestration"]
  node_gateway_server["Gateway Server<br/>[server.go]"]
  node_config_loader["Config Loader<br/>[configloader.go]"]
end

subgraph group_inputs["Resource Ingestion"]
  node_k8s_provider["Kubernetes Provider<br/>[controller.go]"]
end

subgraph group_translation["Translation Pipeline"]
  node_gateway_translator["Gateway Translator<br/>[translator.go]"]
  node_infra_ir["Infrastructure IR<br/>[infra.go]"]
  node_xds_ir["xDS IR<br/>[xds.go]"]
  node_xds_runner["xDS Runner<br/>[runner.go]"]
  node_xds_translator["xDS Translator<br/>[translator.go]"]
  node_xds_cache[("xDS Snapshot Cache<br/>[snapshotcache.go]")]
end

subgraph group_infrastructure["Infrastructure Management"]
  node_infra_manager["Infrastructure Manager<br/>[manager.go]"]
  node_k8s_infra["Kubernetes Infrastructure<br/>[infra.go]"]
end

subgraph group_operations["Operations and Extensions"]
  node_extension_manager["Extension Manager"]
  node_global_ratelimit["Global Rate Limit<br/>[runner.go]"]
  node_admin_server["Admin Server<br/>[server.go]"]
  node_admin_console["Admin Console<br/>[api.go]"]
  node_status_updates["Status Updates<br/>[status_updater.go]"]
end

node_operator(("Platform Operator"))
node_kubernetes_api[("Kubernetes API")]
node_envoy_proxy["Envoy Proxy"]
node_extension_service["Extension Service"]

node_operator -->|"applies resources"| node_kubernetes_api
node_kubernetes_api -->|"watches resources"| node_k8s_provider
node_gateway_server -->|"loads config"| node_config_loader
node_gateway_server -->|"starts runner"| node_k8s_provider
node_gateway_server -->|"starts runner"| node_gateway_translator
node_gateway_server -->|"starts runner"| node_infra_manager
node_gateway_server -->|"creates manager"| node_extension_manager
node_k8s_provider -->|"publishes resources"| node_gateway_translator
node_k8s_provider -->|"writes status"| node_status_updates
node_status_updates -->|"updates status"| node_kubernetes_api
node_gateway_translator -->|"publishes IR"| node_xds_ir
node_gateway_translator -->|"publishes IR"| node_infra_ir
node_xds_ir -->|"consumes IR"| node_xds_runner
node_xds_runner -->|"translates resources"| node_xds_translator
node_xds_translator -.->|"invokes hooks"| node_extension_manager
node_extension_manager -.->|"calls hooks"| node_extension_service
node_xds_runner -->|"updates snapshots"| node_xds_cache
node_xds_cache -->|"serves xDS"| node_envoy_proxy
node_infra_ir -->|"consumes IR"| node_infra_manager
node_infra_manager -.->|"selects provider"| node_k8s_infra
node_k8s_infra -->|"provisions proxy"| node_envoy_proxy
node_xds_ir -.->|"consumes resources"| node_global_ratelimit
node_gateway_server -->|"starts runner"| node_admin_server
node_admin_server -->|"registers handlers"| node_admin_console
node_admin_console -->|"reads resources"| node_k8s_provider

click node_gateway_server "https://github.com/envoyproxy/gateway/blob/main/internal/cmd/server.go"
click node_config_loader "https://github.com/envoyproxy/gateway/blob/main/internal/envoygateway/config/loader/configloader.go"
click node_k8s_provider "https://github.com/envoyproxy/gateway/blob/main/internal/provider/kubernetes/controller.go"
click node_gateway_translator "https://github.com/envoyproxy/gateway/blob/main/internal/gatewayapi/translator.go"
click node_infra_ir "https://github.com/envoyproxy/gateway/blob/main/internal/ir/infra.go"
click node_xds_ir "https://github.com/envoyproxy/gateway/blob/main/internal/ir/xds.go"
click node_xds_runner "https://github.com/envoyproxy/gateway/blob/main/internal/xds/runner/runner.go"
click node_xds_translator "https://github.com/envoyproxy/gateway/blob/main/internal/xds/translator/translator.go"
click node_xds_cache "https://github.com/envoyproxy/gateway/blob/main/internal/xds/cache/snapshotcache.go"
click node_infra_manager "https://github.com/envoyproxy/gateway/blob/main/internal/infrastructure/manager.go"
click node_k8s_infra "https://github.com/envoyproxy/gateway/blob/main/internal/infrastructure/kubernetes/infra.go"
click node_extension_manager "https://github.com/envoyproxy/gateway/blob/main/internal/extension/registry/extension_manager.go"
click node_global_ratelimit "https://github.com/envoyproxy/gateway/blob/main/internal/globalratelimit/runner/runner.go"
click node_admin_server "https://github.com/envoyproxy/gateway/blob/main/internal/admin/server.go"
click node_admin_console "https://github.com/envoyproxy/gateway/blob/main/internal/admin/console/api.go"
click node_status_updates "https://github.com/envoyproxy/gateway/blob/main/internal/provider/kubernetes/status_updater.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway_server,node_config_loader toneBlue
class node_k8s_provider,node_kubernetes_api toneAmber
class node_gateway_translator,node_infra_ir,node_xds_ir,node_xds_runner,node_xds_translator,node_xds_cache toneMint
class node_infra_manager,node_k8s_infra toneRose
class node_extension_manager,node_global_ratelimit,node_admin_server,node_admin_console,node_status_updates,node_operator,node_envoy_proxy,node_extension_service toneIndigo
```

## Components

### Runtime Orchestration

- [Gateway Server](https://github.com/envoyproxy/gateway/blob/main/internal/cmd/server.go): `internal/cmd/server.go`
- [Config Loader](https://github.com/envoyproxy/gateway/blob/main/internal/envoygateway/config/loader/configloader.go): `internal/envoygateway/config/loader/configloader.go`

### Resource Ingestion

- [Kubernetes Provider](https://github.com/envoyproxy/gateway/blob/main/internal/provider/kubernetes/controller.go): `internal/provider/kubernetes/controller.go`

### Translation Pipeline

- [Gateway Translator](https://github.com/envoyproxy/gateway/blob/main/internal/gatewayapi/translator.go): `internal/gatewayapi/translator.go`
- [Infrastructure IR](https://github.com/envoyproxy/gateway/blob/main/internal/ir/infra.go): `internal/ir/infra.go`
- [xDS IR](https://github.com/envoyproxy/gateway/blob/main/internal/ir/xds.go): `internal/ir/xds.go`
- [xDS Runner](https://github.com/envoyproxy/gateway/blob/main/internal/xds/runner/runner.go): `internal/xds/runner/runner.go`
- [xDS Translator](https://github.com/envoyproxy/gateway/blob/main/internal/xds/translator/translator.go): `internal/xds/translator/translator.go`
- [xDS Snapshot Cache](https://github.com/envoyproxy/gateway/blob/main/internal/xds/cache/snapshotcache.go): `internal/xds/cache/snapshotcache.go`

### Infrastructure Management

- [Infrastructure Manager](https://github.com/envoyproxy/gateway/blob/main/internal/infrastructure/manager.go): `internal/infrastructure/manager.go`
- [Kubernetes Infrastructure](https://github.com/envoyproxy/gateway/blob/main/internal/infrastructure/kubernetes/infra.go): `internal/infrastructure/kubernetes/infra.go`

### Operations and Extensions

- [Extension Manager](https://github.com/envoyproxy/gateway/blob/main/internal/extension/registry/extension_manager.go): `internal/extension/registry/extension_manager.go`
- [Global Rate Limit](https://github.com/envoyproxy/gateway/blob/main/internal/globalratelimit/runner/runner.go): `internal/globalratelimit/runner/runner.go`
- [Admin Server](https://github.com/envoyproxy/gateway/blob/main/internal/admin/server.go): `internal/admin/server.go`
- [Admin Console](https://github.com/envoyproxy/gateway/blob/main/internal/admin/console/api.go): `internal/admin/console/api.go`
- [Status Updates](https://github.com/envoyproxy/gateway/blob/main/internal/provider/kubernetes/status_updater.go): `internal/provider/kubernetes/status_updater.go`

### Other components

- **Platform Operator**
- **Kubernetes API**
- **Envoy Proxy**
- **Extension Service**

## Connections

- Platform Operator → Kubernetes API: applies resources
- Kubernetes API → Kubernetes Provider: watches resources
- Gateway Server → Config Loader: loads config
- Gateway Server → Kubernetes Provider: starts runner
- Gateway Server → Gateway Translator: starts runner
- Gateway Server → Infrastructure Manager: starts runner
- Gateway Server → Extension Manager: creates manager
- Kubernetes Provider → Gateway Translator: publishes resources
- Kubernetes Provider → Status Updates: writes status
- Status Updates → Kubernetes API: updates status
- Gateway Translator → xDS IR: publishes IR
- Gateway Translator → Infrastructure IR: publishes IR
- xDS IR → xDS Runner: consumes IR
- xDS Runner → xDS Translator: translates resources
- xDS Translator → Extension Manager: invokes hooks
- Extension Manager → Extension Service: calls hooks
- xDS Runner → xDS Snapshot Cache: updates snapshots
- xDS Snapshot Cache → Envoy Proxy: serves xDS
- Infrastructure IR → Infrastructure Manager: consumes IR
- Infrastructure Manager → Kubernetes Infrastructure: selects provider
- Kubernetes Infrastructure → Envoy Proxy: provisions proxy
- xDS IR → Global Rate Limit: consumes resources
- Gateway Server → Admin Server: starts runner
- Admin Server → Admin Console: registers handlers
- Admin Console → Kubernetes Provider: reads resources
