Writing Kong plugins with Go

03/10/2023 989 words 5 minutes

Contents

The Kong, quoting its own documentation, is an open-source API gateway, cloud-native, platform-agnostic, scalable API Gateway distinguished for its high performance and extensibility via plugins. Kong has a lot of official plugins that allow us to customize what we need, and when there aren’t any available, you can build your own.

The default language for building plugins its Lua, but other languages are supported, including Go. I don’t have much experience writing code with Lua, so using Go allows me a higher development speed and quality on my plugins.

Development

Building a Go plugin is easy, as you need to follow the signature proposed by Kong’s plugin development kit or PDK, but it is easy to understand. To demonstrate that, we will build a plugin that will read a request header and set a new response header.

The first thing to do is define both constants: version and priority. As the name says, we will configure the current version of the plugin and its execution priority within the other plugins. Its worth mentioning that the higher the priority, the earlier it will be executed. If you wanna understand more about it, check this post.

1
2
var Version = "0.0.1"
var Priority = 1

After, we will define which params the plugin accepts by building a struct called Config. Here, we will receive the field message as a string.

1
2
3
type Config struct {
	Message string `json:"message"`
}

All kong plugins work based on which phase access they need to run. The possible phase access are:

Certificate
Rewrite
Access
Response
Preread
Log

In this example, we will be using Access because we need to update the response before forwarding the request to the responsible microservice. You don’t need to worry about it because the signatures for all phases are the same. To know more about all phase access, check this documentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
func (conf Config) Access(kong *pdk.PDK) {
	host, err := kong.Request.GetHeader("host")
	if err != nil {
		log.Printf("Error reading 'host' header: %s", err.Error())
	}

	message := conf.Message
	if message == "" {
		message = "hello"
	}
	kong.Response.SetHeader("x-hello-from-go", fmt.Sprintf("Go says %s to %s", message, host))
}

This function uses the PDK to read the available headers by using kong.Request.GetHeader, and later we add a response header using kong.Response.SetHeader. For more information about all available functions, you can check the Go PDK.

At last, let’s check the main function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
package main

import (
	"fmt"
	"log"

	"github.com/Kong/go-pdk"
	"github.com/Kong/go-pdk/server"
)

func main() {
	server.StartServer(New, Version, Priority)
}

func New() interface{} {
	return &Config{}
}

As we can notice, the main function initializes the Kong server, sending the Config, Version, and Priority defined before. The full code is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
package main

import (
	"fmt"
	"log"

	"github.com/Kong/go-pdk"
	"github.com/Kong/go-pdk/server"
)

var Version = "0.0.1"
var Priority = 1

func main() {
	server.StartServer(New, Version, Priority)
}

type Config struct {
	Message string `json:"message"`
}

func New() interface{} {
	return &Config{}
}

func (conf Config) Access(kong *pdk.PDK) {
	host, err := kong.Request.GetHeader("host")
	if err != nil {
		log.Printf("Error reading 'host' header: %s", err.Error())
	}

	message := conf.Message
	if message == "" {
		message = "hello"
	}
	kong.Response.SetHeader("x-hello-from-go", fmt.Sprintf("Go says %s to %s", message, host))
}

Tests

Testing our Go plugins is also easy once the PDK gives us tools that make it straightforward. Let’s test our plugin:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
package main

import (
	"testing"

	"github.com/Kong/go-pdk/test"
	"github.com/stretchr/testify/assert"
)

func TestPluginWithoutConfig(t *testing.T) {
	env, err := test.New(t, test.Request{
		Method:  "GET",
		Url:     "http://example.com?q=search&x=9",
		Headers: map[string][]string{"host": {"localhost"}},
	})
	assert.NoError(t, err)

	env.DoHttps(&Config{})
	assert.Equal(t, 200, env.ClientRes.Status)
	assert.Equal(t, "Go says hello to localhost", env.ClientRes.Headers.Get("x-hello-from-go"))
}

func TestPluginWithConfig(t *testing.T) {
	env, err := test.New(t, test.Request{
		Method:  "GET",
		Url:     "http://example.com?q=search&x=9",
		Headers: map[string][]string{"host": {"localhost"}},
	})
	assert.NoError(t, err)

	env.DoHttps(&Config{Message: "nice to meet you"})
	assert.Equal(t, 200, env.ClientRes.Status)
	assert.Equal(t, "Go says nice to meet you to localhost", env.ClientRes.Headers.Get("x-hello-from-go"))
}

Deploy

To deploy our plugin, we build an executable and must add it to the Kong image.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# Build Golang plugins

FROM golang:1.20 AS plugin-builder

WORKDIR /builder

COPY ./hello ./go_plugins/hello

RUN find ./go_plugins -maxdepth 1 -mindepth 1 -type d -not -path "*/.git*" | \
    while read dir; do \
        cd $dir && go build -o /builds/$dir main.go  ; \
    done

# Build Kong
FROM kong:3.4.0-ubuntu

COPY --from=plugin-builder ./builds/go_plugins/  ./kong/

USER kong

Kong needs some information to be able to find and load the customized plugin, so we need to add some environment variables:

1
2
3
4
KONG_PLUGINS: "bundled,hello"
KONG_PLUGINSERVER_NAMES: hello
KONG_PLUGINSERVER_HELLO_START_CMD: /kong/hello
KONG_PLUGINSERVER_HELLO_QUERY_CMD: /kong/hello -dump

Considerations about performance

The Kong company already did a study about the performance, and you can find it here.

Conclusion

Go is an excellent tool for writing plugins for Kong. We can have all the performance and tools it provides to us. In my case, I have also been able to speed up my deliveries and have a higher code coverage. It is also possible to isolate the plugin’s logic with the PDK use, making it easy to write plugins that work for different technologies, decoupling Kong.

If you wanna check all the code shown in this post, you can access the repo.

You also can find me on Twitter, Github, or LinkedIn.