For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Advanced settings

Install agentgateway and related components.

You can update several installation settings in your Helm values file. For example, you can update the namespace, set resource limits and requests, or enable extensions such as for AI.

• Show all values:

  helm show values oci://cr.agentgateway.dev/charts/agentgateway --version v$NEW_VERSION

• Get a file with all values: You can get a agentgateway/values.yaml file for the upgrade version by pulling and inspecting the Helm chart locally.

  helm pull oci://cr.agentgateway.dev/charts/agentgateway --version v$NEW_VERSION
  tar -xvf agentgateway-v$NEW_VERSION.tgz
  open agentgateway/values.yaml

For more information, see the Helm reference docs.

Development builds

When using the development build 0.0.0-latest-dev, add --set controller.image.pullPolicy=Always to ensure you get the latest image. For production environments, this setting is not recommended as it might impact performance.

Experimental Gateway API features

To use experimental Gateway API features, you must enable the experimental feature gate, KGW_ENABLE_GATEWAY_API_EXPERIMENTAL_FEATURES. This setting defaults to false and must be explicitly enabled to use experimental features such as the following:

• CORS policies
• Retries
• Session persistence

To enable these features, set the environment variable in your kgateway controller deployment in your Helm values file.

controller:
  extraEnv:
    KGW_ENABLE_GATEWAY_API_EXPERIMENTAL_FEATURES: "true"

Leader election

Leader election is enabled by default to ensure that you can run agentgateway in a multi-control plane replica setup for high availability.

You can disable leader election by setting the controller.disableLeaderElection to true in your Helm chart.

controller:
  disableLeaderElection: true

Multiple control planes

You can run multiple independent agentgateway control planes in the same cluster. This setup is different from running multiple replicas of one control plane for high availability. Each independent control plane manages its own GatewayClass and set of Gateways.

Each additional control plane needs the following Helm settings.

The following steps add a second control plane for a tenant-b team. The agentgateway and Kubernetes Gateway API custom resource definitions (CRDs) are cluster-scoped, so you install them only once per cluster and not again for each control plane.

1. Create the namespace for the workloads and Gateways that the second control plane manages, and label it so that the second control plane discovers it.

   kubectl create namespace tenant-b
   kubectl label namespace tenant-b gateway-controller=tenant-b

2. Create a secondary-values.yaml file for the second control plane. Each entry in discoveryNamespaceSelectors is disjunctive (OR semantics), so the control plane watches a namespace if that namespace matches any entry. This example matches two sets of namespaces: the control plane’s own namespace, agentgateway-tenant-b-system, and every namespace with the gateway-controller: tenant-b label. Include the control plane’s own namespace, because the controller watches resources in that namespace, such as the certificate that secures its xDS connection.

   gatewayClassName: agentgateway-tenant-b
   controllerName: agentgateway.dev/agentgateway-tenant-b
   
   discoveryNamespaceSelectors:
   - matchExpressions:
     - key: kubernetes.io/metadata.name
       operator: In
       values:
       - agentgateway-tenant-b-system
   - matchLabels:
       gateway-controller: tenant-b

3. Install the second control plane in its own namespace.

   helm upgrade -i --create-namespace \
   -n agentgateway-tenant-b-system agentgateway-tenant-b oci://cr.agentgateway.dev/charts/agentgateway \
   --version v1.4.1 \
   -f secondary-values.yaml

4. Verify that each control plane owns its own GatewayClass.

   kubectl get gatewayclass -o custom-columns='NAME:.metadata.name,CONTROLLER:.spec.controllerName'

   Example output:

   NAME                    CONTROLLER
   agentgateway            agentgateway.dev/agentgateway
   agentgateway-tenant-b   agentgateway.dev/agentgateway-tenant-b
   

5. Create a Gateway that references the GatewayClass of the second control plane.

   kubectl apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: tenant-b-gateway
     namespace: tenant-b
   spec:
     gatewayClassName: agentgateway-tenant-b
     listeners:
     - name: http
       protocol: HTTP
       port: 80
   EOF

6. Verify that the second control plane provisions the proxy for the Gateway.

   kubectl get gateway,pods -n tenant-b

   Example output:

   NAME                                                 CLASS                   ADDRESS   PROGRAMMED   AGE
   gateway.gateway.networking.k8s.io/tenant-b-gateway   agentgateway-tenant-b             True         12s
   
   NAME                                   READY   STATUS    RESTARTS   AGE
   pod/tenant-b-gateway-766895c6d-zkpxt   1/1     Running   0          12s
   

Namespace discovery

You can limit the namespaces that agentgateway watches for gateway configuration. For example, you might have a multi-tenant cluster with different namespaces for different tenants. You can limit agentgateway to only watch a specific namespace for gateway configuration.

Namespace selectors are a list of matched expressions or labels.

• matchExpressions: Use this field for more complex selectors where you want to specify an operator such as In or NotIn.
• matchLabels: Use this field for simple selectors where you want to specify a label key-value pair.

Each entry in the list is disjunctive (OR semantics). This means that a namespace is selected if it matches any selector.

You can also use matched expressions and labels together in the same entry, which is conjunctive (AND semantics).

The following example selects namespaces for discovery that meet either of the following conditions:

• The namespace has the label environment=prod and the label version=v2, or
• The namespace has the label version=v3

discoveryNamespaceSelectors:
- matchExpressions:
  - key: environment
    operator: In
    values:
    - prod
  matchLabels:
    version: v2
- matchLabels:
    version: v3

TLS encryption

You can enable TLS encryption for the xDS gRPC server in the agentgateway control plane. For more information, see the TLS encryption docs.

Autoscaling

You can configure Horizontal Pod Autoscaler or Vertical Pod Autoscaler policies for the agentgateway control plane. To set up these policies, you use the horizontalPodAutoscaler or verticalPodAutoscaler fields in the Helm chart.

Vertical Pod Autoscaler (VPA)

Vertical Pod Autoscaler (VPA) is a Kubernetes component that automatically adjusts the CPU and memory reservations of your pods to match their actual usage.

The following Helm configuration ensures that the control plane pod is always assigned a minimum of 0.1 CPU cores (100millicores) and 128Mi of memory.

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

Horizontal Pod Autoscaler (HPA)

Horizontal Pod Autoscaler (HPA) adds more instances of the pod to your environment when certain memory or CPU thresholds are reached.

In the following example, you want to have 1 control plane replica running at any given time. If the CPU utilization averages 80%, you want to gradually scale up your replicas. You can have a maximum of 5 replicas at any given time.

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

Note: To monitor the memory and CPU threshold, you need to deploy the Kubernetes metrics-server in your cluster. The metrics-server retrieves metrics, such as CPU and memory consumption for your workloads.

You can install the server with the following command:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
kubectl -n kube-system patch deployment metrics-server \
 --type=json \
 -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

Then, start monitoring CPU and memory consumption with the kubectl top pod command.

PriorityClass

You can assign a PriorityClassName to the control plane pods by using the Helm chart. Priority indicates the importance of a pod relative to other pods. If a pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority pods to make scheduling of the pending pod possible.

To assign a PriorityClassName to the control plane, you must first create a PriorityClass resource. The following example creates a PriorityClass with the name system-cluster-critical that assigns a priority of 1 Million.

kubectl apply -f- <<EOF
apiVersion: scheduling.k8s.io/v1
kind: PriorityClass
metadata:
  name: system-cluster-critical
value: 1000000
globalDefault: false
description: "Use this priority class on system-critical pods only."
EOF

In your Helm values file, add the name of the PriorityClass in the controller.priorityClassName field.

controller: 
  priorityClassName: 

Common labels

Add custom labels to all resources that are created by the agentgateway Helm charts, including the Deployment, Service, ServiceAccount, and ClusterRoles. This allows you to better organize your resources or integrate with external tooling.

The following snippet adds the label-key and agw-managed labels to all resources.

commonLabels: 
  label-key: label-value
  agw-managed: "true"

PodDisruptionBudget

Configure a Pod Disruption Budget to ensure that a minimum number of control plane instances are up and running at any given time during voluntary disruptions, such as upgrades. In this example, 50% of your control plane instances must be running.

controller: 
  podDisruptionBudget:
    minAvailable: 50%