|
| 1 | +--- |
| 2 | +title: Custom plugins in Dedicated Cloud Gateways |
| 3 | +content_type: reference |
| 4 | +--- |
| 5 | + |
| 6 | +With Dedicated Cloud Gateways, {{site.konnect_short_name}} can stream custom plugins from the control plane to the data plane. |
| 7 | + |
| 8 | +This means that the control plane becomes a single source of truth for plugin versions. You only need to upload a plugin once, to the control plane, and {{site.konnect_short_name}} handles distributing the plugin code to all data planes in that control plane. |
| 9 | + |
| 10 | +Compared to the manual process required in a regular hybrid {{site.konnect_short_name}} deployment, custom plugin streaming in Dedicated Cloud Gateways provides the following benefits: |
| 11 | +* Faster custom plugin distribution |
| 12 | +* Minimal manual maintenance |
| 13 | +* The control plane is the single source of truth |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +* Your [custom plugin](/gateway/latest/plugin-development/) meets the following requirements: |
| 18 | + * Each custom plugin must have a unique name. |
| 19 | + * Each custom plugin can have a maximum of 1 `handler.lua` file and 1 `schema.lua` file. |
| 20 | + * The plugin can't execute in the `init_worker` phase and can't set any timers. |
| 21 | + * The plugin must be written in Lua. No other languages are supported. |
| 22 | +* You have a [personal access token or system access token](/konnect/org-management/access-tokens) for the {{site.konnect_short_name}} API |
| 23 | + |
| 24 | +## Adding a custom plugin to a Dedicated Cloud Gateway deployment |
| 25 | + |
| 26 | +Upload custom plugin schema and handler files to create a configurable entity in {{site.konnect_short_name}}. |
| 27 | +If you prefer using the {{site.konnect_short_name}} UI, you can also upload these files through the Plugins menu in [Gateway Manager](https://cloud.konghq.com/gateway-manager/). |
| 28 | + |
| 29 | +{:.important} |
| 30 | +> The name you give the plugin must be identical to the name of the plugin in the schema file. |
| 31 | +
|
| 32 | +Using the following command, make a `POST` request to the [`/custom-plugins`](/konnect/api/control-plane-configuration/latest/#/operations/list-custom-plugin) endpoint of the {{site.konnect_short_name}} Control Plane Config API: |
| 33 | + |
| 34 | +```sh |
| 35 | +curl -X POST https://{region}.api.konghq.com/v2/control-planes/{control-plane-id}/core-entities/custom-plugins \ |
| 36 | + -H "Content-Type: application/json" \ |
| 37 | + -H "Authorization: Bearer {your-access-token}" \ |
| 38 | + -d "$(jq -n \ |
| 39 | + --arg handler "$(cat handler.lua)" \ |
| 40 | + --arg schema "$(cat schema.lua)" \ |
| 41 | + '{"handler":$handler,"name":"streaming-headers","schema":$schema}')" \ |
| 42 | + | jq |
| 43 | +``` |
| 44 | + |
| 45 | +This request returns an `HTTP 200` response with the schema and handler for your plugin as a JSON object. |
| 46 | + |
| 47 | +Once a custom plugin is uploaded to a Dedicated Cloud Gateway control plane, it can be managed like any other plugin, using any of the following tools: |
| 48 | +* [decK](/konnect/gateway-manager/declarative-config/) |
| 49 | +* [{{site.konnect_short_name}} Control Plane Config API](/konnect/api/control-plane-configuration/latest/#/operations/list-custom-plugin) |
| 50 | +* [{{site.konnect_short_name}} UI](https://cloud.konghq.com/) |
| 51 | + |
| 52 | +## More information |
| 53 | + |
| 54 | +* [Custom plugin schema endpoints (Control Plane Config API)](/konnect/api/control-plane-configuration/latest/#/Custom%20Plugin%20Schemas) |
| 55 | +* [Custom plugin template](https://github.com/Kong/kong-plugin) |
| 56 | +* [Plugin development guide](/gateway/latest/plugin-development/) |
| 57 | +* [PDK reference](/gateway/latest/plugin-development/pdk/) |
0 commit comments