> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://gateway-api.sigs.k8s.io/) and extends it with Agentgateway-specific custom resources.

## Prerequisites

* A running Kubernetes cluster (v1.24+)
* `kubectl` configured to talk to the cluster
* [Helm](https://helm.sh) v3.x
* Gateway API CRDs installed on the cluster

## Installation

<Steps>
  <Step title="Install the Gateway API CRDs">
    Agentgateway requires the standard Kubernetes Gateway API CRDs. Install them before deploying the controller.

    ```bash theme={null}
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/standard-install.yaml
    ```
  </Step>

  <Step title="Install the Agentgateway CRDs">
    The Agentgateway CRDs are packaged in a separate Helm chart so they can be upgraded independently of the controller.

    ```bash theme={null}
    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.)    |
  </Step>

  <Step title="Install the Agentgateway controller">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    kubectl get pods -n agentgateway-system
    ```

    Wait until the controller pod shows `Running` and passes its readiness probe.
  </Step>
</Steps>

## Helm values

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

### Image configuration

```yaml values.yaml theme={null}
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:

```yaml values.yaml theme={null}
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi
```

Enable the Horizontal Pod Autoscaler for the controller:

```yaml values.yaml theme={null}
controller:
  horizontalPodAutoscaler:
    minReplicas: 1
    maxReplicas: 5
    metrics:
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 80
```

Enable the Vertical Pod Autoscaler:

```yaml values.yaml theme={null}
controller:
  verticalPodAutoscaler:
    updatePolicy:
      updateMode: Auto
    resourcePolicy:
      containerPolicies:
        - containerName: "*"
          minAllowed:
            cpu: 100m
            memory: 128Mi
```

### Pod disruption budget

```yaml values.yaml theme={null}
controller:
  podDisruptionBudget:
    minAvailable: 1
```

## Creating a Gateway

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

```yaml gateway.yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: agentgateway
  listeners:
    - name: http
      protocol: HTTP
      port: 8080
```

Apply it:

```bash theme={null}
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:

```yaml parameters.yaml theme={null}
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:

```yaml values.yaml theme={null}
discoveryNamespaceSelectors:
  - matchLabels:
      agentgateway.dev/discovery: "true"
```

Then label the namespaces you want included:

```bash theme={null}
kubectl label namespace my-namespace agentgateway.dev/discovery=true
```

## Health checks

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

```yaml theme={null}
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`)      |

<Note>
  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`).
</Note>

## TLS for xDS communication

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

```bash theme={null}
# 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
```

```yaml values.yaml theme={null}
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:

```yaml values.yaml theme={null}
imagePullSecrets:
  - name: my-registry-credentials
```

## Development with Tilt

For iterative development on a local [Kind](https://kind.sigs.k8s.io/) cluster, the repository includes a `Tiltfile` that builds both the controller and data plane with live-update support:

```bash theme={null}
# 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.

<Tip>
  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.
</Tip>