Docs
Edge StackThe External Filter Type (v1alpha1)
The External Filter Type (v1alpha1)
The External Filter allows users to provide their own Kubernetes Service speaking the ext_authz protocol.
Ambassador Edge Stack will send a request to this "External Service" that contains a copy of the incoming request. The External Service will then be able
to examine details of the incoming request, make changes to its headers, and allow or reject it by sending back a response to Ambassador Edge Stack.
The external service is free to perform any logic it likes before responding to Ambassador Edge Stack, allowing for custom filtering and
processing on incoming requests. The External Filter may be used along with any of the other Filter types. For more information about
how requests are matched to Filter resources and the order in which Filters are executed, please refer to the FilterPolicy Resource documentation.
This doc is an overview of all the fields on the External Filter Custom Resource with descriptions of the purpose, type, and default values of those fields.
This page is specific to the gateway.getambassador.io/v1alpha1 version of the External Filter resource. For the older getambassador.io/v3alpha1 resource,
please see the v3alpha1 External Filter api reference.
External Filter API Reference
To create an External Filter, the spec.type must be set to external, and the external field must contain the configuration for your
external filter.
ExternalFilter
| Field | Type | Description |
|---|---|---|
protocol | Enum ("http"/"grpc") | The type of protocol to use when communicating with the External Service. It is recommended to use "grpc" over "http" due to supporting additional capabilities. |
authServiceURL | string | The URL of the service performing the authorization / filtering logic. Must be an absolute URL. |
statusOnError | int | Allows overriding the status code returned when the External Service returns a non 200 response code for protocol: "http" or DeniedHttpResponse for protocol: "grpc" |
failureModeAllow | bool | Determines what happens when Ambassador Edge Stack cannot communicate with the External Service due to network issues, or the service not being available. By default, the ExternalFilter will reject the request if it is unable to communicate. This can be overriden by setting this setting to "true" so that it fails open, allowing the request through to the upstream service. |
timeout | Duration | The amount of time Ambassador Edge Stack will wait before erring on a timeout. Note: this value cannot be larger than the overall Auth Service timeout that is configured in Envoy or else it would effectively not have any timeout. |
httpSettings | HTTPSettings | Settings specific to the http protocol. This can only be set when protocol: "http". |
grpcSettings | GRPCSettings | Settings specific to the grpc protocol. This can only be set when protocol: "grpc". |
include_body | IncludeBody | Configures passing along the request body to the External Service. If not set then a blank body is sent over to the External Service. |
tlsConfig | TLSConfig | Configures tls settings between Ambassador Edge Stack and the configured AuthService |
Duration
Appears On: ExternalFilter
Duration is a field that accepts a string that will be parsed as a sequence of decimal numbers (metav1.Duration), each with optional fraction
and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s",
"m", "h". See Go time.ParseDuration.
HTTPSettings
Appears On:
Settings specific to the http protocol. This can only be set when protocol: "http".
| Field | Type | Description |
|---|---|---|
pathPrefix | string | Value that gets appended to the path of the downsteam request. Nothing is appended when this field is omitted |
allowedRequestHeaders | []string | A list of headers from the downstream request that will be passed along as headers in the request to the external service. This includes metadata sent from Envoy to the EdgeStack Auth Service. By default, the following list of headers are passed through: authorization,cookie,from,proxy-authorization, user-agent, x-forwarded-for, x-forwarded-host, x-forwarded-proto. |
allowedAuthorizationHeaders | []string | Headers from the External Service that will be added to the request to the upstream service. By default, the following headers are passed to the upstream service: location,authorization,proxy-authenticate,set-cookie,www-authenticate. Any additional headers that are needed should be added and are case-insenstive. |
addLinkerdHeaders | bool | When set to true, injects the l5d-dst-override header set to hostname and port of the external service which is used by LinkerD when proxying through the Service Mesh. |
GRPCSettings
Appears On: ExternalFilter
Settings specific to the http protocol. This can only be set when protocol: "grpc".
| Field | Type | Description |
|---|---|---|
protocolVersion | Enum ("v3") | Indicates the version of the transport protocol that the External Filter is using. This is only applicable to External Filters using protocol: "grpc". Currently the only supported version is "v3", so this field exists to provide compatability for future verions of ext_authz. |
IncludeBody
Appears On: ExternalFilter Configures passing along the request body to the External Service. If not set then a blank body is sent over to the External Service.
| Field | Type | Description |
|---|---|---|
maxBytes | int | Sets the number of bytes of the request body to buffer over to the External Service |
allowPartial | bool | Indicates whether the included body can be a partially buffered body or if the complete buffered body is expected. If not partial then a 413 http error is returned by Envoy. |
TLSConfig
Appears On: ExternalFilter Configures passing along the request body to the External Service. If not set then a blank body is sent over to the External Service.
| Field | Type | Description |
|---|---|---|
certificate.fromSecret | SecretReference | Configures Ambassador Edge Stack to use the provided certificate to present to the server when connecting. Provide the name and namespace (optional) of a kubernetes.io/tls [Kubernetes Secret][] that contains the private key and public certificate that will be presented to the AuthService. Secret namespace defaults to Filter namespace if not set |
caCertificate.fromSecret | SecretReference | Configures Ambassador Edge Stack to use the provided CA certifcate to verify the server provided certificate. Provide the name and namespace (optional) of an Opaque [Kubernetes Secret][] that contains the tls.crt key with the CA Certificate. Secret namespace defaults to Filter namespace if not set |