このページは、まだ日本語ではご利用いただけません。翻訳中です。
構成
このプラグインはDB-lessモードと部分的に互換性があります。
The cluster strategy is not supported in DB-less and hybrid modes. For Kong
Gateway in DB-less or hybrid mode, the redis
strategy is the only available option to configure the plugin with a central data store.
Note: We recommend setting
namespace
to a static value in DB-less mode. Thenamespace
will be regenerated on every configuration change if not explicitly set, resetting counters to zero.
互換性のあるプロトコル
Rate Limiting Advancedプラグインは以下のプロトコルに対応しています:
grpc
, grpcs
, http
, https
パラメータ
このプラグインの設定で使用できるすべてのパラメータのリストは次のとおりです。
-
name or plugin
string requiredプラグイン名。この場合は
rate-limiting-advanced
。- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
name
です。 - Kubernetes で KongPlugin オブジェクトを使用する場合、フィールドは
plugin
です。
- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
-
instance_name
stringプラグインのインスタンスを識別するための任意のカスタム名 (例:
rate-limiting-advanced_my-service
。インスタンス名はKong ManagerとKonnectに表示されるので、 例えば複数のサービスで同じプラグインを複数のコンテキストで実行する場合に便利です。また、Kong Admin API経由で特定のプラグインインスタンスに アクセスするためにも使用できます。
インスタンス名は、次のコンテキスト内で一意である必要があります。
- Kong Gateway Enterpriseのワークスペース内
- Konnectのコントロールプレーン(CP)またはコントロールプレーン(CP)グループ内
- Kong Gateway (OSS)の全世界
-
service.name or service.id
stringプラグインが対象とするサービス名または ID。最上位の
/plugins
エンドポイント. からプラグインをサービスに追加する場合は、これらのパラメータのいずれかを設定してください/services/{serviceName|Id}/plugins
を使用する場合は必要ありません。 -
route.name or route.id
stringプラグインがターゲットとするルート名または ID。最上位の
/plugins
エンドポイント. を通るルートにプラグインを追加する場合は、これらのパラメータのいずれかを設定してください/routes/{routeName|Id}/plugins
を使用する場合は必要ありません。 -
consumer.name or consumer.id
stringプラグインがターゲットとするコンシューマーの名前または ID。 最上位の
/plugins
エンドポイント. からコンシューマーにプラグインを追加する場合は、これらのパラメーターのいずれかを設定してください/consumers/{consumerName|Id}/plugins
を使用する場合は必要ありません。 -
consumer_group.name or consumer_group.id
stringプラグインが対象とするコンシューマグループの名前または ID。 設定されている場合、プラグインは指定されたグループが認証されているリクエストに対してのみアクティブになります
/plugins
エンドポイント./consumer_groups/{consumerGroupName|Id}/plugins
を使用する場合は必要ありません。 -
enabled
boolean default:true
このプラグインが適用されるかどうか。
-
config
record required-
identifier
string required default:consumer
Must be one of:ip
,credential
,consumer
,service
,header
,path
,consumer-group
The type of identifier used to generate the rate limit key. Defines the scope used to increment the rate limiting counters. Can be
ip
,credential
,consumer
,service
,header
,path
orconsumer-group
.
-
compound_identifier
array of typestring
Must be one of:ip
,credential
,consumer
,service
,header
,path
,consumer-group
Similar to
identifer
, but supports combining multiple items. The priority ofcompound_identifier
is higher thanidentifier
, which means ifcompound_identifer
is set, it will be used, otherwiseidentifier
will be used.
-
window_size
array of typenumber
requiredOne or more window sizes to apply a limit to (defined in seconds). There must be a matching number of window limits and sizes specified.
-
window_type
string default:sliding
Must be one of:fixed
,sliding
Sets the time window type to either
sliding
(default) orfixed
. Sliding windows apply the rate limiting logic while taking into account previous hit rates (from the window that immediately precedes the current) using a dynamic weight. Fixed windows consist of buckets that are statically assigned to a definitive time range, each request is mapped to only one fixed window based on its timestamp and will affect only that window’s counters.
-
limit
array of typenumber
requiredOne or more requests-per-window limits to apply. There must be a matching number of window limits and sizes specified.
-
sync_rate
numberHow often to sync counter data to the central data store. A value of 0 results in synchronous behavior; a value of -1 ignores sync behavior entirely and only stores counters in node memory. A value greater than 0 will sync the counters in the specified number of seconds. The minimum allowed interval is 0.02 seconds (20ms).
-
namespace
string requiredThe rate limiting library namespace to use for this plugin instance. Counter data and sync configuration is isolated in each namespace. NOTE: For the plugin instances sharing the same namespace, all the configurations that are required for synchronizing counters, e.g.
strategy
,redis
,sync_rate
,dictionary_name
, need to be the same.
-
strategy
string required default:local
Must be one of:cluster
,redis
,local
The rate-limiting strategy to use for retrieving and incrementing the limits. Available values are:
local
andcluster
.
-
dictionary_name
string required default:kong_rate_limiting_counters
The shared dictionary where counters are stored. When the plugin is configured to synchronize counter data externally (that is
config.strategy
iscluster
orredis
andconfig.sync_rate
isn’t-1
), this dictionary serves as a buffer to populate counters in the data store on each synchronization cycle.
-
lock_dictionary_name
string required default:kong_locks
The shared dictionary where concurrency control locks are stored. The default shared dictionary is
kong_locks
. The shared dictionary should be declare in nginx-kong.conf.
-
hide_client_headers
boolean default:false
Optionally hide informative response headers that would otherwise provide information about the current status of limits and counters.
-
retry_after_jitter_max
number default:0
The upper bound of a jitter (random delay) in seconds to be added to the
Retry-After
header of denied requests (status =429
) in order to prevent all the clients from coming back at the same time. The lower bound of the jitter is0
; in this case, theRetry-After
header is equal to theRateLimit-Reset
header.
-
header_name
stringA string representing an HTTP header name.
-
path
string starts_with:/
A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).
-
redis
record required-
host
string default:127.0.0.1
A string representing a host name, such as example.com.
-
port
integer default:6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
connect_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
send_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
read_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
username
string referenceableUsername 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
.
-
password
string referenceable encryptedPassword to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
-
sentinel_username
string referenceableSentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
-
sentinel_password
string referenceable encryptedSentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
-
database
integer default:0
Database to use for the Redis connection when using the
redis
strategy
-
keepalive_pool_size
integer default:256
between:1
2147483646
The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither
keepalive_pool_size
norkeepalive_backlog
is specified, no pool is created. Ifkeepalive_pool_size
isn’t specified butkeepalive_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.
-
keepalive_backlog
integer between:0
2147483646
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 thankeepalive_pool_size
. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger thankeepalive_pool_size
.
-
sentinel_master
stringSentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
-
sentinel_role
string Must be one of:master
,slave
,any
Sentinel role to use for Redis connections when the
redis
strategy is defined. Defining this value implies using Redis Sentinel.
-
sentinel_nodes
array of typerecord
len_min:1
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.-
host
string required default:127.0.0.1
A string representing a host name, such as example.com.
-
port
integer default:6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
-
cluster_nodes
array of typerecord
len_min:1
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.-
ip
string required default:127.0.0.1
A string representing a host name, such as example.com.
-
port
integer default:6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
-
ssl
boolean default:false
If set to true, uses SSL to connect to Redis.
-
ssl_verify
boolean default:false
If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure
lua_ssl_trusted_certificate
inkong.conf
to specify the CA (or server) certificate used by your Redis server. You may also need to configurelua_ssl_verify_depth
accordingly.
-
server_name
stringA string representing an SNI (server name indication) value for TLS.
-
cluster_max_redirections
integer default:5
Maximum retry attempts for redirection.
-
connection_is_proxied
boolean default:false
If the connection to Redis is proxied (e.g. Envoy), set it
true
. Set thehost
andport
to point to the proxy address.
-
redis_proxy_type
string Must be one of:envoy_v1.31
If the
connection_is_proxied
is enabled, this field indicates the proxy type and version you are using. For example, you can enable this optioin when you want authentication between Kong and Envoy proxy.
-
-
enforce_consumer_groups
boolean default:false
Determines if consumer groups are allowed to override the rate limiting settings for the given Route or Service. Flipping
enforce_consumer_groups
fromtrue
tofalse
disables the group override, but does not clear the list of consumer groups. You can then flipenforce_consumer_groups
totrue
to re-enforce the groups.
-
consumer_groups
array of typestring
List of consumer groups allowed to override the rate limiting settings for the given Route or Service. Required if
enforce_consumer_groups
is set totrue
.
-
disable_penalty
boolean default:false
If set to
true
, this doesn’t count denied requests (status =429
). If set tofalse
, all requests, including denied ones, are counted. This parameter only affects thesliding
window_type.
-
error_code
number default:429
Set a custom error code to return when the rate limit is exceeded.
-
error_message
string default:API rate limit exceeded
Set a custom error message to return when the rate limit is exceeded.
-