Pre-Processing, Augmenting, and Transforming User Ingress Requests: Using Filters in Ambassador Pro
In early March we announced the launch of request Filters and Filter Policies for the Ambassador Pro API gateway, and we have seen lots of interesting developments in this space. Many users of Ambassador want to manipulate the request from an end user before it hits the backend services, and filters provide the perfect framework to do this.
For example, do you want to add additional customer metadata to a request based on a customer ID header, cookie, or JWT? Do you want to remove inappropriate or sensitive data that may be accidentally added to a request? Or do you want to perform a simple transformation to the request payload? The solution could be to implement a plugin Filter.
Implementing Ingress Cross-Cutting Concerns
Anyone who has worked on an enterprise Java or .NET application will be familiar with the concept of HTTP filters, as will developers of many other languages and frameworks. Filters are a good abstraction point for implementing cross-cutting concerns like authentication / authorization, manipulating request data, and adding metadata to the incoming HTTP request that is then used further down the stack. They can also contain conditional logic in order to only trigger for specific requests or patterns, and they can be chained together to form an arbitrarily complicated pipeline of functionality.
Ambassador Pro provides Kubernetes Custom Resource Definitions (CRD) for Filters, which initialises and configures the filter for use, and Filter Policies, which are configured to specify which requests should be filtered and the ordering in which filters are applied. Currently Ambassador Pro supports the implementation of four types of filters: external, JWT, OAuth2, and Plugin. The first three are primarily concerned with implementing authentication and authorization, but the fourth provides a lot of flexibility for implementing custom logic.
Creating Filters for Ambassador Pro is made easier by the inclusion of an SDK and local plugin runner for rapid development. There is also useful out-of-the box functionality that is provided when running filters, such as automatic injection of tracing headers to help debugging, and easy runtime declarative configuration and customisation via the use of the FilterPolicy CRD.
Filters and Filter Policies
Plugin filters are written in Go, and they must have a main.PluginMain function with the signature PluginMain(w http.ResponseWriter, r *http.Request). For example, an excerpt from a simple plugin would look something like this:
package mainimport (
"net/http"
)func PluginMain(w http.ResponseWriter, r *http.Request) {
...
w.Header().Set(“customer-details”, customer)
w.WriteHeader(http.StatusOK).
}
Complete instructions for the compilation, packaging, and deployment of the plugin filter are included within the Ambassador Pro “Developing Filters” docs.
Once you’ve deployed your filters alongside Ambassador you can then define the Filter as a Kubernetes resource:
---
apiVersion: getambassador.io/v1beta2
kind: Filter
metadata:
name: "customer-metadata-inject"
spec:
ambassador_id: "x457"
Plugin:
name: "customer-metadata-inject" # Plugin's `.so` file nameYou can also define the FilterPolicy resource to specify which requests, based on host and path, should be sent to your filter.
---
apiVersion: getambassador.io/v1beta2
kind: FilterPolicy
metadata:
name: customer-metadata-inject-policy
spec:
rules:
# Default to authorizing all requests with auth0
- host: "*"
path: "*"
filters:
- name: auth0
# Inject customer metadata for /user/ path
- host: "*"
path: /user/*
filters:
- name: auth0
- name: customer-metadata-inject
# Don't run any filters for the /logout/ path
- host: "*"
path: /logout/*
filters: nullIt’s as simple as that. The only limit for implementing filters is your imagination — and being conscious to not incorporate highly-coupled business logic into a filter, which could become a maintenance issue!
Get Started with Filters
If you haven’t downloaded Ambassador Pro yet, you can get started with a free 14-day trial via the project’s website. Once you’ve installed Ambassador Pro into your Kubernetes cluster, the next best resources to consult are the Filter Reference docs and the Filter Development Guide docs.
As usual, you can also ask any questions you may have via Twitter (@getambassadorio), Slack or raise issues via GitHub.
