Partials

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

What is a Partial?

Partials allow you to reuse shared Redis configurations across plugins.

Some plugins in Kong Gateway share common Redis configuration settings that often need to be repeated. Partials allow you to extract those shared configurations into reusable entities that can be linked to multiple plugins. Without Partials, you would need to replicate this configuration across all plugins. If the settings change, you would need to update each plugin individually.

To ensure validation and consistency, Partials have defined types. Kong Gateway supports the following types of Partials; each plugin supports only one type:

redis-ce: A short and simple configuration.
redis-ee: A configuration with support for Redis Sentinel or Redis Cluster connections.

Any plugin that supports Redis configuration can reference those settings using Partial entities, enabling shared configuration across plugin instances.

In Konnect, Partials are only supported for bundled Konnect plugins. Custom plugins don’t support Partials.

Schema

Set up a Partial

kong.yaml

Copied!

_format_version: "3.0"
partials:
  - name: my-redis-config
    type: redis-ee
    config:
      host: host.docker.internal
      port: 6379

To create a Partial, call the Admin API’s /partials endpoint.

curl -i -X POST http://localhost:8001/partials/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "my-redis-config",
      "type": "redis-ee",
      "config": {
        "host": "host.docker.internal",
        "port": 6379
      }
    }
    '

Copied!

To create a Partial, call the Konnect control plane config API’s /partials endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/partials/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "my-redis-config",
      "type": "redis-ee",
      "config": {
        "host": "host.docker.internal",
        "port": 6379
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPartial
metadata:
  name: my-redis-config
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
name: my-redis-config
type: redis-ee
config:
  host: host.docker.internal
  port: 6379
" | kubectl apply -f -

Copied!

Prerequisite: Configure your Personal Access Token

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

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

Copied!

resource "konnect_gateway_partial" "my_partial" {
  type = "redis-ee"
  config = {
    host = "host.docker.internal"
    port = 6379
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

The following creates a new Partial called my-redis-config:

Navigate to your Gateway instance:
- In Konnect, open API Gateway from the sidebar, then choose a control plane.
- In Kong Manager, select your Workspace.
Navigate to Redis Configurations.
Click New configuration.
Select the Redis type Host/Port (Enterprise).
Enter the Name my-redis-config.
Enter the Host host.docker.internal and Port 6379.
Click Save.

Use Partials

By defining a Redis Partial once and then referencing it across these plugins, you avoid repeating connection details, reduce configuration errors, and ensure consistent Redis behaviour throughout your gateway. The following plugins use Redis for storing counters, sessions, or cached data:

Plugin Name	Redis Usage (What’s Stored)	Partial type	Benefit of using a Partial
ACME	Certificate state (Let’s Encrypt ACME data)	`redis-ce`	Keep certificate state storage consistent across environments by reusing one Redis config.
GraphQL Proxy Caching Advanced	Cached GraphQL responses	`redis-ee`	Apply the same Redis configuration to multiple GraphQL caches for easier management.
GraphQL Rate Limiting Advanced	GraphQL request counters	`redis-ee`	Standardise Redis-based GraphQL rate limiting across endpoints with one Partial.
OpenID Connect	Sessions and tokens	`redis-ee`	Reuse Redis settings for session storage, avoiding redundant configs across identity flows.
Proxy Caching Advanced	Cached API responses	`redis-ee`	Reuse a single Redis definition to simplify and stabilise cache behaviour.
Rate Limiting	Request counters	`redis-ce`	Apply the same Redis setup across multiple rate limiting policies without duplication.
Rate Limiting Advanced	Request counters (supports Sentinel/Cluster)	`redis-ee`	Centralize complex Redis HA configuration so all services use it reliably.
Response Rate Limiting	Response counters	`redis-ce`	Ensure consistent Redis-backed throttling rules across different services.
SAML	Session data	`redis-ee`	Centralize session handling so all SAML flows share the same Redis configuration.

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:

Add this section to your kong.yaml configuration file:

kong.yaml

Copied!

_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

Make the following request:

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
            ]
          }
        ]
      }
    }
    '

Copied!

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "ai-rate-limiting-advanced",
      "partials": [
        {
          "id": "602317b0-9503-45c1-bcbf-c69f13155b49"
        }
      ],
      "config": {
        "llm_providers": [
          {
            "name": "openai",
            "limit": [
              100
            ],
            "window_size": [
              60
            ]
          }
        ]
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

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 -

Copied!

Prerequisite: Configure your Personal Access Token

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

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

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

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
}

Copied!

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:

Add this section to your kong.yaml configuration file:

kong.yaml

Copied!

_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

Make the following request:

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
        }
      }
    }
    '

Copied!

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "ai-rate-limiting-advanced",
      "config": {
        "llm_providers": [
          {
            "name": "openai",
            "limit": [
              100
            ],
            "window_size": [
              60
            ]
          }
        ],
        "redis": {
          "host": "localhost",
          "port": 6379
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

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 -

Copied!

Prerequisite: Configure your Personal Access Token

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

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

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

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
}

Copied!

Check Partial usage

To see which plugins use a specific Partial:

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

Enable Partials support in custom plugins

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 }
        },
      },
    },
  },
}

Copied!

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

Partials

What is a Partial?

Schema

Set up a Partial

Use Partials

Add a Partial to a plugin

Remove a Partial from a plugin

Check Partial usage

Enable Partials support in custom plugins

Help us make these docs great!

Still need help