Write plugins in Go

    To write a Kong Gateway plugin in Go, you need to:

    1. Define a structure type to hold configuration.
    2. Write a New() function to create instances of your structure.
    3. Add methods to that structure to handle phases.
    4. Include the go-pdk/server sub-library.
    5. Add a main() function that calls server.StartServer(New, Version, Priority).
    6. Compile as an executable with go build.

    The plugin you write needs a way to handle incoming configuration data from the data store or the Admin API. You can use a struct to create a schema of the incoming data.

    Because this plugin will be processing configuration data, you are going to want to control encoding using the encoding/json package. Go fields that start with a capital letter can be exported, making them accessible outside of the current package, including by the encoding/json package. If you want the fields to have a different name in the data store, add tags to the fields in your struct.

    1.     Path   string `json:"my_file_path"`
    2.     Reopen bool   `json:"reopen"`
    3. }
    1. func New() interface{} {
    2.     return &MyConfig{}
    3. }

    Each plugin is compiled as a standalone executable. Include github.com/Kong/go-pdk in the imports list, and add a main() function:

    Executables can be placed somewhere in your path (for example, /usr/local/bin). The common -h flag shows a usage help message:

    1. my-plugin -h

    Output:

    1. Usage of my-plugin:
    2.   -dump
    3.         Dump info about plugins
    4.   -help
    5.         Show usage info
    6.   -kong-prefix string
    7.         Kong prefix path (specified by the -p argument commonly used in the Kong CLI) (default "/usr/local/kong")

    When you run the plugin without arguments, it creates a socket file within the kong-prefix and the executable name, appending .socket. For example, if the executable is my-plugin, the socket file would be /usr/local/kong/my-plugin.socket.

    You can implement custom logic during the following phases using the same function signature:

    • Certificate
    • Rewrite
    • Response
    • Preread
    • Log

    The presence of the Response handler automatically enables the buffered proxy mode.

    You can define the version number and priority of execution by declaring the following constants within the plugin code:

    1. const Version = "1.0.0"
    2. const Priority = 1

    Kong Gateway executes plugins from highest priority to lowest.

    1. pluginserver_names = my-plugin,other-one
    3. pluginserver_my_plugin_socket = /usr/local/kong/my-plugin.socket
    4. pluginserver_my_plugin_start_cmd = /usr/local/bin/my-plugin
    5. pluginserver_my_plugin_query_cmd = /usr/local/bin/my-plugin -dump
    7. pluginserver_other_one_socket = /usr/local/kong/other-one.socket
    8. pluginserver_other_one_start_cmd = /usr/local/bin/other-one
    9. pluginserver_other_one_query_cmd = /usr/local/bin/other-one -dump

    The socket and start command settings coincide with their defaults and can be omitted: