Kong — Write your first custom plugin

1. Create a new Lua file for the plugin

You’ll start by creating a new Lua file for your plugin, for example modify-headers-and-body.lua.

2. Define the Plugin Schema

Define the schema for your plugin in the Lua file. This defines any configuration parameters your plugin accepts.

local typedefs = require "kong.db.schema.typedefs"

return {
    name = "modify-headers-and-body",
    fields = {
        { consumer = typedefs.no_consumer },
        { protocols = typedefs.protocols_http },
        { config = {
            type = "record",
            fields = {
                { request_header_name = { type = "string", default = "X-Request-Added" }, },
                { request_header_value = { type = "string", default = "added-value" }, },
                { response_header_name = { type = "string", default = "X-Response-Added" }, },
                { response_header_value = { type = "string", default = "added-value" }, },
                { remove_body_string = { type = "string", default = "remove-this-string" }, },
            },
        }, },
    },
}

3. Implement the Plugin Logic

You need to implement the logic for modifying the request headers, response headers, and response body.

local BasePlugin = require "kong.plugins.base_plugin"
local kong = kong
local gsub = string.gsub

local ModifyHeadersAndBodyHandler = BasePlugin:extend()

ModifyHeadersAndBodyHandler.VERSION  = "1.0.0"
ModifyHeadersAndBodyHandler.PRIORITY = 1000

function ModifyHeadersAndBodyHandler:new()
    ModifyHeadersAndBodyHandler.super.new(self, "modify-headers-and-body")
end

function ModifyHeadersAndBodyHandler:access(conf)
    ModifyHeadersAndBodyHandler.super.access(self)

    -- Add header to request
    kong.service.request.add_header(conf.request_header_name, conf.request_header_value)
end

function ModifyHeadersAndBodyHandler:header_filter(conf)
    ModifyHeadersAndBodyHandler.super.header_filter(self)

    -- Add header to response
    kong.response.add_header(conf.response_header_name, conf.response_header_value)
end

function ModifyHeadersAndBodyHandler:body_filter(conf)
    ModifyHeadersAndBodyHandler.super.body_filter(self)

    local chunk, eof = ngx.arg[1], ngx.arg[2]
    if chunk ~= "" and not eof then
        -- Remove string from response body
        chunk = gsub(chunk, conf.remove_body_string, "")
        ngx.arg[1] = chunk
    end
end

return ModifyHeadersAndBodyHandler

4. Install and Enable the Plugin

Place this Lua file in the appropriate directory for Kong plugins (usually under /usr/local/share/lua/5.1/kong/plugins/ or a similar path depending on your installation). You will also need to update your Kong configuration to include this custom plugin by adding it to the plugins directive in your Kong configuration file.

5. Enable the Plugin on a Service, Route, or Globally

You can enable the plugin on a specific service, route, or globally via the Kong Admin API. For example:

curl -X POST http://localhost:8001/services/{service_id}/plugins \
    --data "name=modify-headers-and-body" \
    --data "config.request_header_name=X-Custom-Request-Header" \
    --data "config.request_header_value=RequestValue" \
    --data "config.response_header_name=X-Custom-Response-Header" \
    --data "config.response_header_value=ResponseValue" \
    --data "config.remove_body_string=string-to-remove"

This script and configuration will allow Kong to add specified headers to requests and responses and remove specified strings from the response body as it’s streamed back to the client. Adjust the config values as needed for your use case.