- Advanced configuration topics
- Upgrading Ambassador
- Statistics and Monitoring
- Need Help?
This feature is supported in Ambassador Pro. Ambassador Pro helps developers and operators accelerate their adoption of Kubernetes.
Register here to get started with a free trial of Ambassador Pro.
Sometimes you may want Ambassador to manipulate an incoming request. Some example use cases:
- Inspect an incoming request, and add a custom header that can then be used for routing
- Add custom Authorization headers
- Validate an incoming request fits an OpenAPI specification before passing the request to a target service
Ambassador supports these use cases by allowing you to execute custom logic in
Filters. Filters are written in Golang, and managed by Ambassador Pro.
Creating and Deploying Filters
We've created an example filter that you can customize for your particular use case.
Start with the example filter:
git clone https://github.com/datawire/apro-example-plugin/.
Make code changes to
param-plugin.go. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter.
make DOCKER_REGISTRY=..., setting
DOCKER_REGISTRYto point to a registry you have access to. This will generate a Docker image named
Push the image to your Docker registry:
docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION.
Configure Ambassador Pro to use the plugin by creating a
FilterPolicyCRD, as per the filter reference.
If you're adding additional headers, configure the
AuthServiceconfiguration to allow the filter to inject the new header, e.g.,
allowed_authorization_headers: - "Authorization" - "Client-Id" - "Client-Secret" + - "X-Wikipedia"
Update the standard Ambassador Pro manifest to use your Docker image instead of the standard sidecar.
containers: - name: ambassador-pro - image: quay.io/datawire/ambassador_pro:amb-sidecar-0.2.4 + image: DOCKER_REGISTRY/amb-sidecar-plugin:VERSION ports: - name: ratelimit-grpc containerPort: 8081 - name: ratelimit-debug containerPort: 6070
Rapid development of a custom filter
During development, you may want to sidestep the deployment process for a faster development loop. The
apro-plugin-runner helps you rapidly develop Ambassador filters locally.
To install the runner, download the latest version:
Note that the plugin runner must match the version of Ambassador Pro that you are running. Place the binary somewhere in your
Now, you can quickly test and develop your filter.
In your filter directory, type:
apro-plugin-runner :8080 ./param-plugin.so.
Test the filter by running
$ curl -v localhost:8080?db=2 * Rebuilt URL to: localhost:8080/?db=2 * Trying ::1... * TCP_NODELAY set * Connected to localhost (::1) port 8080 (#0) > GET /?db=2 HTTP/1.1 > Host: localhost:8080 > User-Agent: curl/7.54.0 > Accept: */* > < HTTP/1.1 200 OK < X-Dc: Even < Date: Mon, 25 Feb 2019 19:58:38 GMT < Content-Length: 0 < * Connection #0 to host localhost left intact
Note in the example above the
X-Dcheader is added. This lets you inspect the changes the filter is making to your HTTP header.
For more details about configuring filters and the
plugin interface, see the filter reference.