Conditional expressions for plugins

Plugin conditions let you attach an optional condition expression to any plugin. When a request comes in, Kong Gateway evaluates the expression immediately before the plugin’s access phase. If the expression evaluates to true, the plugin runs normally. If it evaluates to false, the plugin is skipped for that request.

Conditions use Common Expression Language (CEL), a lightweight expression language.

Here are some common use cases for setting a condition on a plugin:

• Skip a global plugin for specific Routes, hosts, or request paths without removing the plugin or duplicating it across individual Routes.
• Enforce a plugin only for specific HTTP methods, headers, or query parameters.
• Make one plugin’s execution depend on context set by a higher-priority plugin.
• Condition plugin behavior on the authenticated Consumer, matched Route, or target Gateway Service.

When Kong Gateway receives a request, it matches the request to a Route and determines which plugins are in scope according to the plugin scoping rules. For each in-scope plugin that has a condition set, Kong Gateway evaluates the expression before that plugin’s access phase runs.

The following plugin contexts always execute, regardless of the condition: init_worker, configure, certificate, and rewrite. If the condition evaluates to false, the plugin’s access phase and all later phases are skipped. Because of this, values set during or after the response phase (for example, kong.ctx.shared values written in header_filter or body_filter) aren’t available to condition expressions.

Unlike plugin scopes, which are evaluated once at router time before any plugins run, conditions are evaluated per request, per plugin, immediately before each plugin executes. This means a higher-priority plugin can set values in kong.ctx.shared that a lower-priority plugin’s condition can then read.

If no condition is set, the plugin always executes.

Plugin scopes are evaluated once at router time and are more efficient than conditions, which are evaluated per request for each conditioned plugin. Where possible, use plugin scopes to control plugin execution rather than conditions.

When conditions are necessary, keep the following in mind:

• A plugin’s configuration is always loaded into memory, even if its condition evaluates to false.
• Complex compound expressions with many fields are more expensive to evaluate than simple single-field expressions.
• Conditions that reference kong.ctx.shared fields require a higher-priority plugin to set those values on every request, which adds its own overhead.

Plugin conditions are only supported in the HTTP subsystem. They can’t be used with stream (TCP, TLS, UDP) Routes.

The following plugins do not support conditions:

• Pre-Function
• Post-Function
• WebSocket Size Limit
• WebSocket Validator

All other Kong Gateway plugins support conditions.

Condition expressions have a maximum length of 1024 characters.

This reference describes the CEL expression syntax and available fields for plugin conditions.

Expression syntax

A condition expression is a string value assigned to the condition field of a plugin object. A predicate is the basic unit of an expression and compares a field against a value:

http.method == "GET"

This predicate has the following structure:

Combining predicates

Multiple predicates can be combined using logical operators:

Available fields

Plugin conditions support HTTP request fields, Kong Gateway context fields, and plugin state fields.

HTTP request fields

These fields reflect the state of the incoming HTTP request at the time the condition is evaluated. Higher-priority plugins may have already modified these values (for example, by rewriting a header or query parameter) before the condition is evaluated.

Gateway context fields

The following fields are populated during plugin execution and reflect the Gateway context at the time the condition is evaluated.

consumer.* and consumer_group.* fields are only populated after an authentication plugin (such as Key Auth or Basic Auth) has run. Conditions referencing these fields must be on a plugin with a lower priority than the authentication plugin.

Plugin state fields

The following fields reflect the configured state of other plugins in the same Gateway workspace or control plane at the time the condition is evaluated.

Null handling

How null values behave depends on the field type.

The following fields return null when a value isn’t set:

• http.headers.*
• http.queries.*
• http.headers_list.*
• http.queries_list.*
• net.tls.sni
• All context fields (consumer.*, route.*, service.*, principal.*, consumer_group.*, plugins.*)

You can compare these directly using null:

consumer.id != null
route.tags != null && "internal" in route.tags

The kong.ctx.shared and principal.metadata fields are maps whose inner keys are not pre-populated by Kong Gateway. Accessing a missing key in these maps causes a runtime error (500). Before accessing a key, use has() to check for its existence:

has(kong.ctx.shared.my_flag) && kong.ctx.shared.my_flag == "enabled"

Alternatively, wrap the entire expression in default() to return a safe fallback if the key is missing:

default(kong.ctx.shared.my_flag == "enabled", false)

Operators and functions

The following operators and functions are supported in plugin condition expressions:

Regular expressions follow the rules of Rust Crate regex. Regular expression matches succeed if they match a substring of the argument. Use explicit anchors (^ and $) in the pattern to force full-string matching, if desired. For example, http.path.matches("^/api/v[0-9]+$") matches /api/v1 but not /other/api/v1.

Types

Plugins support the following CEL types:

Handling default values

default() makes condition expressions safe at runtime. If the expression raises an evaluation error (for example, accessing a missing key in a map), default() returns the fallback value instead of causing a 500 error.

default() must wrap the entire expression. It can’t appear inline within a larger expression:

# Valid — wraps the entire expression
default(kong.ctx.shared.my_flag == "enabled", false)

# Not valid — default() can't be used inline
kong.ctx.shared.my_flag == "enabled" && default(principal.id == "abc", false)

Use default() when your expression references fields that might not be set for every request, such as kong.ctx.shared.* or principal.metadata.*:

default(principal.metadata["Department"] == "finance", false)

When Kong Gateway is running with debug logging enabled, a log line is emitted for each condition evaluation.

When a condition is not matched and the plugin is skipped:

plugin condition not matched for plugin 'request-termination' (ID: 66a1adbb-0179-49af-a065-4d0bc6c28cd6): skipped

When a condition is matched and the plugin executes:

plugin condition matched for plugin 'request-termination' (ID: 66a1adbb-0179-49af-a065-4d0bc6c28cd6)

If a condition expression fails at runtime, the error is logged at the ERROR level and Kong Gateway returns a 500 to the client:

error evaluating plugin condition for plugin 'request-termination' (ID: 66a1adbb-0179-49af-a065-4d0bc6c28cd6): No such key: foo

To prevent runtime errors, wrap your expression in default():

"condition": "default(kong.ctx.shared.my_flag == \"enabled\", false)"

The plugin expression language changed between 3.14 and 3.15. In Kong Gateway 3.14, the feature was in beta and used ATC (Abstract Tree Classifier) syntax for plugin conditions. Kong Gateway 3.15 uses CEL (Common Expression Language), which isn’t backwards-compatible.

Any conditional expression that worked in 3.14 will need to be rewritten for 3.15. The main syntax changes are:

• Prefix matching: ^= → startsWith(). For example, http.path ^= "/api" becomes http.path.startsWith("/api").
• Suffix matching: =^ → endsWith(). For example, http.path =^ ".json" becomes http.path.endsWith(".json").
• Regex matching: ~ → matches(). For example, http.path ~ r#"^/api/v[0-9]+"# becomes http.path.matches("^/api/v[0-9]+").
• The http.path.segments.<index> fields are replaced by http.path_segments (a list).
• Header and query fields now return null when absent (instead of an empty string), so null checks may be needed.

For the 3.14 beta reference, see Conditional expressions for plugins in 3.14.