Configuration

configobjectrequired
Hide Child Parameters
cacheobject

Plugin global caching configuration.

Hide Child Parameters
cache_ttlinteger

TTL in seconds of cache entities.

Default:300

>= 0

memoryobject
Hide Child Parameters
dictionary_namestring

The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note that this dictionary currently must be defined manually in the Kong Nginx template.

Default:kong_db_cache

redisobject
Hide Child Parameters
cluster_max_redirectionsinteger

Maximum retry attempts for redirection.

Default:5

cluster_nodesarray[object]

Cluster addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.

>= 1 characters

Show Child Parameters
connect_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

connection_is_proxiedboolean

If the connection to Redis is proxied (e.g. Envoy), set it true. Set the host and port to point to the proxy address.

Default:false

databaseinteger

Database to use for the Redis connection when using the redis strategy

Default:0

hoststring

A string representing a host name, such as example.com.

Default:127.0.0.1

keepalive_backloginteger

Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return nil. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than keepalive_pool_size. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than keepalive_pool_size.

>= 0<= 2147483646

keepalive_pool_sizeinteger

The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither keepalive_pool_size nor keepalive_backlog is specified, no pool is created. If keepalive_pool_size isn’t specified but keepalive_backlog is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.

Default:256

>= 1<= 2147483646

passwordstring

Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
This field is referenceable.
This field is encrypted.

portinteger

An integer representing a port number between 0 and 65535, inclusive.

Default:6379

>= 0<= 65535

read_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

send_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

sentinel_masterstring

Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.

sentinel_nodesarray[object]

Sentinel node addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.

>= 1 characters

Show Child Parameters
sentinel_passwordstring

Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
This field is referenceable.
This field is encrypted.

sentinel_rolestring

Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel.

Allowed values:anymasterslave

sentinel_usernamestring

Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
This field is referenceable.

server_namestring

A string representing an SNI (server name indication) value for TLS.

sslboolean

If set to true, uses SSL to connect to Redis.

Default:false

ssl_verifyboolean

If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

Default:false

usernamestring

Username to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to default.
This field is referenceable.

strategystring

The backing data store in which to hold cache entities. Accepted values are: off, memory, and redis.

Allowed values:memoryoffredis

Default:off

calloutsarray[object]required

A collection of callout objects, where each object represents an HTTP request made in the context of a proxy request.

Hide Child Parameters
cacheobjectrequired

Callout caching configuration.

Hide Child Parameters
bypassboolean

If true, skips caching the callout response.

Default:false

depends_onarray[string]

An array of callout names the current callout depends on. This dependency list determines the callout execution order via a topological sorting algorithm.

Default:[]

namestringrequired

A string identifier for a callout. A callout object is referenceable via its name in the kong.ctx.shared.callouts.<name>

requestobjectrequired

The customizations for the callout request.

Hide Child Parameters
bodyobjectrequired

Callout request body customizations.

Show Child Parameters
by_luastring

Lua code that executes before the callout request is made. Warning can impact system behavior. Standard Lua sandboxing restrictions apply.

errorobjectrequired

The error handling policy the plugin will apply to TCP and HTTP errors.

Show Child Parameters
headersobjectrequired

Callout request header customizations.

Show Child Parameters
http_optsobjectrequired

HTTP connection parameters.

Show Child Parameters
methodstring

The HTTP method that will be requested.

Match pattern:^[A-Z]+$

Default:GET

queryobjectrequired

Callout request query param customizations.

Show Child Parameters
urlstringrequired

The URL that will be requested.
This field is referenceable.

responseobjectrequired

Configurations of callout response handling.

Hide Child Parameters
bodyobjectrequired
Show Child Parameters
by_luastring

Lua code that executes after the callout response is received, before caching takes place. Can produce side effects. Standard Lua sandboxing restrictions apply.

headersobjectrequired

Callout response header customizations.

Show Child Parameters
upstreamobject

Customizations to the upstream request.

Hide Child Parameters
bodyobject

Callout request body customizations.

Hide Child Parameters
customobject

The custom body fields to be added in the upstream request body. Values can contain Lua expressions in the form $(some_lua_expression). The syntax is based on request-transformer-advanced templates.

* Additional properties are allowed.
decodeboolean

If true, decodes the request’s body to make it available for upstream by_lua customizations. Only JSON content type is supported.

Default:true

forwardboolean

If false, skips forwarding the incoming request’s body to the upstream request.

Default:true

by_luastring

Lua code that executes before the upstream request is made. Can produce side effects. Standard Lua sandboxing restrictions apply.

headersobject

Callout request header customizations.

Hide Child Parameters
customobject

The custom headers to be added in the upstream HTTP request. Values can contain Lua expressions in the form $(some_lua_expression). The syntax is based on request-transformer-advanced templates.

* Additional properties are allowed.
forwardboolean

If false, does not forward request headers to upstream request.

Default:true

queryobject

Upstream request query param customizations.

Hide Child Parameters
customobject

The custom query params to be added in the upstream HTTP request. Values can contain Lua expressions in the form $(some_lua_expression). The syntax is based on request-transformer-advanced templates.

* Additional properties are allowed.
forwardboolean

If false, does not forward request query params to upstream request.

Default:true

consumerobject

If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
consumer_groupobject

If set, the plugin will activate only for requests where the specified consumer group has been authenticated. (Note that some plugins can not be restricted to consumers groups this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer Groups

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
protocolsarray[string]

A set of strings representing HTTP protocols.

Allowed values:grpcgrpcshttphttps

Default:grpc, grpcs, http, https

routeobject

If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
serviceobject

If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!