2 min • read

Plugin Filter

The Plugin filter type allows you to plug in your own custom code. This code is compiled to a .so file, which you load into the Ambassador Edge Stack container at /etc/ambassador-plugins/${NAME}.so. The Filter Development Guide contains a tutorial on developing filters.

The Plugin interface

This code is written in the Go programming language and must be compiled with the exact same compiler settings as Ambassador Edge Stack (any overlapping libraries used must have their versions match exactly). This information is documented in the /ambassador/aes-abi.txt file in the AES docker image.

Plugins are compiled with go build -buildmode=plugin -trimpath and must have a main.PluginMain function with the signature PluginMain(w http.ResponseWriter, r *http.Request):

go
package main
import (
"net/http"
)
func PluginMain(w http.ResponseWriter, r *http.Request) {}

*http.Request is the incoming HTTP request that can be mutated or intercepted, which is done by http.ResponseWriter.

Headers can be mutated by calling w.Header().Set(HEADERNAME, VALUE). Finalize changes by calling w.WriteHeader(http.StatusOK).

If you call w.WriteHeader() with any value other than 200 (http.StatusOK) instead of modifying the request, the plugin has taken over the request, and the request will not be sent to your backend service. You can call w.Write() to write the body of an error page.

Plugin global arguments

yaml
---
apiVersion: getambassador.io/v2
kind: Filter
metadata:
name: "example-plugin-filter"
namespace: "example-namespace"
spec:
Plugin:
name: "string" # required; this tells it where to look for the compiled plugin file; "/etc/ambassador-plugins/${NAME}.so"

Plugin path-specific arguments

Path specific arguments are not supported for Plugin filters at this time.


Questions?

We’re here to help if you have questions.