Advanced settings

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.2.9).

export NEW_VERSION=2.2.9

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.

Mode Behavior

standard (default) The control plane translates all valid resources and replaces invalid routes with a direct response (typically HTTP 500). Valid routes that are unrelated to the invalid resource are unaffected. The control plane does not run Envoy in this mode, so configuration that only Envoy can detect as invalid, such as an invalid RE2 regular expression in a route matcher, is still sent to the proxies. Envoy rejects (NACKs) that update and keeps serving the last route configuration that it accepted, so later route changes on the same listener are not applied until you fix the error.

strict In addition to the standard checks, the control plane validates the generated configuration with Envoy before it sends the configuration to the proxies. Instead of sending invalid configuration, the control plane removes or replaces only the invalid parts, so that Envoy does not NACK the update and valid changes continue to be applied. For more information, see How strict mode handles invalid configuration.

Mode	Behavior
`standard` (default)	The control plane translates all valid resources and replaces invalid routes with a direct response (typically `HTTP 500`). Valid routes that are unrelated to the invalid resource are unaffected. The control plane does not run Envoy in this mode, so configuration that only Envoy can detect as invalid, such as an invalid RE2 regular expression in a route matcher, is still sent to the proxies. Envoy rejects (NACKs) that update and keeps serving the last route configuration that it accepted, so later route changes on the same listener are not applied until you fix the error.
`strict`	In addition to the `standard` checks, the control plane validates the generated configuration with Envoy before it sends the configuration to the proxies. Instead of sending invalid configuration, the control plane removes or replaces only the invalid parts, so that Envoy does not NACK the update and valid changes continue to be applied. For more information, see How strict mode handles invalid configuration.

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.

Invalid configuration	Result	Status
A route matcher, such as an invalid RE2 regular expression in a path, header, or query parameter match	The control plane removes the route rule. Requests that the rule matched are handled by the remaining routes, or receive an `HTTP 404` response if no other route matches.	`Accepted=False` with reason `RouteRuleDropped` on the route
Any other part of a route rule, such as a filter or policy setting that Envoy rejects	The control plane replaces the route rule with a direct `HTTP 500` response.	`Accepted=False` with reason `RouteRuleReplaced` on the route

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.

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"

Sample HTTP app TLS encryption

Was this page helpful?