Partials

Some entities in Kong Gateway share common configuration settings that often need to be repeated. For example, multiple plugins that connect to Redis may require the same connection settings. Without Partials, you would need to replicate this configuration across all plugins. If the settings change, you would need to update each plugin individually.

Partials address this issue by allowing you to extract shared configurations into reusable entities that can be linked to multiple plugins. To ensure validation and consistency, Partials have defined types.

Kong Gateway supports the following types of Partials, redis-ce and redis-ee. redis-ce has a shorter and simpler configuration, whereas redis-ee provides options for configuring Redis Sentinel or Redis Cluster connections. Each plugin that supports Partials only supports one of these types.

The following examples describe how to use Partials with plugins.

Add a Partial to a plugin

To use a Partial in a plugin, configure the partials.id parameter:

_format_version: "3.0"
plugins:
  - name: ai-rate-limiting-advanced
    partials:
    - id: 602317b0-9503-45c1-bcbf-c69f13155b49
    config:
      llm_providers:
      - name: openai
        limit:
        - 100
        window_size:
        - 60

curl -i -X POST http://localhost:8001/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "ai-rate-limiting-advanced",
      "partials": [
        {
          "id": "602317b0-9503-45c1-bcbf-c69f13155b49"
        }
      ],
      "config": {
        "llm_providers": [
          {
            "name": "openai",
            "limit": [
              100
            ],
            "window_size": [
              60
            ]
          }
        ]
      }
    }
    '

echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: ai-rate-limiting-advanced
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: 'true'
partials:
- id: 602317b0-9503-45c1-bcbf-c69f13155b49
config:
  llm_providers:
  - name: openai
    limit:
    - 100
    window_size:
    - 60
plugin: ai-rate-limiting-advanced
" | kubectl apply -f -

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_plugin_ai_rate_limiting_advanced" "my_ai_rate_limiting_advanced" {
  enabled = true

  partials = [
    {
      id = "602317b0-9503-45c1-bcbf-c69f13155b49"
    }  ]
  config = {
    llm_providers = [
      {
        name = "openai"
        limit = [100]
        window_size = [60]
      }    ]
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Remove a Partial from a plugin

To remove a Partial, remove the partials parameter. Make sure to configure the corresponding elements directly in your plugin configuration:

_format_version: "3.0"
plugins:
  - name: ai-rate-limiting-advanced
    config:
      llm_providers:
      - name: openai
        limit:
        - 100
        window_size:
        - 60
      redis:
        host: localhost
        port: 6379

curl -i -X POST http://localhost:8001/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "ai-rate-limiting-advanced",
      "config": {
        "llm_providers": [
          {
            "name": "openai",
            "limit": [
              100
            ],
            "window_size": [
              60
            ]
          }
        ],
        "redis": {
          "host": "localhost",
          "port": 6379
        }
      }
    }
    '

echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: ai-rate-limiting-advanced
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: 'true'
config:
  llm_providers:
  - name: openai
    limit:
    - 100
    window_size:
    - 60
  redis:
    host: localhost
    port: 6379
plugin: ai-rate-limiting-advanced
" | kubectl apply -f -

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_plugin_ai_rate_limiting_advanced" "my_ai_rate_limiting_advanced" {
  enabled = true

  config = {
    llm_providers = [
      {
        name = "openai"
        limit = [100]
        window_size = [60]
      }    ]

    redis = {
      host = "localhost"
      port = 6379
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Check Partial usage

To see which plugins use a specific Partial:

1. Use GET /partials/ to get the list of Partials, and get the ID of the Partial to check.
2. Use GET /partials/$PARTIAL_ID to get a list of plugins that use this Partial.

You can leverage the Partials feature in your custom plugins by adjusting the plugin schema. To make custom plugins compatible with Partials, add the supported_partials key to the schema and specify the appropriate Partial type.

Here is an example schema for a custom plugin using a Partial:

{
  name = "custom-plugin-with-redis",
  supported_partials = {
    ["redis-ee"] = { "config.redis" },
  },
  fields = {
    {
      config = {
        type = "record",
        fields = {
          { some_other_config_key = { type = "string", required = true }},
          { redis = redis.config_schema }
        },
      },
    },
  },
}

Using DAO in custom plugins

Be aware that when using a Partial, the configuration belonging to the Partial is no longer stored alongside the plugin. If your code relies on Kong Gateway’s DAO and expects entities to contain Redis information, this data won’t be retrieved when using kong.db.plugins:select(plugin_id). Such a call will only fetch data stored in the plugin itself.

To include the Partial’s data within the plugin configuration, you must pass a special option parameter, such as: kong.db.plugins:select(plugin_id, { expand_partials = true }).