Docs
Edge StackThe FilterPolicy Resource (v1alpha1)
The FilterPolicy Resource (v1alpha1)
The FilterPolicy custom resource works in conjunction with the Filter custom resource to define how and when Ambassador Edge Stack will
modify or intercept incoming requests before sending to your upstream Service. Filters define what actions to take on a request,
while FilterPolicies define the matching criteria for requests such as the headers, hostname, and path, and supply references to
one or more Filters to execute on those requests.
This doc is an overview of all the fields on the FilterPolicy 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 FilterPolicy resource. For the older getambassador.io/v3alpha1 resource,
please see the v3alpha1 FilterPolicy api reference.
FilterPolicy API Reference
FilterPolicy
| Field | Type | Description |
|---|---|---|
rules | []FilterPolicyRule | Set of matching rules that are checked against incoming request to determine which set of Filter's to apply. If no matches are found then the request is allowed through to the upstream service without executing any Filters. |
FilterPolicyRule
Appears on: FilterPolicy
Configures matching rules that are checked against incoming request to determine which Filter to apply (if any).
| Field | Type | Description |
|---|---|---|
host | string | "glob-string" that matches on the :authority header of the incoming request. If not set it will match on all incoming requests. |
path | string | "glob-string" that matches on the request path. If not provided then it will match on all incoming requests. |
filterRefs | []FilterReference | List of references to Filters that will be applied to the incoming request. Filters will be applied to the request in the order they are listed. If no filters are provided then the request will be allowed through to the upstream service without any additional processing. This allows for having one Rule that is overly permissive and then using a single rule to opt-out on certain paths. |
precedence | int | Allows forcing a precedence ordering on the rules. By default the rules are evaluated in the order they are in the FilterPolicy.spec.rules field. However, multiple FilterPolicy's can be applied to a cluster. To ensure that a specific ordering is enforced then using a precedence is an option. |
FilterReference
Appears on: FilterPolicyRule, OAuth2Redirect
List of references to Filters that will be applied to the incoming request. Filters will be applied to the request in the order they are listed. If no filters are provided then the request will be allowed through to the upstream service without any additional processing. This allows for having one Rule that is overly permissive and then using a single rule to opt-out on certain paths.
| Field | Type | Description |
|---|---|---|
name | string | Name that identifies the Filter |
namespace | string | Kubernetes namespace that the Filter resides. It must be a RFC 1123 label. Valid values include: "example", Invalid values include: "example.com" (. is an invalid character). This validation is based off of the corresponding Kubernetes validation. |
onDeny | Enum ("break","continue") | Determines the behavior when a Filter denies the request. |
onAllow | Enum ("break","continue") | Determines the behavior when a Filter denies the request. |
ifRequestHeader | HTTPHeaderMatch | Checks if exact or regular expression matches a value in a request Header to determine if an individual Filter is executed or not. |
arguments | FilterArguments | Strongly typed input arguments that can be passed into a Filter on per FilterReference level allowing for different behavior on different Rules. |
HTTPHeaderMatch
Appears on: FilterPolicyRule, OAuth2Redirect Checks if exact or regular expression matches a value in a request Header to determine if an individual Filter is executed or not.
| Field | Type | Description |
|---|---|---|
type | Enum("Exact","RegularExpression") | The semantics of how HTTP header values should be evaluated |
name | string | Name of the header to match. Matching is case insensitive. (See https://tools.ietf.org/html/rfc7230). Valid examples: "Authorization"/"Set-Cookie"/":method". |
value | string | Value of HTTP Header to be matched. If type is RegularExpression then this must be a valid regex with length being at least 1. |
negate | bool | Allows the match criteria to be negated or flipped. For example, you can have a regex that checks for any non-empty string which would indicate would translate to if header exists on request then match on it. With negate turned on this would translate to match on any request that doesn't have a header. |
FilterArguments
Appears on: FilterPolicyRule Strongly typed input arguments that can be passed into a Filter on per FilterReference level allowing for different behavior on different Rules.
| Field | Type | Description |
|---|---|---|
type | Enum ("jwt"/"oauth2") | Identifies the expected type of the arguments that will be passed to the FilterRef. This must match the type of the filterRef and if it doesn't the FilterPolicy rule will be considered invalid and a status condition will be updated to indicate the mismatch. |
jwt | JWTArguments | Defines the input arguments that can be set for an JWT Filter on a per FilterPolicy rule level. |
oauth2 | OAuth2Arguments | Defines the input arguments that can be set for an OAuth2 Filter on a per FilterPolicy rule level. |
JWTArguments
Appears on: FilterArguments
Defines the input arguments that can be set for an JWT Filter on a per FilterPolicy rule level.
| Field | Type | Description |
|---|---|---|
scope | []string | Set of scopes the JWT will be validated against |
OAuth2Arguments
Appears on: FilterArguments
Defines the input arguments that can be set for an OAuth2 Filter on a per FilterPolicy rule level.
| Field | Type | Description |
|---|---|---|
scope | []string | Set of scopes the JWT will be validated against |
insteadOfRedirect | OAuth2Redirect | Allows customizing the behavior of the OAuth2 redirect and whether it will redirect the browser or not. |
sameSite | Enum("default","none","lax","strict") | Set of options for setting the SameSite attribute on a cookie. https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 for details. |
OAuth2Redirect
Appears on: OAuth2Arguments Allows customizing the behavior of the OAuth2 redirect and whether it will redirect the browser or not.
| Field | Type | Description |
|---|---|---|
statusCode | int | The HTTP status code to be used in response. If filterRef is not set then this will default to a 403 forbidden. |
ifRequestHeader | HTTPHeaderMatch | Allows only applying the InsteadOfRedirect logic when a the header matches. |
filterRefs | []FilterReference | List of references to Filter's that will be applied when an OAuth2 session has expired and the user would like to try a secondary authentication mechanism without redircting to the iDP. Nesting an OAuth2 Filter inside of an OAuth2 Filter is not supported. |
FilterPolicyStatus
Automatically managed by the controller to reflect the state of the FilterPolicy
| Field | Type | Description |
|---|---|---|
conditions | []metav1.Condition | Describes the current condition of the FilterPolicy. |
rules | []FilterPolicyRuleStatus | Describes the status for each unique Rule defined in the Spec |
rules.index | string | The zero-based index of the rule within rules with the problem to help with identifying the error |
rules.host | string | host of the rule with the problem to help with identifying the error |
rules.path | string | path of the rule with the problem to help with identifying the error |
rules.conditions | []metav1.Condition | Describes the current condition of a specific rule. |