Partials

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

What is a Partial?

Partials allow you to reuse shared configuration across plugins.

Some plugins in Kong Gateway share common 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 Partial types:

redis-ce: A short and simple Redis configuration.
redis-ee: A Redis configuration with support for Redis Sentinel or Redis Cluster connections.
vectordb v3.13+: Vector database connection and search settings, shared across AI plugins that perform semantic search.
embeddings v3.13+: Embeddings model provider and authentication, shared across AI plugins that generate vector embeddings.
model v3.13+: LLM provider, model name, authentication, and inference settings, shared across AI plugins that call language models.

Each plugin supports only the Partial types listed in its documentation.

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

Redis Partials

Define a Redis Partial once and reference it across plugins to avoid repeating connection details, reduce configuration errors, and ensure consistent Redis behavior. 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.

Set up a Redis 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.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.

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.

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.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.

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:
  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.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.

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:
  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.

AI plugin Partials v3.13+

AI Gateway plugins often share the same vector database, embeddings model, or LLM configuration across multiple plugins. For example, you might run both the AI Semantic Cache plugin and the AI RAG Injector plugin against the same pgvector database using the same OpenAI embeddings model. Without Partials, you would need to define this configuration in each plugin individually.

With AI Partials, define the shared configuration once and link it to any number of plugins.

Partial type	Supported plugins
`vectordb`	AI Semantic Cache, AI RAG Injector, AI Semantic Prompt Guard, AI Semantic Response Guard
`embeddings`	AI Semantic Cache, AI RAG Injector, AI Semantic Prompt Guard, AI Semantic Response Guard
`model`	AI Proxy Advanced, AI Request Transformer, AI Response Transformer, AI LLM as Judge

The AI Proxy Advanced plugin supports all three AI Partial types. A model Partial applies to each entry in the config.targets array, so you can share one provider configuration across multiple targets.

Set up AI Partials

The following examples use OpenAI as the embeddings and model provider, and pgvector as the vector database. You’ll need an OpenAI API key and a running pgvector instance.

VectorDB Partial (pgvector)

Create a Partial with type: vectordb:

kong.yaml

Copied!

_format_version: "3.0"
partials:
  - name: shared-vectordb
    type: vectordb
    config:
      strategy: pgvector
      dimensions: 1536
      distance_metric: cosine
      pgvector:
        host: ${{ env "DECK_PGVECTOR_HOST" }}
        port: 5432
        database: kong-pgvector
        user: postgres
        password: ${{ env "DECK_PGVECTOR_PASSWORD" }}

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": "shared-vectordb",
      "type": "vectordb",
      "config": {
        "strategy": "pgvector",
        "dimensions": 1536,
        "distance_metric": "cosine",
        "pgvector": {
          "host": "'$PGVECTOR_HOST'",
          "port": 5432,
          "database": "kong-pgvector",
          "user": "postgres",
          "password": "'$PGVECTOR_PASSWORD'"
        }
      }
    }
    '

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": "shared-vectordb",
      "type": "vectordb",
      "config": {
        "strategy": "pgvector",
        "dimensions": 1536,
        "distance_metric": "cosine",
        "pgvector": {
          "host": "${pgvector_host}",
          "port": 5432,
          "database": "kong-pgvector",
          "user": "postgres",
          "password": "${pgvector_password}"
        }
      }
    }
    '

Copied!

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

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

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: shared-vectordb
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
name: shared-vectordb
type: vectordb
config:
  strategy: pgvector
  dimensions: 1536
  distance_metric: cosine
  pgvector:
    host: '$PGVECTOR_HOST'
    port: 5432
    database: kong-pgvector
    user: postgres
    password: '$PGVECTOR_PASSWORD'
" | 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 = "vectordb"
  config = {
    strategy = "pgvector"
    dimensions = 1536
    distance_metric = "cosine"

    pgvector = {
      host = var.pgvector_host
      port = 5432
      database = "kong-pgvector"
      user = "postgres"
      password = var.pgvector_password
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

Embeddings Partial (OpenAI)

Create a Partial with type: embeddings:

kong.yaml

Copied!

_format_version: "3.0"
partials:
  - name: shared-embeddings
    type: embeddings
    config:
      auth:
        header_name: Authorization
        header_value: Bearer ${{ env "DECK_OPENAI_API_KEY" }}
      model:
        provider: openai
        name: text-embedding-3-small

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": "shared-embeddings",
      "type": "embeddings",
      "config": {
        "auth": {
          "header_name": "Authorization",
          "header_value": "Bearer '$OPENAI_API_KEY'"
        },
        "model": {
          "provider": "openai",
          "name": "text-embedding-3-small"
        }
      }
    }
    '

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": "shared-embeddings",
      "type": "embeddings",
      "config": {
        "auth": {
          "header_name": "Authorization",
          "header_value": "Bearer ${openai_api_key}"
        },
        "model": {
          "provider": "openai",
          "name": "text-embedding-3-small"
        }
      }
    }
    '

Copied!

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

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

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: shared-embeddings
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
name: shared-embeddings
type: embeddings
config:
  auth:
    header_name: Authorization
    header_value: Bearer $OPENAI_API_KEY
  model:
    provider: openai
    name: text-embedding-3-small
" | 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 = "embeddings"
  config = {

    auth = {
      header_name = "Authorization"
      header_value = "Bearer var.openai_api_key"
    }

    model = {
      provider = "openai"
      name = "text-embedding-3-small"
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

Model Partial (OpenAI GPT-4o)

Create a Partial with type: model:

kong.yaml

Copied!

_format_version: "3.0"
partials:
  - name: shared-llm
    type: model
    config:
      route_type: llm/v1/chat
      auth:
        header_name: Authorization
        header_value: Bearer ${{ env "DECK_OPENAI_API_KEY" }}
      model:
        provider: openai
        name: gpt-5.1

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": "shared-llm",
      "type": "model",
      "config": {
        "route_type": "llm/v1/chat",
        "auth": {
          "header_name": "Authorization",
          "header_value": "Bearer '$OPENAI_API_KEY'"
        },
        "model": {
          "provider": "openai",
          "name": "gpt-5.1"
        }
      }
    }
    '

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": "shared-llm",
      "type": "model",
      "config": {
        "route_type": "llm/v1/chat",
        "auth": {
          "header_name": "Authorization",
          "header_value": "Bearer ${openai_api_key}"
        },
        "model": {
          "provider": "openai",
          "name": "gpt-5.1"
        }
      }
    }
    '

Copied!

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

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

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: shared-llm
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
name: shared-llm
type: model
config:
  route_type: llm/v1/chat
  auth:
    header_name: Authorization
    header_value: Bearer $OPENAI_API_KEY
  model:
    provider: openai
    name: gpt-5.1
" | 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 = "model"
  config = {
    route_type = "llm/v1/chat"

    auth = {
      header_name = "Authorization"
      header_value = "Bearer var.openai_api_key"
    }

    model = {
      provider = "openai"
      name = "gpt-5.1"
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

Link AI Partials to plugins

Once created, link AI Partials to plugins the same way as Redis Partials: pass the Partial ID in the partials array. See Add a Partial to a plugin.

You cannot provide inline configuration for the same fields that a linked Partial covers. Either define the settings directly in the plugin, or leave that block empty and use a Partial instead.

Enable Partials support in custom plugins

Use 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?

Redis Partials

Set up a Redis Partial

Add a Partial to a plugin

Remove a Partial from a plugin

Check Partial usage

AI plugin Partials v3.13+

Set up AI Partials

VectorDB Partial (pgvector)

Embeddings Partial (OpenAI)

Model Partial (OpenAI GPT-4o)

Link AI Partials to plugins

Enable Partials support in custom plugins

Schema

Help us make these docs great!

Still need help?