CustomResponsePolicy

microgateway.airlock.com/v1alpha1

CustomResponsePolicy is a Direct Attached Policy for the Kubernetes Gateway API.
It defines a rule-based policy for replacing local responses with custom responses.
Note: For requests matching any valid HTTPRoute to which the policy is attached, the policy fully overrides any global custom response configuration in GatewayParameters (no merging).

​
apiVersion: microgateway.airlock.com/v1alpha1
kind: CustomResponsePolicy
metadata:
  name: custom-response-policy-example
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: backend
  policies:
    local:
      # Only use custom 401 for requests to /api
      - requestConditions:
          path:
            matcher:
              prefix: /api
        responses:
        - statusCodeCondition:
            matcher:
              exact: 401
          customResponseRef:
            name: api-401

      # Use default responses for requests to /default
      - requestConditions:
          path:
            matcher:
              prefix: /default
        responses: []

      # Customize all local error responses for other requests
      - responses:
         - statusCodeCondition:
             matcher:
               exact: 401
           customResponseRef:
             name: custom-401
         - statusCodeCondition:
             matcher:
               exact: 404
           customResponseRef:
             name: custom-404
         - statusCodeCondition:
             matcher:
               range:
                 start: 400
                 end: 499
           customResponseRef:
             name: custom-400
         - statusCodeCondition:
             matcher:
               range:
                 start: 500
                 end: 599
           customResponseRef:
             name: custom-5xx

    upstream:
      # Don't replace upstream error responses on API endpoints
      - requestConditions:
          path:
            matcher:
              prefix: /api
        responses: []

      # Replace all other upstream error responses
      - responses:
          - responseConditions:
              statusCode:
                matcher:
                  range:
                    start: 400
                    end: 499
            customResponseRef:
              name: upstream-4xx
          - responseConditions:
              statusCode:
                matcher:
                  range:
                    start: 500
                    end: 599
            customResponseRef:
              name: upstream-5xx

CustomResponsePolicy

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired custom response configuration. object yes
status describes the current status of the CustomResponsePolicy. PolicyStatus no

CustomResponsePolicy.spec

Field Description Type Required Default Allowed Values
policies configures replacement policies for different kinds of responses. object yes
targetRefs are the resources this policy is being attached to. Referenced resources must be in the same namespace as the policy.
Support: HTTPRoute.		 LocalPolicyTargetReference[] yes

CustomResponsePolicy.spec.policies

Field Description Type Required Default Allowed Values
local configures policies for customizing direct responses originating from the Gateway itself during its processing (i.e., not from the upstream/backend). The first matching policy (from top to bottom) applies.
If local is not specified or if the request does not match any policy, default responses will be served.		 object[] no
upstream configures policies for replacing upstream (backend) responses with custom responses. The first matching policy (from top to bottom) applies.
If upstream is not specified or if the request does not match any policy, the original upstream responses will be forwarded to the client.		 object[] no

CustomResponsePolicy.spec.policies.local[]

Field Description Type Required Default Allowed Values
requestConditions defines additional request properties which must all be matched in order for this policy to apply. A policy without request conditions will always match. object no
responses specifies the local response customization rules to apply when the request matches this policy.

The rules are processed as follows:
  • The first rule (from top to bottom) where the statusCodeCondition matches the local response’s status code determines the custom response to be sent.
  • If no rule matches (or if no rules are defined), the Gateway will send default responses.
Default error responses, available as text/html, application/json and text/plain (fallback):
  • 401 -> built-in 401 response
  • 403 -> built-in 403 response
  • 404 -> built-in 404 response
  • 429 -> built-in 429 response
  • 4xx -> built-in 400 response (status code replaced with 400)
  • 5xx -> built-in 5xx response (status code preserved for 502-504, others replaced with 500)
If you wish to customize all built-in error responses, we recommend at least the following set of rules as a starting point: 
local:
 - statusCodeCondition:
     matcher:
       exact: 401
   customResponseRef:
     name: custom-401
 - statusCodeCondition:
     matcher:
       exact: 404
   customResponseRef:
     name: custom-404
 - statusCodeCondition:
     matcher:
       range:
         start: 400
         end: 499
   customResponseRef:
     name: custom-400
 - statusCodeCondition:
     matcher:
       range:
         start: 500
         end: 599
   customResponseRef:
     name: custom-5xx
Examples of local responses sent by the Gateway:
  • 301 | 302 | 303 | 307 | 308 (redirects)
  • 400 (invalid requests, blocked requests, rejected requests due to invalid configuration e.g., invalid OpenAPI spec)
  • 401 (denied by access control, OIDC/JWT authentication errors, token exchange errors)
  • 403 (CSRF protection, wrong scheme)
  • 404 (request does not match any route)
  • 408 (request timeout)
  • 429 (community rate limit reached)
  • 500 (invalid route/backend/policy configuration)
  • 502 | 503 (other errors)
  • 504 (backend timeout)
Note: If EnvoyExtensionPolicy is allowed, custom filters may generate arbitrary local responses.		 object[] yes

CustomResponsePolicy.spec.policies.local[].requestConditions

Field Description Type Required Default Allowed Values
header defines the matching headers of a request. object no
invert indicates whether the request condition should be inverted. bool no false true, false
mediaType defines the matching media type from the content-type header of a request. object no
method defines the matching methods of a request. enum[] no CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE
path defines the matching path of a request. object no
remoteIP defines the matching remote IPs of a request.
Note: Depending on your setup you may need to adapt the remoteIP configuration in the SidecarGateway / GatewayParameters resource to ensure correct client IP detection.		 object no

CustomResponsePolicy.spec.policies.local[].requestConditions.header

Field Description Type Required Default Allowed Values
name defines the name of a header. object no
value defines the value of a header. object no

CustomResponsePolicy.spec.policies.local[].requestConditions.header.name

Field Description Type Required Default Allowed Values
matcher defines the way to match a string. In comparison to a normal StringMatcher, a value is always matched ignoring the case and can’t be inverted. object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.local[].requestConditions.header.name.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.local[].requestConditions.header.value

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.local[].requestConditions.header.value.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.local[].requestConditions.mediaType

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.local[].requestConditions.mediaType.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.local[].requestConditions.path

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.local[].requestConditions.path.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.local[].requestConditions.remoteIP

Field Description Type Required Default Allowed Values
cidrRanges defines the IPv4 or IPv6 CIDR ranges, e.g. 196.148.3.128/26 or 2001:db8::/28. string[] yes
invert indicates whether the match should be inverted. bool no false true, false

CustomResponsePolicy.spec.policies.local[].responses[]

Field Description Type Required Default Allowed Values
customResponseRef selects the custom response to send. object yes
statusCodeCondition specifies a condition which the status code of the original local response must satisfy in order for this custom response to be sent. object yes

CustomResponsePolicy.spec.policies.local[].responses[].customResponseRef

Field Description Type Required Default Allowed Values
name of the resource string yes

CustomResponsePolicy.spec.policies.local[].responses[].statusCodeCondition

Field Description Type Required Default Allowed Values
matcher matches one or more status codes. object yes exact{}, range{}

CustomResponsePolicy.spec.policies.local[].responses[].statusCodeCondition.matcher

Field Description Type Required Default Allowed Values
exact matches a specific status code. int32 no [100, 599]
range matches an inclusive range of status codes. object no

CustomResponsePolicy.spec.policies.local[].responses[].statusCodeCondition.matcher.range

Field Description Type Required Default Allowed Values
end of the range (inclusive). int32 yes [100, 599]
start of the range (inclusive). int32 yes [100, 599]

CustomResponsePolicy.spec.policies.upstream[]

Field Description Type Required Default Allowed Values
requestConditions defines additional request properties which must all be matched in order for this policy to apply. A policy without request conditions will always match. object no
responses specifies the upstream response customization rules to apply when the request matches this policy.

The rules are processed as follows:
  • The first rule (from top to bottom) where the responseConditions matches the upstream response determines the custom response to be sent.
  • If no rule matches (or if no upstream rules are defined), the unmodified upstream response is forwarded to the client.
object[] yes

CustomResponsePolicy.spec.policies.upstream[].requestConditions

Field Description Type Required Default Allowed Values
header defines the matching headers of a request. object no
invert indicates whether the request condition should be inverted. bool no false true, false
mediaType defines the matching media type from the content-type header of a request. object no
method defines the matching methods of a request. enum[] no CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE
path defines the matching path of a request. object no
remoteIP defines the matching remote IPs of a request.
Note: Depending on your setup you may need to adapt the remoteIP configuration in the SidecarGateway / GatewayParameters resource to ensure correct client IP detection.		 object no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.header

Field Description Type Required Default Allowed Values
name defines the name of a header. object no
value defines the value of a header. object no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.header.name

Field Description Type Required Default Allowed Values
matcher defines the way to match a string. In comparison to a normal StringMatcher, a value is always matched ignoring the case and can’t be inverted. object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.upstream[].requestConditions.header.name.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.header.value

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.upstream[].requestConditions.header.value.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.mediaType

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.upstream[].requestConditions.mediaType.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.path

Field Description Type Required Default Allowed Values
matcher object yes contains{}, exact{}, prefix{}, regex{}, suffix{}

CustomResponsePolicy.spec.policies.upstream[].requestConditions.path.matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

CustomResponsePolicy.spec.policies.upstream[].requestConditions.remoteIP

Field Description Type Required Default Allowed Values
cidrRanges defines the IPv4 or IPv6 CIDR ranges, e.g. 196.148.3.128/26 or 2001:db8::/28. string[] yes
invert indicates whether the match should be inverted. bool no false true, false

CustomResponsePolicy.spec.policies.upstream[].responses[]

Field Description Type Required Default Allowed Values
customResponseRef selects the custom response to send. object yes
responseConditions specifies conditions which the upstream response must all satisfy in order for this custom response to be sent. object yes

CustomResponsePolicy.spec.policies.upstream[].responses[].customResponseRef

Field Description Type Required Default Allowed Values
name of the resource string yes

CustomResponsePolicy.spec.policies.upstream[].responses[].responseConditions

Field Description Type Required Default Allowed Values
statusCode specifies a condition on the original upstream response’s status code. object yes

CustomResponsePolicy.spec.policies.upstream[].responses[].responseConditions.statusCode

Field Description Type Required Default Allowed Values
matcher matches one or more status codes. object yes exact{}, range{}

CustomResponsePolicy.spec.policies.upstream[].responses[].responseConditions.statusCode.matcher

Field Description Type Required Default Allowed Values
exact matches a specific status code. int32 no [100, 599]
range matches an inclusive range of status codes. object no

CustomResponsePolicy.spec.policies.upstream[].responses[].responseConditions.statusCode.matcher.range

Field Description Type Required Default Allowed Values
end of the range (inclusive). int32 yes [100, 599]
start of the range (inclusive). int32 yes [100, 599]