feat(gateway): Streaming and cloning plugins

[lena-larionova]

Description

References and how-to guides for streaming and cloning plugins.
These were logged as one ticket by product but are actually two separate features that use the same env variable to enable them.

Includes a small fix to the Konnect prereq include to add linebreaks when using env variables.

Fixes #5401

To do: check when rc2 comes out, but the config parameter looks like it's changing to custom_plugin_streaming_enabled.

Preview Links

How-to guides:
https://deploy-preview-5445--kongdeveloper.netlify.app/how-to/clone-gateway-plugin/
https://deploy-preview-5445--kongdeveloper.netlify.app/how-to/stream-custom-plugins/

References:
https://deploy-preview-5445--kongdeveloper.netlify.app/custom-plugins/streaming-plugins/
https://deploy-preview-5445--kongdeveloper.netlify.app/gateway/entities/plugin/#cloning-plugins
https://deploy-preview-5445--kongdeveloper.netlify.app/custom-plugins/konnect-hybrid-mode/#streaming-plugins

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	5a0d2ae
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a21ec23a7a14200089c39e7
😎 Deploy Preview	https://deploy-preview-5445--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds Kong Gateway 3.15 documentation for two related capabilities—streaming custom plugins (control plane streams plugin code to data planes) and cloning plugins (run multiple instances of the same plugin with different configs/scopes)—by introducing new reference/how-to pages and extending the Plugin entity reference.

Changes:

• Adds a new reference page for streaming custom plugins and links it from the custom plugins reference/hybrid-mode docs.
• Adds two new how-tos: one for streaming custom plugins (via custom_plugins) and one for cloning a Gateway plugin (via cloned_plugins).
• Extends the Plugin entity reference with a new “Cloning plugins” section and adjusts the Konnect quickstart prereq snippet formatting.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
app/custom-plugins/streaming-plugins.md	New reference page describing streaming custom plugin requirements, limitations, and configuration methods.
app/custom-plugins/reference.md	Adds a related-resource link to the new streaming reference page.
app/custom-plugins/konnect-hybrid-mode.md	Adds a “Streaming plugins” section pointing users to the new reference/how-to.
app/_includes/prereqs/products/konnect.md	Reformats the quickstart command snippet (but currently breaks Liquid expansion due to escaping).
app/_how-tos/gateway/stream-custom-plugins.md	New how-to demonstrating defining and validating streamed custom plugins using decK.
app/_how-tos/gateway/clone-gateway-plugin.md	New how-to demonstrating cloning a plugin and validating behavior across routes.
app/_gateway_entities/plugin.md	Adds “Cloning plugins” reference section, supported list, and an example snippet.

[yijin-kong]

I wonder if you want to mention custom_plugin_streaming_enabled here

[lena-larionova]

This is part of the Gateway or Konnect prerequisite:

I can mention it somewhere more explicitly to make sure people don't miss this, if that helps.

[yijin-kong]

Do we want to put the flag [custom_plugin_streaming_enabled] into the "Kong Gateway configuration reference" page

[yijin-kong]

There are a few minor things I are not if we want to mention or not:

1. We have a limitation of 5 for cloned plugin on the same ref
2. There is permission for streaming/cloning plugins. Usually default workspace-super-admin will not have the permission to operate on it. the default space super-admin will have the the permission by default.
3. Cloned/Streaming plugin cannot be removed or updated if they are configured.

[lena-larionova]

Do we want to put the flag [custom_plugin_streaming_enabled] into the "Kong Gateway configuration reference" page

This will be pulled in automatically from rc.2 - we generate that doc from source. Right now it still has custom_plugins_enabled from rc1, but I'll run the generator against rc2 to pick that up.

[catbro666]

Considering we generally don't allow deleting or updating streamed plugins and cloned plugins when there are still existing plugin instances that refer to them because it may break the existing plugin instances, prehaps we'd better add a section (similar to this) to guide customers how to upgrade their streamed plugins or update the cloned plugins safely in a running gateway instance.

For streamed plugins:

1. Start a migration/maintenance window.
2. Create a new version custom plugin.
3. Update all the plugin instances of the custom plugin to comply with the new version schema.
4. Remove the old version custom plugin.
5. Stop the migration/maintenance window.

For cloned plugins:

1. Start a migration/maintenance window.
2. Create a new cloned plugin.
3. Update all the plugin instances of the cloned plugin to comply with the new cloned plugin. (Change the name to the new one and change the config if the source plugin which the ref field specifies is also changed.)
4. Remove the old cloned plugin.
5. Stop the migration/maintenance window.

[catbro666]

There is permission for streaming/cloning plugins. Usually default workspace-super-admin will not have the permission to operate on it. the default space super-admin will have the the permission by default.

Yes, that the case for on-prem. super-admin and admin have full access to /cloned-plugins and /custom-plugins, and workspace-super-admin and workspace-admin only have the read access to /cloned-plugins and /custom-plugins.
Konnect has a different role permission system. It seems the roles mentioned in the thread have access to /cloned-plugins and /custom-plugins.
https://kongstrong.slack.com/archives/C0A1JBUT7A9/p1776718696652559?thread_ts=1776710558.688239&cid=C0A1JBUT7A9

[catbro666]

Let's not use upper case letters in the example, the name only accepts lowercase letters, numbers, and hyphens. To be more precise, the first character must be a lowercase letter and the last character must not be a hyphen.