Note well: Go's support for WebAssembly is fast evolving. The contents of this page have been written during April 2021, hence they could be outdated.

Go

Currently the official Go compiler cannot produce WebAssembly binaries that can be run outside of the browser. This upstream issue is tracking the evolution of this topic. Due to that, it's not possible to use the Go compiler to write Kubewarden policies.

Luckily there's another Go compiler that is capable of building WebAssembly binaries that can be used by Kubewarden. This compiler is called TinyGo:

TinyGo is a project to bring the Go programming language to microcontrollers and modern web browsers by creating a new compiler based on LLVM.

You can compile and run TinyGo programs on many different microcontroller boards such as the BBC micro:bit and the Arduino Uno.

TinyGo can also be used to produce WebAssembly (Wasm) code which is very compact in size.

Limitations

TinyGo doesn't yet support all the Go features (see here to see the current project status). Currently its biggest limitation is the lack of a fully supported reflect package. That leads to the inability to use the encoding/json package against structures and user defined types.

Kubewarden policies need to process JSON data like the policy settings and the actual request received by Kubernetes.

Despite TinyGo's current limitations, it's still easy and doable to write Kubewarden validation policies with it.

Note well: unfortunately, it's currently impossible to write mutating policies using TinyGo.

Tooling

Writing Kubewarden policies requires a version of TinyGo greater than 0.17.0.

These Go libraries are extremely useful when writing a Kubewarden policy:

  • Kubewarden Go SDK: provides a series of structures and functions that reduce the amount of code to write. It also provides test helpers.
  • gjson: provides a powerful query language that allows quick navigation of JSON documents and data retrieval. This library doesn't use the encoding/json package provided by Go's stdlib, hence it's usable with TinyGo.
  • mapset: provides a Go implementation of the Set data structure. This library significantly reduces the amount of code to be written, that's because operations like Set union, intersection, difference are pretty frequent inside of policies.

Last but not least, the Kubewarden project provides a template Go policy project that can be used to quickly create Kubewarden policies written in Go.

Getting TinyGo dependencies

The easiest way to get TinyGo is by using the upstream container images. Official releases can be found here, while builds from the development branch are automatically pushed here.

If needed, checkout TinyGo's getting started page for more information.

Note well: Kubewarden's requires code that is available only on the development branch. This will be solved once TinyGo 0.17.0 is released. In the meantime we will use the container image based on the development branch: tinygo/tinygo-dev:latest.