Documenting Kong-owned plugins

Plugin documentation is posted on the Plugin Hub. All Kong plugin docs must follow a specific template.

Looking for instructions on submitting a partner plugin? See the Partner Plugins guide.

Prerequisites

You have a parallel plugin PR in one of the Kong source code repositories.
You plugin has description for every config parameter field in its Lua schema file.
You have set up a local clone of the docs repository.

Add a new plugin doc

In your local clone of the docs repository, create a new branch for your plugin.
Create a subdirectory for the plugin within the _app/_hub/kong-inc directory. For example, _app/_hub/kong-inc/your-plugin.

Copy the contents of the /docs/templates/kong-plugin-template directory into your own plugin’s directory.

You should now have a directory that looks like this:

 _app
   _hub
     kong-inc
       example-plugin
         how-to
           _index.md
         _changelog.md
         overview
           _index.md
         _metadata
           _index.yml
         versions.yml

Populate the files in the directory with your own info:
- _metadata/_index.yml: Sets the metadata for the plugin. Follow the instructions in the file to fill it out.
- overview/_index.md: Introduction for your plugin. This is where you explain how the plugin works and why someone would want to use it.
- _changelog.md: A changelog for your plugin. For the first entry, just note when the plugin was published.
- how-to/_index.md: Markdown documentation on how to use the plugin. You can create any number of files in the how-to folder, e.g. how-to/_getting-started.md, how-to/_metrics.md, etc.
- versions.yml: Set the Kong Gateway version that the plugin is introduced in. This will generate a doc for every subsequent gateway version, starting with the one you specify.
Add an icon for your plugin into the /app/assets/images/icons/hub directory.

Plugin icons are required for publication on the Kong plugin hub. Icons should be a PNG or SVG file, 120x120 pixels in size.

The filename of your image should be kong-inc_plugin-name. For example, kong-inc_oas-validation.
Create a basic example for your plugin in the plugin toolkit repository.

This example will be validated against the plugin’s schema, so make sure to include all required configuration parameters.

Adding images

If you have any diagrams or screenshots that you want to add to your plugin documentation:

Add to the images into the app/_assets/images/docs/plugins directory.

Make sure that any screenshots follow the screenshot guidelines.

Insert images into any of the markdown files for your plugin using the following format:

 ![Authentication flow diagram](/assets/images/docs/plugins/my-plugin-auth-flow.png)
 > *Figure 1: Diagram showing an OAuth2 authentication flow with Keycloak.*

Adding plugin examples

You can use plugin_example to easily define and format examples using the plugin.

The example accepts all plugin config, and you can configure it to output any combination of targets and formats that you need.

Possible targets:

service
route
consumer
consumer_group
global

Possible formats:

curl
konnect
yaml
kubernetes
terrafrom

Here’s an example of how to format plugin_example using OpenAI and AI Semantic Cache:

{% plugin_example %}
title: OpenAI Example
plugin: kong-inc/ai-semantic-cache
name: ai-semantic-cache
config:
  embeddings:
    auth:
      header_name: Authorization
      header_value: Bearer OPENAI_API_KEY
  model:
    provider: openai
    name: text-embedding-3-large
    options:
      upstream_url: https://api.openai.com/v1/embeddings
  vectordb:
    dimensions: 3072
    distance_metric: cosine
    strategy: redis
    threshold: 0.1
    redis:
      host: redis-stack.redis.svc.cluster.local
      port: 6379
targets:
  - route
formats:
  - curl
  - konnect
  - yaml
  - kubernetes
  - terraform
{% endplugin_example %}

And here’s how that example would render:

OpenAI Example

Enable on a route

Kong Admin API

Konnect API

Kubernetes

Declarative (YAML)

Make the following request:

curl -X POST http://localhost:8001/routes/{routeName|Id}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "ai-semantic-cache",
  "config": {
    "embeddings": {
      "auth": {
        "header_name": "Authorization",
        "header_value": "Bearer OPENAI_API_KEY"
      }
    },
    "model": {
      "provider": "openai",
      "name": "text-embedding-3-large",
      "options": {
        "upstream_url": "https://api.openai.com/v1/embeddings"
      }
    },
    "vectordb": {
      "dimensions": 3072,
      "distance_metric": "cosine",
      "strategy": "redis",
      "threshold": 0.1,
      "redis": {
        "host": "redis-stack.redis.svc.cluster.local",
        "port": 6379
      }
    }
  }
}
    '

Replace ROUTE_NAME|ID with the id or name of the route that this plugin configuration will target.

Make the following request, substituting your own access token, region, control plane ID, and route ID:

curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer TOKEN" \
    --data '{"name":"ai-semantic-cache","config":{"embeddings":{"auth":{"header_name":"Authorization","header_value":"Bearer OPENAI_API_KEY"}},"model":{"provider":"openai","name":"text-embedding-3-large","options":{"upstream_url":"https://api.openai.com/v1/embeddings"}},"vectordb":{"dimensions":3072,"distance_metric":"cosine","strategy":"redis","threshold":0.1,"redis":{"host":"redis-stack.redis.svc.cluster.local","port":6379}}}}'

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

First, create a KongPlugin resource:

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: ai-semantic-cache-example
plugin: ai-semantic-cache
config:
  embeddings:
    auth:
      header_name: Authorization
      header_value: Bearer OPENAI_API_KEY
  model:
    provider: openai
    name: text-embedding-3-large
    options:
      upstream_url: https://api.openai.com/v1/embeddings
  vectordb:
    dimensions: 3072
    distance_metric: cosine
    strategy: redis
    threshold: 0.1
    redis:
      host: redis-stack.redis.svc.cluster.local
      port: 6379
" | kubectl apply -f -

Next, apply the KongPlugin resource to an ingress by annotating the ingress as follows:

kubectl annotate ingress INGRESS_NAME konghq.com/plugins=ai-semantic-cache-example

Replace INGRESS_NAME with the name of the ingress that this plugin configuration will target. You can see your available ingresses by running kubectl get ingress.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: ai-semantic-cache
  route: ROUTE_NAME|ID
  config:
    embeddings:
      auth:
        header_name: Authorization
        header_value: Bearer OPENAI_API_KEY
    model:
      provider: openai
      name: text-embedding-3-large
      options:
        upstream_url: https://api.openai.com/v1/embeddings
    vectordb:
      dimensions: 3072
      distance_metric: cosine
      strategy: redis
      threshold: 0.1
      redis:
        host: redis-stack.redis.svc.cluster.local
        port: 6379

Replace ROUTE_NAME|ID with the id or name of the route that this plugin configuration will target.

Test and submit plugin

Run the docs site locally per the instructions in the docs README.

You should find your Hub contribution listed at localhost:3000/hub.
Once you are happy with your listing, push your branch to the GitHub repository:
```
 git push --set-upstream origin [name_of_your_new_branch]
```
Make a pull request against the docs.konghq.com repository to add your documentation to the Plugin Hub.

The Kong docs team will review your PR, suggest improvements and adjustments as necessary, and once approved, will merge and deploy your Plugin Hub addition!

Custom plugins and documentation

If you want to write a custom plugin for your own needs, start by reading the Plugin Development Guide.

If you already wrote a plugin, and are thinking about making it available to the community, we strongly encourage you to host it on a publicly available repository (like GitHub), and distribute it via LuaRocks. A good resource on how to do so is the distribution section of the Plugin Development Guide.

To give visibility to your plugin, you can create a post in the Announcements category of Kong Nation.

If you’re interested in becoming a technical partner and publishing your plugin on the Kong Plugin Hub, please reach out to our Kong Partners team.