DocsEdge StackUsing The External Filter
Using The External Filter
The External
Filter
calls out to an external service speaking the
ext_authz
protocol, providing
a highly flexible interface to plug in your own authentication,
authorization, and filtering logic.
The External
spec is identical to the AuthService
spec, with the following
exceptions:
- In an
AuthService
, thetls
field must be a string referring to aTLSContext
. In anExternal
Filter
, it may only be a Boolean; referring to aTLSContext
is not supported. - In an
AuthService
, the default value of theadd_linkerd_headers
field is based on theambassador
Module
. In anExternal
Filter
, the default value is alwaysfalse
. External
Filters
lack thestats_name
, andadd_auth_headers
fields thatAuthServices
have.
See the External Filter API reference for an overview of all the supported fields.
Tracing Header Propagation
If Ambassador Edge Stack is configured to use a TraceService
, Envoy will send tracing information as gRPC Metadata. Add the trace headers to the allowed_request_headers
field to propagate the trace headers when using an ExternalFilter configured with proto:http
. For example, if using Zipkin with B3 Propagation headers you can configure your External Filter like this:
Configuring TLS Settings
When an External Filter
has the auth_service
field configured with a URL that starts with https://
then Ambassador Edge Stack
will attempt to communicate with the AuthService
over a TLS connection. The following configurations are supported:
- Verify server certificate with host CA Certificates - default when
tls: true
- Verify server certificate with provided CA Certificate
- Mutual TLS between client and server
Overall, these new configuration options enhance the security of the communications between Ambassador Edge Stack and your External Filter
by providing a way to
verify the server's certificate, allowing customization of the trust verification process, and enabling mutual TLS (mTLS) between Ambassador Edge Stack and the
External Filter
service. By employing these security measures, users can have greater confidence in the authenticity, integrity,
and confidentiality of their filter's actions, especially if it interacts with any sensitive information.
Example - Verify Server with Custom CA Certificate
Example - Mutual TLS (mTLS)
Metrics
As of Ambassador Edge Stack 3.4.0, the following metrics for External Filters are available via the metrics endpoint
Metric | Type | Description |
---|---|---|
ambassador_edge_stack_external_filter_allowed | Counter | Number of requests that were allowed by Ambassador Edge Stack External Filters. Includes requests that are allowed by failure_mode_allow when unable to connect to the External Filter. |
ambassador_edge_stack_external_filter_denied | Counter | Number of requests that were denied by Ambassador Edge Stack External Filters. Includes requests that are denied by an inability to connect to the External Filter or due to a Filter config error. |
ambassador_edge_stack_external_filter_error | Counter | Number of errors returned directly from Ambassador Edge Stack External Filters and errors from an inability to connect to the External Filter |
ambassador_edge_stack_external_handler_error | Counter | Number of errors caused by Ambassador Edge Stack encountering invalid Filter config or an error while parsing the config. \nThese errors will always result in a HTTP 500 response being returned to the client and do not count towards metrics that track response codes from external filters. |
ambassador_edge_stack_external_filter_rq_class | Counter (with labels) | Aggregated counter of response code classes returned to downstream clients from Ambassador Edge Stack External Filters. Includes requests that are denied by an inability to connect to the External Filter. |
ambassador_edge_stack_external_filter_rq_status | Counter (with labels) | Counter of response codes returned to downstream clients from Ambassador Edge Stack External Filters. Includes requests that are denied by an inability to connect to the External Filter. |
An example of what the metrics may look like can be seen below
Transport Protocol Migration
Note: The following information is only applicable to External Filters using
proto: grpc
As of Ambassador Edge Stack version 2.3, thev2
transport protocol is deprecated and any External Filters making use of it should migrate tov3
before support forv2
is removed in a future release.
The following imports simply need to be updated to migrate an External Filter
v2
Imports:
v3
Imports:
In the datawire/sample-external-service repository, you can find examples of an External Filter using both the
v2
transport protocol as well as v3
along with deployment instructions for reference. The External Filter in this repo does not perform any authorization and is instead meant to serve as a reference for the operations that an External can make use of.