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.
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.