Ambassador Pro 0.2: Filters and Filter Policies

Ambassador Pro 0.2 introduces a powerful new capability: Filters and Filter Policies. With filters, Ambassador can manipulate incoming requests before they are routed to your upstream service. This opens up many new possibilities. For example:

• You can use an HTTP basic authentication filter for requests to /foo, while using an OAuth filter for requests to /bar.
• You can dynamically route requests to different services based on a given customer ID or request parameter.
• Dynamically inject HTTP headers for a given category of requests

Filters

Filters are individual plugins that run arbitrary business logic with full access to the request stream. In 0.2, we’re shipping with two filter types:

• The OAuth filter type, which performs OAuth2 authorization against an identity provider that implements OIDC Discovery. We’ve tested this filter against both Auth0 and Keycloak.
• The Plugin filter type, which lets you write custom filters in Golang.

We’ll be shipping more filters in the near future, so stay tuned.

Filter Policies

Filters are managed using FilterPolicy objects. A FilterPolicy is a custom resource definition that specifies which filters are run for a given HOST or path. Here’s an example FilterPolicy:

apiVersion: getambassador.io/v1beta2
kind: FilterPolicy
metadata:
  name: httpbin-policy
spec:
  rules:
  - host: "*"
    path: /httpbin/ip
    filters: null # make this path public
  - host: "*"
    path: /keycloak/httpbin/headers
    filters:
    - name: keycloak-oauth
    - name: custom-filter

In this example, no filters are run on requests tohttpbin/ip. Meanwhile, requests to/keycloak/httpbin/headers invoke two filters, one named keycloak-oauth and another named custom-filter.

Developing your own filter

Custom filters are written in Go and have a simple interface.

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.

To make it easy to write your own filter, we’re releasing:

• https://github.com/datawire/apro-example-plugin, which contains a sample plugin and Makefile that lets you build your own plugin quickly
• the Pro Plugin Runner, which lets you run your plugin locally for rapid development and testing

Note that the Ambassador filter model is asynchronous, and can only modify incoming requests (not responses).

Further reading

We’ve added several sections to the documentation on filters, including:

• Filter Development Guide for developers
• The Filter Reference, covering the new CRDs and new filter types available

To get started with Ambassador Pro, sign up for a free trial today.