> ## 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 the controller, Helm charts, and Gateway API resources.

Agentgateway includes a Kubernetes controller that integrates with the [Gateway API](https://gateway-api.sigs.k8s.io/). 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 |

<Note>
  Check the [Kubernetes documentation](https://agentgateway.dev/docs/kubernetes/latest) for the latest install commands and chart versions as the registry may change between releases.
</Note>

<Steps>
  <Step title="Install the Gateway API CRDs">
    ```bash theme={null}
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml
    ```
  </Step>

  <Step title="Install the Agentgateway CRDs">
    ```bash theme={null}
    helm install agentgateway-crds \
      oci://cr.agentgateway.dev/helm/agentgateway-crds
    ```
  </Step>

  <Step title="Install the controller">
    ```bash theme={null}
    helm install agentgateway \
      oci://cr.agentgateway.dev/helm/agentgateway \
      --namespace agentgateway-system \
      --create-namespace
    ```
  </Step>

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

    You should see the controller pod in `Running` state.
  </Step>
</Steps>

## Gateway API integration

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

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

<AccordionGroup>
  <Accordion title="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.

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

  <Accordion title="AgentgatewayPolicy (agpol)">
    `AgentgatewayPolicy` attaches traffic, frontend, or backend policies to Gateway API resources.

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

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Helm chart configuration

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

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

```yaml theme={null}
controller:
  xds:
    tls:
      enabled: true
```

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

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

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

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

```yaml theme={null}
gatewayClassParametersRefs:
  agentgateway:
    name: shared-gwp
    namespace: agentgateway-system
```

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

## Scaling and resilience

<CardGroup cols={2}>
  <Card title="Horizontal Pod Autoscaler" icon="arrows-left-right">
    Configure HPA on the controller via `controller.horizontalPodAutoscaler`. The controller manages the HPA `scaleTargetRef` automatically.
  </Card>

  <Card title="Pod Disruption Budget" icon="shield">
    Configure PDB on the controller via `controller.podDisruptionBudget` to ensure availability during voluntary disruptions.
  </Card>

  <Card title="Resource limits" icon="gauge">
    Set CPU and memory requests and limits via `resources` in the Helm values or `AgentgatewayParameters.spec.resources`.
  </Card>

  <Card title="Graceful shutdown" icon="circle-stop">
    Configure `AgentgatewayParameters.spec.shutdown.min` and `.max` to control the drain window for rolling updates.
  </Card>
</CardGroup>