{ "description": "BackendSecurityPolicy specifies configuration for authentication and authorization rules on the traffic\nexiting the gateway to the backend.", "properties": { "apiVersion": { "description": "APIVersion defines the versioned schema of this representation of an object.\nServers should convert recognized schemas to the latest internal value, and\nmay reject unrecognized values.\nMore info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", "type": "string" }, "kind": { "description": "Kind is a string value representing the REST resource this object represents.\nServers may infer this from the endpoint the client submits requests to.\nCannot be updated.\nIn CamelCase.\nMore info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", "type": "string" }, "metadata": { "type": "object" }, "spec": { "description": "BackendSecurityPolicySpec specifies authentication rules on access the provider from the Gateway.\nOnly one mechanism to access a backend(s) can be specified.\n\nOnly one type of BackendSecurityPolicy can be defined.", "maxProperties": 3, "properties": { "anthropicAPIKey": { "description": "AnthropicAPIKey is a mechanism to access Anthropic backend(s). The API key will be injected into the \"x-api-key\" header.\nhttps://docs.claude.com/en/api/overview#authentication", "properties": { "secretRef": { "description": "SecretRef is the reference to the secret containing the Anthropic API key.\nai-gateway must be given the permission to read this secret.\nThe key of the secret should be \"apiKey\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false } }, "required": [ "secretRef" ], "type": "object", "additionalProperties": false }, "apiKey": { "description": "APIKey is a mechanism to access a backend(s). The API key will be injected into the Authorization header.", "properties": { "secretRef": { "description": "SecretRef is the reference to the secret containing the API key.\nai-gateway must be given the permission to read this secret.\nThe key of the secret should be \"apiKey\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false } }, "required": [ "secretRef" ], "type": "object", "additionalProperties": false }, "awsCredentials": { "description": "AWSCredentials is a mechanism to access a backend(s). AWS specific logic will be applied.", "properties": { "credentialsFile": { "description": "CredentialsFile specifies the credentials file to use for the AWS provider.\nWhen specified, this takes precedence over the default credential chain.", "properties": { "profile": { "default": "default", "description": "Profile is the profile to use in the credentials file.", "type": "string" }, "secretRef": { "description": "SecretRef is the reference to the credential file.\n\nThe secret should contain the AWS credentials file keyed on \"credentials\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false } }, "required": [ "secretRef" ], "type": "object", "additionalProperties": false }, "oidcExchangeToken": { "description": "OIDCExchangeToken specifies the oidc configurations used to obtain an oidc token. The oidc token will be\nused to obtain temporary credentials to access AWS.\nWhen specified, this takes precedence over the default credential chain.", "properties": { "aud": { "description": "Aud defines the audience that this ID Token is intended for.", "type": "string" }, "awsRoleArn": { "description": "AwsRoleArn is the AWS IAM Role with the permission to use specific resources in AWS account\nwhich maps to the temporary AWS security credentials exchanged using the authentication token issued by OIDC provider.", "minLength": 1, "type": "string" }, "grantType": { "description": "GrantType is the method application gets access token.", "type": "string" }, "oidc": { "description": "OIDC is used to obtain oidc tokens via an SSO server which will be used to exchange for provider credentials.", "properties": { "clientID": { "description": "The client ID to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nOnly one of clientID or clientIDRef must be set.", "minLength": 1, "type": "string" }, "clientIDRef": { "description": "The Kubernetes secret which contains the client ID to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nExactly one of clientID or clientIDRef must be set.\nThis is an Opaque secret. The client ID should be stored in the key \"client-id\".\n\nOnly one of clientID or clientIDRef must be set.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "clientSecret": { "description": "The Kubernetes secret which contains the OIDC client secret to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nThis is an Opaque secret. The client secret should be stored in the key\n\"client-secret\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "cookieConfig": { "description": "CookieConfigs allows setting the SameSite attribute for OIDC cookies.\nBy default, its unset.", "properties": { "sameSite": { "enum": [ "Lax", "Strict", "None" ], "type": "string" } }, "type": "object", "additionalProperties": false }, "cookieDomain": { "description": "The optional domain to set the access and ID token cookies on.\nIf not set, the cookies will default to the host of the request, not including the subdomains.\nIf set, the cookies will be set on the specified domain and all subdomains.\nThis means that requests to any subdomain will not require reauthentication after users log in to the parent domain.", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9]))*$", "type": "string" }, "cookieNames": { "description": "The optional cookie name overrides to be used for Bearer and IdToken cookies in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses a randomly generated suffix", "properties": { "accessToken": { "description": "The name of the cookie used to store the AccessToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"AccessToken-(randomly generated uid)\"", "type": "string" }, "idToken": { "description": "The name of the cookie used to store the IdToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"IdToken-(randomly generated uid)\"", "type": "string" } }, "type": "object", "additionalProperties": false }, "csrfTokenTTL": { "description": "CSRFTokenTTL defines how long the CSRF token generated during the OAuth2 authorization flow remains valid.\n\nThis duration determines the lifetime of the CSRF cookie, which is validated against the CSRF token\nin the \"state\" parameter when the provider redirects back to the callback endpoint.\n\nIf omitted, Envoy Gateway defaults the token expiration to 10 minutes.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultRefreshTokenTTL": { "description": "DefaultRefreshTokenTTL is the default lifetime of the refresh token.\nThis field is only used when the exp (expiration time) claim is omitted in\nthe refresh token or the refresh token is not JWT.\n\nIf not specified, defaults to 604800s (one week).\nNote: this field is only applicable when the \"refreshToken\" field is set to true.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultTokenTTL": { "description": "DefaultTokenTTL is the default lifetime of the id token and access token.\nPlease note that Envoy will always use the expiry time from the response\nof the authorization server if it is provided. This field is only used when\nthe expiry time is not provided by the authorization.\n\nIf not specified, defaults to 0. In this case, the \"expires_in\" field in\nthe authorization response must be set by the authorization server, or the\nOAuth flow will fail.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "denyRedirect": { "description": "Any request that matches any of the provided matchers (with either tokens that are expired or missing tokens) will not be redirected to the OIDC Provider.\nThis behavior can be useful for AJAX or machine requests.", "properties": { "headers": { "description": "Defines the headers to match against the request to deny redirect to the OIDC Provider.", "items": { "description": "OIDCDenyRedirectHeader defines how a header is matched", "properties": { "name": { "description": "Specifies the name of the header in the request.", "minLength": 1, "type": "string" }, "type": { "default": "Exact", "description": "Type specifies how to match against a string.", "enum": [ "Exact", "Prefix", "Suffix", "RegularExpression" ], "type": "string" }, "value": { "description": "Value specifies the string value that the match must have.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "name", "value" ], "type": "object", "additionalProperties": false }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "headers" ], "type": "object", "additionalProperties": false }, "disableTokenEncryption": { "description": "Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text.\nThis option should only be used in secure environments where token encryption is not required.\nDefault is false (tokens are encrypted).", "type": "boolean" }, "forwardAccessToken": { "description": "ForwardAccessToken indicates whether the Envoy should forward the access token\nvia the Authorization header Bearer scheme to the upstream.\nIf not specified, defaults to false.", "type": "boolean" }, "logoutPath": { "description": "The path to log a user out, clearing their credential cookies.\n\nIf not specified, uses a default logout path \"/logout\"", "type": "string" }, "passThroughAuthHeader": { "description": "Skips OIDC authentication when the request contains a header that will be extracted by the JWT filter. Unless\nexplicitly stated otherwise in the extractFrom field, this will be the \"Authorization: Bearer ...\" header.\n\nThe passThroughAuthHeader option is typically used for non-browser clients that may not be able to handle OIDC\nredirects and wish to directly supply a token instead.\n\nIf not specified, defaults to false.", "type": "boolean" }, "provider": { "description": "The OIDC Provider configuration.", "properties": { "authorizationEndpoint": { "description": "The OIDC Provider's [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" }, "backendRef": { "description": "BackendRef references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.\n\nDeprecated: Use BackendRefs instead.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "backendRefs": { "description": "BackendRefs references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.", "items": { "description": "BackendRef defines how an ObjectReference that is specific to BackendRef.", "properties": { "fallback": { "description": "Fallback indicates whether the backend is designated as a fallback.\nMultiple fallback backends can be configured.\nIt is highly recommended to configure active or passive health checks to ensure that failover can be detected\nwhen the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.\nThe overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when\nthe health of the active backends falls below 72%.", "type": "boolean" }, "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "weight": { "default": 1, "description": "Weight specifies the proportion of requests forwarded to the referenced\nbackend. This is computed as weight/(sum of all weights in this\nBackendRefs list). For non-zero values, there may be some epsilon from\nthe exact proportion defined here depending on the precision an\nimplementation supports. Weight is not a percentage and the sum of\nweights does not need to equal 100.\n\nIf only one backend is specified and it has a weight greater than 0, 100%\nof the traffic is forwarded to that backend. If weight is set to 0, no\ntraffic should be forwarded for this entry. If unspecified, weight\ndefaults to 1.\n\nSupport for this field varies based on the context where used.", "format": "int32", "maximum": 1000000, "minimum": 0, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "maxItems": 16, "type": "array" }, "backendSettings": { "description": "BackendSettings holds configuration for managing the connection\nto the backend.", "properties": { "circuitBreaker": { "description": "Circuit Breaker settings for the upstream connections and requests.\nIf not set, circuit breakers will be enabled with the default thresholds", "properties": { "maxConnections": { "default": 1024, "description": "The maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRequests": { "default": 1024, "description": "The maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRetries": { "default": 1024, "description": "The maximum number of parallel retries that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxPendingRequests": { "default": 1024, "description": "The maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxRequestsPerConnection": { "description": "The maximum number of requests that Envoy will make over a single connection to the referenced backend defined within a xRoute rule.\nDefault: unlimited.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "perEndpoint": { "description": "PerEndpoint defines Circuit Breakers that will apply per-endpoint for an upstream cluster", "properties": { "maxConnections": { "default": 1024, "description": "MaxConnections configures the maximum number of connections that Envoy will establish per-endpoint to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "connection": { "description": "Connection includes backend connection settings.", "properties": { "bufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "BufferLimit Soft limit on size of the cluster\u2019s connections read and write buffers.\nBufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it's in user space.\nIf unspecified, an implementation defined default is applied (32768 bytes).\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote: that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true }, "preconnect": { "description": "Preconnect configures proactive upstream connections to reduce latency by establishing\nconnections before they\u2019re needed and avoiding connection establishment overhead.\n\nIf unset, Envoy will fetch connections as needed to serve in-flight requests.", "properties": { "perEndpointPercent": { "description": "PerEndpointPercent configures how many additional connections to maintain per\nupstream endpoint, useful for high-QPS or latency sensitive services. Expressed as a\npercentage of the connections required by active streams\n(e.g. 100 = preconnect disabled, 105 = 1.05x connections per-endpoint, 200 = 2.00\u00d7).\n\nAllowed value range is between 100-300. When both PerEndpointPercent and\nPredictivePercent are set, Envoy ensures both are satisfied (max of the two).", "format": "int32", "maximum": 300, "minimum": 100, "type": "integer" }, "predictivePercent": { "description": "PredictivePercent configures how many additional connections to maintain\nacross the cluster by anticipating which upstream endpoint the load balancer\nwill select next, useful for low-QPS services. Relies on deterministic\nloadbalancing and is only supported with Random or RoundRobin.\nExpressed as a percentage of the connections required by active streams\n(e.g. 100 = 1.0 (no preconnect), 105 = 1.05\u00d7 connections across the cluster, 200 = 2.00\u00d7).\n\nMinimum allowed value is 100. When both PerEndpointPercent and PredictivePercent are\nset Envoy ensures both are satisfied per host (max of the two).", "format": "int32", "minimum": 100, "type": "integer" } }, "type": "object", "additionalProperties": false }, "socketBufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "SocketBufferLimit provides configuration for the maximum buffer size in bytes for each socket\nto backend.\nSocketBufferLimit applies to socket streaming channel between TCP/IP stacks, it's in kernel space.\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true } }, "type": "object", "additionalProperties": false }, "dns": { "description": "DNS includes dns resolution settings.", "properties": { "dnsRefreshRate": { "description": "DNSRefreshRate specifies the rate at which DNS records should be refreshed.\nDefaults to 30 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "lookupFamily": { "description": "LookupFamily determines how Envoy would resolve DNS for Routes where the backend is specified as a fully qualified domain name (FQDN).\nIf set, this configuration overrides other defaults.", "enum": [ "IPv4", "IPv6", "IPv4Preferred", "IPv6Preferred", "IPv4AndIPv6" ], "type": "string" }, "respectDnsTtl": { "description": "RespectDNSTTL indicates whether the DNS Time-To-Live (TTL) should be respected.\nIf the value is set to true, the DNS refresh rate will be set to the resource record\u2019s TTL.\nDefaults to true.", "type": "boolean" } }, "type": "object", "additionalProperties": false }, "healthCheck": { "description": "HealthCheck allows gateway to perform active health checking on backends.", "properties": { "active": { "description": "Active health check configuration", "properties": { "grpc": { "description": "GRPC defines the configuration of the GRPC health checker.\nIt's optional, and can only be used if the specified type is GRPC.", "properties": { "service": { "description": "Service to send in the health check request.\nIf this is not specified, then the health check request applies to the entire\nserver and not to a specific service.", "type": "string" } }, "type": "object", "additionalProperties": false }, "healthyThreshold": { "default": 1, "description": "HealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy.", "format": "int32", "minimum": 1, "type": "integer" }, "http": { "description": "HTTP defines the configuration of http health checker.\nIt's required while the health checker type is HTTP.", "properties": { "expectedResponse": { "description": "ExpectedResponse defines a list of HTTP expected responses to match.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "expectedStatuses": { "description": "ExpectedStatuses defines a list of HTTP response statuses considered healthy.\nDefaults to 200 only", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "hostname": { "description": "Hostname defines the HTTP host that will be requested during health checking.\nDefault: HTTPRoute or GRPCRoute hostname.", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "method": { "description": "Method defines the HTTP method used for health checking.\nDefaults to GET", "type": "string" }, "path": { "description": "Path defines the HTTP path that will be requested during health checking.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "path" ], "type": "object", "additionalProperties": false }, "initialJitter": { "description": "InitialJitter defines the maximum time Envoy will wait before the first health check.\nEnvoy will randomly select a value between 0 and the initial jitter value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "default": "3s", "description": "Interval defines the time between active health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "tcp": { "description": "TCP defines the configuration of tcp health checker.\nIt's required while the health checker type is TCP.", "properties": { "receive": { "description": "Receive defines the expected response payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "send": { "description": "Send defines the request payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "timeout": { "default": "1s", "description": "Timeout defines the time to wait for a health check response.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "type": { "allOf": [ { "enum": [ "HTTP", "TCP", "GRPC" ] }, { "enum": [ "HTTP", "TCP", "GRPC" ] } ], "description": "Type defines the type of health checker.", "type": "string" }, "unhealthyThreshold": { "default": 3, "description": "UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy.", "format": "int32", "minimum": 1, "type": "integer" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If Health Checker type is HTTP, http field needs to be set.", "rule": "self.type == 'HTTP' ? has(self.http) : !has(self.http)" }, { "message": "If Health Checker type is TCP, tcp field needs to be set.", "rule": "self.type == 'TCP' ? has(self.tcp) : !has(self.tcp)" }, { "message": "The grpc field can only be set if the Health Checker type is GRPC.", "rule": "has(self.grpc) ? self.type == 'GRPC' : true" } ], "additionalProperties": false }, "panicThreshold": { "description": "When number of unhealthy endpoints for a backend reaches this threshold\nEnvoy will disregard health status and balance across all endpoints.\nIt's designed to prevent a situation in which host failures cascade throughout the cluster\nas load increases. If not set, the default value is 50%. To disable panic mode, set value to `0`.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "passive": { "description": "Passive passive check configuration", "properties": { "baseEjectionTime": { "default": "30s", "description": "BaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "consecutive5XxErrors": { "default": 5, "description": "Consecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveGatewayErrors": { "description": "ConsecutiveGatewayErrors sets the number of consecutive gateway errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveLocalOriginFailures": { "default": 5, "description": "ConsecutiveLocalOriginFailures sets the number of consecutive local origin failures triggering ejection.\nParameter takes effect only when split_external_local_origin_errors is set to true.", "format": "int32", "type": "integer" }, "failurePercentageThreshold": { "description": "FailurePercentageThreshold sets the failure percentage threshold for outlier detection.\nIf the failure percentage of a given host is greater than or equal to this value, it will be ejected.\nDefaults to 85.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "interval": { "default": "3s", "description": "Interval defines the time between passive health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxEjectionPercent": { "default": 10, "description": "MaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected.", "format": "int32", "type": "integer" }, "splitExternalLocalOriginErrors": { "default": false, "description": "SplitExternalLocalOriginErrors enables splitting of errors between external and local origin.", "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "http2": { "description": "HTTP2 provides HTTP/2 configuration for backend connections.", "properties": { "initialConnectionWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialConnectionWindowSize sets the initial window size for HTTP/2 connections.\nIf not set, the default value is 1 MiB.", "x-kubernetes-int-or-string": true }, "initialStreamWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialStreamWindowSize sets the initial window size for HTTP/2 streams.\nIf not set, the default value is 64 KiB(64*1024).", "x-kubernetes-int-or-string": true }, "maxConcurrentStreams": { "description": "MaxConcurrentStreams sets the maximum number of concurrent streams allowed per connection.\nIf not set, the default value is 100.", "format": "int32", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "onInvalidMessage": { "description": "OnInvalidMessage determines if Envoy will terminate the connection or just the offending stream in the event of HTTP messaging error\nIt's recommended for L2 Envoy deployments to set this value to TerminateStream.\nhttps://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/level_two\nDefault: TerminateConnection", "type": "string" } }, "type": "object", "additionalProperties": false }, "loadBalancer": { "description": "LoadBalancer policy to apply when routing traffic from the gateway to\nthe backend endpoints. Defaults to `LeastRequest`.", "properties": { "consistentHash": { "description": "ConsistentHash defines the configuration when the load balancer type is\nset to ConsistentHash", "properties": { "cookie": { "description": "Cookie configures the cookie hash policy when the consistent hash type is set to Cookie.", "properties": { "attributes": { "additionalProperties": { "type": "string" }, "description": "Additional Attributes to set for the generated cookie.", "type": "object" }, "name": { "description": "Name of the cookie to hash.\nIf this cookie does not exist in the request, Envoy will generate a cookie and set\nthe TTL on the response back to the client based on Layer 4\nattributes of the backend endpoint, to ensure that these future requests\ngo to the same backend endpoint. Make sure to set the TTL field for this case.", "type": "string" }, "ttl": { "description": "TTL of the generated cookie if the cookie is not present. This value sets the\nMax-Age attribute value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "header": { "description": "Header configures the header hash policy when the consistent hash type is set to Header.\n\nDeprecated: use Headers instead", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "headers": { "description": "Headers configures the header hash policy for each header, when the consistent hash type is set to Headers.", "items": { "description": "Header defines the header hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "queryParams": { "description": "QueryParams configures the query parameter hash policy when the consistent hash type is set to QueryParams.", "items": { "description": "QueryParam defines the query parameter name hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the query param to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "tableSize": { "default": 65537, "description": "The table size for consistent hashing, must be prime number limited to 5000011.", "format": "int64", "maximum": 5000011, "minimum": 2, "type": "integer" }, "type": { "description": "ConsistentHashType defines the type of input to hash on. Valid Type values are\n\"SourceIP\",\n\"Header\",\n\"Headers\",\n\"Cookie\".\n\"QueryParams\".", "enum": [ "SourceIP", "Header", "Headers", "Cookie", "QueryParams" ], "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If consistent hash type is header, the header field must be set.", "rule": "self.type == 'Header' ? has(self.header) : !has(self.header)" }, { "message": "If consistent hash type is headers, the headers field must be set.", "rule": "self.type == 'Headers' ? has(self.headers) : !has(self.headers)" }, { "message": "If consistent hash type is cookie, the cookie field must be set.", "rule": "self.type == 'Cookie' ? has(self.cookie) : !has(self.cookie)" }, { "message": "If consistent hash type is queryParams, the queryParams field must be set.", "rule": "self.type == 'QueryParams' ? has(self.queryParams) : !has(self.queryParams)" } ], "additionalProperties": false }, "endpointOverride": { "description": "EndpointOverride defines the configuration for endpoint override.\nWhen specified, the load balancer will attempt to route requests to endpoints\nbased on the override information extracted from request headers or metadata.\n If the override endpoints are not available, the configured load balancer policy will be used as fallback.", "properties": { "extractFrom": { "description": "ExtractFrom defines the sources to extract endpoint override information from.", "items": { "description": "EndpointOverrideExtractFrom defines a source to extract endpoint override information from.", "properties": { "header": { "description": "Header defines the header to get the override endpoint addresses.\nThe header value must specify at least one endpoint in `IP:Port` format or multiple endpoints in `IP:Port,IP:Port,...` format.\nFor example `10.0.0.5:8080` or `[2600:4040:5204::1574:24ae]:80`.\nThe IPv6 address is enclosed in square brackets.", "type": "string" } }, "type": "object", "additionalProperties": false }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "extractFrom" ], "type": "object", "additionalProperties": false }, "slowStart": { "description": "SlowStart defines the configuration related to the slow start load balancer policy.\nIf set, during slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently this is only supported for RoundRobin and LeastRequest load balancers", "properties": { "window": { "description": "Window defines the duration of the warm up period for newly added host.\nDuring slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently only supports linear growth of traffic. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-slowstartconfig", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "window" ], "type": "object", "additionalProperties": false }, "type": { "description": "Type decides the type of Load Balancer policy.\nValid LoadBalancerType values are\n\"ConsistentHash\",\n\"LeastRequest\",\n\"Random\",\n\"RoundRobin\".", "enum": [ "ConsistentHash", "LeastRequest", "Random", "RoundRobin" ], "type": "string" }, "zoneAware": { "description": "ZoneAware defines the configuration related to the distribution of requests between locality zones.", "properties": { "preferLocal": { "description": "PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone.", "properties": { "force": { "description": "ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior\nwhich maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.", "properties": { "minEndpointsInZoneThreshold": { "description": "MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone\noverride. This is useful for protecting zones with fewer endpoints.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "minEndpointsThreshold": { "description": "MinEndpointsThreshold is the minimum number of total upstream endpoints across all zones required to enable zone-aware routing.", "format": "int64", "type": "integer" }, "percentageEnabled": { "description": "Configures percentage of requests that will be considered for zone aware routing if zone aware routing is configured. If not specified, Envoy defaults to 100%.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If LoadBalancer type is consistentHash, consistentHash field needs to be set.", "rule": "self.type == 'ConsistentHash' ? has(self.consistentHash) : !has(self.consistentHash)" }, { "message": "Currently SlowStart is only supported for RoundRobin and LeastRequest load balancers.", "rule": "self.type in ['Random', 'ConsistentHash'] ? !has(self.slowStart) : true " }, { "message": "Currently ZoneAware is only supported for LeastRequest, Random, and RoundRobin load balancers.", "rule": "self.type == 'ConsistentHash' ? !has(self.zoneAware) : true " } ], "additionalProperties": false }, "proxyProtocol": { "description": "ProxyProtocol enables the Proxy Protocol when communicating with the backend.", "properties": { "version": { "description": "Version of ProxyProtol\nValid ProxyProtocolVersion values are\n\"V1\"\n\"V2\"", "enum": [ "V1", "V2" ], "type": "string" } }, "required": [ "version" ], "type": "object", "additionalProperties": false }, "retry": { "description": "Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions.\nIf not set, retry will be disabled.", "properties": { "numAttemptsPerPriority": { "description": "NumAttemptsPerPriority defines the number of requests (initial attempt + retries)\nthat should be sent to the same priority before switching to a different one.\nIf not specified or set to 0, all requests are sent to the highest priority that is healthy.", "format": "int32", "type": "integer" }, "numRetries": { "default": 2, "description": "NumRetries is the number of retries to be attempted. Defaults to 2.", "format": "int32", "minimum": 0, "type": "integer" }, "perRetry": { "description": "PerRetry is the retry policy to be applied per retry attempt.", "properties": { "backOff": { "description": "Backoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential\nback-off algorithm for retries. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries", "properties": { "baseInterval": { "description": "BaseInterval is the base interval between retries.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxInterval": { "description": "MaxInterval is the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set.\nThe default is 10 times the base_interval", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout is the timeout per retry attempt.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "retryOn": { "description": "RetryOn specifies the retry trigger condition.\n\nIf not specified, the default is to retry on connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes(503).", "properties": { "httpStatusCodes": { "description": "HttpStatusCodes specifies the http status codes to be retried.\nThe retriable-status-codes trigger must also be configured for these status codes to trigger a retry.", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "triggers": { "description": "Triggers specifies the retry trigger condition(Http/Grpc).", "items": { "description": "TriggerEnum specifies the conditions that trigger retries.", "enum": [ "5xx", "gateway-error", "reset", "reset-before-request", "connect-failure", "retriable-4xx", "refused-stream", "retriable-status-codes", "cancelled", "deadline-exceeded", "internal", "resource-exhausted", "unavailable" ], "type": "string" }, "type": "array" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "tcpKeepalive": { "description": "TcpKeepalive settings associated with the upstream client connection.\nDisabled by default.", "properties": { "idleTime": { "description": "The duration a connection needs to be idle before keep-alive\nprobes start being sent.\nThe duration format is\nDefaults to `7200s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "description": "The duration between keep-alive probes.\nDefaults to `75s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "probes": { "description": "The total number of unacknowledged probes to send before deciding\nthe connection is dead.\nDefaults to 9.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout settings for the backend connections.", "properties": { "http": { "description": "Timeout settings for HTTP.", "properties": { "connectionIdleTimeout": { "description": "The idle timeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.\nDefault: 1 hour.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxConnectionDuration": { "description": "The maximum duration of an HTTP connection.\nDefault: unlimited.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxStreamDuration": { "description": "MaxStreamDuration is the maximum duration for a stream to complete. This timeout measures the time\nfrom when the request is sent until the response stream is fully consumed and does not apply to\nnon-streaming requests.\nWhen set to \"0s\", no max duration is applied and streams can run indefinitely.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "requestTimeout": { "description": "RequestTimeout is the time until which entire response is received from the upstream.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "tcp": { "description": "Timeout settings for TCP.", "properties": { "connectTimeout": { "description": "The timeout for network connection establishment, including TCP and TLS handshakes.\nDefault: 10 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "type": "object", "x-kubernetes-validations": [ { "message": "predictivePercent in preconnect policy only works with RoundRobin or Random load balancers", "rule": "!((has(self.connection) && has(self.connection.preconnect) && has(self.connection.preconnect.predictivePercent)) && !(has(self.loadBalancer) && has(self.loadBalancer.type) && self.loadBalancer.type in ['Random', 'RoundRobin']))" } ], "additionalProperties": false }, "endSessionEndpoint": { "description": "The OIDC Provider's [end session endpoint](https://openid.net/specs/openid-connect-core-1_0.html#RPLogout).\n\nIf the end session endpoint is provided, EG will use it to log out the user from the OIDC Provider when the user accesses the logout path.\nEG will also try to discover the end session endpoint from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) when authorizationEndpoint or tokenEndpoint is not provided.", "type": "string" }, "issuer": { "description": "The OIDC Provider's [issuer identifier](https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery).\nIssuer MUST be a URI RFC 3986 [RFC3986] with a scheme component that MUST\nbe https, a host component, and optionally, port and path components and\nno query or fragment components.", "minLength": 1, "type": "string" }, "tokenEndpoint": { "description": "The OIDC Provider's [token endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" } }, "required": [ "issuer" ], "type": "object", "x-kubernetes-validations": [ { "message": "BackendRefs must be used, backendRef is not supported.", "rule": "!has(self.backendRef)" }, { "message": "Retry timeout is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.perRetry)? !has(self.backendSettings.retry.perRetry.timeout):true):true):true" }, { "message": "HTTPStatusCodes is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.retryOn)? !has(self.backendSettings.retry.retryOn.httpStatusCodes):true):true):true" } ], "additionalProperties": false }, "redirectURL": { "description": "The redirect URL to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses the default redirect URI \"%REQ(x-forwarded-proto)%://%REQ(:authority)%/oauth2/callback\"", "type": "string" }, "refreshToken": { "default": true, "description": "RefreshToken indicates whether the Envoy should automatically refresh the\nid token and access token when they expire.\nWhen set to true, the Envoy will use the refresh token to get a new id token\nand access token when they expire.\n\nIf not specified, defaults to true.", "type": "boolean" }, "resources": { "description": "The OIDC resources to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "The OIDC scopes to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nThe \"openid\" scope is always added to the list of scopes if not already\nspecified.", "items": { "type": "string" }, "type": "array" } }, "required": [ "clientSecret", "provider" ], "type": "object", "x-kubernetes-validations": [ { "message": "only one of clientID or clientIDRef must be set", "rule": "(has(self.clientID) && !has(self.clientIDRef)) || (!has(self.clientID) && has(self.clientIDRef))" } ], "additionalProperties": false } }, "required": [ "awsRoleArn", "oidc" ], "type": "object", "additionalProperties": false }, "region": { "description": "Region specifies the AWS region associated with the policy.", "minLength": 1, "type": "string" } }, "required": [ "region" ], "type": "object", "additionalProperties": false }, "azureAPIKey": { "description": "AzureAPIKey is a mechanism to access Azure OpenAI backend(s). The API key will be injected into the api-key header.", "properties": { "secretRef": { "description": "SecretRef is the reference to the secret containing the Azure API key.\nai-gateway must be given the permission to read this secret.\nThe key of the secret should be \"apiKey\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false } }, "required": [ "secretRef" ], "type": "object", "additionalProperties": false }, "azureCredentials": { "description": "AzureCredentials is a mechanism to access a backend(s). Azure OpenAI specific logic will be applied.", "properties": { "clientID": { "description": "ClientID is a unique identifier for an application in Azure.", "minLength": 1, "type": "string" }, "clientSecretRef": { "description": "ClientSecretRef is the reference to the secret containing the Azure client secret.\nai-gateway must be given the permission to read this secret.\nThe key of secret should be \"client-secret\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "oidcExchangeToken": { "description": "OIDCExchangeToken specifies the oidc configurations used to obtain an oidc token. The oidc token will be\nused to obtain temporary credentials to access Azure.", "properties": { "aud": { "description": "Aud defines the audience that this ID Token is intended for.", "type": "string" }, "grantType": { "description": "GrantType is the method application gets access token.", "type": "string" }, "oidc": { "description": "OIDC is used to obtain oidc tokens via an SSO server which will be used to exchange for provider credentials.", "properties": { "clientID": { "description": "The client ID to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nOnly one of clientID or clientIDRef must be set.", "minLength": 1, "type": "string" }, "clientIDRef": { "description": "The Kubernetes secret which contains the client ID to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nExactly one of clientID or clientIDRef must be set.\nThis is an Opaque secret. The client ID should be stored in the key \"client-id\".\n\nOnly one of clientID or clientIDRef must be set.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "clientSecret": { "description": "The Kubernetes secret which contains the OIDC client secret to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nThis is an Opaque secret. The client secret should be stored in the key\n\"client-secret\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "cookieConfig": { "description": "CookieConfigs allows setting the SameSite attribute for OIDC cookies.\nBy default, its unset.", "properties": { "sameSite": { "enum": [ "Lax", "Strict", "None" ], "type": "string" } }, "type": "object", "additionalProperties": false }, "cookieDomain": { "description": "The optional domain to set the access and ID token cookies on.\nIf not set, the cookies will default to the host of the request, not including the subdomains.\nIf set, the cookies will be set on the specified domain and all subdomains.\nThis means that requests to any subdomain will not require reauthentication after users log in to the parent domain.", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9]))*$", "type": "string" }, "cookieNames": { "description": "The optional cookie name overrides to be used for Bearer and IdToken cookies in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses a randomly generated suffix", "properties": { "accessToken": { "description": "The name of the cookie used to store the AccessToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"AccessToken-(randomly generated uid)\"", "type": "string" }, "idToken": { "description": "The name of the cookie used to store the IdToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"IdToken-(randomly generated uid)\"", "type": "string" } }, "type": "object", "additionalProperties": false }, "csrfTokenTTL": { "description": "CSRFTokenTTL defines how long the CSRF token generated during the OAuth2 authorization flow remains valid.\n\nThis duration determines the lifetime of the CSRF cookie, which is validated against the CSRF token\nin the \"state\" parameter when the provider redirects back to the callback endpoint.\n\nIf omitted, Envoy Gateway defaults the token expiration to 10 minutes.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultRefreshTokenTTL": { "description": "DefaultRefreshTokenTTL is the default lifetime of the refresh token.\nThis field is only used when the exp (expiration time) claim is omitted in\nthe refresh token or the refresh token is not JWT.\n\nIf not specified, defaults to 604800s (one week).\nNote: this field is only applicable when the \"refreshToken\" field is set to true.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultTokenTTL": { "description": "DefaultTokenTTL is the default lifetime of the id token and access token.\nPlease note that Envoy will always use the expiry time from the response\nof the authorization server if it is provided. This field is only used when\nthe expiry time is not provided by the authorization.\n\nIf not specified, defaults to 0. In this case, the \"expires_in\" field in\nthe authorization response must be set by the authorization server, or the\nOAuth flow will fail.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "denyRedirect": { "description": "Any request that matches any of the provided matchers (with either tokens that are expired or missing tokens) will not be redirected to the OIDC Provider.\nThis behavior can be useful for AJAX or machine requests.", "properties": { "headers": { "description": "Defines the headers to match against the request to deny redirect to the OIDC Provider.", "items": { "description": "OIDCDenyRedirectHeader defines how a header is matched", "properties": { "name": { "description": "Specifies the name of the header in the request.", "minLength": 1, "type": "string" }, "type": { "default": "Exact", "description": "Type specifies how to match against a string.", "enum": [ "Exact", "Prefix", "Suffix", "RegularExpression" ], "type": "string" }, "value": { "description": "Value specifies the string value that the match must have.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "name", "value" ], "type": "object", "additionalProperties": false }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "headers" ], "type": "object", "additionalProperties": false }, "disableTokenEncryption": { "description": "Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text.\nThis option should only be used in secure environments where token encryption is not required.\nDefault is false (tokens are encrypted).", "type": "boolean" }, "forwardAccessToken": { "description": "ForwardAccessToken indicates whether the Envoy should forward the access token\nvia the Authorization header Bearer scheme to the upstream.\nIf not specified, defaults to false.", "type": "boolean" }, "logoutPath": { "description": "The path to log a user out, clearing their credential cookies.\n\nIf not specified, uses a default logout path \"/logout\"", "type": "string" }, "passThroughAuthHeader": { "description": "Skips OIDC authentication when the request contains a header that will be extracted by the JWT filter. Unless\nexplicitly stated otherwise in the extractFrom field, this will be the \"Authorization: Bearer ...\" header.\n\nThe passThroughAuthHeader option is typically used for non-browser clients that may not be able to handle OIDC\nredirects and wish to directly supply a token instead.\n\nIf not specified, defaults to false.", "type": "boolean" }, "provider": { "description": "The OIDC Provider configuration.", "properties": { "authorizationEndpoint": { "description": "The OIDC Provider's [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" }, "backendRef": { "description": "BackendRef references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.\n\nDeprecated: Use BackendRefs instead.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "backendRefs": { "description": "BackendRefs references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.", "items": { "description": "BackendRef defines how an ObjectReference that is specific to BackendRef.", "properties": { "fallback": { "description": "Fallback indicates whether the backend is designated as a fallback.\nMultiple fallback backends can be configured.\nIt is highly recommended to configure active or passive health checks to ensure that failover can be detected\nwhen the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.\nThe overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when\nthe health of the active backends falls below 72%.", "type": "boolean" }, "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "weight": { "default": 1, "description": "Weight specifies the proportion of requests forwarded to the referenced\nbackend. This is computed as weight/(sum of all weights in this\nBackendRefs list). For non-zero values, there may be some epsilon from\nthe exact proportion defined here depending on the precision an\nimplementation supports. Weight is not a percentage and the sum of\nweights does not need to equal 100.\n\nIf only one backend is specified and it has a weight greater than 0, 100%\nof the traffic is forwarded to that backend. If weight is set to 0, no\ntraffic should be forwarded for this entry. If unspecified, weight\ndefaults to 1.\n\nSupport for this field varies based on the context where used.", "format": "int32", "maximum": 1000000, "minimum": 0, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "maxItems": 16, "type": "array" }, "backendSettings": { "description": "BackendSettings holds configuration for managing the connection\nto the backend.", "properties": { "circuitBreaker": { "description": "Circuit Breaker settings for the upstream connections and requests.\nIf not set, circuit breakers will be enabled with the default thresholds", "properties": { "maxConnections": { "default": 1024, "description": "The maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRequests": { "default": 1024, "description": "The maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRetries": { "default": 1024, "description": "The maximum number of parallel retries that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxPendingRequests": { "default": 1024, "description": "The maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxRequestsPerConnection": { "description": "The maximum number of requests that Envoy will make over a single connection to the referenced backend defined within a xRoute rule.\nDefault: unlimited.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "perEndpoint": { "description": "PerEndpoint defines Circuit Breakers that will apply per-endpoint for an upstream cluster", "properties": { "maxConnections": { "default": 1024, "description": "MaxConnections configures the maximum number of connections that Envoy will establish per-endpoint to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "connection": { "description": "Connection includes backend connection settings.", "properties": { "bufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "BufferLimit Soft limit on size of the cluster\u2019s connections read and write buffers.\nBufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it's in user space.\nIf unspecified, an implementation defined default is applied (32768 bytes).\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote: that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true }, "preconnect": { "description": "Preconnect configures proactive upstream connections to reduce latency by establishing\nconnections before they\u2019re needed and avoiding connection establishment overhead.\n\nIf unset, Envoy will fetch connections as needed to serve in-flight requests.", "properties": { "perEndpointPercent": { "description": "PerEndpointPercent configures how many additional connections to maintain per\nupstream endpoint, useful for high-QPS or latency sensitive services. Expressed as a\npercentage of the connections required by active streams\n(e.g. 100 = preconnect disabled, 105 = 1.05x connections per-endpoint, 200 = 2.00\u00d7).\n\nAllowed value range is between 100-300. When both PerEndpointPercent and\nPredictivePercent are set, Envoy ensures both are satisfied (max of the two).", "format": "int32", "maximum": 300, "minimum": 100, "type": "integer" }, "predictivePercent": { "description": "PredictivePercent configures how many additional connections to maintain\nacross the cluster by anticipating which upstream endpoint the load balancer\nwill select next, useful for low-QPS services. Relies on deterministic\nloadbalancing and is only supported with Random or RoundRobin.\nExpressed as a percentage of the connections required by active streams\n(e.g. 100 = 1.0 (no preconnect), 105 = 1.05\u00d7 connections across the cluster, 200 = 2.00\u00d7).\n\nMinimum allowed value is 100. When both PerEndpointPercent and PredictivePercent are\nset Envoy ensures both are satisfied per host (max of the two).", "format": "int32", "minimum": 100, "type": "integer" } }, "type": "object", "additionalProperties": false }, "socketBufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "SocketBufferLimit provides configuration for the maximum buffer size in bytes for each socket\nto backend.\nSocketBufferLimit applies to socket streaming channel between TCP/IP stacks, it's in kernel space.\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true } }, "type": "object", "additionalProperties": false }, "dns": { "description": "DNS includes dns resolution settings.", "properties": { "dnsRefreshRate": { "description": "DNSRefreshRate specifies the rate at which DNS records should be refreshed.\nDefaults to 30 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "lookupFamily": { "description": "LookupFamily determines how Envoy would resolve DNS for Routes where the backend is specified as a fully qualified domain name (FQDN).\nIf set, this configuration overrides other defaults.", "enum": [ "IPv4", "IPv6", "IPv4Preferred", "IPv6Preferred", "IPv4AndIPv6" ], "type": "string" }, "respectDnsTtl": { "description": "RespectDNSTTL indicates whether the DNS Time-To-Live (TTL) should be respected.\nIf the value is set to true, the DNS refresh rate will be set to the resource record\u2019s TTL.\nDefaults to true.", "type": "boolean" } }, "type": "object", "additionalProperties": false }, "healthCheck": { "description": "HealthCheck allows gateway to perform active health checking on backends.", "properties": { "active": { "description": "Active health check configuration", "properties": { "grpc": { "description": "GRPC defines the configuration of the GRPC health checker.\nIt's optional, and can only be used if the specified type is GRPC.", "properties": { "service": { "description": "Service to send in the health check request.\nIf this is not specified, then the health check request applies to the entire\nserver and not to a specific service.", "type": "string" } }, "type": "object", "additionalProperties": false }, "healthyThreshold": { "default": 1, "description": "HealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy.", "format": "int32", "minimum": 1, "type": "integer" }, "http": { "description": "HTTP defines the configuration of http health checker.\nIt's required while the health checker type is HTTP.", "properties": { "expectedResponse": { "description": "ExpectedResponse defines a list of HTTP expected responses to match.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "expectedStatuses": { "description": "ExpectedStatuses defines a list of HTTP response statuses considered healthy.\nDefaults to 200 only", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "hostname": { "description": "Hostname defines the HTTP host that will be requested during health checking.\nDefault: HTTPRoute or GRPCRoute hostname.", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "method": { "description": "Method defines the HTTP method used for health checking.\nDefaults to GET", "type": "string" }, "path": { "description": "Path defines the HTTP path that will be requested during health checking.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "path" ], "type": "object", "additionalProperties": false }, "initialJitter": { "description": "InitialJitter defines the maximum time Envoy will wait before the first health check.\nEnvoy will randomly select a value between 0 and the initial jitter value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "default": "3s", "description": "Interval defines the time between active health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "tcp": { "description": "TCP defines the configuration of tcp health checker.\nIt's required while the health checker type is TCP.", "properties": { "receive": { "description": "Receive defines the expected response payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "send": { "description": "Send defines the request payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "timeout": { "default": "1s", "description": "Timeout defines the time to wait for a health check response.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "type": { "allOf": [ { "enum": [ "HTTP", "TCP", "GRPC" ] }, { "enum": [ "HTTP", "TCP", "GRPC" ] } ], "description": "Type defines the type of health checker.", "type": "string" }, "unhealthyThreshold": { "default": 3, "description": "UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy.", "format": "int32", "minimum": 1, "type": "integer" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If Health Checker type is HTTP, http field needs to be set.", "rule": "self.type == 'HTTP' ? has(self.http) : !has(self.http)" }, { "message": "If Health Checker type is TCP, tcp field needs to be set.", "rule": "self.type == 'TCP' ? has(self.tcp) : !has(self.tcp)" }, { "message": "The grpc field can only be set if the Health Checker type is GRPC.", "rule": "has(self.grpc) ? self.type == 'GRPC' : true" } ], "additionalProperties": false }, "panicThreshold": { "description": "When number of unhealthy endpoints for a backend reaches this threshold\nEnvoy will disregard health status and balance across all endpoints.\nIt's designed to prevent a situation in which host failures cascade throughout the cluster\nas load increases. If not set, the default value is 50%. To disable panic mode, set value to `0`.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "passive": { "description": "Passive passive check configuration", "properties": { "baseEjectionTime": { "default": "30s", "description": "BaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "consecutive5XxErrors": { "default": 5, "description": "Consecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveGatewayErrors": { "description": "ConsecutiveGatewayErrors sets the number of consecutive gateway errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveLocalOriginFailures": { "default": 5, "description": "ConsecutiveLocalOriginFailures sets the number of consecutive local origin failures triggering ejection.\nParameter takes effect only when split_external_local_origin_errors is set to true.", "format": "int32", "type": "integer" }, "failurePercentageThreshold": { "description": "FailurePercentageThreshold sets the failure percentage threshold for outlier detection.\nIf the failure percentage of a given host is greater than or equal to this value, it will be ejected.\nDefaults to 85.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "interval": { "default": "3s", "description": "Interval defines the time between passive health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxEjectionPercent": { "default": 10, "description": "MaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected.", "format": "int32", "type": "integer" }, "splitExternalLocalOriginErrors": { "default": false, "description": "SplitExternalLocalOriginErrors enables splitting of errors between external and local origin.", "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "http2": { "description": "HTTP2 provides HTTP/2 configuration for backend connections.", "properties": { "initialConnectionWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialConnectionWindowSize sets the initial window size for HTTP/2 connections.\nIf not set, the default value is 1 MiB.", "x-kubernetes-int-or-string": true }, "initialStreamWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialStreamWindowSize sets the initial window size for HTTP/2 streams.\nIf not set, the default value is 64 KiB(64*1024).", "x-kubernetes-int-or-string": true }, "maxConcurrentStreams": { "description": "MaxConcurrentStreams sets the maximum number of concurrent streams allowed per connection.\nIf not set, the default value is 100.", "format": "int32", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "onInvalidMessage": { "description": "OnInvalidMessage determines if Envoy will terminate the connection or just the offending stream in the event of HTTP messaging error\nIt's recommended for L2 Envoy deployments to set this value to TerminateStream.\nhttps://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/level_two\nDefault: TerminateConnection", "type": "string" } }, "type": "object", "additionalProperties": false }, "loadBalancer": { "description": "LoadBalancer policy to apply when routing traffic from the gateway to\nthe backend endpoints. Defaults to `LeastRequest`.", "properties": { "consistentHash": { "description": "ConsistentHash defines the configuration when the load balancer type is\nset to ConsistentHash", "properties": { "cookie": { "description": "Cookie configures the cookie hash policy when the consistent hash type is set to Cookie.", "properties": { "attributes": { "additionalProperties": { "type": "string" }, "description": "Additional Attributes to set for the generated cookie.", "type": "object" }, "name": { "description": "Name of the cookie to hash.\nIf this cookie does not exist in the request, Envoy will generate a cookie and set\nthe TTL on the response back to the client based on Layer 4\nattributes of the backend endpoint, to ensure that these future requests\ngo to the same backend endpoint. Make sure to set the TTL field for this case.", "type": "string" }, "ttl": { "description": "TTL of the generated cookie if the cookie is not present. This value sets the\nMax-Age attribute value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "header": { "description": "Header configures the header hash policy when the consistent hash type is set to Header.\n\nDeprecated: use Headers instead", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "headers": { "description": "Headers configures the header hash policy for each header, when the consistent hash type is set to Headers.", "items": { "description": "Header defines the header hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "queryParams": { "description": "QueryParams configures the query parameter hash policy when the consistent hash type is set to QueryParams.", "items": { "description": "QueryParam defines the query parameter name hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the query param to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "tableSize": { "default": 65537, "description": "The table size for consistent hashing, must be prime number limited to 5000011.", "format": "int64", "maximum": 5000011, "minimum": 2, "type": "integer" }, "type": { "description": "ConsistentHashType defines the type of input to hash on. Valid Type values are\n\"SourceIP\",\n\"Header\",\n\"Headers\",\n\"Cookie\".\n\"QueryParams\".", "enum": [ "SourceIP", "Header", "Headers", "Cookie", "QueryParams" ], "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If consistent hash type is header, the header field must be set.", "rule": "self.type == 'Header' ? has(self.header) : !has(self.header)" }, { "message": "If consistent hash type is headers, the headers field must be set.", "rule": "self.type == 'Headers' ? has(self.headers) : !has(self.headers)" }, { "message": "If consistent hash type is cookie, the cookie field must be set.", "rule": "self.type == 'Cookie' ? has(self.cookie) : !has(self.cookie)" }, { "message": "If consistent hash type is queryParams, the queryParams field must be set.", "rule": "self.type == 'QueryParams' ? has(self.queryParams) : !has(self.queryParams)" } ], "additionalProperties": false }, "endpointOverride": { "description": "EndpointOverride defines the configuration for endpoint override.\nWhen specified, the load balancer will attempt to route requests to endpoints\nbased on the override information extracted from request headers or metadata.\n If the override endpoints are not available, the configured load balancer policy will be used as fallback.", "properties": { "extractFrom": { "description": "ExtractFrom defines the sources to extract endpoint override information from.", "items": { "description": "EndpointOverrideExtractFrom defines a source to extract endpoint override information from.", "properties": { "header": { "description": "Header defines the header to get the override endpoint addresses.\nThe header value must specify at least one endpoint in `IP:Port` format or multiple endpoints in `IP:Port,IP:Port,...` format.\nFor example `10.0.0.5:8080` or `[2600:4040:5204::1574:24ae]:80`.\nThe IPv6 address is enclosed in square brackets.", "type": "string" } }, "type": "object", "additionalProperties": false }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "extractFrom" ], "type": "object", "additionalProperties": false }, "slowStart": { "description": "SlowStart defines the configuration related to the slow start load balancer policy.\nIf set, during slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently this is only supported for RoundRobin and LeastRequest load balancers", "properties": { "window": { "description": "Window defines the duration of the warm up period for newly added host.\nDuring slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently only supports linear growth of traffic. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-slowstartconfig", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "window" ], "type": "object", "additionalProperties": false }, "type": { "description": "Type decides the type of Load Balancer policy.\nValid LoadBalancerType values are\n\"ConsistentHash\",\n\"LeastRequest\",\n\"Random\",\n\"RoundRobin\".", "enum": [ "ConsistentHash", "LeastRequest", "Random", "RoundRobin" ], "type": "string" }, "zoneAware": { "description": "ZoneAware defines the configuration related to the distribution of requests between locality zones.", "properties": { "preferLocal": { "description": "PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone.", "properties": { "force": { "description": "ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior\nwhich maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.", "properties": { "minEndpointsInZoneThreshold": { "description": "MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone\noverride. This is useful for protecting zones with fewer endpoints.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "minEndpointsThreshold": { "description": "MinEndpointsThreshold is the minimum number of total upstream endpoints across all zones required to enable zone-aware routing.", "format": "int64", "type": "integer" }, "percentageEnabled": { "description": "Configures percentage of requests that will be considered for zone aware routing if zone aware routing is configured. If not specified, Envoy defaults to 100%.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If LoadBalancer type is consistentHash, consistentHash field needs to be set.", "rule": "self.type == 'ConsistentHash' ? has(self.consistentHash) : !has(self.consistentHash)" }, { "message": "Currently SlowStart is only supported for RoundRobin and LeastRequest load balancers.", "rule": "self.type in ['Random', 'ConsistentHash'] ? !has(self.slowStart) : true " }, { "message": "Currently ZoneAware is only supported for LeastRequest, Random, and RoundRobin load balancers.", "rule": "self.type == 'ConsistentHash' ? !has(self.zoneAware) : true " } ], "additionalProperties": false }, "proxyProtocol": { "description": "ProxyProtocol enables the Proxy Protocol when communicating with the backend.", "properties": { "version": { "description": "Version of ProxyProtol\nValid ProxyProtocolVersion values are\n\"V1\"\n\"V2\"", "enum": [ "V1", "V2" ], "type": "string" } }, "required": [ "version" ], "type": "object", "additionalProperties": false }, "retry": { "description": "Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions.\nIf not set, retry will be disabled.", "properties": { "numAttemptsPerPriority": { "description": "NumAttemptsPerPriority defines the number of requests (initial attempt + retries)\nthat should be sent to the same priority before switching to a different one.\nIf not specified or set to 0, all requests are sent to the highest priority that is healthy.", "format": "int32", "type": "integer" }, "numRetries": { "default": 2, "description": "NumRetries is the number of retries to be attempted. Defaults to 2.", "format": "int32", "minimum": 0, "type": "integer" }, "perRetry": { "description": "PerRetry is the retry policy to be applied per retry attempt.", "properties": { "backOff": { "description": "Backoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential\nback-off algorithm for retries. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries", "properties": { "baseInterval": { "description": "BaseInterval is the base interval between retries.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxInterval": { "description": "MaxInterval is the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set.\nThe default is 10 times the base_interval", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout is the timeout per retry attempt.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "retryOn": { "description": "RetryOn specifies the retry trigger condition.\n\nIf not specified, the default is to retry on connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes(503).", "properties": { "httpStatusCodes": { "description": "HttpStatusCodes specifies the http status codes to be retried.\nThe retriable-status-codes trigger must also be configured for these status codes to trigger a retry.", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "triggers": { "description": "Triggers specifies the retry trigger condition(Http/Grpc).", "items": { "description": "TriggerEnum specifies the conditions that trigger retries.", "enum": [ "5xx", "gateway-error", "reset", "reset-before-request", "connect-failure", "retriable-4xx", "refused-stream", "retriable-status-codes", "cancelled", "deadline-exceeded", "internal", "resource-exhausted", "unavailable" ], "type": "string" }, "type": "array" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "tcpKeepalive": { "description": "TcpKeepalive settings associated with the upstream client connection.\nDisabled by default.", "properties": { "idleTime": { "description": "The duration a connection needs to be idle before keep-alive\nprobes start being sent.\nThe duration format is\nDefaults to `7200s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "description": "The duration between keep-alive probes.\nDefaults to `75s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "probes": { "description": "The total number of unacknowledged probes to send before deciding\nthe connection is dead.\nDefaults to 9.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout settings for the backend connections.", "properties": { "http": { "description": "Timeout settings for HTTP.", "properties": { "connectionIdleTimeout": { "description": "The idle timeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.\nDefault: 1 hour.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxConnectionDuration": { "description": "The maximum duration of an HTTP connection.\nDefault: unlimited.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxStreamDuration": { "description": "MaxStreamDuration is the maximum duration for a stream to complete. This timeout measures the time\nfrom when the request is sent until the response stream is fully consumed and does not apply to\nnon-streaming requests.\nWhen set to \"0s\", no max duration is applied and streams can run indefinitely.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "requestTimeout": { "description": "RequestTimeout is the time until which entire response is received from the upstream.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "tcp": { "description": "Timeout settings for TCP.", "properties": { "connectTimeout": { "description": "The timeout for network connection establishment, including TCP and TLS handshakes.\nDefault: 10 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "type": "object", "x-kubernetes-validations": [ { "message": "predictivePercent in preconnect policy only works with RoundRobin or Random load balancers", "rule": "!((has(self.connection) && has(self.connection.preconnect) && has(self.connection.preconnect.predictivePercent)) && !(has(self.loadBalancer) && has(self.loadBalancer.type) && self.loadBalancer.type in ['Random', 'RoundRobin']))" } ], "additionalProperties": false }, "endSessionEndpoint": { "description": "The OIDC Provider's [end session endpoint](https://openid.net/specs/openid-connect-core-1_0.html#RPLogout).\n\nIf the end session endpoint is provided, EG will use it to log out the user from the OIDC Provider when the user accesses the logout path.\nEG will also try to discover the end session endpoint from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) when authorizationEndpoint or tokenEndpoint is not provided.", "type": "string" }, "issuer": { "description": "The OIDC Provider's [issuer identifier](https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery).\nIssuer MUST be a URI RFC 3986 [RFC3986] with a scheme component that MUST\nbe https, a host component, and optionally, port and path components and\nno query or fragment components.", "minLength": 1, "type": "string" }, "tokenEndpoint": { "description": "The OIDC Provider's [token endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" } }, "required": [ "issuer" ], "type": "object", "x-kubernetes-validations": [ { "message": "BackendRefs must be used, backendRef is not supported.", "rule": "!has(self.backendRef)" }, { "message": "Retry timeout is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.perRetry)? !has(self.backendSettings.retry.perRetry.timeout):true):true):true" }, { "message": "HTTPStatusCodes is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.retryOn)? !has(self.backendSettings.retry.retryOn.httpStatusCodes):true):true):true" } ], "additionalProperties": false }, "redirectURL": { "description": "The redirect URL to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses the default redirect URI \"%REQ(x-forwarded-proto)%://%REQ(:authority)%/oauth2/callback\"", "type": "string" }, "refreshToken": { "default": true, "description": "RefreshToken indicates whether the Envoy should automatically refresh the\nid token and access token when they expire.\nWhen set to true, the Envoy will use the refresh token to get a new id token\nand access token when they expire.\n\nIf not specified, defaults to true.", "type": "boolean" }, "resources": { "description": "The OIDC resources to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "The OIDC scopes to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nThe \"openid\" scope is always added to the list of scopes if not already\nspecified.", "items": { "type": "string" }, "type": "array" } }, "required": [ "clientSecret", "provider" ], "type": "object", "x-kubernetes-validations": [ { "message": "only one of clientID or clientIDRef must be set", "rule": "(has(self.clientID) && !has(self.clientIDRef)) || (!has(self.clientID) && has(self.clientIDRef))" } ], "additionalProperties": false } }, "required": [ "oidc" ], "type": "object", "additionalProperties": false }, "tenantID": { "description": "TenantId is a unique identifier for an Azure Active Directory instance.", "minLength": 1, "type": "string" } }, "required": [ "clientID", "tenantID" ], "type": "object", "x-kubernetes-validations": [ { "message": "Exactly one of clientSecretRef or oidcExchangeToken must be specified", "rule": "(has(self.clientSecretRef) && !has(self.oidcExchangeToken)) || (!has(self.clientSecretRef) && has(self.oidcExchangeToken))" } ], "additionalProperties": false }, "gcpCredentials": { "description": "GCPCredentials is a mechanism to access a backend(s). GCP specific logic will be applied.", "properties": { "credentialsFile": { "description": "CredentialsFile specifies the service account credentials file to use for the GCP provider.", "properties": { "secretRef": { "description": "SecretRef is the reference to the credential file.\n\nThe secret should contain the GCP service account credentials file keyed on \"service_account.json\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false } }, "required": [ "secretRef" ], "type": "object", "additionalProperties": false }, "projectName": { "description": "ProjectName is the GCP project name.", "minLength": 1, "type": "string" }, "region": { "description": "Region is the GCP region associated with the policy.", "minLength": 1, "type": "string" }, "workloadIdentityFederationConfig": { "description": "WorkloadIdentityFederationConfig is the configuration for the GCP Workload Identity Federation.", "properties": { "oidcExchangeToken": { "description": "OIDCExchangeToken specifies the oidc configurations used to obtain an oidc token. The oidc token will be\nused to obtain temporary credentials to access GCP.", "properties": { "aud": { "description": "Aud defines the audience that this ID Token is intended for.", "type": "string" }, "grantType": { "description": "GrantType is the method application gets access token.", "type": "string" }, "oidc": { "description": "OIDC is used to obtain oidc tokens via an SSO server which will be used to exchange for provider credentials.", "properties": { "clientID": { "description": "The client ID to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nOnly one of clientID or clientIDRef must be set.", "minLength": 1, "type": "string" }, "clientIDRef": { "description": "The Kubernetes secret which contains the client ID to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nExactly one of clientID or clientIDRef must be set.\nThis is an Opaque secret. The client ID should be stored in the key \"client-id\".\n\nOnly one of clientID or clientIDRef must be set.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "clientSecret": { "description": "The Kubernetes secret which contains the OIDC client secret to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\n\nThis is an Opaque secret. The client secret should be stored in the key\n\"client-secret\".", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Secret", "description": "Kind is kind of the referent. For example \"Secret\".", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the referenced object. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "cookieConfig": { "description": "CookieConfigs allows setting the SameSite attribute for OIDC cookies.\nBy default, its unset.", "properties": { "sameSite": { "enum": [ "Lax", "Strict", "None" ], "type": "string" } }, "type": "object", "additionalProperties": false }, "cookieDomain": { "description": "The optional domain to set the access and ID token cookies on.\nIf not set, the cookies will default to the host of the request, not including the subdomains.\nIf set, the cookies will be set on the specified domain and all subdomains.\nThis means that requests to any subdomain will not require reauthentication after users log in to the parent domain.", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9]))*$", "type": "string" }, "cookieNames": { "description": "The optional cookie name overrides to be used for Bearer and IdToken cookies in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses a randomly generated suffix", "properties": { "accessToken": { "description": "The name of the cookie used to store the AccessToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"AccessToken-(randomly generated uid)\"", "type": "string" }, "idToken": { "description": "The name of the cookie used to store the IdToken in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, defaults to \"IdToken-(randomly generated uid)\"", "type": "string" } }, "type": "object", "additionalProperties": false }, "csrfTokenTTL": { "description": "CSRFTokenTTL defines how long the CSRF token generated during the OAuth2 authorization flow remains valid.\n\nThis duration determines the lifetime of the CSRF cookie, which is validated against the CSRF token\nin the \"state\" parameter when the provider redirects back to the callback endpoint.\n\nIf omitted, Envoy Gateway defaults the token expiration to 10 minutes.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultRefreshTokenTTL": { "description": "DefaultRefreshTokenTTL is the default lifetime of the refresh token.\nThis field is only used when the exp (expiration time) claim is omitted in\nthe refresh token or the refresh token is not JWT.\n\nIf not specified, defaults to 604800s (one week).\nNote: this field is only applicable when the \"refreshToken\" field is set to true.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "defaultTokenTTL": { "description": "DefaultTokenTTL is the default lifetime of the id token and access token.\nPlease note that Envoy will always use the expiry time from the response\nof the authorization server if it is provided. This field is only used when\nthe expiry time is not provided by the authorization.\n\nIf not specified, defaults to 0. In this case, the \"expires_in\" field in\nthe authorization response must be set by the authorization server, or the\nOAuth flow will fail.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "denyRedirect": { "description": "Any request that matches any of the provided matchers (with either tokens that are expired or missing tokens) will not be redirected to the OIDC Provider.\nThis behavior can be useful for AJAX or machine requests.", "properties": { "headers": { "description": "Defines the headers to match against the request to deny redirect to the OIDC Provider.", "items": { "description": "OIDCDenyRedirectHeader defines how a header is matched", "properties": { "name": { "description": "Specifies the name of the header in the request.", "minLength": 1, "type": "string" }, "type": { "default": "Exact", "description": "Type specifies how to match against a string.", "enum": [ "Exact", "Prefix", "Suffix", "RegularExpression" ], "type": "string" }, "value": { "description": "Value specifies the string value that the match must have.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "name", "value" ], "type": "object", "additionalProperties": false }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "headers" ], "type": "object", "additionalProperties": false }, "disableTokenEncryption": { "description": "Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text.\nThis option should only be used in secure environments where token encryption is not required.\nDefault is false (tokens are encrypted).", "type": "boolean" }, "forwardAccessToken": { "description": "ForwardAccessToken indicates whether the Envoy should forward the access token\nvia the Authorization header Bearer scheme to the upstream.\nIf not specified, defaults to false.", "type": "boolean" }, "logoutPath": { "description": "The path to log a user out, clearing their credential cookies.\n\nIf not specified, uses a default logout path \"/logout\"", "type": "string" }, "passThroughAuthHeader": { "description": "Skips OIDC authentication when the request contains a header that will be extracted by the JWT filter. Unless\nexplicitly stated otherwise in the extractFrom field, this will be the \"Authorization: Bearer ...\" header.\n\nThe passThroughAuthHeader option is typically used for non-browser clients that may not be able to handle OIDC\nredirects and wish to directly supply a token instead.\n\nIf not specified, defaults to false.", "type": "boolean" }, "provider": { "description": "The OIDC Provider configuration.", "properties": { "authorizationEndpoint": { "description": "The OIDC Provider's [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" }, "backendRef": { "description": "BackendRef references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.\n\nDeprecated: Use BackendRefs instead.", "properties": { "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "backendRefs": { "description": "BackendRefs references a Kubernetes object that represents the\nbackend server to which the authorization request will be sent.", "items": { "description": "BackendRef defines how an ObjectReference that is specific to BackendRef.", "properties": { "fallback": { "description": "Fallback indicates whether the backend is designated as a fallback.\nMultiple fallback backends can be configured.\nIt is highly recommended to configure active or passive health checks to ensure that failover can be detected\nwhen the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.\nThe overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when\nthe health of the active backends falls below 72%.", "type": "boolean" }, "group": { "default": "", "description": "Group is the group of the referent. For example, \"gateway.networking.k8s.io\".\nWhen unspecified or empty string, core API group is inferred.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "default": "Service", "description": "Kind is the Kubernetes resource kind of the referent. For example\n\"Service\".\n\nDefaults to \"Service\" when not specified.\n\nExternalName services can refer to CNAME DNS records that may live\noutside of the cluster and as such are difficult to reason about in\nterms of conformance. They also may not be safe to forward to (see\nCVE-2021-25740 for more information). Implementations SHOULD NOT\nsupport ExternalName Services.\n\nSupport: Core (Services with a type other than ExternalName)\n\nSupport: Implementation-specific (Services with type ExternalName)", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the referent.", "maxLength": 253, "minLength": 1, "type": "string" }, "namespace": { "description": "Namespace is the namespace of the backend. When unspecified, the local\nnamespace is inferred.\n\nNote that when a namespace different than the local namespace is specified,\na ReferenceGrant object is required in the referent namespace to allow that\nnamespace's owner to accept the reference. See the ReferenceGrant\ndocumentation for details.\n\nSupport: Core", "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", "type": "string" }, "port": { "description": "Port specifies the destination port number to use for this resource.\nPort is required when the referent is a Kubernetes Service. In this\ncase, the port number is the service port number, not the target port.\nFor other resources, destination port might be derived from the referent\nresource or this field.", "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "weight": { "default": 1, "description": "Weight specifies the proportion of requests forwarded to the referenced\nbackend. This is computed as weight/(sum of all weights in this\nBackendRefs list). For non-zero values, there may be some epsilon from\nthe exact proportion defined here depending on the precision an\nimplementation supports. Weight is not a percentage and the sum of\nweights does not need to equal 100.\n\nIf only one backend is specified and it has a weight greater than 0, 100%\nof the traffic is forwarded to that backend. If weight is set to 0, no\ntraffic should be forwarded for this entry. If unspecified, weight\ndefaults to 1.\n\nSupport for this field varies based on the context where used.", "format": "int32", "maximum": 1000000, "minimum": 0, "type": "integer" } }, "required": [ "name" ], "type": "object", "x-kubernetes-validations": [ { "message": "Must have port for Service reference", "rule": "(size(self.group) == 0 && self.kind == 'Service') ? has(self.port) : true" } ], "additionalProperties": false }, "maxItems": 16, "type": "array" }, "backendSettings": { "description": "BackendSettings holds configuration for managing the connection\nto the backend.", "properties": { "circuitBreaker": { "description": "Circuit Breaker settings for the upstream connections and requests.\nIf not set, circuit breakers will be enabled with the default thresholds", "properties": { "maxConnections": { "default": 1024, "description": "The maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRequests": { "default": 1024, "description": "The maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxParallelRetries": { "default": 1024, "description": "The maximum number of parallel retries that Envoy will make to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxPendingRequests": { "default": 1024, "description": "The maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "maxRequestsPerConnection": { "description": "The maximum number of requests that Envoy will make over a single connection to the referenced backend defined within a xRoute rule.\nDefault: unlimited.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" }, "perEndpoint": { "description": "PerEndpoint defines Circuit Breakers that will apply per-endpoint for an upstream cluster", "properties": { "maxConnections": { "default": 1024, "description": "MaxConnections configures the maximum number of connections that Envoy will establish per-endpoint to the referenced backend defined within a xRoute rule.", "format": "int64", "maximum": 4294967295, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "connection": { "description": "Connection includes backend connection settings.", "properties": { "bufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "BufferLimit Soft limit on size of the cluster\u2019s connections read and write buffers.\nBufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it's in user space.\nIf unspecified, an implementation defined default is applied (32768 bytes).\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote: that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true }, "preconnect": { "description": "Preconnect configures proactive upstream connections to reduce latency by establishing\nconnections before they\u2019re needed and avoiding connection establishment overhead.\n\nIf unset, Envoy will fetch connections as needed to serve in-flight requests.", "properties": { "perEndpointPercent": { "description": "PerEndpointPercent configures how many additional connections to maintain per\nupstream endpoint, useful for high-QPS or latency sensitive services. Expressed as a\npercentage of the connections required by active streams\n(e.g. 100 = preconnect disabled, 105 = 1.05x connections per-endpoint, 200 = 2.00\u00d7).\n\nAllowed value range is between 100-300. When both PerEndpointPercent and\nPredictivePercent are set, Envoy ensures both are satisfied (max of the two).", "format": "int32", "maximum": 300, "minimum": 100, "type": "integer" }, "predictivePercent": { "description": "PredictivePercent configures how many additional connections to maintain\nacross the cluster by anticipating which upstream endpoint the load balancer\nwill select next, useful for low-QPS services. Relies on deterministic\nloadbalancing and is only supported with Random or RoundRobin.\nExpressed as a percentage of the connections required by active streams\n(e.g. 100 = 1.0 (no preconnect), 105 = 1.05\u00d7 connections across the cluster, 200 = 2.00\u00d7).\n\nMinimum allowed value is 100. When both PerEndpointPercent and PredictivePercent are\nset Envoy ensures both are satisfied per host (max of the two).", "format": "int32", "minimum": 100, "type": "integer" } }, "type": "object", "additionalProperties": false }, "socketBufferLimit": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "SocketBufferLimit provides configuration for the maximum buffer size in bytes for each socket\nto backend.\nSocketBufferLimit applies to socket streaming channel between TCP/IP stacks, it's in kernel space.\nFor example, 20Mi, 1Gi, 256Ki etc.\nNote that when the suffix is not provided, the value is interpreted as bytes.", "x-kubernetes-int-or-string": true } }, "type": "object", "additionalProperties": false }, "dns": { "description": "DNS includes dns resolution settings.", "properties": { "dnsRefreshRate": { "description": "DNSRefreshRate specifies the rate at which DNS records should be refreshed.\nDefaults to 30 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "lookupFamily": { "description": "LookupFamily determines how Envoy would resolve DNS for Routes where the backend is specified as a fully qualified domain name (FQDN).\nIf set, this configuration overrides other defaults.", "enum": [ "IPv4", "IPv6", "IPv4Preferred", "IPv6Preferred", "IPv4AndIPv6" ], "type": "string" }, "respectDnsTtl": { "description": "RespectDNSTTL indicates whether the DNS Time-To-Live (TTL) should be respected.\nIf the value is set to true, the DNS refresh rate will be set to the resource record\u2019s TTL.\nDefaults to true.", "type": "boolean" } }, "type": "object", "additionalProperties": false }, "healthCheck": { "description": "HealthCheck allows gateway to perform active health checking on backends.", "properties": { "active": { "description": "Active health check configuration", "properties": { "grpc": { "description": "GRPC defines the configuration of the GRPC health checker.\nIt's optional, and can only be used if the specified type is GRPC.", "properties": { "service": { "description": "Service to send in the health check request.\nIf this is not specified, then the health check request applies to the entire\nserver and not to a specific service.", "type": "string" } }, "type": "object", "additionalProperties": false }, "healthyThreshold": { "default": 1, "description": "HealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy.", "format": "int32", "minimum": 1, "type": "integer" }, "http": { "description": "HTTP defines the configuration of http health checker.\nIt's required while the health checker type is HTTP.", "properties": { "expectedResponse": { "description": "ExpectedResponse defines a list of HTTP expected responses to match.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "expectedStatuses": { "description": "ExpectedStatuses defines a list of HTTP response statuses considered healthy.\nDefaults to 200 only", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "hostname": { "description": "Hostname defines the HTTP host that will be requested during health checking.\nDefault: HTTPRoute or GRPCRoute hostname.", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "method": { "description": "Method defines the HTTP method used for health checking.\nDefaults to GET", "type": "string" }, "path": { "description": "Path defines the HTTP path that will be requested during health checking.", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "path" ], "type": "object", "additionalProperties": false }, "initialJitter": { "description": "InitialJitter defines the maximum time Envoy will wait before the first health check.\nEnvoy will randomly select a value between 0 and the initial jitter value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "default": "3s", "description": "Interval defines the time between active health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "tcp": { "description": "TCP defines the configuration of tcp health checker.\nIt's required while the health checker type is TCP.", "properties": { "receive": { "description": "Receive defines the expected response payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false }, "send": { "description": "Send defines the request payload.", "properties": { "binary": { "description": "Binary payload base64 encoded.", "format": "byte", "type": "string" }, "text": { "description": "Text payload in plain text.", "type": "string" }, "type": { "allOf": [ { "enum": [ "Text", "Binary" ] }, { "enum": [ "Text", "Binary" ] } ], "description": "Type defines the type of the payload.", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If payload type is Text, text field needs to be set.", "rule": "self.type == 'Text' ? has(self.text) : !has(self.text)" }, { "message": "If payload type is Binary, binary field needs to be set.", "rule": "self.type == 'Binary' ? has(self.binary) : !has(self.binary)" } ], "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "timeout": { "default": "1s", "description": "Timeout defines the time to wait for a health check response.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "type": { "allOf": [ { "enum": [ "HTTP", "TCP", "GRPC" ] }, { "enum": [ "HTTP", "TCP", "GRPC" ] } ], "description": "Type defines the type of health checker.", "type": "string" }, "unhealthyThreshold": { "default": 3, "description": "UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy.", "format": "int32", "minimum": 1, "type": "integer" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If Health Checker type is HTTP, http field needs to be set.", "rule": "self.type == 'HTTP' ? has(self.http) : !has(self.http)" }, { "message": "If Health Checker type is TCP, tcp field needs to be set.", "rule": "self.type == 'TCP' ? has(self.tcp) : !has(self.tcp)" }, { "message": "The grpc field can only be set if the Health Checker type is GRPC.", "rule": "has(self.grpc) ? self.type == 'GRPC' : true" } ], "additionalProperties": false }, "panicThreshold": { "description": "When number of unhealthy endpoints for a backend reaches this threshold\nEnvoy will disregard health status and balance across all endpoints.\nIt's designed to prevent a situation in which host failures cascade throughout the cluster\nas load increases. If not set, the default value is 50%. To disable panic mode, set value to `0`.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "passive": { "description": "Passive passive check configuration", "properties": { "baseEjectionTime": { "default": "30s", "description": "BaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "consecutive5XxErrors": { "default": 5, "description": "Consecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveGatewayErrors": { "description": "ConsecutiveGatewayErrors sets the number of consecutive gateway errors triggering ejection.", "format": "int32", "type": "integer" }, "consecutiveLocalOriginFailures": { "default": 5, "description": "ConsecutiveLocalOriginFailures sets the number of consecutive local origin failures triggering ejection.\nParameter takes effect only when split_external_local_origin_errors is set to true.", "format": "int32", "type": "integer" }, "failurePercentageThreshold": { "description": "FailurePercentageThreshold sets the failure percentage threshold for outlier detection.\nIf the failure percentage of a given host is greater than or equal to this value, it will be ejected.\nDefaults to 85.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "interval": { "default": "3s", "description": "Interval defines the time between passive health checks.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxEjectionPercent": { "default": 10, "description": "MaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected.", "format": "int32", "type": "integer" }, "splitExternalLocalOriginErrors": { "default": false, "description": "SplitExternalLocalOriginErrors enables splitting of errors between external and local origin.", "type": "boolean" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "http2": { "description": "HTTP2 provides HTTP/2 configuration for backend connections.", "properties": { "initialConnectionWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialConnectionWindowSize sets the initial window size for HTTP/2 connections.\nIf not set, the default value is 1 MiB.", "x-kubernetes-int-or-string": true }, "initialStreamWindowSize": { "allOf": [ { "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$" }, { "pattern": "^[1-9]+[0-9]*([EPTGMK]i|[EPTGMk])?$" } ], "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "InitialStreamWindowSize sets the initial window size for HTTP/2 streams.\nIf not set, the default value is 64 KiB(64*1024).", "x-kubernetes-int-or-string": true }, "maxConcurrentStreams": { "description": "MaxConcurrentStreams sets the maximum number of concurrent streams allowed per connection.\nIf not set, the default value is 100.", "format": "int32", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "onInvalidMessage": { "description": "OnInvalidMessage determines if Envoy will terminate the connection or just the offending stream in the event of HTTP messaging error\nIt's recommended for L2 Envoy deployments to set this value to TerminateStream.\nhttps://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/level_two\nDefault: TerminateConnection", "type": "string" } }, "type": "object", "additionalProperties": false }, "loadBalancer": { "description": "LoadBalancer policy to apply when routing traffic from the gateway to\nthe backend endpoints. Defaults to `LeastRequest`.", "properties": { "consistentHash": { "description": "ConsistentHash defines the configuration when the load balancer type is\nset to ConsistentHash", "properties": { "cookie": { "description": "Cookie configures the cookie hash policy when the consistent hash type is set to Cookie.", "properties": { "attributes": { "additionalProperties": { "type": "string" }, "description": "Additional Attributes to set for the generated cookie.", "type": "object" }, "name": { "description": "Name of the cookie to hash.\nIf this cookie does not exist in the request, Envoy will generate a cookie and set\nthe TTL on the response back to the client based on Layer 4\nattributes of the backend endpoint, to ensure that these future requests\ngo to the same backend endpoint. Make sure to set the TTL field for this case.", "type": "string" }, "ttl": { "description": "TTL of the generated cookie if the cookie is not present. This value sets the\nMax-Age attribute value.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "header": { "description": "Header configures the header hash policy when the consistent hash type is set to Header.\n\nDeprecated: use Headers instead", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "headers": { "description": "Headers configures the header hash policy for each header, when the consistent hash type is set to Headers.", "items": { "description": "Header defines the header hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the header to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "queryParams": { "description": "QueryParams configures the query parameter hash policy when the consistent hash type is set to QueryParams.", "items": { "description": "QueryParam defines the query parameter name hashing configuration for consistent hash based\nload balancing.", "properties": { "name": { "description": "Name of the query param to hash.", "type": "string" } }, "required": [ "name" ], "type": "object", "additionalProperties": false }, "type": "array" }, "tableSize": { "default": 65537, "description": "The table size for consistent hashing, must be prime number limited to 5000011.", "format": "int64", "maximum": 5000011, "minimum": 2, "type": "integer" }, "type": { "description": "ConsistentHashType defines the type of input to hash on. Valid Type values are\n\"SourceIP\",\n\"Header\",\n\"Headers\",\n\"Cookie\".\n\"QueryParams\".", "enum": [ "SourceIP", "Header", "Headers", "Cookie", "QueryParams" ], "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If consistent hash type is header, the header field must be set.", "rule": "self.type == 'Header' ? has(self.header) : !has(self.header)" }, { "message": "If consistent hash type is headers, the headers field must be set.", "rule": "self.type == 'Headers' ? has(self.headers) : !has(self.headers)" }, { "message": "If consistent hash type is cookie, the cookie field must be set.", "rule": "self.type == 'Cookie' ? has(self.cookie) : !has(self.cookie)" }, { "message": "If consistent hash type is queryParams, the queryParams field must be set.", "rule": "self.type == 'QueryParams' ? has(self.queryParams) : !has(self.queryParams)" } ], "additionalProperties": false }, "endpointOverride": { "description": "EndpointOverride defines the configuration for endpoint override.\nWhen specified, the load balancer will attempt to route requests to endpoints\nbased on the override information extracted from request headers or metadata.\n If the override endpoints are not available, the configured load balancer policy will be used as fallback.", "properties": { "extractFrom": { "description": "ExtractFrom defines the sources to extract endpoint override information from.", "items": { "description": "EndpointOverrideExtractFrom defines a source to extract endpoint override information from.", "properties": { "header": { "description": "Header defines the header to get the override endpoint addresses.\nThe header value must specify at least one endpoint in `IP:Port` format or multiple endpoints in `IP:Port,IP:Port,...` format.\nFor example `10.0.0.5:8080` or `[2600:4040:5204::1574:24ae]:80`.\nThe IPv6 address is enclosed in square brackets.", "type": "string" } }, "type": "object", "additionalProperties": false }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "extractFrom" ], "type": "object", "additionalProperties": false }, "slowStart": { "description": "SlowStart defines the configuration related to the slow start load balancer policy.\nIf set, during slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently this is only supported for RoundRobin and LeastRequest load balancers", "properties": { "window": { "description": "Window defines the duration of the warm up period for newly added host.\nDuring slow start window, traffic sent to the newly added hosts will gradually increase.\nCurrently only supports linear growth of traffic. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-slowstartconfig", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "required": [ "window" ], "type": "object", "additionalProperties": false }, "type": { "description": "Type decides the type of Load Balancer policy.\nValid LoadBalancerType values are\n\"ConsistentHash\",\n\"LeastRequest\",\n\"Random\",\n\"RoundRobin\".", "enum": [ "ConsistentHash", "LeastRequest", "Random", "RoundRobin" ], "type": "string" }, "zoneAware": { "description": "ZoneAware defines the configuration related to the distribution of requests between locality zones.", "properties": { "preferLocal": { "description": "PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone.", "properties": { "force": { "description": "ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior\nwhich maintains equal distribution among upstream endpoints while sending as much traffic as possible locally.", "properties": { "minEndpointsInZoneThreshold": { "description": "MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone\noverride. This is useful for protecting zones with fewer endpoints.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "minEndpointsThreshold": { "description": "MinEndpointsThreshold is the minimum number of total upstream endpoints across all zones required to enable zone-aware routing.", "format": "int64", "type": "integer" }, "percentageEnabled": { "description": "Configures percentage of requests that will be considered for zone aware routing if zone aware routing is configured. If not specified, Envoy defaults to 100%.", "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "If LoadBalancer type is consistentHash, consistentHash field needs to be set.", "rule": "self.type == 'ConsistentHash' ? has(self.consistentHash) : !has(self.consistentHash)" }, { "message": "Currently SlowStart is only supported for RoundRobin and LeastRequest load balancers.", "rule": "self.type in ['Random', 'ConsistentHash'] ? !has(self.slowStart) : true " }, { "message": "Currently ZoneAware is only supported for LeastRequest, Random, and RoundRobin load balancers.", "rule": "self.type == 'ConsistentHash' ? !has(self.zoneAware) : true " } ], "additionalProperties": false }, "proxyProtocol": { "description": "ProxyProtocol enables the Proxy Protocol when communicating with the backend.", "properties": { "version": { "description": "Version of ProxyProtol\nValid ProxyProtocolVersion values are\n\"V1\"\n\"V2\"", "enum": [ "V1", "V2" ], "type": "string" } }, "required": [ "version" ], "type": "object", "additionalProperties": false }, "retry": { "description": "Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions.\nIf not set, retry will be disabled.", "properties": { "numAttemptsPerPriority": { "description": "NumAttemptsPerPriority defines the number of requests (initial attempt + retries)\nthat should be sent to the same priority before switching to a different one.\nIf not specified or set to 0, all requests are sent to the highest priority that is healthy.", "format": "int32", "type": "integer" }, "numRetries": { "default": 2, "description": "NumRetries is the number of retries to be attempted. Defaults to 2.", "format": "int32", "minimum": 0, "type": "integer" }, "perRetry": { "description": "PerRetry is the retry policy to be applied per retry attempt.", "properties": { "backOff": { "description": "Backoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential\nback-off algorithm for retries. For additional details,\nsee https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries", "properties": { "baseInterval": { "description": "BaseInterval is the base interval between retries.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxInterval": { "description": "MaxInterval is the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set.\nThe default is 10 times the base_interval", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout is the timeout per retry attempt.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "retryOn": { "description": "RetryOn specifies the retry trigger condition.\n\nIf not specified, the default is to retry on connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes(503).", "properties": { "httpStatusCodes": { "description": "HttpStatusCodes specifies the http status codes to be retried.\nThe retriable-status-codes trigger must also be configured for these status codes to trigger a retry.", "items": { "description": "HTTPStatus defines the http status code.", "maximum": 599, "minimum": 100, "type": "integer" }, "type": "array" }, "triggers": { "description": "Triggers specifies the retry trigger condition(Http/Grpc).", "items": { "description": "TriggerEnum specifies the conditions that trigger retries.", "enum": [ "5xx", "gateway-error", "reset", "reset-before-request", "connect-failure", "retriable-4xx", "refused-stream", "retriable-status-codes", "cancelled", "deadline-exceeded", "internal", "resource-exhausted", "unavailable" ], "type": "string" }, "type": "array" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "tcpKeepalive": { "description": "TcpKeepalive settings associated with the upstream client connection.\nDisabled by default.", "properties": { "idleTime": { "description": "The duration a connection needs to be idle before keep-alive\nprobes start being sent.\nThe duration format is\nDefaults to `7200s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "interval": { "description": "The duration between keep-alive probes.\nDefaults to `75s`.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "probes": { "description": "The total number of unacknowledged probes to send before deciding\nthe connection is dead.\nDefaults to 9.", "format": "int32", "type": "integer" } }, "type": "object", "additionalProperties": false }, "timeout": { "description": "Timeout settings for the backend connections.", "properties": { "http": { "description": "Timeout settings for HTTP.", "properties": { "connectionIdleTimeout": { "description": "The idle timeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.\nDefault: 1 hour.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxConnectionDuration": { "description": "The maximum duration of an HTTP connection.\nDefault: unlimited.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "maxStreamDuration": { "description": "MaxStreamDuration is the maximum duration for a stream to complete. This timeout measures the time\nfrom when the request is sent until the response stream is fully consumed and does not apply to\nnon-streaming requests.\nWhen set to \"0s\", no max duration is applied and streams can run indefinitely.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" }, "requestTimeout": { "description": "RequestTimeout is the time until which entire response is received from the upstream.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false }, "tcp": { "description": "Timeout settings for TCP.", "properties": { "connectTimeout": { "description": "The timeout for network connection establishment, including TCP and TLS handshakes.\nDefault: 10 seconds.", "pattern": "^([0-9]{1,5}(h|m|s|ms)){1,4}$", "type": "string" } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false } }, "type": "object", "x-kubernetes-validations": [ { "message": "predictivePercent in preconnect policy only works with RoundRobin or Random load balancers", "rule": "!((has(self.connection) && has(self.connection.preconnect) && has(self.connection.preconnect.predictivePercent)) && !(has(self.loadBalancer) && has(self.loadBalancer.type) && self.loadBalancer.type in ['Random', 'RoundRobin']))" } ], "additionalProperties": false }, "endSessionEndpoint": { "description": "The OIDC Provider's [end session endpoint](https://openid.net/specs/openid-connect-core-1_0.html#RPLogout).\n\nIf the end session endpoint is provided, EG will use it to log out the user from the OIDC Provider when the user accesses the logout path.\nEG will also try to discover the end session endpoint from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) when authorizationEndpoint or tokenEndpoint is not provided.", "type": "string" }, "issuer": { "description": "The OIDC Provider's [issuer identifier](https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery).\nIssuer MUST be a URI RFC 3986 [RFC3986] with a scheme component that MUST\nbe https, a host component, and optionally, port and path components and\nno query or fragment components.", "minLength": 1, "type": "string" }, "tokenEndpoint": { "description": "The OIDC Provider's [token endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint).\nIf not provided, EG will try to discover it from the provider's [Well-Known Configuration Endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).", "type": "string" } }, "required": [ "issuer" ], "type": "object", "x-kubernetes-validations": [ { "message": "BackendRefs must be used, backendRef is not supported.", "rule": "!has(self.backendRef)" }, { "message": "Retry timeout is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.perRetry)? !has(self.backendSettings.retry.perRetry.timeout):true):true):true" }, { "message": "HTTPStatusCodes is not supported.", "rule": "has(self.backendSettings)? (has(self.backendSettings.retry)?(has(self.backendSettings.retry.retryOn)? !has(self.backendSettings.retry.retryOn.httpStatusCodes):true):true):true" } ], "additionalProperties": false }, "redirectURL": { "description": "The redirect URL to be used in the OIDC\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nIf not specified, uses the default redirect URI \"%REQ(x-forwarded-proto)%://%REQ(:authority)%/oauth2/callback\"", "type": "string" }, "refreshToken": { "default": true, "description": "RefreshToken indicates whether the Envoy should automatically refresh the\nid token and access token when they expire.\nWhen set to true, the Envoy will use the refresh token to get a new id token\nand access token when they expire.\n\nIf not specified, defaults to true.", "type": "boolean" }, "resources": { "description": "The OIDC resources to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "The OIDC scopes to be used in the\n[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nThe \"openid\" scope is always added to the list of scopes if not already\nspecified.", "items": { "type": "string" }, "type": "array" } }, "required": [ "clientSecret", "provider" ], "type": "object", "x-kubernetes-validations": [ { "message": "only one of clientID or clientIDRef must be set", "rule": "(has(self.clientID) && !has(self.clientIDRef)) || (!has(self.clientID) && has(self.clientIDRef))" } ], "additionalProperties": false } }, "required": [ "oidc" ], "type": "object", "additionalProperties": false }, "projectID": { "description": "ProjectID is the GCP project ID.", "minLength": 1, "type": "string" }, "serviceAccountImpersonation": { "description": "ServiceAccountImpersonation is the service account impersonation configuration.\nThis is used to impersonate a service account when getting access token.", "properties": { "serviceAccountName": { "description": "ServiceAccountName is the name of the service account to impersonate.", "minLength": 1, "type": "string" } }, "required": [ "serviceAccountName" ], "type": "object", "additionalProperties": false }, "workloadIdentityPoolName": { "description": "WorkloadIdentityPoolName is the name of the workload identity pool defined in GCP.\nhttps://cloud.google.com/iam/docs/workload-identity-federation?hl=en", "minLength": 1, "type": "string" }, "workloadIdentityProviderName": { "description": "WorkloadIdentityProviderName is the name of the external identity provider as registered on Google Cloud Platform.", "minLength": 1, "type": "string" } }, "required": [ "oidcExchangeToken", "projectID", "workloadIdentityPoolName", "workloadIdentityProviderName" ], "type": "object", "additionalProperties": false } }, "required": [ "projectName", "region" ], "type": "object", "x-kubernetes-validations": [ { "message": "Exactly one of GCPWorkloadIdentityFederationConfig or GCPCredentialsFile must be specified", "rule": "(has(self.credentialsFile) && !has(self.workloadIdentityFederationConfig)) || (has(self.workloadIdentityFederationConfig) && !has(self.credentialsFile))" } ], "additionalProperties": false }, "targetRefs": { "description": "TargetRefs are the names of the AIServiceBackend or InferencePool resources this BackendSecurityPolicy is being attached to.\nAttaching multiple BackendSecurityPolicies to the same resource is invalid and will result in an error\nduring the reconciliation of the resource.", "items": { "description": "LocalPolicyTargetReference identifies an API object to apply a direct or\ninherited policy to. This should be used as part of Policy resources\nthat can target Gateway API resources. For more information on how this\npolicy attachment model works, and a sample Policy resource, refer to\nthe policy attachment documentation for Gateway API.", "properties": { "group": { "description": "Group is the group of the target resource.", "maxLength": 253, "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$", "type": "string" }, "kind": { "description": "Kind is kind of the target resource.", "maxLength": 63, "minLength": 1, "pattern": "^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$", "type": "string" }, "name": { "description": "Name is the name of the target resource.", "maxLength": 253, "minLength": 1, "type": "string" } }, "required": [ "group", "kind", "name" ], "type": "object", "additionalProperties": false }, "maxItems": 16, "type": "array", "x-kubernetes-validations": [ { "message": "targetRefs must reference AIServiceBackend or InferencePool resources", "rule": "self.all(ref, (ref.group == 'aigateway.envoyproxy.io' && ref.kind == 'AIServiceBackend') || (ref.group == 'inference.networking.k8s.io' && ref.kind == 'InferencePool'))" } ] }, "type": { "description": "Type specifies the type of the backend security policy.", "enum": [ "APIKey", "AWSCredentials", "AzureAPIKey", "AzureCredentials", "GCPCredentials", "AnthropicAPIKey" ], "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "When type is APIKey, only apiKey field should be set", "rule": "self.type == 'APIKey' ? (has(self.apiKey) && !has(self.awsCredentials) && !has(self.azureAPIKey) && !has(self.azureCredentials) && !has(self.gcpCredentials) && !has(self.anthropicAPIKey)) : true" }, { "message": "When type is AWSCredentials, only awsCredentials field should be set", "rule": "self.type == 'AWSCredentials' ? (has(self.awsCredentials) && !has(self.apiKey) && !has(self.azureAPIKey) && !has(self.azureCredentials) && !has(self.gcpCredentials) && !has(self.anthropicAPIKey)) : true" }, { "message": "When type is AzureAPIKey, only azureAPIKey field should be set", "rule": "self.type == 'AzureAPIKey' ? (has(self.azureAPIKey) && !has(self.apiKey) && !has(self.awsCredentials) && !has(self.azureCredentials) && !has(self.gcpCredentials) && !has(self.anthropicAPIKey)) : true" }, { "message": "When type is AzureCredentials, only azureCredentials field should be set", "rule": "self.type == 'AzureCredentials' ? (has(self.azureCredentials) && !has(self.apiKey) && !has(self.awsCredentials) && !has(self.azureAPIKey) && !has(self.gcpCredentials) && !has(self.anthropicAPIKey)) : true" }, { "message": "When type is GCPCredentials, only gcpCredentials field should be set", "rule": "self.type == 'GCPCredentials' ? (has(self.gcpCredentials) && !has(self.apiKey) && !has(self.awsCredentials) && !has(self.azureAPIKey) && !has(self.azureCredentials) && !has(self.anthropicAPIKey)) : true" }, { "message": "When type is AnthropicAPIKey, only anthropicAPIKey field should be set", "rule": "self.type == 'AnthropicAPIKey' ? (has(self.anthropicAPIKey) && !has(self.apiKey) && !has(self.awsCredentials) && !has(self.azureAPIKey) && !has(self.azureCredentials) && !has(self.gcpCredentials)) : true" } ], "additionalProperties": false }, "status": { "description": "Status defines the status details of the BackendSecurityPolicy.", "properties": { "conditions": { "description": "Conditions is the list of conditions by the reconciliation result.\nCurrently, at most one condition is set.\n\nKnown .status.conditions.type are: \"Accepted\", \"NotAccepted\".", "items": { "description": "Condition contains details for one aspect of the current state of this API Resource.", "properties": { "lastTransitionTime": { "description": "lastTransitionTime is the last time the condition transitioned from one status to another.\nThis should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.", "format": "date-time", "type": "string" }, "message": { "description": "message is a human readable message indicating details about the transition.\nThis may be an empty string.", "maxLength": 32768, "type": "string" }, "observedGeneration": { "description": "observedGeneration represents the .metadata.generation that the condition was set based upon.\nFor instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date\nwith respect to the current state of the instance.", "format": "int64", "minimum": 0, "type": "integer" }, "reason": { "description": "reason contains a programmatic identifier indicating the reason for the condition's last transition.\nProducers of specific condition types may define expected values and meanings for this field,\nand whether the values are considered a guaranteed API.\nThe value should be a CamelCase string.\nThis field may not be empty.", "maxLength": 1024, "minLength": 1, "pattern": "^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$", "type": "string" }, "status": { "description": "status of the condition, one of True, False, Unknown.", "enum": [ "True", "False", "Unknown" ], "type": "string" }, "type": { "description": "type of condition in CamelCase or in foo.example.com/CamelCase.", "maxLength": 316, "pattern": "^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$", "type": "string" } }, "required": [ "lastTransitionTime", "message", "reason", "status", "type" ], "type": "object", "additionalProperties": false }, "type": "array" } }, "type": "object", "additionalProperties": false } }, "type": "object" }