Last changed in Kgateway v2.3.0
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
TrafficPolicySpec defines the desired state of a traffic policy.
ACL configures IP-based access control for HTTP requests. Rules are evaluated using longest-prefix matching on the effictive client IP from envoy base on settings. See the UseRemoteAddress, XffTrustedCIDRs, XffNumTrustedHops settings under ListenerPolicy -> HttpSettings for details.
DefaultAction is the action to take when no rule matches the client IP.
DenyResponse customizes the HTTP response sent when a request is denied.
BlockedByHeaderName, when set, adds a response header with this name on every deny. The header value mirrors the blocked-by dynamic metadata: the matched rule's name, "rule" for an unnamed rule, or "default" for a default-action deny.
Headers are additional response headers to attach on every deny.
Name is the header name.
Value is the header value.
StatusCode is the HTTP status code returned on deny. Defaults to 403.
Rules is a list of IP/CIDR-based rules. Longest-prefix match wins regardless of rule order.
Action determines what to do when a client IP matches this rule.
CIDRs is a list of IP addresses or CIDR ranges (e.g. "10.0.0.0/8", "2001:db8::/32", "192.168.1.1", "::1"). Bare IPs without a prefix are treated as /32 for IPv4 and /128 for IPv6. All entries share the same name and action.
Name is an optional rule identifier emitted as blocked-by dynamic metadata on deny.
APIKeyAuth authenticates users based on a configured API Key.
clientIdHeader specifies the header name to forward the authenticated client identifier. If not specified, the client identifier will not be forwarded in any header. Example: "x-client-id"
Disable the API key authentication filter. Can be used to disable API key authentication policies applied at a higher level in the config hierarchy.
forwardCredential controls whether the API key is included in the request sent to the upstream. If false (default), the API key is removed from the request before sending to upstream. If true, the API key is included in the request sent to upstream. This applies to all configured key sources (header, query parameter, or cookie).
keySources specifies the list of key sources to extract the API key from. Key sources are processed in array order and the first one that successfully extracts a key is used. Within each key source, if multiple types (header, query, cookie) are specified, precedence is: header > query parameter > cookie. If empty, defaults to a single key source with header "api-key". Example: keySources: - header: "X-API-KEY" - query: "api_key" - header: "Authorization" query: "token" cookie: "auth_token" In this example, the system will: 1. First try header "X-API-KEY" 2. If not found, try query parameter "api_key" 3. If not found, try header "Authorization" (then query "token", then cookie "auth_token" within that key source)
cookie specifies the name of the cookie that contains the API key.
header specifies the name of the header that contains the API key.
query specifies the name of the query parameter that contains the API key.
secretRef references a Kubernetes secret storing a set of API Keys. If there are many keys, 'secretSelector' can be used instead. Each entry in the Secret represents one API Key. The key is an arbitrary identifier. The value is a string, representing the API Key. Example: apiVersion: v1 kind: Secret metadata: name: api-key stringData: client1: "k-123" client2: "k-456"
Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred.
Kind is kind of the referent. For example "Secret".
Name is the name of the referent.
Namespace is the namespace of the referenced object. When unspecified, the local namespace is inferred. Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. Support: Core
secretSelector selects multiple secrets containing API Keys. If the same key is defined in multiple secrets, the behavior is undefined. Each entry in the Secret represents one API Key. The key is an arbitrary identifier. The value is a string, representing the API Key. Example: apiVersion: v1 kind: Secret metadata: name: api-key stringData: client1: "k-123" client2: "k-456"
Label selector to select the target resource.
AutoHostRewrite rewrites the Host header to the DNS name of the selected upstream. NOTE: This field is only honored for HTTPRoute targets. NOTE: If `autoHostRewrite` is set on a route that also has a [URLRewrite filter](https://gateway-api.sigs.k8s.io/reference/spec/#httpurlrewritefilter) configured to override the `hostname`, the `hostname` value will be used and `autoHostRewrite` will be ignored.
BasicAuth specifies the HTTP basic authentication configuration for the policy. This controls authentication using username/password credentials in the Authorization header.
Disable basic auth. Can be used to disable basic auth policies applied at a higher level in the config hierarchy.
SecretRef references a Kubernetes secret containing htpasswd data. The secret must contain username/password pairs in htpasswd format.
Key in the secret that contains the htpasswd data. Defaults to ".htpasswd" if not specified.
Name of the secret containing htpasswd data.
Namespace of the secret. If not specified, defaults to the namespace of the TrafficPolicy. Note that a secret in a different namespace requires a ReferenceGrant to be accessible.
Users provides an inline list of username/password pairs in htpasswd format. Each entry should be formatted as "username:hashed_password". The only supported hash format is SHA-1 Example entries: - "user1:{SHA}d95o2uzYI7q7tY7bHI4U1xBug7s="
Buffer can be used to set the maximum request size that will be buffered. Requests exceeding this size will return a 413 response.
Disable the buffer filter. Can be used to disable buffer policies applied at a higher level in the config hierarchy.
MaxRequestSize sets the maximum size in bytes of a message body to buffer. Requests exceeding this size will receive HTTP 413. Example format: "1Mi", "512Ki", "1Gi"
Compression configures response compression (per-route) and request/response decompression (listener-level insertion triggered by route enable). The response compression configuration is only honored for HTTPRoute targets.
RequestDecompression controls request decompression. If set, gzip requests will be decompressed.
Disables decompression.
ResponseCompression controls response compression to the downstream. If set, responses with the appropriate `Accept-Encoding` header with certain textual content types will be compressed using gzip. The content-types that will be compressed are: - `application/javascript` - `application/json` - `application/xhtml+xml` - `image/svg+xml` - `text/css` - `text/html` - `text/plain` - `text/xml`
Disables compression.
Cors specifies the CORS configuration for the policy.
AllowCredentials indicates whether the actual cross-origin request allows to include credentials. When set to true, the gateway will include the `Access-Control-Allow-Credentials` response header with value true (case-sensitive). When set to false or omitted the gateway will omit the header `Access-Control-Allow-Credentials` entirely (this is the standard CORS behavior). Support: Extended
AllowHeaders indicates which HTTP request headers are supported for accessing the requested resource. Header names are not case-sensitive. Multiple header names in the value of the `Access-Control-Allow-Headers` response header are separated by a comma (","). When the `AllowHeaders` field is configured with one or more headers, the gateway must return the `Access-Control-Allow-Headers` response header which value is present in the `AllowHeaders` field. If any header name in the `Access-Control-Request-Headers` request header is not included in the list of header names specified by the response header `Access-Control-Allow-Headers`, it will present an error on the client side. If any header name in the `Access-Control-Allow-Headers` response header does not recognize by the client, it will also occur an error on the client side. A wildcard indicates that the requests with all HTTP headers are allowed. If config contains the wildcard "*" in allowHeaders and the request is not credentialed, the `Access-Control-Allow-Headers` response header can either use the `*` wildcard or the value of Access-Control-Request-Headers from the request. When the request is credentialed, the gateway must not specify the `*` wildcard in the `Access-Control-Allow-Headers` response header. When also the `AllowCredentials` field is true and `AllowHeaders` field is specified with the `*` wildcard, the gateway must specify one or more HTTP headers in the value of the `Access-Control-Allow-Headers` response header. The value of the header `Access-Control-Allow-Headers` is same as the `Access-Control-Request-Headers` header provided by the client. If the header `Access-Control-Request-Headers` is not included in the request, the gateway will omit the `Access-Control-Allow-Headers` response header, instead of specifying the `*` wildcard. Support: Extended
AllowMethods indicates which HTTP methods are supported for accessing the requested resource. Valid values are any method defined by RFC9110, along with the special value `*`, which represents all HTTP methods are allowed. Method names are case-sensitive, so these values are also case-sensitive. (See https://www.rfc-editor.org/rfc/rfc2616#section-5.1.1) Multiple method names in the value of the `Access-Control-Allow-Methods` response header are separated by a comma (","). A CORS-safelisted method is a method that is `GET`, `HEAD`, or `POST`. (See https://fetch.spec.whatwg.org/#cors-safelisted-method) The CORS-safelisted methods are always allowed, regardless of whether they are specified in the `AllowMethods` field. When the `AllowMethods` field is configured with one or more methods, the gateway must return the `Access-Control-Allow-Methods` response header which value is present in the `AllowMethods` field. If the HTTP method of the `Access-Control-Request-Method` request header is not included in the list of methods specified by the response header `Access-Control-Allow-Methods`, it will present an error on the client side. If config contains the wildcard "*" in allowMethods and the request is not credentialed, the `Access-Control-Allow-Methods` response header can either use the `*` wildcard or the value of Access-Control-Request-Method from the request. When the request is credentialed, the gateway must not specify the `*` wildcard in the `Access-Control-Allow-Methods` response header. When also the `AllowCredentials` field is true and `AllowMethods` field specified with the `*` wildcard, the gateway must specify one HTTP method in the value of the Access-Control-Allow-Methods response header. The value of the header `Access-Control-Allow-Methods` is same as the `Access-Control-Request-Method` header provided by the client. If the header `Access-Control-Request-Method` is not included in the request, the gateway will omit the `Access-Control-Allow-Methods` response header, instead of specifying the `*` wildcard. Support: Extended
AllowOrigins indicates whether the response can be shared with requested resource from the given `Origin`. The `Origin` consists of a scheme and a host, with an optional port, and takes the form `<scheme>://<host>(:<port>)`. Valid values for scheme are: `http` and `https`. Valid values for port are any integer between 1 and 65535 (the list of available TCP/UDP ports). Note that, if not included, port `80` is assumed for `http` scheme origins, and port `443` is assumed for `https` origins. This may affect origin matching. The host part of the origin may contain the wildcard character `*`. These wildcard characters behave as follows: * `*` is a greedy match to the _left_, including any number of DNS labels to the left of its position. This also means that `*` will include any number of period `.` characters to the left of its position. * A wildcard by itself matches all hosts. An origin value that includes _only_ the `*` character indicates requests from all `Origin`s are allowed. When the `AllowOrigins` field is configured with multiple origins, it means the server supports clients from multiple origins. If the request `Origin` matches the configured allowed origins, the gateway must return the given `Origin` and sets value of the header `Access-Control-Allow-Origin` same as the `Origin` header provided by the client. The status code of a successful response to a "preflight" request is always an OK status (i.e., 204 or 200). If the request `Origin` does not match the configured allowed origins, the gateway returns 204/200 response but doesn't set the relevant cross-origin response headers. Alternatively, the gateway responds with 403 status to the "preflight" request is denied, coupled with omitting the CORS headers. The cross-origin request fails on the client side. Therefore, the client doesn't attempt the actual cross-origin request. Conversely, if the request `Origin` matches one of the configured allowed origins, the gateway sets the response header `Access-Control-Allow-Origin` to the same value as the `Origin` header provided by the client. When config has the wildcard ("*") in allowOrigins, and the request is not credentialed (e.g., it is a preflight request), the `Access-Control-Allow-Origin` response header either contains the wildcard as well or the Origin from the request. When the request is credentialed, the gateway must not specify the `*` wildcard in the `Access-Control-Allow-Origin` response header. When also the `AllowCredentials` field is true and `AllowOrigins` field specified with the `*` wildcard, the gateway must return a single origin in the value of the `Access-Control-Allow-Origin` response header, instead of specifying the `*` wildcard. The value of the header `Access-Control-Allow-Origin` is same as the `Origin` header provided by the client. Support: Extended
Disable the CORS filter. Can be used to disable CORS policies applied at a higher level in the config hierarchy.
ExposeHeaders indicates which HTTP response headers can be exposed to client-side scripts in response to a cross-origin request. A CORS-safelisted response header is an HTTP header in a CORS response that it is considered safe to expose to the client scripts. The CORS-safelisted response headers include the following headers: `Cache-Control` `Content-Language` `Content-Length` `Content-Type` `Expires` `Last-Modified` `Pragma` (See https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name) The CORS-safelisted response headers are exposed to client by default. When an HTTP header name is specified using the `ExposeHeaders` field, this additional header will be exposed as part of the response to the client. Header names are not case-sensitive. Multiple header names in the value of the `Access-Control-Expose-Headers` response header are separated by a comma (","). A wildcard indicates that the responses with all HTTP headers are exposed to clients. The `Access-Control-Expose-Headers` response header can only use `*` wildcard as value when the request is not credentialed. When the `exposeHeaders` config field contains the "*" wildcard and the request is credentialed, the gateway cannot use the `*` wildcard in the `Access-Control-Expose-Headers` response header. Support: Extended
MaxAge indicates the duration (in seconds) for the client to cache the results of a "preflight" request. The information provided by the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` response headers can be cached by the client until the time specified by `Access-Control-Max-Age` elapses. The default value of `Access-Control-Max-Age` response header is 5 (seconds). When the `MaxAge` field is unspecified, the gateway sets the response header "Access-Control-Max-Age: 5" by default.
Csrf specifies the Cross-Site Request Forgery (CSRF) policy for this traffic policy.
Specifies additional source origins that will be allowed in addition to the destination origin.
The input string must contain the substring specified here. Example: abc matches the value xyz.abc.def
The input string must match exactly the string specified here. Example: abc matches the value abc
If true, indicates the exact/prefix/suffix/contains matching should be case insensitive. This has no effect on the regex match. For example, the matcher data will match both input string Data and data if this option is set to true.
The input string must have the prefix specified here. Note: empty prefix is not allowed, please use regex instead. Example: abc matches the value abc.xyz
The input string must match the Google RE2 regular expression specified here. See https://github.com/google/re2/wiki/Syntax for the syntax.
The input string must have the suffix specified here. Note: empty prefix is not allowed, please use regex instead. Example: abc matches the value xyz.abc
Specifies the percentage of requests for which the CSRF filter is enabled.
Specifies that CSRF policies will be evaluated and tracked, but not enforced.
ExtAuth specifies the external authentication configuration for the policy. This controls what external server to send requests to for authentication.
Additional context for the auth service.
Disable all external auth filters. Can be used to disable external auth policies applied at a higher level in the config hierarchy.
ExtensionRef references the GatewayExtension that should be used for auth.
The name of the target resource.
The namespace of the target resource. If not set, defaults to the namespace of the parent object.
WithRequestBody allows the request body to be buffered and sent to the auth service. Warning buffering has implications for streaming and therefore performance.
AllowPartialMessage determines if partial messages should be allowed. When true, requests will be sent to the auth service even if they exceed maxRequestBytes. The default behavior is false.
MaxRequestBytes sets the maximum size of a message body to buffer. Requests exceeding this size will receive HTTP 413 and not be sent to the auth service.
PackAsBytes determines if the body should be sent as raw bytes. When true, the body is sent as raw bytes in the raw_body field. When false, the body is sent as UTF-8 string in the body field. The default behavior is false.
ExtProc specifies the external processing configuration for the policy.
Disable all external processing filters. Can be used to disable external processing policies applied at a higher level in the config hierarchy.
ExtensionRef references the GatewayExtension that should be used for external processing.
The name of the target resource.
The namespace of the target resource. If not set, defaults to the namespace of the parent object.
ProcessingMode defines how the filter should interact with the request/response streams
RequestBodyMode determines how to handle the request body
RequestHeaderMode determines how to handle the request headers
RequestTrailerMode determines how to handle the request trailers
ResponseBodyMode determines how to handle the response body
ResponseHeaderMode determines how to handle the response headers
ResponseTrailerMode determines how to handle the response trailers
FaultInjection configures fault injection for chaos engineering and resiliency testing. Supports delay injection, abort injection, and response rate limiting.
Abort injects HTTP or gRPC errors to terminate requests early.
GrpcStatus is the gRPC status code to return when aborting a request.
HttpStatus is the HTTP status code to return when aborting a request.
Percentage of requests to abort. Defaults to 100.
Delay injects latency into requests before forwarding upstream.
FixedDelay is the duration to delay before forwarding the request.
Percentage of requests to inject the delay on. Defaults to 100.
Disable the fault injection filter. Can be used to disable fault injection policies applied at a higher level in the config hierarchy.
MaxActiveFaults limits the number of concurrent active faults. When this limit is reached, new requests will not have faults injected. If not specified, defaults to unlimited.
ResponseRateLimit limits the response body data rate to simulate slow or degraded upstream connections.
KbitsPerSecond limits the response rate to the specified kilobits per second.
Percentage of requests to apply the rate limit on. Defaults to 100.
HeaderModifiers defines the policy to modify request and response headers.
Request modifies request headers.
Add adds the given header(s) (name, value) to the request before the action. It appends to any existing values associated with the header name. Input: GET /foo HTTP/1.1 my-header: foo Config: add: - name: "my-header" value: "bar,baz" Output: GET /foo HTTP/1.1 my-header: foo,bar,baz
Name is the name of the HTTP Header to be matched. Name matching MUST be case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
Value is the value of HTTP Header to be matched. <gateway:experimental:description> Must consist of printable US-ASCII characters, optionally separated by single tabs or spaces. See: https://tools.ietf.org/html/rfc7230#section-3.2 </gateway:experimental:description> <gateway:experimental:validation:Pattern=`^[!-~]+([\t ]?[!-~]+)*$`>
Remove the given header(s) from the HTTP request before the action. The value of Remove is a list of HTTP header names. Note that the header names are case-insensitive (see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). Input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz Config: remove: ["my-header1", "my-header3"] Output: GET /foo HTTP/1.1 my-header2: bar
Set overwrites the request with the given header (name, value) before the action. Input: GET /foo HTTP/1.1 my-header: foo Config: set: - name: "my-header" value: "bar" Output: GET /foo HTTP/1.1 my-header: bar
Name is the name of the HTTP Header to be matched. Name matching MUST be case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
Value is the value of HTTP Header to be matched. <gateway:experimental:description> Must consist of printable US-ASCII characters, optionally separated by single tabs or spaces. See: https://tools.ietf.org/html/rfc7230#section-3.2 </gateway:experimental:description> <gateway:experimental:validation:Pattern=`^[!-~]+([\t ]?[!-~]+)*$`>
Response modifies response headers.
Add adds the given header(s) (name, value) to the request before the action. It appends to any existing values associated with the header name. Input: GET /foo HTTP/1.1 my-header: foo Config: add: - name: "my-header" value: "bar,baz" Output: GET /foo HTTP/1.1 my-header: foo,bar,baz
Name is the name of the HTTP Header to be matched. Name matching MUST be case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
Value is the value of HTTP Header to be matched. <gateway:experimental:description> Must consist of printable US-ASCII characters, optionally separated by single tabs or spaces. See: https://tools.ietf.org/html/rfc7230#section-3.2 </gateway:experimental:description> <gateway:experimental:validation:Pattern=`^[!-~]+([\t ]?[!-~]+)*$`>
Remove the given header(s) from the HTTP request before the action. The value of Remove is a list of HTTP header names. Note that the header names are case-insensitive (see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). Input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz Config: remove: ["my-header1", "my-header3"] Output: GET /foo HTTP/1.1 my-header2: bar
Set overwrites the request with the given header (name, value) before the action. Input: GET /foo HTTP/1.1 my-header: foo Config: set: - name: "my-header" value: "bar" Output: GET /foo HTTP/1.1 my-header: bar
Name is the name of the HTTP Header to be matched. Name matching MUST be case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
Value is the value of HTTP Header to be matched. <gateway:experimental:description> Must consist of printable US-ASCII characters, optionally separated by single tabs or spaces. See: https://tools.ietf.org/html/rfc7230#section-3.2 </gateway:experimental:description> <gateway:experimental:validation:Pattern=`^[!-~]+([\t ]?[!-~]+)*$`>
JWT specifies the JWT authentication configuration for the policy. This defines the JWT providers and their configurations.
Disable all JWT filters. Can be used to disable JWT policies applied at a higher level in the config hierarchy.
ExtensionRef references a GatewayExtension that provides the jwt providers
The name of the target resource.
The namespace of the target resource. If not set, defaults to the namespace of the parent object.
OAuth2 specifies the configuration to use for OAuth2/OIDC. Note: the OAuth2 filter does not protect against Cross-Site-Request-Forgery attacks on domains with cached authentication (in the form of cookies). It is recommended to pair this with the CSRF policy to prevent malicious social engineering.
ExtensionRef specifies the GatewayExtension that should be used for OAuth2.
The name of the target resource.
The namespace of the target resource. If not set, defaults to the namespace of the parent object.
RateLimit specifies the rate limiting configuration for the policy. This controls the rate at which requests are allowed to be processed.
Global defines a global rate limiting policy using an external service.
Descriptors define the dimensions for rate limiting. These values are passed to the rate limit service which applies configured limits based on them. Each descriptor represents a single rate limit rule with one or more entries.
Entries are the individual components that make up this descriptor. When translated to Envoy, these entries combine to form a single descriptor.
Generic contains the configuration for a generic key-value descriptor entry. This field must be specified when Type is Generic.
Key is the name of this descriptor entry.
Value is the static value for this descriptor entry.
Header specifies a request header to extract the descriptor value from. This field must be specified when Type is Header.
Type specifies what kind of rate limit descriptor entry this is.
ExtensionRef references a GatewayExtension that provides the global rate limit service.
The name of the target resource.
The namespace of the target resource. If not set, defaults to the namespace of the parent object.
Local defines a local rate limiting policy.
PercentEnabled specifies the percentage of requests for which the rate limiter is enabled.
PercentEnforced specifies the percentage of requests for which the rate limiter is enforced.
TokenBucket represents the configuration for a token bucket local rate-limiting mechanism. It defines the parameters for controlling the rate at which requests are allowed.
FillInterval defines the time duration between consecutive token fills. This value must be a valid duration string (e.g., "1s", "500ms"). It determines the frequency of token replenishment.
MaxTokens specifies the maximum number of tokens that the bucket can hold. This value must be greater than or equal to 1. It determines the burst capacity of the rate limiter.
TokensPerFill specifies the number of tokens added to the bucket during each fill interval. If not specified, it defaults to 1. This controls the steady-state rate of token generation.
RBAC specifies the role-based access control configuration for the policy. This defines the rules for authorization based on roles and permissions. RBAC policies applied at different attachment points in the configuration hierarchy are not cumulative, and only the most specific policy is enforced. This means an RBAC policy attached to a route will override any RBAC policies applied to the gateway or listener.
Action defines whether the rule allows or denies the request if matched. If unspecified, the default is "Allow".
Policy specifies the Authorization rule to evaluate. A policy matches when **any** of the conditions evaluates to true.
MatchExpressions defines a set of conditions that must be satisfied for the rule to match. These expression should be in the form of a Common Expression Language (CEL) expression.
Retry defines the policy for retrying requests. It is applicable to HTTPRoutes, Gateway listeners and ListenerSets, and ignored for other targeted kinds.
Attempts specifies the number of retry attempts for a request. Defaults to 1 attempt if not set. A value of 0 effectively disables retries.
BackoffBaseInterval specifies the base interval used with a fully jittered exponential back-off between retries. Defaults to 25ms if not set. Given a backoff base interval B and retry number N, the back-off for the retry is in the range [0, (2^N-1)*B]. The backoff interval is capped at a max of 10 times the base interval. E.g., given a value of 25ms, the first retry will be delayed randomly by 0-24ms, the 2nd by 0-74ms, the 3rd by 0-174ms, and so on, and capped to a max of 10 times the base interval (250ms).
PerTryTimeout specifies the timeout per retry attempt (incliding the initial attempt). If a global timeout is configured on a route, this timeout must be less than the global route timeout. It is specified as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "1s" or "500ms".
RetryOn specifies the conditions under which a retry should be attempted.
StatusCodes specifies the HTTP status codes in the range 400-599 that should be retried in addition to the conditions specified in RetryOn.
TargetRefs specifies the target resources by reference to attach the policy to.
The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`.
The API kind of the target resource, such as Gateway or HTTPRoute.
The name of the target resource.
The section name of the target resource.
TargetSelectors specifies the target selectors to select resources to attach the policy to.
The API group of the target resource. For Kubernetes Gateway API resources, the group is `gateway.networking.k8s.io`.
The API kind of the target resource, such as Gateway or HTTPRoute.
Label selector to select the target resource.
The section name of the target resource.
Timeouts defines the timeouts for requests It is applicable to HTTPRoutes and ignored for other targeted kinds.
Request specifies a timeout for an individual request from the gateway to a backend. This spans between the point at which the entire downstream request (i.e. end-of-stream) has been processed and when the backend response has been completely processed. A value of 0 effectively disables the timeout. It is specified as a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "1s" or "500ms".
StreamIdle specifies a timeout for a requests' idle streams. A value of 0 effectively disables the timeout.
Tracing configures per-route tracing overrides. These settings override the listener-level tracing configuration (configured via ListenerPolicy) for matched routes. The tracing provider (e.g., OpenTelemetry collector endpoint) must be configured at the listener level via ListenerPolicy. Without a listener-level tracing provider, route-level settings have no effect. NOTE: This field is only honored for HTTPRoute and GRPCRoute targets.
Additional attributes to add to active spans for this route. These are merged with listener-level attributes configured via ListenerPolicy. On name collision, route-level attributes take priority.
An environment attribute value.
When the environment variable is not found, the attribute value will be populated with this default value if specified, otherwise no attribute will be populated.
Environment variable name to obtain the value to populate the attribute value.
A literal attribute value.
Static literal value to populate the attribute value.
An attribute to obtain the value from the metadata.
When no valid metadata is found, the attribute value would be populated with this default value if specified, otherwise no attribute would be populated.
Specify what kind of metadata to obtain attribute value from
Metadata key to define the path to retrieve the attribute value.
The key name of the Metadata from which to retrieve the Struct
The path used to retrieve a specific Value from the Struct. This can be either a prefix or a full path, depending on the use case
The key used to retrieve the value in the struct
The name of the attribute
A request header attribute value.
When the header does not exist, the attribute value will be populated with this default value if specified, otherwise no attribute will be populated.
Header name to obtain the value to populate the attribute value.
Target percentage of requests that will be force traced if the x-client-trace-id header is set. Overrides the listener-level setting.
Disable tracing for this route. Can be used to disable tracing for specific routes when listener-level tracing is configured via ListenerPolicy.
Target percentage of requests that will be traced after all other sampling checks have been applied. This acts as an upper limit on the total configured sampling rate. Overrides the listener-level setting.
Target percentage of requests that will be randomly selected for trace generation. Overrides the listener-level setting.
Transformation is used to mutate and transform requests and responses before forwarding them to the destination.
Request is used to modify the request path.
Add is a list of headers to add to the request and what that value should be set to. If there is already a header with these values then append the value as an extra entry. Add is not supported on arm64 build, see docs/guides/transformation.md for details
Name is the name of the header to interact with.
Value is the Inja template to apply to generate the output value for the header.
Body controls both how to parse the body and if needed how to set. If empty, body will not be buffered.
ParseAs defines what auto formatting should be applied to the body. This can make interacting with keys within a json body much easier if AsJson is selected. When set to None, it will not buffer the body and will skip all body processing. In addition, attempt to extract json variables from the body using inja template in the header will result in 400 response.
Value is the template to apply to generate the output value for the body. Only Inja templates are supported. If ParseAs field is set to None, this Value field is ignored and no body transformation will be done.
DynamicMetadata is a list of dynamic metadata entries to set. The values are stored in Envoy dynamic metadata and can be used in access log templates or consumed by other filters down the chain.
Key is the metadata key within the namespace.
Namespace is the dynamic metadata namespace.
Value is the value to set in dynamic metadata.
StringValue is an Inja template whose rendered output is stored as the metadata string value.
Remove is a list of header names to remove from the request/response.
Set is a list of headers and the value they should be set to.
Name is the name of the header to interact with.
Value is the Inja template to apply to generate the output value for the header.
Response is used to modify the response path.
Add is a list of headers to add to the request and what that value should be set to. If there is already a header with these values then append the value as an extra entry. Add is not supported on arm64 build, see docs/guides/transformation.md for details
Name is the name of the header to interact with.
Value is the Inja template to apply to generate the output value for the header.
Body controls both how to parse the body and if needed how to set. If empty, body will not be buffered.
ParseAs defines what auto formatting should be applied to the body. This can make interacting with keys within a json body much easier if AsJson is selected. When set to None, it will not buffer the body and will skip all body processing. In addition, attempt to extract json variables from the body using inja template in the header will result in 400 response.
Value is the template to apply to generate the output value for the body. Only Inja templates are supported. If ParseAs field is set to None, this Value field is ignored and no body transformation will be done.
DynamicMetadata is a list of dynamic metadata entries to set. The values are stored in Envoy dynamic metadata and can be used in access log templates or consumed by other filters down the chain.
Key is the metadata key within the namespace.
Namespace is the dynamic metadata namespace.
Value is the value to set in dynamic metadata.
StringValue is an Inja template whose rendered output is stored as the metadata string value.
Remove is a list of header names to remove from the request/response.
Set is a list of headers and the value they should be set to.
Name is the name of the header to interact with.
Value is the Inja template to apply to generate the output value for the header.
UrlRewrite specifies URL rewrite rules for matching requests. NOTE: This field is only honored for HTTPRoute targets.
Path specifies the path rewrite configuration.
Pattern is the regex pattern that matches the URL path. The pattern must be a valid RE2 regular expression. If the HTTPRoute uses a RegularExpression path match, this field can use capture groups from that match.
Substitution is the replacement string for the matched pattern. It can include backreferences to captured groups from the pattern (e.g., \1, \2) or named groups (e.g., \g<name>).
PolicyStatus defines the common attributes that all Policies should include within their status.
Ancestors is a list of ancestor resources (usually Gateways) that are associated with the policy, and the status of the policy with respect to each ancestor. When this policy attaches to a parent, the controller that manages the parent and the ancestors MUST add an entry to this list when the controller first sees the policy and SHOULD update the entry as appropriate when the relevant ancestor is modified. Note that choosing the relevant ancestor is left to the Policy designers; an important part of Policy design is designing the right object level at which to namespace this status. Note also that implementations MUST ONLY populate ancestor status for the Ancestor resources they are responsible for. Implementations MUST use the ControllerName field to uniquely identify the entries in this list that they are responsible for. Note that to achieve this, the list of PolicyAncestorStatus structs MUST be treated as a map with a composite key, made up of the AncestorRef and ControllerName fields combined. A maximum of 16 ancestors will be represented in this list. An empty list means the Policy is not relevant for any ancestors. If this slice is full, implementations MUST NOT add further entries. Instead they MUST consider the policy unimplementable and signal that on any related resources such as the ancestor that would be referenced here. For example, if this list was full on BackendTLSPolicy, no additional Gateways would be able to reference the Service targeted by the BackendTLSPolicy.
AncestorRef corresponds with a ParentRef in the spec that this PolicyAncestorStatus struct describes the status of.
Group is the group of the referent. When unspecified, "gateway.networking.k8s.io" is inferred. To set the core API group (such as for a "Service" kind referent), Group must be explicitly set to "" (empty string). Support: Core
Kind is kind of the referent. There are two kinds of parent resources with "Core" support: * Gateway (Gateway conformance profile) * Service (Mesh conformance profile, ClusterIP Services only) Support for other resources is Implementation-Specific.
Name is the name of the referent. Support: Core
Namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route. Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example: Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference. <gateway:experimental:description> ParentRefs from a Route to a Service in the same namespace are "producer" routes, which apply default routing rules to inbound connections from any namespace to the Service. ParentRefs from a Route to a Service in a different namespace are "consumer" routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route. </gateway:experimental:description> Support: Core
Port is the network port this Route targets. It can be interpreted differently based on the type of parent resource. When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It's not recommended to set `Port` unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values. <gateway:experimental:description> When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values. </gateway:experimental:description> Implementations MAY choose to support other parent resources. Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted. For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. Support: Extended
SectionName is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following: * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. Implementations MAY choose to support attaching Routes to other resources. If that is the case, they MUST clearly document how SectionName is interpreted. When unspecified (empty string), this will reference the entire resource. For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. Support: Core
Conditions describes the status of the Policy with respect to the given Ancestor. <gateway:util:excludeFromCRD> Notes for implementors: Conditions are a listType `map`, which means that they function like a map with a key of the `type` field _in the k8s apiserver_. This means that implementations must obey some rules when updating this section. * Implementations MUST perform a read-modify-write cycle on this field before modifying it. That is, when modifying this field, implementations must be confident they have fetched the most recent version of this field, and ensure that changes they make are on that recent version. * Implementations MUST NOT remove or reorder Conditions that they are not directly responsible for. For example, if an implementation sees a Condition with type `special.io/SomeField`, it MUST NOT remove, change or update that Condition. * Implementations MUST always _merge_ changes into Conditions of the same Type, rather than creating more than one Condition of the same Type. * Implementations MUST always update the `observedGeneration` field of the Condition to the `metadata.generation` of the Gateway at the time of update creation. * If the `observedGeneration` of a Condition is _greater than_ the value the implementation knows about, then it MUST NOT perform the update on that Condition, but must wait for a future reconciliation and status update. (The assumption is that the implementation's copy of the object is stale and an update will be re-triggered if relevant.) </gateway:util:excludeFromCRD>
lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
message is a human readable message indicating details about the transition. This may be an empty string.
observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
status of the condition, one of True, False, Unknown.
type of condition in CamelCase or in foo.example.com/CamelCase.
ControllerName is a domain/path string that indicates the name of the controller that wrote this status. This corresponds with the controllerName field on GatewayClass. Example: "example.net/gateway-controller". The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). Controllers MUST populate this field when writing status. Controllers should ensure that entries to status populated with their ControllerName are cleaned up when they are no longer necessary.
Source: gateway.kgateway.dev_trafficpolicies.yaml
Changes to TrafficPolicy (gateway.kgateway.dev/v1alpha1) in each Kgateway version, compared to the version before it.
7 properties have been added
16 properties have changed the description
Released · View TrafficPolicy in v2.3.0
6 properties have been added
1 property has been removed
2 properties are now required
3 properties are no longer required
144 properties have changed the description
Released · View TrafficPolicy in v2.2.0
18 properties have been added
4 properties have been removed
2 properties are now required
2 properties are no longer required
Released · View TrafficPolicy in v2.1.0
2 properties have been removed
Released · View TrafficPolicy in v2.0.2
TrafficPolicy was already present in this version of Kgateway, the oldest one on kubespec.dev
Released · View TrafficPolicy in v2.0.0
No examples of TrafficPolicy yet. Contribute one on GitHub.
kubespec.dev