Home / How-to Guides
Edit
Report

Configure dynamic plugin config with CEL in Kong Gateway

Uses: Kong Gateway Kong Identity Konnect API
Incompatible with
on-prem
Related Documentation
Gateway Documentation
Tags
#traffic-control #authentication
Related Resources
Dynamic plugin config with CEL
CEL expressions for plugins
Rate Limiting Advanced plugin
Minimum Version
Kong Gateway - 3.16
TL;DR

To compute a plugin’s config from a CEL expression instead of a fixed value, set a config field’s parallel expressions.FIELD entry to a CEL expression, alongside the field’s ordinary static config.FIELD value. Kong Gateway evaluates the expression per request. If it succeeds, its result overrides the field for that request; if it fails, Kong Gateway falls back to the static config value.

This guide computes Rate Limiting Advanced’s limit and custom_key fields from a Principal’s metadata, so each authenticated client gets their own rate limit and their own counter from a single plugin instance.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

    export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN \
     --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

    export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
export DECK_KONNECT_ADDR=https://us.api.konghq.com
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

  1. Run the following command:

    echo '
_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
    protocols:
    - http
    - https
' | deck gateway apply -

To learn more about entities, you can read our entities documentation.

Kong Identity directory

A directory is a regional collection of principals. A Konnect organization supports only one Kong Identity directory. Create a directory for the tutorial, or look up your existing one.

Create a directory for this tutorial:

DIRECTORY_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "kong-identity-directory",
       "description": "Directory for this tutorial",
       "allow_all_control_planes": true
     }' | jq -r ".id"
)

If you run into 403 errors when trying to create a directory, the directory likely already exists. Look up your existing directory instead.

Konnect API

To use the copy, paste, and run the instructions in this how-to, you need the ID of your control plane.

Look it up using DECK_KONNECT_CONTROL_PLANE_NAME, exported in a previous prerequisite, or substitute the name of your own control plane:

CONTROL_PLANE_ID=$(curl -X GET "https://us.api.konghq.com/v2/control-planes?filter%5Bname%5D%5Beq%5D=$DECK_KONNECT_CONTROL_PLANE_NAME" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].id"
)

Create a Principal

A plugin’s config can be computed per request from a CEL expression, for example, reading an attribute of the authenticated Consumer or Principal, instead of always using a fixed value. In this guide, you’ll create a Principal so that a custom limit can be applied to authenticated Principals. Create the Principal by sending a POST request to the /v2/directories/{directoryId}/principals endpoint:

PRINCIPAL_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "display_name": "example-principal",
       "description": "Example principal"
     }' | jq -r ".id"
)

This script:

  • Creates a Principal named example-principal
  • Saves the returned ID as $PRINCIPAL_ID

Set rate_limit and partner_id metadata on the Principal so the plugin’s expressions have something to read:

curl -X PUT "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "display_name": "example-principal",
       "description": "Example principal",
       "metadata": {
         "rate_limit": 20,
         "partner_id": "acme-rockets"
       }
     }'

Add key auth

Add an API key credential to the Principal so clients can authenticate with Kong Gateway using key authentication.

The following example sets a system-generated key (v1) and stores the key secret as $KEY_SECRET:

KEY_SECRET=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/api-keys" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "type": "v1"
     }' | jq -r ".secret"
)

Get the directory name

 
DECK_DIRECTORY_NAME=$(curl -X GET "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].name"
)

Export the directory name so decK can read it during sync:

export DECK_DIRECTORY_NAME

Configure the Key Auth plugin

Enable the Key Auth plugin so clients can authenticate with an API key, and resolve the authenticated Principal for later plugins to read:

echo '
_format_version: "3.0"
plugins:
  - name: key-auth
    route: example-route
    config:
      identity_realms: []
      principals:
        enabled: true
        directory: "${{ env "DECK_DIRECTORY_NAME" }}"
' | deck gateway apply -

Configure Rate Limiting Advanced with CEL expressions

limit and custom_key are expressible config fields on Rate Limiting Advanced. They both have parallel entries under expressions, alongside their static config values. Configure the plugin globally with:

  • identifier: principal, so the plugin keys and limits by the authenticated Principal.
  • A static config.limit and config.custom_key, used as the fallback whenever a request’s expressions can’t be evaluated.
  • expressions.limit and expressions.custom_key, reading the authenticated Principal’s rate_limit and partner_id metadata.
curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/plugins/" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "rate-limiting-advanced",
       "config": {
         "identifier": "principal",
         "custom_key": "unknown-partner",
         "limit": [
           10
         ],
         "window_size": [
           60
         ],
         "strategy": "local"
       },
       "expressions": {
         "custom_key": "principal.metadata.partner_id",
         "limit": [
           "principal.metadata.rate_limit"
         ]
       }
     }'

Validate

Send a request with the API key stored in $KEY_SECRET:

curl -i -X GET "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: $KEY_SECRET"

Check the RateLimit-Limit response header:

RateLimit-Limit: 20

The limit is now 20 from expressions.limit instead of the static fallback value of 10 from principal.metadata.rate_limit.

To see the static fallback take over, remove the Principal’s rate_limit metadata:

curl -X PUT "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "display_name": "example-principal",
       "description": "Example principal",
       "metadata": {
         "partner_id": "acme-rockets"
       }
     }'

Kong Gateway caches a successfully authenticated Principal for the directory’s configured ttl_secs (5 minutes at minimum, 10 minutes by default). Wait at least 5 minutes after the previous request before continuing, or the next request will still show the cached Principal’s old metadata.

After the ttl has elapsed (5-10 minutes), send another request:

curl -i -X GET "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: $KEY_SECRET"

With rate_limit no longer present on the Principal, expressions.limit fails to evaluate, and Kong Gateway falls back to the static config.limit value of 10:

RateLimit-Limit: 10

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

 
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

What happens if a Principal is missing the metadata that an expression expects to find?

If the Principal is missing expected metadata, the expression fails to evaluate, and Kong Gateway falls back to the field’s static config value for that request. Kong Gateway doesn’t raise an error, and the plugin still runs normally.

Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

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!
Contribute

Still need help?

Ask in our Slack Community
Contact Support