Partials

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

What is a Partial?

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.

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

Schema

* Additional properties are NOT allowed.

One Of

configobjectrequired

Hide Child Parameters

databaseinteger

Database to use for the Redis connection when using the redis strategy

Default:0

hoststring

A string representing a host name, such as example.com.

passwordstring

Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.

portinteger

An integer representing a port number between 0 and 65535, inclusive.

Default:6379

>= 0<= 65535

server_namestring

A string representing an SNI (server name indication) value for TLS.

sslboolean

If set to true, uses SSL to connect to Redis.

Default:false

ssl_verifyboolean

If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

Default:false

timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

usernamestring

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

created_atinteger

Unix epoch when the resource was created.

idstring

A string representing a UUID (universally unique identifier).

namestring

A unique string representing a UTF-8 encoded name.

tagsarray[string]

A string representing a tag.

typestringrequired

Allowed values:redis-ce

updated_atinteger

Unix epoch when the resource was last updated.

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

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

Did this doc help?

Help us make these docs great!

Still need help