Golang

The HTTP Golang filter allows Golang to be run during both the request and response flows and makes it easier to extend Envoy.

Go plugins used by this filter can be recompiled independently of Envoy.

See the Envoy’s Golang extension proposal documentation for more details on the filter’s implementation.

Warning

The Envoy Golang filter is designed to be run with the GODEBUG=cgocheck=0 environment variable set.

This disables the cgo pointer check.

Failure to set this environment variable will cause Envoy to crash!

Developing a Go plugin

Envoy’s Go plugins must implement the StreamFilter API.

Attention

The Go plugin API is not yet stable, you are strongly recommended to use the same version of Go plugin SDK and Envoy.

When you are using a release version of Envoy, i.e. 1.26.x, you should use github.com/envoyproxy/envoy v1.26.x in the go.mod file.

When you are not using a release, i.e. the latest main branch of Envoy, you could use go get -u github.com/envoyproxy/envoy@SHA to get the same version of Go plugin SDK, the SHA is the latest commit sha.

Building a Go plugin

Attention

When building a Go plugin dynamic library, you must use a Go version consistent with Envoy’s version of glibc.

One way to ensure a compatible Go version is to use the Go binary provided by Envoy’s bazel setup:

$ bazel run @go_sdk//:bin/go -- version
...
go version goX.YZ linux/amd64

For example, to build the .so for a foo plugin, you might run:

$ bazel run @go_sdk//:bin/go build -- --buildmode=c-shared  -v -o path/to/output/libfoo.so path/to/src/foo

Configuration

Tip

This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config.

A prebuilt Golang HTTP filter my_plugin.so might be configured as follows:

16          http_filters:
17          - name: envoy.filters.http.golang
18            typed_config:
19              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
20              library_id: my-plugin-id
21              library_path: "lib/my_plugin.so"
22              plugin_name: my_plugin
23          - name: envoy.filters.http.header_to_metadata

An HttpConnectionManager can have multiple Go plugins in its http_filters:

16          http_filters:
17          - name: envoy.filters.http.golang
18            typed_config:
19              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
20              library_id: my-plugin-id
21              library_path: "lib/my_plugin.so"
22              plugin_name: my_plugin
23          - name: envoy.filters.http.header_to_metadata
24            typed_config:
25              "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
26          - name: envoy.filters.http.golang
27            typed_config:
28              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
29              library_id: my-other-plugin-id
30              library_path: "lib/my_other_plugin.so"
31              plugin_name: my_other_plugin
32          - name: envoy.filters.http.router
33            typed_config:

This can be useful if, for example, you have one plugin that provides authentication, and another that provides connection limiting.

Extensible plugin configuration

Envoy’s Go plugins can specify and use their own configuration.

Below is a very simple example of how such a plugin might be configured in Envoy:

17          - name: envoy.filters.http.golang
18            typed_config:
19              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
20              library_id: my-configurable-plugin-id
21              library_path: "lib/my_configurable_plugin.so"
22              plugin_name: my_configurable_plugin
23              plugin_config:
24                "@type": type.googleapis.com/xds.type.v3.TypedStruct
25                value:
26                  foo: bar
27          - name: envoy.filters.http.router

See the StreamFilter API for more information about how the plugin’s configuration data can be accessed.

Per-route plugin configuration

Go plugins can be configured on a per-route basis, as in the example below:

16          http_filters:
17          - name: envoy.filters.http.golang
18            typed_config:
19              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
20              library_id: my-configurable-plugin-id
21              library_path: "lib/my_configurable_plugin.so"
22              plugin_name: my_configurable_plugin
23          - name: envoy.filters.http.router
24            typed_config:
25              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
26          route_config:
27            name: route_0
28            virtual_hosts:
29            - name: service_0
30              domains: ["*"]
31              routes:
32              - match:
33                  prefix: "/"
34                route:
35                  cluster: cluster_0
36            typed_per_filter_config:
37              envoy.filters.http.golang:
38                "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.ConfigsPerRoute
39                plugins_config:
40                  my_configurable_plugin:
41                    config:
42                      "@type": type.googleapis.com/xds.type.v3.TypedStruct
43                      value:
44                        foo: route_bar

Per-virtualhost plugin configuration

Go plugins can also be configured on a per-virtualhost basis:

 1          http_filters:
 2          - name: envoy.filters.http.golang
 3            typed_config:
 4              "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
 5              library_id: my-configurable-plugin-id
 6              library_path: "lib/my_configurable_plugin.so"
 7              plugin_name: my_configurable_plugin
 8          - name: envoy.filters.http.router
 9            typed_config:
10              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
11          route_config:
12            name: route_0
13            virtual_hosts:
14            - name: service_0
15              domains: ["*"]
16              routes:
17              - match:
18                  prefix: "/"
19                route:
20                  cluster: cluster_0
21                typed_per_filter_config:
22                  envoy.filters.http.golang:
23                    "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.ConfigsPerRoute
24                    plugins_config:
25                      my_configurable_plugin:
26                        config:
27                          "@type": type.googleapis.com/xds.type.v3.TypedStruct
28                          value:
29                            foo: vh_bar

Complete example

Learn more about building and running a plugin for the Envoy Go filter in the step by step Envoy Go Sandbox.