Advanced settings

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://ghcr.io/kgateway-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://ghcr.io/kgateway-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 2.3.0-main, 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:

• ListenerSets
• 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

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"