Conditional expressions for plugins

Plugin conditions allow you to 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.

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

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

Expression formatting

A condition expression is a string value assigned to the condition field of a plugin object. It follows the same ATC (Abstract Tree Classifier) expression syntax used by Kong Gateway’s expressions router.

A predicate is the basic unit of an expression and takes the following form:

http.method == "GET"

This predicate has the following structure:

• http.method: Field
• ==: Operator
• "GET": Constant value

Predicates are made up of smaller units that you can configure:

Field and constant value types

Types define what you can use for a predicate’s field and constant value. Expressions language is strongly typed. Operations are only performed if such an operation makes sense in regard to the actual type of field and constant.

Type conversion at runtime is not supported, either explicitly or implicitly. Types are always known at the time a route is parsed. An error is returned if the operator cannot be performed on the provided field and constant.

The expressions language currently supports the following types:

In addition, the expressions router also supports one composite type, Array. Array types are written as Type[]. For example: String[], Int[]. Currently, arrays can only be present in field values. They are used in case one field could contain multiple values. For example, http.headers.x or http.queries.x.

Available fields

Plugin conditions support all standard HTTP fields from the expressions router, plus additional context fields that are only available during plugin execution.

HTTP request fields

These fields reflect the state of the incoming HTTP request at the time the condition is evaluated. These values may have been modified by higher-priority plugins before the condition is evaluated (for example, a plugin that rewrites a header or query parameter).

Hyphens (-) in header names must be replaced with underscores (_) in ATC expressions. For example, x-my-header becomes http.headers.x_my_header.

Plugin condition-specific fields

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

Notes:

• consumer.* fields are only populated after an authentication plugin (such as Key Auth or Basic Auth) has run. Conditions referencing consumer fields must be on a plugin with a lower priority than the authentication plugin.
• kong.ctx.shared.KEY_NAME fields are only populated if a higher-priority plugin has set them during the access phase. Values set during the response phase are not available.

Operators

An operator defines the desired comparison action to be performed on the field against the provided constant value. The operator always displays in the middle of the predicate, between the field and constant value.

The expressions language supports a rich set of operators that can be performed on various data types.

Allowed type and operator combinations

Depending on the field type, only certain content types and operators are supported.

The ~ regex operator does not automatically anchor to the start of the string. http.path ~ r#"/foo/\d"# would match /foo/1 and /other/foo/1. To anchor from the start, use the ^ character: http.path ~ r#"^/foo/\d"#.

The following tables contain examples of different types of expressions.

HTTP request fields

The following expressions can be used to match HTTP requests.

Consumer fields

The following expressions can be used to match Consumer metadata.

Route and Service fields

The following expressions can be used to match Route and Service metadata.

kong.ctx.shared fields

The following expressions can be used to match kong.ctx.shared fields.

When Kong Gateway is running with debug logging enabled, a log line is emitted for each condition evaluation, showing the plugin name, plugin ID, the expression, and the result:

[kong] plugin_condition.lua:234 plugin condition evaluated for plugin
'request-termination' (ID: 66a1adbb-0179-49af-a065-4d0bc6c28cd6):
expression="http.headers.x_block == "true"", result=false

When result=false, the plugin was skipped for that request. When result=true, the plugin executed normally.