Kubernetes

Deploy agentgateway on Kubernetes using the controller, Helm charts, and Gateway API resources.

Agentgateway includes a Kubernetes controller that integrates with the Gateway API. The controller watches Gateway API resources and dynamically provisions and configures agentgateway data plane instances.

Architecture

The Kubernetes deployment has two layers:

• Controller — a Go-based Kubernetes controller that reconciles Gateway API and agentgateway CRDs, then pushes configuration to data plane instances via xDS.
• Data plane (proxy) — the agentgateway Rust binary, deployed as a managed Deployment per Gateway resource.

Kubernetes API server
        │
        ▼
  agentgateway controller   ←── GatewayClass, Gateway, HTTPRoute,
        │                        AgentgatewayPolicy, AgentgatewayParameters
        │ xDS (gRPC)
        ▼
  agentgateway proxy pods

Installation

Agentgateway is distributed as two Helm charts:

Chart	Description
agentgateway-crds	Installs the Custom Resource Definitions (CRDs)
agentgateway	Installs the controller and related RBAC resources

Check the Kubernetes documentation for the latest install commands and chart versions as the registry may change between releases.

1. Install the Gateway API CRDs

   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml
   
2. Install the Agentgateway CRDs

   helm install agentgateway-crds \
     oci://cr.agentgateway.dev/helm/agentgateway-crds
   
3. Install the controller

   helm install agentgateway \
     oci://cr.agentgateway.dev/helm/agentgateway \
     --namespace agentgateway-system \
     --create-namespace
   
4. Verify the controller is running

   kubectl get pods -n agentgateway-system
   

   You should see the controller pod in Running state.

Gateway API integration

Agentgateway registers a GatewayClass named agentgateway. Create a Gateway referencing this class to provision a data plane instance:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: agentgateway
spec:
  controllerName: agentgateway.dev/controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: agentgateway
  listeners:
  - name: http
    protocol: HTTP
    port: 80

When you create the Gateway resource, the controller provisions a Deployment and Service for the agentgateway proxy in the same namespace.

Custom Resources

Agentgateway defines three CRDs under the agentgateway.dev API group:

AgentgatewayParameters (agpar)

AgentgatewayParameters customizes how the controller provisions the data plane. Attach it to a GatewayClass via parametersRef to apply settings to all gateways using that class, or target individual gateways.

apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayParameters
metadata:
  name: my-params
  namespace: agentgateway-system
spec:
  logging:
    level: debug
    format: json
  image:
    registry: cr.agentgateway.dev
    repository: agentgateway
    tag: "latest"
  rawConfig:
    binds:
    - port: 3000
      listeners:
      - routes:
        - policies:
            cors:
              allowOrigins:
                - "*"
              allowHeaders:
                - mcp-protocol-version
                - content-type
                - cache-control
          backends:
          - mcp:
              targets:
              - name: everything
                stdio:
                  cmd: npx
                  args: ["@modelcontextprotocol/server-everything"]

Key spec fields:

Field	Description
logging.level	Log level in RUST_LOG syntax
logging.format	json or text
image	Override the data plane container image
rawConfig	Opaque agentgateway config merged with typed fields
env	Additional environment variables for the proxy container
resources	CPU/memory resource requests and limits
shutdown.min / shutdown.max	Graceful shutdown delay range in seconds

AgentgatewayPolicy (agpol)

AgentgatewayPolicy attaches traffic, frontend, or backend policies to Gateway API resources.

apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: rate-limit-policy
  namespace: default
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: my-route
  traffic:
    rateLimit:
      ...

Policies support three sections:

Section	Targets	Purpose
frontend	Gateway	Incoming TLS, HTTP settings, access logging, tracing
traffic	Gateway, ListenerSet, HTTPRoute, GRPCRoute	Rate limiting, CORS, auth, retries, timeouts
backend	Any of the above, plus Service / AgentgatewayBackend	TLS to upstream, connection settings, mTLS

Policies merge at each level with more specific policies taking precedence: Gateway < Listener < Route < Route Rule < Backend.

AgentgatewayBackend

AgentgatewayBackend defines a static backend (e.g. an MCP server reachable via HTTP) that can be referenced from HTTPRoute rules.

Use this when your MCP or AI backend is not a Kubernetes Service — for example, an external API or a stdio-based process.

Helm chart configuration

The agentgateway chart exposes values for tuning the controller and proxy:

# values.yaml
controller:
  replicaCount: 1
  logLevel: info
  image:
    registry: ""
    repository: controller
    tag: ""
  service:
    ports:
      agwGrpc: 9978    # xDS gRPC port
      health: 9093     # Readiness probe
      metrics: 9092    # Prometheus metrics
  xds:
    tls:
      enabled: false   # Enable TLS for xDS communication

proxy:
  image:
    repository: agentgateway

image:
  registry: cr.agentgateway.dev
  pullPolicy: IfNotPresent

# Namespace selector for config discovery
discoveryNamespaceSelectors: []

# Inference Extension support
inferenceExtension:
  enabled: false

Enabling xDS TLS

To encrypt communication between the controller and proxy on the xDS gRPC channel:

controller:
  xds:
    tls:
      enabled: true

When TLS is enabled, create a Secret named agentgateway-xds-cert in the installation namespace:

kubectl create secret tls agentgateway-xds-cert \
  --cert=tls.crt \
  --key=tls.key \
  --namespace agentgateway-system

The Secret must include tls.crt, tls.key, and ca.crt data fields.

Namespace isolation and multi-tenancy

By default, the controller discovers Gateway API resources across all namespaces. Use discoveryNamespaceSelectors to restrict discovery to specific namespaces:

discoveryNamespaceSelectors:
  - matchLabels:
      agentgateway.dev/managed: "true"

This restricts the controller to only reconcile resources in namespaces labelled agentgateway.dev/managed: "true", enabling multi-tenant deployments where different teams control their own namespaces.

Istio integration

Agentgateway can connect natively to Istio-enabled pods using mTLS. Enable Istio integration in AgentgatewayParameters:

spec:
  istio:
    caAddress: https://istiod.istio-system.svc:15012
    trustDomain: cluster.local

When configured, agentgateway joins the Istio mesh and establishes mTLS connections to workloads without requiring sidecar injection on the gateway pod itself.

GatewayClass parameters

To attach AgentgatewayParameters to a GatewayClass, configure gatewayClassParametersRefs in the Helm values:

gatewayClassParametersRefs:
  agentgateway:
    name: shared-gwp
    namespace: agentgateway-system

This sets the default AgentgatewayParameters for all Gateway resources using the agentgateway GatewayClass.

Scaling and resilience

Horizontal Pod Autoscaler

Configure HPA on the controller via controller.horizontalPodAutoscaler. The controller manages the HPA scaleTargetRef automatically.

Pod Disruption Budget

Configure PDB on the controller via controller.podDisruptionBudget to ensure availability during voluntary disruptions.

Resource limits

Set CPU and memory requests and limits via resources in the Helm values or AgentgatewayParameters.spec.resources.

Graceful shutdown

Configure AgentgatewayParameters.spec.shutdown.min and .max to control the drain window for rolling updates.