Kubernetes

Deploy Agentgateway on Kubernetes using Helm and the Gateway API.

The Kubernetes deployment of Agentgateway consists of two components:

• Controller — a Go-based control plane that watches Kubernetes resources and translates them into xDS configuration for the data plane.
• Proxy (data plane) — the Rust-based agentgateway binary, deployed per-Gateway resource by the controller.

The controller integrates with the Kubernetes Gateway API and extends it with Agentgateway-specific custom resources.

Prerequisites

• A running Kubernetes cluster (v1.24+)
• kubectl configured to talk to the cluster
• Helm v3.x
• Gateway API CRDs installed on the cluster

Installation

1. Install the Gateway API CRDs

   Agentgateway requires the standard Kubernetes Gateway API CRDs. Install them before deploying the controller.

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

   The Agentgateway CRDs are packaged in a separate Helm chart so they can be upgraded independently of the controller.

   helm install agentgateway-crds oci://cr.agentgateway.dev/agentgateway/agentgateway-crds \
     --namespace agentgateway-system \
     --create-namespace
   

   This installs three CRDs in the agentgateway.dev API group:

   CRD	Short name	Description
   AgentgatewayParameters	agpar	Data-plane deployment configuration per Gateway
   AgentgatewayBackends	—	Backend pool definitions
   AgentgatewayPolicies	—	Policy attachments (auth, rate-limiting, etc.)

3. Install the Agentgateway controller

   helm install agentgateway oci://cr.agentgateway.dev/agentgateway/agentgateway \
     --namespace agentgateway-system \
     --create-namespace
   

   The chart deploys the controller Deployment, Service, ServiceAccount, and Role resources into the target namespace.

4. Verify the installation

   kubectl get pods -n agentgateway-system
   

   Wait until the controller pod shows Running and passes its readiness probe.

Helm values

The chart ships with a comprehensive values.yaml. The most commonly customized sections are shown below.

Image configuration

values.yaml

image:
  registry: cr.agentgateway.dev
  tag: ""           # defaults to the chart appVersion
  pullPolicy: IfNotPresent

controller:
  replicaCount: 1
  logLevel: info    # debug | info | warn | error
  image:
    registry: ""    # inherits from image.registry
    repository: controller
    tag: ""

proxy:
  image:
    registry: ""    # inherits from image.registry
    repository: agentgateway
    tag: ""

Resource limits and autoscaling

Set resource requests and limits on the controller pod:

values.yaml

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Enable the Horizontal Pod Autoscaler for the controller:

values.yaml

controller:
  horizontalPodAutoscaler:
    minReplicas: 1
    maxReplicas: 5
    metrics:
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 80

Enable the Vertical Pod Autoscaler:

values.yaml

controller:
  verticalPodAutoscaler:
    updatePolicy:
      updateMode: Auto
    resourcePolicy:
      containerPolicies:
        - containerName: "*"
          minAllowed:
            cpu: 100m
            memory: 128Mi

Pod disruption budget

values.yaml

controller:
  podDisruptionBudget:
    minAvailable: 1

Creating a Gateway

Once the controller is running, create a Gateway resource that references the agentgateway GatewayClass:

gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: agentgateway
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

Apply it:

kubectl apply -f gateway.yaml

The controller detects the new Gateway and provisions a proxy Deployment and Service for it automatically.

Customizing the data plane with AgentgatewayParameters

AgentgatewayParameters lets you customize the proxy Deployment that the controller generates for each Gateway. Reference it from a Gateway using the infrastructure.parametersRef field:

parameters.yaml

apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayParameters
metadata:
  name: my-gwparams
spec:
  image:
    registry: cr.agentgateway.dev
    repository: agentgateway
    tag: latest
  deployment:
    spec:
      template:
        spec:
          containers:
            - name: agentgateway
              resources:
                requests:
                  cpu: 250m
                  memory: 256Mi
                limits:
                  cpu: 1000m
                  memory: 1Gi
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: agentgateway
  infrastructure:
    parametersRef:
      group: agentgateway.dev
      kind: AgentgatewayParameters
      name: my-gwparams
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

Namespace isolation and discovery

By default the controller discovers Gateway resources across all namespaces. To restrict discovery to specific namespaces, set discoveryNamespaceSelectors in your Helm values:

values.yaml

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

Then label the namespaces you want included:

kubectl label namespace my-namespace agentgateway.dev/discovery=true

Health checks

The controller deployment includes readiness and startup probes configured in the Helm chart:

readinessProbe:
  httpGet:
    path: /readyz
    port: 9093
  initialDelaySeconds: 1
  periodSeconds: 10
startupProbe:
  httpGet:
    path: /readyz
    port: 9093
  initialDelaySeconds: 0
  periodSeconds: 1
  failureThreshold: 120

The controller exposes three ports:

Port	Name	Description
9978	grpc-xds-agw	xDS gRPC server (controller → proxy)
9093	health	Readiness probe endpoint (/readyz)
9092	metrics	Prometheus metrics (/metrics)

The proxy pods provisioned per-Gateway expose port 8080 (or whatever port is declared in the Gateway listeners) and the standard agentgateway admin ports (15000, 15020, 15021).

TLS for xDS communication

To encrypt traffic between the controller and the proxy over gRPC, enable xDS TLS and create the required secret:

# Create the TLS secret in the agentgateway installation namespace
kubectl create secret tls agentgateway-xds-cert \
  --cert=tls.crt \
  --key=tls.key \
  -n agentgateway-system

values.yaml

controller:
  xds:
    tls:
      enabled: true

The secret must contain tls.crt, tls.key, and ca.crt fields and must be named agentgateway-xds-cert in the installation namespace.

Private image registries

To pull images from a private registry, add image pull secrets to your Helm values:

values.yaml

imagePullSecrets:
  - name: my-registry-credentials

Development with Tilt

For iterative development on a local Kind cluster, the repository includes a Tiltfile that builds both the controller and data plane with live-update support:

# Create a Kind cluster with a local registry
ctlptl create cluster kind --name kind-kind --registry=ctlptl-registry

# Start Tilt
tilt up

Tilt compiles the Go controller and Rust proxy incrementally, syncs binaries into running containers without full rebuilds, and deploys everything via Helm.

See the Tiltfile in the repository root for the full configuration, including how AgentgatewayParameters overrides are used to allow live-update file writes inside the proxy container.