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

Install kgateway 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.

Set the version you want to configure in an environment variable, such as the latest patch version (2.5.0-main).

export NEW_VERSION=2.5.0-main

• Show all values:

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

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

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

For more information, see the Helm reference docs.

Development builds

When using the development build 2.5.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

The KGW_ENABLE_EXPERIMENTAL_GATEWAY_API_FEATURES feature gate controls support for experimental Gateway API features such as the following:

• TCPRoutes
• TLSRoutes
• ListenerSets
• CORS policies
• Retries
• Session persistence

In kgateway version 2.2 and later, this setting defaults to true, so experimental features are enabled by default and no additional configuration is required. To disable these features, set the environment variable to false in your kgateway controller deployment in your Helm values file.

controller:
  extraEnv:
    KGW_ENABLE_EXPERIMENTAL_GATEWAY_API_FEATURES: "false"

Leader election

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

You can disable leader election by setting the KGW_DISABLE_LEADER_ELECTION environment variable to "true" through the controller.extraEnv Helm value.

controller:
  extraEnv:
    KGW_DISABLE_LEADER_ELECTION: "true"

Namespace discovery

You can limit the namespaces that kgateway watches for gateway configuration. For example, you might have a multi-tenant cluster with different namespaces for different tenants. You can limit kgateway 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 kgateway control plane. For more information, see the TLS encryption docs.

Strict validation

Kgateway supports two validation modes for routes and policies in the control plane: standard and strict. The validation mode controls how the control plane handles invalid configuration before it is sent to Envoy.

Validation modes

Kgateway supports the following validation modes. The mode is set globally on the controller through a single Helm value.

standard mode is the default and is appropriate for most production environments. strict mode is recommended when you cannot tolerate a NACKed xDS update reaching the data plane, for example when one team’s invalid route must not block configuration updates for other routes on the same listener.

How strict mode handles invalid configuration

Strict mode does not keep a previous version of a route when an update to the route is invalid. The control plane translates the current state of your resources, and handles invalid configuration as follows.

If a virtual host is still invalid after its invalid route rules are removed or replaced, the control plane replaces all routes for the virtual host’s domains with a direct HTTP 500 response, and the affected listener reports Accepted=False with reason ListenerReplaced.

For example, suppose that route-a and route-b are attached to the same listener, and you update route-b with an invalid regular expression in a path match. In strict mode, route-a continues to serve traffic, the invalid rule of route-b is removed so that its requests receive an HTTP 404 response, and route-b reports the RouteRuleDropped reason. In standard mode, the invalid regular expression is sent to Envoy, which rejects the update. Both routes keep their previous configuration on the proxies that already accepted it, but no further route changes on that listener take effect until you fix route-b.

Enable strict validation

Set the validation.level Helm value to strict when you install or upgrade kgateway. Restart the control plane to apply the change.

validation:
  level: strict

Internally, the Helm chart passes the value to the control plane through the KGW_VALIDATION_MODE environment variable. If you manage the control plane deployment manually, set KGW_VALIDATION_MODE=STRICT on the kgateway container.

The accepted values for validation.level are standard and strict (case-insensitive). Any other value causes the Helm install to fail.

Verify the validation mode

To check which mode is active, inspect the KGW_VALIDATION_MODE environment variable on the kgateway controller deployment. The expected output is standard or strict.

kubectl -n kgateway-system get deployment kgateway \
  -o jsonpath='{.spec.template.spec.containers[*].env[?(@.name=="KGW_VALIDATION_MODE")].value}'

Transformation policies and strict validation

Strict validation runs the preflight against an Envoy binary that is bundled in the kgateway control plane image. The control plane image is built from the envoy-wrapper image, which bundles the rustformation dynamic module, and the validator sets ENVOY_DYNAMIC_MODULES_SEARCH_PATH=/usr/local/lib before invoking the preflight. As a result, the preflight understands rustformation per-route config and can validate TrafficPolicies that use transformation.

For more information about transformation engines, see Transformation engines.

Tune the controller Go memory limit

By default, the Go runtime that the kgateway controller runs on does not know how much memory Kubernetes allows its container to use. The controller’s garbage collector just runs on its own schedule, so the controller can keep allocating memory right up to the container’s limit. When it crosses that limit, the Linux kernel kills the container immediately, with no warning and no chance for the controller to free memory first. This event appears as a Kubernetes pod restart, often labeled OOMKilled.

The GOMEMLIMIT environment variable fixes this issue by giving the Go runtime a soft memory ceiling. As the pod’s memory usage approaches that ceiling, the garbage collector starts freeing up memory, so the controller can stay under the container’s limit instead of being killed when it goes over.

By default, controller.goMemLimitPercent is set to 0, which disables the Go memory limit feature. The Helm chart sets the GOMEMLIMIT environment variable when the controller pod starts by reading the resources.limits.memory on the associated Deployment. This limit is fixed throughout the pod’s lifecycle. If the container’s memory limit changes later, such as when a Kubernetes LimitRange resource is applied or a Vertical Pod Autoscaler (VPA) resizes the pod in place, GOMEMLIMIT does not follow that change until the pod restarts.

To adjust the GOMEMLIMIT variable dynamically, set the controller.goMemLimitPercent field to a value between 1 and 100. This way, the GOMEMLIMIT environment variable is kept in sync with the container’s memory limit as it changes. Instead of reading the memory limit once at startup, the controller reads the container’s live memory limit directly from its cgroup every 30 seconds, and sets GOMEMLIMIT to the percentage you configure of that current value. A value of 90 is the recommended starting point. The controller targets 90% of the container’s memory limit, leaving 10% as headroom for memory that the Go runtime does not track, such as memory that is used by Envoy subprocesses.

controller:
  goMemLimitPercent: 90

If you enable strict validation, use a lower value such as 80 because Envoy subprocess memory is not covered by GOMEMLIMIT. Do not set controller.extraEnv.GOMEMLIMIT or controller.extraEnv.AUTOMEMLIMIT with controller.goMemLimitPercent. If the controller container has no finite cgroup memory limit, GOMEMLIMIT remains unconstrained and the controller logs a warning.

ReferenceGrant enforcement modes

In multi-tenant clusters, different teams typically own separate namespaces and share a gateway. The Gateway API ReferenceGrant mechanism controls which cross-namespace references are permitted, ensuring that one team cannot silently access another team’s resources. Without a ReferenceGrant in the target namespace, the reference is denied.

In kgateway, you can configure how strictly you want ReferenceGrant requirements to be enforced by using the KGW_REFERENCE_GRANT_MODE environment variable on the control plane. You can choose between the following modes:

• STRICT: Enforce ReferenceGrants for every cross-namespace reference in the following table, including cross-namespace ExtensionRef references. This mode provides the strongest namespace isolation and is recommended for new clusters.
• PERMISSIVE (default): Enforce ReferenceGrants for every cross-namespace reference in the following table except cross-namespace ExtensionRef references. Before reference grant modes were introduced, TrafficPolicy resources were able to reference and access a GatewayExtension resource in another namespace without a ReferenceGrant. PERMISSIVE mode allows these setups to function as before. Over time, you can add the missing ReferenceGrant resources in the required namespaces and migrate your cluster to STRICT ReferenceGrant validation.
• OFF: Disable all ReferenceGrant validation. Not recommended for multi-tenant or production environments.

  Caution

  Do not use OFF in multi-tenant or production environments. It breaks Gateway API compliance, bypasses namespace isolation, and lets any namespace access backends, secrets, and GatewayExtensions in other namespaces without restriction.

Reference validation by mode

The following table shows which cross-namespace references are checked in each mode. Same-namespace references always pass, regardless of the mode.

ReferenceGrant example

To reference resources across namespaces, create a ReferenceGrant in the namespace of the resource that you want to access, not in the namespace of the resource that makes the reference. The from section describes the resource that makes the reference, and the to section describes the resource it is allowed to reach. For more information about which resource to reference in each field, see Reference validation by mode.

The following example allows a policy in the httpbin namespace to read Secrets in the team-secrets namespace.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-apikey-secrets
  # The namespace that holds the Secrets.
  namespace: team-secrets
spec:
  from:
  - group: gateway.kgateway.dev
    kind: TrafficPolicy
    # The namespace that holds the policy.
    namespace: httpbin
  to:
  - group: ""
    kind: Secret
EOF

To restrict the grant to a single Secret, add name to the to entry. When you omit name, every Secret in the namespace is allowed.

Enable STRICT mode

1. Check which mode is currently active by inspecting the KGW_REFERENCE_GRANT_MODE environment variable on the controller deployment. If the variable is not set, the active mode is PERMISSIVE.

   kubectl -n kgateway-system get deployment kgateway \
     -o jsonpath='{.spec.template.spec.containers[*].env[?(@.name=="KGW_REFERENCE_GRANT_MODE")].value}'

2. Make sure that any existing cross-namespace TrafficPolicy → GatewayExtension references have a corresponding ReferenceGrant.

3. Get the current Helm values for your kgateway release and save them to a file.

   helm get values kgateway -n kgateway-system -o yaml > values.yaml
   open values.yaml

4. Add the following values to enable STRICT ReferenceGrant validation.

   controller:
     extraEnv:
       KGW_REFERENCE_GRANT_MODE: "STRICT"

5. Apply the change by upgrading the Helm release.

   helm upgrade -i -n kgateway-system kgateway \
     oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
     --version 2.5.0-main \
     -f values.yaml

6. Confirm that the kgateway control plane restarted and is running.

   kubectl get pods -n kgateway-system

7. Verify the active mode.

   kubectl -n kgateway-system get deployment kgateway  \
     -o jsonpath='{.spec.template.spec.containers[*].env[?(@.name=="KGW_REFERENCE_GRANT_MODE")].value}'

Disable automatic RBAC creation

By default, the kgateway Helm chart creates a ClusterRole and ClusterRoleBinding that grant the controller’s service account the permissions it needs to watch and manage Kubernetes resources. In environments where RBAC resources are managed externally, such as by a platform or security team that controls all cluster-scoped permissions, you can disable the creation of these resources by setting rbac.create: false.

To skip RBAC resource creation, set rbac.create: false in your Helm values:

rbac:
  create: false

Common labels

Add custom labels to all resources that are created by the Helm charts. These resources include the controller Deployment metadata, controller pod template, Service, ServiceAccount, and ClusterRoles. The labels are separate from selector labels, so you can update commonLabels without changing the Deployment’s immutable selector labels.

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

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

Topology spread constraints

Use topology spread constraints to control how kgateway controller pods are distributed across failure domains such as zones or nodes. This setup helps improve availability and resilience by preventing all replicas from landing in the same zone or node.

For more information, see the Kubernetes topology spread constraints documentation.

The following example spreads controller pods evenly across availability zones, and prevents scheduling if the skew cannot be satisfied.

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        app.kubernetes.io/name: kgateway

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: 

Autoscaling

You can configure Horizontal Pod Autoscaler (HPA) or Vertical Pod Autoscaler (VPA) policies for the kgateway 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.

controller:
  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.

controller: 
  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 must deploy the Kubernetes metrics-server to 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.

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%

Controller probes

You can customize the readiness and startup probes for the kgateway controller container by using the controller.readinessProbe and controller.startupProbe Helm values. Your settings are deep-merged with the default probe configuration, so you only need to specify the fields you want to change.

By default, both probes use an httpGet handler that checks the /readyz endpoint on the health port. The default readiness probe polls every 10 seconds with an initial delay of 1 second. The default startup probe polls every second with no initial delay and a failure threshold of 600, allowing up to 10 minutes for the controller to start.

If you provide an exec, grpc, or tcpSocket handler, the default httpGet handler is replaced entirely. Otherwise, the httpGet handler is kept and your overrides are merged on top.

The following example adjusts the timing fields of the default readiness probe without changing the default httpGet handler.

controller:
  readinessProbe:
    initialDelaySeconds: 5
    periodSeconds: 20
    failureThreshold: 3

The following example replaces the default httpGet handler with a custom exec handler on the startup probe.

controller:
  startupProbe:
    exec:
      command: ["cat", "/tmp/ready"]
    initialDelaySeconds: 10
    periodSeconds: 5
    failureThreshold: 60

xDS first-connect grace period

By default, the control plane waits 1 second after a new proxy connects before sending its first xDS snapshot. This gives per-client translation time to converge and prevents newly started gateway pods from receiving incomplete configuration after a controller restart.

You can adjust the grace period by using the KGW_XDS_FIRST_CONNECT_DELAY environment variable on the controller. The value is a Go duration string, for example 2s. Set it to 0 to disable the grace period entirely.

controller:
  extraEnv:
    KGW_XDS_FIRST_CONNECT_DELAY: "2s"

Controller admin server bind address

The kgateway controller runs an admin and debug server on port 9095. By default, the server binds to localhost and is only accessible from within the pod.

To access the admin and debug servers from your local machine, use the kubectl port-forward command to expose port 9095 on your local machine. No change of the bind address is required.

kubectl port-forward deployment/kgateway -n kgateway-system 9095:9095

If you need other pods in the cluster to reach the admin server directly, you can change the bind address by using the controller.admin.bindAddress Helm value or the KGW_ADMIN_BIND_ADDRESS environment variable. Setting bindAddress to 0.0.0.0 makes the server listen on all pod interfaces, so other pods can reach it at http://<pod-ip>:9095. To find the pod IP, run kubectl get pod -l app.kubernetes.io/name=kgateway -n kgateway-system -o wide.

controller:
  admin:
    bindAddress: 0.0.0.0