For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Static configuration
Configure static settings that are applied at startup time.
Most agentgateway configurations dynamically update as you make changes to the binds, policies, backends, and so on.
However, a few configurations are statically configured at startup. These static configurations are under the config section.
Static configuration file schema
The following table shows the config file schema for static configurations at startup. For the full agentgateway schema of dynamic and static configuration, see the reference docs.
| Field | Type | Description |
|---|---|---|
config | object | config defines top-level settings for DNS, admin, networking, observability, and session management. Unlike other sections, these are applied only at startup and are not dynamically reloaded. |
config.enableIpv6 | boolean | Enable IPv6 address resolution and binding. Defaults to true. |
config.dns | object | DNS resolver settings. |
config.dns.lookupFamily | enum | Controls which IP address families the DNS resolver will query for upstream connections. Accepted values: All, Auto, V4Preferred, V4Only, V6Only. Defaults to Auto (IPv4-only when enableIpv6 is false, both when true). |
config.dns.edns0 | boolean | Whether to enable EDNS0 (Extension Mechanisms for DNS) in the resolver. When None, the system-provided resolver setting is preserved.Can also be set via the DNS_EDNS0 environment variable. |
config.localXdsPath | string | Local XDS path. If not specified, the current configuration file will be used. |
config.modelCatalog | []object | Model cost catalog sources; entries are merged in order, with later entries taking precedence. |
config.modelCatalog[].file | string | Path to a file on disk containing the model cost catalog. |
config.modelCatalog[].inline | string | Model cost catalog provided inline as a string. |
config.modelCatalog[].inline | object | Model cost catalog provided inline as structured data. |
config.modelCatalog[].inline.providers | object | Map of provider name to its supported models and pricing. |
config.modelCatalog[].inline.providers.*.models | object | Map of model ID to its pricing rates and tiers. |
config.modelCatalog[].inline.providers.*.models.*.rates | object | Base pricing rates for this model. |
config.modelCatalog[].inline.providers.*.models.*.rates.input | string | Cost per 1M input (prompt) tokens. |
config.modelCatalog[].inline.providers.*.models.*.rates.output | string | Cost per 1M output (completion) tokens. |
config.modelCatalog[].inline.providers.*.models.*.rates.cacheRead | string | Cost per 1M tokens read from cache. |
config.modelCatalog[].inline.providers.*.models.*.rates.cacheWrite | string | Cost per 1M tokens written to cache. |
config.modelCatalog[].inline.providers.*.models.*.rates.reasoning | string | Cost per 1M reasoning tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.rates.inputAudio | string | Cost per 1M input audio tokens. Falls back to the input rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.rates.outputAudio | string | Cost per 1M output audio tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers | []object | Context-length pricing tiers that override the base rates. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].contextOver | integer | Context-token threshold above which this tier’s rates apply. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates | object | Pricing rates for this tier, overlaid on the base model rates. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.input | string | Cost per 1M input (prompt) tokens. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.output | string | Cost per 1M output (completion) tokens. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.cacheRead | string | Cost per 1M tokens read from cache. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.cacheWrite | string | Cost per 1M tokens written to cache. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.reasoning | string | Cost per 1M reasoning tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.inputAudio | string | Cost per 1M input audio tokens. Falls back to the input rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.outputAudio | string | Cost per 1M output audio tokens. Falls back to the output rate if unset. |
config.database | object | Primary database used by local runtime features. |
config.database.url | string | Connection URL for the request log database. A postgres:// or postgresql:// URL uses Postgres; any other value is treated as a SQLite database. |
config.caAddress | string | Address of the Certificate Authority used to issue SPIFFE certificates. |
config.caAuthToken | string | Authentication token for communicating with the Certificate Authority. |
config.xdsAddress | string | Address of the xDS control plane used for dynamic configuration. |
config.xdsAuthToken | string | Authentication token for communicating with the xDS control plane. |
config.namespace | string | Kubernetes namespace for this gateway instance. |
config.gateway | string | Name of this gateway. Required when xDS is configured. |
config.trustDomain | string | SPIFFE trust domain for this gateway. |
config.additionalTrustDomains | string | Comma-separated list of additional SPIFFE trust domains accepted on inbound HBONE connections. The local trust_domain is always implicitly included. |
config.skipValidateTrustDomain | boolean | When true, skip SPIFFE trust-domain verification on inbound HBONE connections. |
config.serviceAccount | string | Kubernetes service account for this gateway, used in its SPIFFE identity. |
config.clusterId | string | Identifier for the cluster this gateway runs in. Defaults to “Kubernetes”. |
config.network | string | Network name for this gateway, used for locality-aware routing. |
config.adminAddr | string | Admin UI address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.standardAttributes | object | Standard request log attributes populated for database-backed local runtime features. |
config.standardAttributes.user | string | CEL expression used to populate the agentgateway.user request log attribute. |
config.standardAttributes.group | string | CEL expression used to populate the agentgateway.group request log attribute. |
config.statsAddr | string | Stats/metrics server address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.readinessAddr | string | Readiness probe server address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.session | object | Configuration for stateful session management |
config.session.key | string | The AES-256-GCM session protection key to be used for session tokens. If not set, sessions will not be encrypted. For example, generated via openssl rand -hex 32. |
| `config | `config | config.customFunctions |
config.connectionTerminationDeadline | string | Maximum time to wait for connections to close gracefully during shutdown. |
config.connectionMinTerminationDeadline | string | Minimum time to allow for graceful connection termination. Defaults to zero. |
config.workerThreads | string | Number of worker threads for the async runtime. Accepts a number or a string such as “auto”. |
config.tracing | object | Distributed tracing configuration. |
config.tracing.otlpEndpoint | string | OTLP collector endpoint URL for exporting traces. |
config.tracing.headers | object | HTTP headers to include on OTLP trace exports, such as authentication headers. |
config.tracing.otlpProtocol | enum | OTLP transport protocol: grpc or http.Possible values: grpc, http. |
config.tracing.fields | object | Custom fields to add to or remove from trace spans. |
config.tracing.fields.remove | []string | Field names to remove from log entries. |
config.tracing.fields.add | object | Map of field name to a CEL expression that computes the value to add to logs. |
config.tracing.randomSampling | string | Expression to determine the amount of random sampling. Random sampling will initiate a new trace span if the incoming request does not have a trace already. This should evaluate to either a float between 0.0-1.0 (0-100%) or true/false. This defaults to ‘false’. |
config.tracing.clientSampling | string | Expression to determine the amount of client sampling. Client sampling determines whether to initiate a new trace span if the incoming request does have a trace already. This should evaluate to either a float between 0.0-1.0 (0-100%) or true/false. This defaults to ’true'. |
config.tracing.path | string | OTLP path. Default is /v1/traces |
config.logging | object | Logging configuration, including filter, level, format, and custom fields. |
config.logging.filter | string | CEL expression that selects which requests are logged. |
config.logging.fields | object | Custom fields to add to or remove from log entries. |
config.logging.fields.remove | []string | Field names to remove from log entries. |
config.logging.fields.add | object | Map of field name to a CEL expression that computes the value to add to logs. |
config.logging.level | string | Log level: a single level (e.g. info), a comma-separated string of per-module levels (e.g. info,agent_core=trace), or a list of per-module levels (e.g. [info, agent_core=trace]). |
config.logging.format | enum | Log output format: text or json.Possible values: text, json, null. |
config.logging.database | object | Log-store database configuration; enables request logging to a database backend. |
config.logging.database.url | string | Connection URL for the request log database. A postgres:// or postgresql:// URL uses Postgres; any other value is treated as a SQLite database. |
config.metrics | object | Metrics configuration, including metric removal and custom fields. |
config.metrics.remove | []string | Metric names to exclude from collection. |
config.metrics.fields | object | Custom fields to add to all metrics. |
config.metrics.fields.add | object | Map of field name to a CEL expression that computes the value to add to metrics. |
config.backend | object | Configuration for upstream connections, including keepalives, timeouts, and pooling. |
config.backend.keepalives | object | TCP keepalive configuration for upstream connections. |
config.backend.keepalives.enabled | boolean | Enable TCP keepalive probes on backend connections. Defaults to true. |
config.backend.keepalives.time | string | Idle time before the first keepalive probe is sent. |
config.backend.keepalives.interval | string | Time between successive keepalive probes. |
config.backend.keepalives.retries | integer | Number of unacknowledged probes before the connection is considered dead. |
config.backend.connectTimeout | string | Maximum time to wait when establishing a connection to an upstream. Defaults to 10 seconds. |
config.backend.poolIdleTimeout | string | The maximum duration to keep an idle connection alive. |
config.backend.poolMaxSize | integer | The maximum number of connections allowed in the pool, per hostname. If set, this will limit the total number of connections kept alive to any given host. Note: excess connections will still be created, they will just not remain idle. If unset, there is no limit |
config.hbone | object | HBONE (HTTP/2 CONNECT tunnel) protocol configuration. |
config.hbone.windowSize | integer | HTTP/2 per-stream flow-control window size in bytes. Defaults to 4 MiB. |
config.hbone.connectionWindowSize | integer | HTTP/2 connection-level flow-control window size in bytes. Defaults to 16 MiB. |
config.hbone.frameSize | integer | HTTP/2 maximum frame size in bytes. Defaults to 1 MiB. |
config.hbone.poolMaxStreamsPerConn | integer | Maximum concurrent streams per pooled connection. Defaults to 100. |
config.hbone.poolUnusedReleaseTimeout | string | Duration after which unused pooled connections are released. |
gateways.*.port | integer | port is the port to listen on for this gateway. |
gateways.*.protocol | enum | protocol controls whether this gateway accepts HTTP/HTTPS routes or TCP/TLS routes. When omitted, gateways default to HTTP, or HTTPS when tls is set. Possible values: HTTP, HTTPS, TCP, TLS, null. |
gateways.*.listeners | []object | listeners defines multiple named listeners under this gateway. When set, only port may be configured on the top level gateway. |
gateways.*.listeners[].name | string | name identifies this listener for gateway references like gateways: gateway-name/listener-name. |
gateways.*.listeners[].hostname | string | Hostname defines what hostnames are served under this listener. Can be a wildcard. This allows serving multiple domains with different TLS configurations. If unset, all domains will be served (implicit wildcard). |
gateways.*.listeners[].protocol | enum | protocol controls whether this listener accepts HTTP/HTTPS routes or TCP/TLS routes. When omitted, listeners default to HTTP, or HTTPS when tls is set. Possible values: HTTP, HTTPS, TCP, TLS, null. |
gateways.*.listeners[].tls | object | tls enables HTTPS for this listener. |
gateways.*.listeners[].tls.mode | enum | Certificate source mode. Static mode uses cert/key as the leaf certificate; dynamic CA mode uses cert/key as a CA for on-demand SNI leaf certificate issuance. Possible values: static, dynamicCa. |
gateways.*.listeners[].tls.cert | string | Path to the TLS certificate file (leaf certificate, or CA certificate in dynamic CA mode). |
gateways.*.listeners[].tls.key | string | Path to the TLS private key file. |
gateways.*.listeners[].tls.root | string | Path to a root CA certificate file used to validate client certificates. |
gateways.*.listeners[].tls.cipherSuites | []string | Optional cipher suite allowlist (order is preserved). |
gateways.*.listeners[].tls.minTLSVersion | enum | Minimum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.listeners[].tls.minTlsVersion | enum | Minimum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.listeners[].tls.maxTLSVersion | enum | Maximum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.listeners[].tls.maxTlsVersion | enum | Maximum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.listeners[].tls.keyExchangeGroups | []string | Key exchange groups allowed for negotiating TLS. |
gateways.*.listeners[].oidc | object | Authenticate browser requests with OIDC authorization code flow. |
gateways.*.listeners[].oidc.issuer | string | Issuer used for discovery and ID token validation. |
gateways.*.listeners[].oidc.discovery | object | Optional discovery document override. If omitted, discovery uses${issuer}/.well-known/openid-configuration. |
gateways.*.listeners[].oidc.discovery.file | string | Path to a file on disk to load the value from. |
gateways.*.listeners[].oidc.discovery.url | string | |
gateways.*.listeners[].oidc.authorizationEndpoint | string | Authorization endpoint used to start the browser login flow. |
gateways.*.listeners[].oidc.tokenEndpoint | string | Token endpoint used to exchange the authorization code. |
gateways.*.listeners[].oidc.tokenEndpointAuth | enum | Token endpoint client authentication method for explicit provider configuration. Discovery mode derives this from provider metadata. Explicit mode defaults to clientSecretBasic when omitted.Possible values: clientSecretBasic, clientSecretPost, null. |
gateways.*.listeners[].oidc.jwks | object | JWKS source used to validate returned ID tokens. |
gateways.*.listeners[].oidc.jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.listeners[].oidc.jwks.url | string | |
gateways.*.listeners[].oidc.clientId | string | OAuth2 client identifier used for authorization and token exchange. |
gateways.*.listeners[].oidc.clientSecret | string | OAuth2 client secret used for token exchange. |
gateways.*.listeners[].oidc.redirectURI | string | Absolute callback URI handled by the gateway. This policy always redirects unauthenticated non-callback requests back through this login flow. |
gateways.*.listeners[].oidc.scopes | []string | Additional OAuth2 scopes to request. openid is always included. |
gateways.*.listeners[].jwtAuth | object | Authenticate incoming requests with JWT bearer tokens. |
gateways.*.listeners[].jwtAuth.mode | enum | Controls whether requests must include a JWT and how validation failures are handled. Possible values: strict, optional, permissive. |
gateways.*.listeners[].jwtAuth.location | object | Where to read the JWT from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.listeners[].jwtAuth.location.header | object | Read the credential from an HTTP header. |
gateways.*.listeners[].jwtAuth.location.header.name | string | Header name containing the credential. |
gateways.*.listeners[].jwtAuth.location.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.listeners[].jwtAuth.location.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.listeners[].jwtAuth.location.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.listeners[].jwtAuth.location.cookie | object | Read the credential from a request cookie. |
gateways.*.listeners[].jwtAuth.location.cookie.name | string | Cookie name containing the credential. |
gateways.*.listeners[].jwtAuth.location.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
gateways.*.listeners[].jwtAuth.providers | []object | Trusted issuers and their signing keys. |
gateways.*.listeners[].jwtAuth.providers[].issuer | string | Expected token issuer, matched against the JWT iss claim. |
gateways.*.listeners[].jwtAuth.providers[].audiences | []string | Accepted token audiences, matched against the JWT aud claim when set. |
gateways.*.listeners[].jwtAuth.providers[].jwks | object | JSON Web Key Set used to verify token signatures. Can be inline, from a file, or fetched remotely. |
gateways.*.listeners[].jwtAuth.providers[].jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.listeners[].jwtAuth.providers[].jwks.url | string | |
gateways.*.listeners[].jwtAuth.providers[].jwtValidationOptions | object | Claim requirements to enforce after the token signature is verified. |
gateways.*.listeners[].jwtAuth.providers[].jwtValidationOptions.requiredClaims | []string | Claims that must be present in the token before validation. Only “exp”, “nbf”, “aud”, “iss”, “sub” are enforced; others (including “iat” and “jti”) are ignored. Defaults to [“exp”]. Use an empty list to require no claims. |
gateways.*.listeners[].jwtAuth.issuer | string | Expected token issuer, matched against the JWT iss claim. |
gateways.*.listeners[].jwtAuth.audiences | []string | Accepted token audiences, matched against the JWT aud claim when set. |
gateways.*.listeners[].jwtAuth.jwks | object | JSON Web Key Set used to verify token signatures. Can be inline, from a file, or fetched remotely. |
gateways.*.listeners[].jwtAuth.jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.listeners[].jwtAuth.jwks.url | string | |
gateways.*.listeners[].jwtAuth.jwtValidationOptions | object | Claim requirements to enforce after the token signature is verified. |
gateways.*.listeners[].jwtAuth.jwtValidationOptions.requiredClaims | []string | Claims that must be present in the token before validation. Only “exp”, “nbf”, “aud”, “iss”, “sub” are enforced; others (including “iat” and “jti”) are ignored. Defaults to [“exp”]. Use an empty list to require no claims. |
gateways.*.listeners[].authorization | object | Authorization rules for incoming HTTP requests. |
gateways.*.listeners[].authorization.rules | []object | CEL authorization rules to evaluate for a request. |
gateways.*.listeners[].authorization.rules[].allow | string | Allow the request when this CEL expression is true. |
gateways.*.listeners[].authorization.rules[].deny | string | Deny the request when this CEL expression is true. |
gateways.*.listeners[].authorization.rules[].require | string | Require this CEL expression to be true. |
gateways.*.listeners[].extAuthz | object | Authorize incoming requests by calling an external authorization service. |
gateways.*.listeners[].extAuthz.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.listeners[].extAuthz.conditional[].service | object | Service reference. Service must be defined in the top level |
gateways.*.listeners[].extAuthz.conditional[].host | string | Hostname or IP address |
gateways.*.listeners[].extAuthz.conditional[].backend | string | Explicit backend reference. Backend must be defined in the top level |
| `gateways.*.listeners[].extAuthz.conditional[] | `gateways.*.listeners[].extAuthz.conditional[] | `gateways.*.listeners[].extAuthz.conditional[] |
gateways.*.listeners[].extAuthz.conditional[].protocol.grpc | object | Call the authorization service using the gRPC authorization protocol. |
gateways.*.listeners[].extAuthz.conditional[].protocol.grpc.context | object | Static context values to send to the authorization service. Maps to the context_extensions field in the request. |
gateways.*.listeners[].extAuthz.conditional[].protocol.grpc.metadata | object | Metadata values to send to the authorization service, computed from CEL expressions. Maps to the metadata_context.filter_metadata field in the request.If unset, envoy.filters.http.jwt_authn is set when JWT auth is also used, for compatibility. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http | object | Call the authorization service using HTTP. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.path | string | CEL expression that computes the authorization request path. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.redirect | string | CEL expression that computes a redirect URL when authorization fails. When the authorization service returns unauthorized, this redirects instead of returning the error directly. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.body | string | CEL expression that computes the authorization request body. Strings and bytes are used directly; other values are JSON-encoded. If set, this replaces forwarding the incoming request body. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.includeResponseHeaders | []string | Authorization response headers to copy into the backend request. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.addRequestHeaders | object | Headers to add to the authorization request using CEL expressions. Empty means all headers. |
gateways.*.listeners[].extAuthz.conditional[].protocol.http.metadata | object | Metadata values to expose under the extauthz variable after authorization. |
gateways.*.listeners[].extAuthz.conditional[].failureMode | object | Behavior when the authorization service is unavailable or returns an error. |
gateways.*.listeners[].extAuthz.conditional[].failureMode.denyWithStatus | integer | Deny the request with the configured HTTP status code. |
gateways.*.listeners[].extAuthz.conditional[].includeRequestHeaders | []string | Request headers to send to the authorization service. If unset, gRPC sends all request headers and HTTP sends only Authorization. |
gateways.*.listeners[].extAuthz.conditional[].includeRequestBody | object | Options for sending the request body to the authorization service. |
gateways.*.listeners[].extAuthz.conditional[].includeRequestBody.maxRequestBytes | integer | Maximum request body size to send to the authorization service. Defaults to 8192 bytes. |
gateways.*.listeners[].extAuthz.conditional[].includeRequestBody.allowPartialMessage | boolean | Whether to send a partial body when the request exceeds maxRequestBytes. |
gateways.*.listeners[].extAuthz.conditional[].includeRequestBody.packAsBytes | boolean | Whether to send the body as raw bytes for gRPC authorization checks. |
gateways.*.listeners[].extAuthz.conditional[].cache | object | Cache authorization results using CEL expressions as the cache key. Warning: the safety of this feature depends on the cache key accurately capturing the fields the server operates on. For example, if you return a different result based on header A but only cache header B, users may get incorrect cache hits. |
gateways.*.listeners[].extAuthz.conditional[].cache.key | []string | CEL expressions that make up the cache key. Empty keys are accepted, but do not produce cache hits. |
gateways.*.listeners[].extAuthz.conditional[].cache.ttl | string | CEL expression that returns how long cached authorization results are reused. The expression is evaluated after the authorization response has been applied to the request, and must return either a duration or timestamp. |
gateways.*.listeners[].extAuthz.conditional[].cache.maxEntries | integer | Maximum number of authorization results to keep in the cache. |
gateways.*.listeners[].extAuthz.service | object | Service reference. Service must be defined in the top level |
gateways.*.listeners[].extAuthz.host | string | Hostname or IP address |
gateways.*.listeners[].extAuthz.backend | string | Explicit backend reference. Backend must be defined in the top level |
gateways.*.listeners[].extAuthz.protocol.grpc | object | Call the authorization service using the gRPC authorization protocol. |
gateways.*.listeners[].extAuthz.protocol.grpc.context | object | Static context values to send to the authorization service. Maps to the context_extensions field in the request. |
gateways.*.listeners[].extAuthz.protocol.grpc.metadata | object | Metadata values to send to the authorization service, computed from CEL expressions. Maps to the metadata_context.filter_metadata field in the request.If unset, envoy.filters.http.jwt_authn is set when JWT auth is also used, for compatibility. |
gateways.*.listeners[].extAuthz.protocol.http | object | Call the authorization service using HTTP. |
gateways.*.listeners[].extAuthz.protocol.http.path | string | CEL expression that computes the authorization request path. |
gateways.*.listeners[].extAuthz.protocol.http.redirect | string | CEL expression that computes a redirect URL when authorization fails. When the authorization service returns unauthorized, this redirects instead of returning the error directly. |
gateways.*.listeners[].extAuthz.protocol.http.body | string | CEL expression that computes the authorization request body. Strings and bytes are used directly; other values are JSON-encoded. If set, this replaces forwarding the incoming request body. |
gateways.*.listeners[].extAuthz.protocol.http.includeResponseHeaders | []string | Authorization response headers to copy into the backend request. |
gateways.*.listeners[].extAuthz.protocol.http.addRequestHeaders | object | Headers to add to the authorization request using CEL expressions. Empty means all headers. |
gateways.*.listeners[].extAuthz.protocol.http.metadata | object | Metadata values to expose under the extauthz variable after authorization. |
gateways.*.listeners[].extAuthz.failureMode | object | Behavior when the authorization service is unavailable or returns an error. |
gateways.*.listeners[].extAuthz.failureMode.denyWithStatus | integer | Deny the request with the configured HTTP status code. |
gateways.*.listeners[].extAuthz.includeRequestHeaders | []string | Request headers to send to the authorization service. If unset, gRPC sends all request headers and HTTP sends only Authorization. |
gateways.*.listeners[].extAuthz.includeRequestBody | object | Options for sending the request body to the authorization service. |
gateways.*.listeners[].extAuthz.includeRequestBody.maxRequestBytes | integer | Maximum request body size to send to the authorization service. Defaults to 8192 bytes. |
gateways.*.listeners[].extAuthz.includeRequestBody.allowPartialMessage | boolean | Whether to send a partial body when the request exceeds maxRequestBytes. |
gateways.*.listeners[].extAuthz.includeRequestBody.packAsBytes | boolean | Whether to send the body as raw bytes for gRPC authorization checks. |
gateways.*.listeners[].extAuthz.cache | object | Cache authorization results using CEL expressions as the cache key. Warning: the safety of this feature depends on the cache key accurately capturing the fields the server operates on. For example, if you return a different result based on header A but only cache header B, users may get incorrect cache hits. |
gateways.*.listeners[].extAuthz.cache.key | []string | CEL expressions that make up the cache key. Empty keys are accepted, but do not produce cache hits. |
gateways.*.listeners[].extAuthz.cache.ttl | string | CEL expression that returns how long cached authorization results are reused. The expression is evaluated after the authorization response has been applied to the request, and must return either a duration or timestamp. |
gateways.*.listeners[].extAuthz.cache.maxEntries | integer | Maximum number of authorization results to keep in the cache. |
gateways.*.listeners[].extProc | object | Send request and response data to an external processing service. |
gateways.*.listeners[].extProc.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.listeners[].extProc.conditional[].service | object | Service reference. Service must be defined in the top level |
gateways.*.listeners[].extProc.conditional[].host | string | Hostname or IP address |
gateways.*.listeners[].extProc.conditional[].backend | string | Explicit backend reference. Backend must be defined in the top level |
| `gateways.*.listeners[].extProc.conditional[] | `gateways.*.listeners[].extProc.conditional[] | `gateways.*.listeners[].extProc.conditional[] |
gateways.*.listeners[].extProc.conditional[].metadataContext | object | Additional metadata to send to the external processing service. Maps to the metadata_context.filter_metadata field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.conditional[].requestAttributes | object | Maps to the request attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.conditional[].responseAttributes | object | Maps to the response attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.conditional[].processingOptions | object | Controls which request and response parts are sent to the external processing service. |
gateways.*.listeners[].extProc.conditional[].processingOptions.requestBodyMode | enum | How request bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.listeners[].extProc.conditional[].processingOptions.responseBodyMode | enum | How response bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.listeners[].extProc.conditional[].processingOptions.requestHeaderMode | enum | Whether request headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.conditional[].processingOptions.responseHeaderMode | enum | Whether response headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.conditional[].processingOptions.requestTrailerMode | enum | Whether request trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.conditional[].processingOptions.responseTrailerMode | enum | Whether response trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.conditional[].processingOptions.allowModeOverride | boolean | Whether the external processing service can change processing modes during a request. |
gateways.*.listeners[].extProc.service | object | Service reference. Service must be defined in the top level |
gateways.*.listeners[].extProc.host | string | Hostname or IP address |
gateways.*.listeners[].extProc.backend | string | Explicit backend reference. Backend must be defined in the top level |
gateways.*.listeners[].extProc.metadataContext | object | Additional metadata to send to the external processing service. Maps to the metadata_context.filter_metadata field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.requestAttributes | object | Maps to the request attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.responseAttributes | object | Maps to the response attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.listeners[].extProc.processingOptions | object | Controls which request and response parts are sent to the external processing service. |
gateways.*.listeners[].extProc.processingOptions.requestBodyMode | enum | How request bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.listeners[].extProc.processingOptions.responseBodyMode | enum | How response bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.listeners[].extProc.processingOptions.requestHeaderMode | enum | Whether request headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.processingOptions.responseHeaderMode | enum | Whether response headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.processingOptions.requestTrailerMode | enum | Whether request trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.processingOptions.responseTrailerMode | enum | Whether response trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.listeners[].extProc.processingOptions.allowModeOverride | boolean | Whether the external processing service can change processing modes during a request. |
gateways.*.listeners[].cors | object | Handle CORS preflight requests and append configured CORS headers to applicable requests. |
gateways.*.listeners[].cors.allowCredentials | boolean | Add Access-Control-Allow-Credentials: true on allowed CORS responses. |
gateways.*.listeners[].cors.allowHeaders | []string | Values to return in Access-Control-Allow-Headers for allowed preflight requests. |
gateways.*.listeners[].cors.allowMethods | []string | Values to return in Access-Control-Allow-Methods for allowed preflight requests. |
gateways.*.listeners[].cors.allowOrigins | []string | Request origins that receive CORS response headers. Use * to match any origin. |
gateways.*.listeners[].cors.exposeHeaders | []string | Values to return in Access-Control-Expose-Headers for allowed CORS responses. |
gateways.*.listeners[].cors.maxAge | string | Value to return in Access-Control-Max-Age for allowed preflight requests. |
gateways.*.listeners[].transformations | object | Modify request and response headers, bodies, or metadata. |
gateways.*.listeners[].transformations.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.listeners[].transformations.conditional[].condition | string | condition must evaluate to true for this policy to execute. If unset, the policy is the fallback. |
gateways.*.listeners[].transformations.conditional[].request | object | Transform the request before it is forwarded. |
gateways.*.listeners[].transformations.conditional[].request.add | object | Headers to append using CEL expressions for values. |
gateways.*.listeners[].transformations.conditional[].request.set | object | Headers to set using CEL expressions for values. |
gateways.*.listeners[].transformations.conditional[].request.remove | []string | Header names to remove. |
gateways.*.listeners[].transformations.conditional[].request.body | string | CEL expression that computes a replacement body. |
gateways.*.listeners[].transformations.conditional[].request.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.listeners[].transformations.conditional[].response | object | Transform the response before it is returned. |
gateways.*.listeners[].transformations.conditional[].response.add | object | Headers to append using CEL expressions for values. |
gateways.*.listeners[].transformations.conditional[].response.set | object | Headers to set using CEL expressions for values. |
gateways.*.listeners[].transformations.conditional[].response.remove | []string | Header names to remove. |
gateways.*.listeners[].transformations.conditional[].response.body | string | CEL expression that computes a replacement body. |
gateways.*.listeners[].transformations.conditional[].response.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.listeners[].transformations.request | object | Transform the request before it is forwarded. |
gateways.*.listeners[].transformations.request.add | object | Headers to append using CEL expressions for values. |
gateways.*.listeners[].transformations.request.set | object | Headers to set using CEL expressions for values. |
gateways.*.listeners[].transformations.request.remove | []string | Header names to remove. |
gateways.*.listeners[].transformations.request.body | string | CEL expression that computes a replacement body. |
gateways.*.listeners[].transformations.request.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.listeners[].transformations.response | object | Transform the response before it is returned. |
gateways.*.listeners[].transformations.response.add | object | Headers to append using CEL expressions for values. |
gateways.*.listeners[].transformations.response.set | object | Headers to set using CEL expressions for values. |
gateways.*.listeners[].transformations.response.remove | []string | Header names to remove. |
gateways.*.listeners[].transformations.response.body | string | CEL expression that computes a replacement body. |
gateways.*.listeners[].transformations.response.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.listeners[].basicAuth | object | Authenticate incoming requests with Basic Auth credentials from an htpasswd user database. |
gateways.*.listeners[].basicAuth.htpasswd | object | User database in htpasswd format. Can be inline or loaded from a file. |
gateways.*.listeners[].basicAuth.htpasswd.file | string | Path to a file on disk to load the value from. |
gateways.*.listeners[].basicAuth.realm | string | Realm shown in the WWW-Authenticate response header when credentials are missing or invalid. |
gateways.*.listeners[].basicAuth.mode | enum | Controls whether requests must include valid Basic Auth credentials. Possible values: strict, optional. |
gateways.*.listeners[].basicAuth.authorizationLocation | object | Where to read the Basic Auth credentials from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.listeners[].basicAuth.authorizationLocation.header | object | Read the credential from an HTTP header. |
gateways.*.listeners[].basicAuth.authorizationLocation.header.name | string | Header name containing the credential. |
gateways.*.listeners[].basicAuth.authorizationLocation.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.listeners[].basicAuth.authorizationLocation.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.listeners[].basicAuth.authorizationLocation.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.listeners[].basicAuth.authorizationLocation.cookie | object | Read the credential from a request cookie. |
gateways.*.listeners[].basicAuth.authorizationLocation.cookie.name | string | Cookie name containing the credential. |
gateways.*.listeners[].basicAuth.authorizationLocation.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
gateways.*.listeners[].apiKey | object | Authenticate incoming requests with API keys. |
gateways.*.listeners[].apiKey.keys | []object | API keys that are accepted by this policy. |
gateways.*.listeners[].apiKey.keys[].key | string | API key value to accept. |
gateways.*.listeners[].apiKey.keys[].metadata | any | Optional metadata attached to requests authenticated with this key. |
gateways.*.listeners[].apiKey.keys[].keyHash | string | SHA-256 hash of an API key value to accept, in sha256:<hex> format. |
gateways.*.listeners[].apiKey.mode | enum | Controls whether requests must include a valid API key. Possible values: strict, optional, permissive. |
gateways.*.listeners[].apiKey.location | object | Where to read the API key from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.listeners[].apiKey.location.header | object | Read the credential from an HTTP header. |
gateways.*.listeners[].apiKey.location.header.name | string | Header name containing the credential. |
gateways.*.listeners[].apiKey.location.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.listeners[].apiKey.location.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.listeners[].apiKey.location.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.listeners[].apiKey.location.cookie | object | Read the credential from a request cookie. |
gateways.*.listeners[].apiKey.location.cookie.name | string | Cookie name containing the credential. |
gateways.*.listeners[].apiKey.location.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
gateways.*.tls | object | tls enables HTTPS for this gateway. Maybe not be set with listeners |
gateways.*.tls.mode | enum | Certificate source mode. Static mode uses cert/key as the leaf certificate; dynamic CA mode uses cert/key as a CA for on-demand SNI leaf certificate issuance. Possible values: static, dynamicCa. |
gateways.*.tls.cert | string | Path to the TLS certificate file (leaf certificate, or CA certificate in dynamic CA mode). |
gateways.*.tls.key | string | Path to the TLS private key file. |
gateways.*.tls.root | string | Path to a root CA certificate file used to validate client certificates. |
gateways.*.tls.cipherSuites | []string | Optional cipher suite allowlist (order is preserved). |
gateways.*.tls.minTLSVersion | enum | Minimum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.tls.minTlsVersion | enum | Minimum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.tls.maxTLSVersion | enum | Maximum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.tls.maxTlsVersion | enum | Maximum supported TLS version (only TLS 1.2 and 1.3 are supported). Possible values: TLS_V1_0, TLS_V1_1, TLS_V1_2, TLS_V1_3, null. |
gateways.*.tls.keyExchangeGroups | []string | Key exchange groups allowed for negotiating TLS. |
gateways.*.oidc | object | Authenticate browser requests with OIDC authorization code flow. |
gateways.*.oidc.issuer | string | Issuer used for discovery and ID token validation. |
gateways.*.oidc.discovery | object | Optional discovery document override. If omitted, discovery uses${issuer}/.well-known/openid-configuration. |
gateways.*.oidc.discovery.file | string | Path to a file on disk to load the value from. |
gateways.*.oidc.discovery.url | string | |
gateways.*.oidc.authorizationEndpoint | string | Authorization endpoint used to start the browser login flow. |
gateways.*.oidc.tokenEndpoint | string | Token endpoint used to exchange the authorization code. |
gateways.*.oidc.tokenEndpointAuth | enum | Token endpoint client authentication method for explicit provider configuration. Discovery mode derives this from provider metadata. Explicit mode defaults to clientSecretBasic when omitted.Possible values: clientSecretBasic, clientSecretPost, null. |
gateways.*.oidc.jwks | object | JWKS source used to validate returned ID tokens. |
gateways.*.oidc.jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.oidc.jwks.url | string | |
gateways.*.oidc.clientId | string | OAuth2 client identifier used for authorization and token exchange. |
gateways.*.oidc.clientSecret | string | OAuth2 client secret used for token exchange. |
gateways.*.oidc.redirectURI | string | Absolute callback URI handled by the gateway. This policy always redirects unauthenticated non-callback requests back through this login flow. |
gateways.*.oidc.scopes | []string | Additional OAuth2 scopes to request. openid is always included. |
gateways.*.jwtAuth | object | Authenticate incoming requests with JWT bearer tokens. |
gateways.*.jwtAuth.mode | enum | Controls whether requests must include a JWT and how validation failures are handled. Possible values: strict, optional, permissive. |
gateways.*.jwtAuth.location | object | Where to read the JWT from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.jwtAuth.location.header | object | Read the credential from an HTTP header. |
gateways.*.jwtAuth.location.header.name | string | Header name containing the credential. |
gateways.*.jwtAuth.location.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.jwtAuth.location.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.jwtAuth.location.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.jwtAuth.location.cookie | object | Read the credential from a request cookie. |
gateways.*.jwtAuth.location.cookie.name | string | Cookie name containing the credential. |
gateways.*.jwtAuth.location.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
gateways.*.jwtAuth.providers | []object | Trusted issuers and their signing keys. |
gateways.*.jwtAuth.providers[].issuer | string | Expected token issuer, matched against the JWT iss claim. |
gateways.*.jwtAuth.providers[].audiences | []string | Accepted token audiences, matched against the JWT aud claim when set. |
gateways.*.jwtAuth.providers[].jwks | object | JSON Web Key Set used to verify token signatures. Can be inline, from a file, or fetched remotely. |
gateways.*.jwtAuth.providers[].jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.jwtAuth.providers[].jwks.url | string | |
gateways.*.jwtAuth.providers[].jwtValidationOptions | object | Claim requirements to enforce after the token signature is verified. |
gateways.*.jwtAuth.providers[].jwtValidationOptions.requiredClaims | []string | Claims that must be present in the token before validation. Only “exp”, “nbf”, “aud”, “iss”, “sub” are enforced; others (including “iat” and “jti”) are ignored. Defaults to [“exp”]. Use an empty list to require no claims. |
gateways.*.jwtAuth.issuer | string | Expected token issuer, matched against the JWT iss claim. |
gateways.*.jwtAuth.audiences | []string | Accepted token audiences, matched against the JWT aud claim when set. |
gateways.*.jwtAuth.jwks | object | JSON Web Key Set used to verify token signatures. Can be inline, from a file, or fetched remotely. |
gateways.*.jwtAuth.jwks.file | string | Path to a file on disk to load the value from. |
gateways.*.jwtAuth.jwks.url | string | |
gateways.*.jwtAuth.jwtValidationOptions | object | Claim requirements to enforce after the token signature is verified. |
gateways.*.jwtAuth.jwtValidationOptions.requiredClaims | []string | Claims that must be present in the token before validation. Only “exp”, “nbf”, “aud”, “iss”, “sub” are enforced; others (including “iat” and “jti”) are ignored. Defaults to [“exp”]. Use an empty list to require no claims. |
gateways.*.authorization | object | Authorization rules for incoming HTTP requests. |
gateways.*.authorization.rules | []object | CEL authorization rules to evaluate for a request. |
gateways.*.authorization.rules[].allow | string | Allow the request when this CEL expression is true. |
gateways.*.authorization.rules[].deny | string | Deny the request when this CEL expression is true. |
gateways.*.authorization.rules[].require | string | Require this CEL expression to be true. |
gateways.*.extAuthz | object | Authorize incoming requests by calling an external authorization service. |
gateways.*.extAuthz.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.extAuthz.conditional[].service | object | Service reference. Service must be defined in the top level |
gateways.*.extAuthz.conditional[].host | string | Hostname or IP address |
gateways.*.extAuthz.conditional[].backend | string | Explicit backend reference. Backend must be defined in the top level |
| `gateways.*.extAuthz.conditional[] | `gateways.*.extAuthz.conditional[] | `gateways.*.extAuthz.conditional[] |
gateways.*.extAuthz.conditional[].protocol.grpc | object | Call the authorization service using the gRPC authorization protocol. |
gateways.*.extAuthz.conditional[].protocol.grpc.context | object | Static context values to send to the authorization service. Maps to the context_extensions field in the request. |
gateways.*.extAuthz.conditional[].protocol.grpc.metadata | object | Metadata values to send to the authorization service, computed from CEL expressions. Maps to the metadata_context.filter_metadata field in the request.If unset, envoy.filters.http.jwt_authn is set when JWT auth is also used, for compatibility. |
gateways.*.extAuthz.conditional[].protocol.http | object | Call the authorization service using HTTP. |
gateways.*.extAuthz.conditional[].protocol.http.path | string | CEL expression that computes the authorization request path. |
gateways.*.extAuthz.conditional[].protocol.http.redirect | string | CEL expression that computes a redirect URL when authorization fails. When the authorization service returns unauthorized, this redirects instead of returning the error directly. |
gateways.*.extAuthz.conditional[].protocol.http.body | string | CEL expression that computes the authorization request body. Strings and bytes are used directly; other values are JSON-encoded. If set, this replaces forwarding the incoming request body. |
gateways.*.extAuthz.conditional[].protocol.http.includeResponseHeaders | []string | Authorization response headers to copy into the backend request. |
gateways.*.extAuthz.conditional[].protocol.http.addRequestHeaders | object | Headers to add to the authorization request using CEL expressions. Empty means all headers. |
gateways.*.extAuthz.conditional[].protocol.http.metadata | object | Metadata values to expose under the extauthz variable after authorization. |
gateways.*.extAuthz.conditional[].failureMode | object | Behavior when the authorization service is unavailable or returns an error. |
gateways.*.extAuthz.conditional[].failureMode.denyWithStatus | integer | Deny the request with the configured HTTP status code. |
gateways.*.extAuthz.conditional[].includeRequestHeaders | []string | Request headers to send to the authorization service. If unset, gRPC sends all request headers and HTTP sends only Authorization. |
gateways.*.extAuthz.conditional[].includeRequestBody | object | Options for sending the request body to the authorization service. |
gateways.*.extAuthz.conditional[].includeRequestBody.maxRequestBytes | integer | Maximum request body size to send to the authorization service. Defaults to 8192 bytes. |
gateways.*.extAuthz.conditional[].includeRequestBody.allowPartialMessage | boolean | Whether to send a partial body when the request exceeds maxRequestBytes. |
gateways.*.extAuthz.conditional[].includeRequestBody.packAsBytes | boolean | Whether to send the body as raw bytes for gRPC authorization checks. |
gateways.*.extAuthz.conditional[].cache | object | Cache authorization results using CEL expressions as the cache key. Warning: the safety of this feature depends on the cache key accurately capturing the fields the server operates on. For example, if you return a different result based on header A but only cache header B, users may get incorrect cache hits. |
gateways.*.extAuthz.conditional[].cache.key | []string | CEL expressions that make up the cache key. Empty keys are accepted, but do not produce cache hits. |
gateways.*.extAuthz.conditional[].cache.ttl | string | CEL expression that returns how long cached authorization results are reused. The expression is evaluated after the authorization response has been applied to the request, and must return either a duration or timestamp. |
gateways.*.extAuthz.conditional[].cache.maxEntries | integer | Maximum number of authorization results to keep in the cache. |
gateways.*.extAuthz.service | object | Service reference. Service must be defined in the top level |
gateways.*.extAuthz.host | string | Hostname or IP address |
gateways.*.extAuthz.backend | string | Explicit backend reference. Backend must be defined in the top level |
gateways.*.extAuthz.protocol.grpc | object | Call the authorization service using the gRPC authorization protocol. |
gateways.*.extAuthz.protocol.grpc.context | object | Static context values to send to the authorization service. Maps to the context_extensions field in the request. |
gateways.*.extAuthz.protocol.grpc.metadata | object | Metadata values to send to the authorization service, computed from CEL expressions. Maps to the metadata_context.filter_metadata field in the request.If unset, envoy.filters.http.jwt_authn is set when JWT auth is also used, for compatibility. |
gateways.*.extAuthz.protocol.http | object | Call the authorization service using HTTP. |
gateways.*.extAuthz.protocol.http.path | string | CEL expression that computes the authorization request path. |
gateways.*.extAuthz.protocol.http.redirect | string | CEL expression that computes a redirect URL when authorization fails. When the authorization service returns unauthorized, this redirects instead of returning the error directly. |
gateways.*.extAuthz.protocol.http.body | string | CEL expression that computes the authorization request body. Strings and bytes are used directly; other values are JSON-encoded. If set, this replaces forwarding the incoming request body. |
gateways.*.extAuthz.protocol.http.includeResponseHeaders | []string | Authorization response headers to copy into the backend request. |
gateways.*.extAuthz.protocol.http.addRequestHeaders | object | Headers to add to the authorization request using CEL expressions. Empty means all headers. |
gateways.*.extAuthz.protocol.http.metadata | object | Metadata values to expose under the extauthz variable after authorization. |
gateways.*.extAuthz.failureMode | object | Behavior when the authorization service is unavailable or returns an error. |
gateways.*.extAuthz.failureMode.denyWithStatus | integer | Deny the request with the configured HTTP status code. |
gateways.*.extAuthz.includeRequestHeaders | []string | Request headers to send to the authorization service. If unset, gRPC sends all request headers and HTTP sends only Authorization. |
gateways.*.extAuthz.includeRequestBody | object | Options for sending the request body to the authorization service. |
gateways.*.extAuthz.includeRequestBody.maxRequestBytes | integer | Maximum request body size to send to the authorization service. Defaults to 8192 bytes. |
gateways.*.extAuthz.includeRequestBody.allowPartialMessage | boolean | Whether to send a partial body when the request exceeds maxRequestBytes. |
gateways.*.extAuthz.includeRequestBody.packAsBytes | boolean | Whether to send the body as raw bytes for gRPC authorization checks. |
gateways.*.extAuthz.cache | object | Cache authorization results using CEL expressions as the cache key. Warning: the safety of this feature depends on the cache key accurately capturing the fields the server operates on. For example, if you return a different result based on header A but only cache header B, users may get incorrect cache hits. |
gateways.*.extAuthz.cache.key | []string | CEL expressions that make up the cache key. Empty keys are accepted, but do not produce cache hits. |
gateways.*.extAuthz.cache.ttl | string | CEL expression that returns how long cached authorization results are reused. The expression is evaluated after the authorization response has been applied to the request, and must return either a duration or timestamp. |
gateways.*.extAuthz.cache.maxEntries | integer | Maximum number of authorization results to keep in the cache. |
gateways.*.extProc | object | Send request and response data to an external processing service. |
gateways.*.extProc.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.extProc.conditional[].service | object | Service reference. Service must be defined in the top level |
gateways.*.extProc.conditional[].host | string | Hostname or IP address |
gateways.*.extProc.conditional[].backend | string | Explicit backend reference. Backend must be defined in the top level |
| `gateways.*.extProc.conditional[] | `gateways.*.extProc.conditional[] | `gateways.*.extProc.conditional[] |
gateways.*.extProc.conditional[].metadataContext | object | Additional metadata to send to the external processing service. Maps to the metadata_context.filter_metadata field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.conditional[].requestAttributes | object | Maps to the request attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.conditional[].responseAttributes | object | Maps to the response attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.conditional[].processingOptions | object | Controls which request and response parts are sent to the external processing service. |
gateways.*.extProc.conditional[].processingOptions.requestBodyMode | enum | How request bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.extProc.conditional[].processingOptions.responseBodyMode | enum | How response bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.extProc.conditional[].processingOptions.requestHeaderMode | enum | Whether request headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.conditional[].processingOptions.responseHeaderMode | enum | Whether response headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.conditional[].processingOptions.requestTrailerMode | enum | Whether request trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.conditional[].processingOptions.responseTrailerMode | enum | Whether response trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.conditional[].processingOptions.allowModeOverride | boolean | Whether the external processing service can change processing modes during a request. |
gateways.*.extProc.service | object | Service reference. Service must be defined in the top level |
gateways.*.extProc.host | string | Hostname or IP address |
gateways.*.extProc.backend | string | Explicit backend reference. Backend must be defined in the top level |
gateways.*.extProc.metadataContext | object | Additional metadata to send to the external processing service. Maps to the metadata_context.filter_metadata field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.requestAttributes | object | Maps to the request attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.responseAttributes | object | Maps to the response attributes field in ProcessingRequest, and allows dynamic CEL expressions. |
gateways.*.extProc.processingOptions | object | Controls which request and response parts are sent to the external processing service. |
gateways.*.extProc.processingOptions.requestBodyMode | enum | How request bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.extProc.processingOptions.responseBodyMode | enum | How response bodies are sent to the external processing service. Possible values: none, buffered, bufferedPartial, fullDuplexStreamed. |
gateways.*.extProc.processingOptions.requestHeaderMode | enum | Whether request headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.processingOptions.responseHeaderMode | enum | Whether response headers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.processingOptions.requestTrailerMode | enum | Whether request trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.processingOptions.responseTrailerMode | enum | Whether response trailers are sent to the external processing service. Possible values: send, skip. |
gateways.*.extProc.processingOptions.allowModeOverride | boolean | Whether the external processing service can change processing modes during a request. |
gateways.*.cors | object | Handle CORS preflight requests and append configured CORS headers to applicable requests. |
gateways.*.cors.allowCredentials | boolean | Add Access-Control-Allow-Credentials: true on allowed CORS responses. |
gateways.*.cors.allowHeaders | []string | Values to return in Access-Control-Allow-Headers for allowed preflight requests. |
gateways.*.cors.allowMethods | []string | Values to return in Access-Control-Allow-Methods for allowed preflight requests. |
gateways.*.cors.allowOrigins | []string | Request origins that receive CORS response headers. Use * to match any origin. |
gateways.*.cors.exposeHeaders | []string | Values to return in Access-Control-Expose-Headers for allowed CORS responses. |
gateways.*.cors.maxAge | string | Value to return in Access-Control-Max-Age for allowed preflight requests. |
gateways.*.transformations | object | Modify request and response headers, bodies, or metadata. |
gateways.*.transformations.conditional | []object | conditional policy entries. An entry without a condition must be the final fallback. |
gateways.*.transformations.conditional[].condition | string | condition must evaluate to true for this policy to execute. If unset, the policy is the fallback. |
gateways.*.transformations.conditional[].request | object | Transform the request before it is forwarded. |
gateways.*.transformations.conditional[].request.add | object | Headers to append using CEL expressions for values. |
gateways.*.transformations.conditional[].request.set | object | Headers to set using CEL expressions for values. |
gateways.*.transformations.conditional[].request.remove | []string | Header names to remove. |
gateways.*.transformations.conditional[].request.body | string | CEL expression that computes a replacement body. |
gateways.*.transformations.conditional[].request.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.transformations.conditional[].response | object | Transform the response before it is returned. |
gateways.*.transformations.conditional[].response.add | object | Headers to append using CEL expressions for values. |
gateways.*.transformations.conditional[].response.set | object | Headers to set using CEL expressions for values. |
gateways.*.transformations.conditional[].response.remove | []string | Header names to remove. |
gateways.*.transformations.conditional[].response.body | string | CEL expression that computes a replacement body. |
gateways.*.transformations.conditional[].response.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.transformations.request | object | Transform the request before it is forwarded. |
gateways.*.transformations.request.add | object | Headers to append using CEL expressions for values. |
gateways.*.transformations.request.set | object | Headers to set using CEL expressions for values. |
gateways.*.transformations.request.remove | []string | Header names to remove. |
gateways.*.transformations.request.body | string | CEL expression that computes a replacement body. |
gateways.*.transformations.request.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.transformations.response | object | Transform the response before it is returned. |
gateways.*.transformations.response.add | object | Headers to append using CEL expressions for values. |
gateways.*.transformations.response.set | object | Headers to set using CEL expressions for values. |
gateways.*.transformations.response.remove | []string | Header names to remove. |
gateways.*.transformations.response.body | string | CEL expression that computes a replacement body. |
gateways.*.transformations.response.metadata | object | Metadata values to add using CEL expressions. |
gateways.*.basicAuth | object | Authenticate incoming requests with Basic Auth credentials from an htpasswd user database. |
gateways.*.basicAuth.htpasswd | object | User database in htpasswd format. Can be inline or loaded from a file. |
gateways.*.basicAuth.htpasswd.file | string | Path to a file on disk to load the value from. |
gateways.*.basicAuth.realm | string | Realm shown in the WWW-Authenticate response header when credentials are missing or invalid. |
gateways.*.basicAuth.mode | enum | Controls whether requests must include valid Basic Auth credentials. Possible values: strict, optional. |
gateways.*.basicAuth.authorizationLocation | object | Where to read the Basic Auth credentials from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.basicAuth.authorizationLocation.header | object | Read the credential from an HTTP header. |
gateways.*.basicAuth.authorizationLocation.header.name | string | Header name containing the credential. |
gateways.*.basicAuth.authorizationLocation.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.basicAuth.authorizationLocation.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.basicAuth.authorizationLocation.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.basicAuth.authorizationLocation.cookie | object | Read the credential from a request cookie. |
gateways.*.basicAuth.authorizationLocation.cookie.name | string | Cookie name containing the credential. |
gateways.*.basicAuth.authorizationLocation.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
gateways.*.apiKey | object | Authenticate incoming requests with API keys. |
gateways.*.apiKey.keys | []object | API keys that are accepted by this policy. |
gateways.*.apiKey.keys[].key | string | API key value to accept. |
gateways.*.apiKey.keys[].metadata | any | Optional metadata attached to requests authenticated with this key. |
gateways.*.apiKey.keys[].keyHash | string | SHA-256 hash of an API key value to accept, in sha256:<hex> format. |
gateways.*.apiKey.mode | enum | Controls whether requests must include a valid API key. Possible values: strict, optional, permissive. |
gateways.*.apiKey.location | object | Where to read the API key from in incoming requests. Exactly one of header, queryParameter, cookie, or expression may be set. |
gateways.*.apiKey.location.header | object | Read the credential from an HTTP header. |
gateways.*.apiKey.location.header.name | string | Header name containing the credential. |
gateways.*.apiKey.location.header.prefix | string | Prefix to remove from the header value before validation, such as Bearer or Basic . |
gateways.*.apiKey.location.queryParameter | object | Read the credential from a URL query parameter. |
gateways.*.apiKey.location.queryParameter.name | string | Query parameter name containing the credential. |
gateways.*.apiKey.location.cookie | object | Read the credential from a request cookie. |
gateways.*.apiKey.location.cookie.name | string | Cookie name containing the credential. |
gateways.*.apiKey.location.expression | string | Read the credential from a CEL expression evaluated against the incoming request. CEL expression that returns the credential string. This location can extract credentials but cannot insert them. |
routes | []object | routes defines HTTP routes attached to one or more named gateways. |
routes[].gateways | string | gateways attaches this route to named gateways or gateway listeners. This can take the form of <gateway-name> or <gateway-name>/<listener-name> to attach to a specific listener within a gateway.If unset, the ‘default’ gateway will be used. |
routes[].name | string | Name identifying this route. |
routes[].namespace | string | Namespace scoping this route. |
routes[].ruleName | string | Specific rule within this route. |
routes[].hostnames | []string | Can be a wildcard |
routes[].matches | []object | Conditions (path, method, headers, query) that select this route. |
routes[].matches[].headers | []object | HTTP headers that must match for this route to apply. |
routes[].matches[].headers[].name | string | HTTP header or pseudo-header name (such as :method) to match. |
routes[].matches[].headers[].value | object | Exact or regex pattern the header value must match. Exactly one of exact or regex may be set. |
routes[].matches[].headers[].value.exact | string | |
routes[].matches[].headers[].value.regex | string | |
routes[].matches[].path | object | Path match rule (exact, prefix, or regex). Defaults to a “/” prefix match. Exactly one of exact, pathPrefix, or regex may be set. |
routes[].matches[].path.exact | string | |
routes[].matches[].path.pathPrefix | string | |
routes[].matches[].path.regex | string | |
routes[].matches[].method | string | HTTP method that must match for this route to apply. |
routes[].matches[].query | []object | Query parameters that must match for this route to apply. |
routes[].matches[].query[].name | string | Query parameter name to match. |
routes[].matches[].query[].value | object | Exact or regex pattern the query parameter value must match. Exactly one of exact or regex may be set. |
routes[].matches[].query[].value.exact | string | |
routes[].matches[].query[].value.regex | string | |
| `routes[] | `routes[] | `routes[] |
tcpRoutes[].gateways | string | gateways attaches this route to named TCP/TLS gateways or gateway listeners. This can take the form of <gateway-name> or <gateway-name>/<listener-name> to attach to a specific listener within a gateway.If unset, the ‘default’ gateway will be used. |
tcpRoutes[].name | string | Name identifying this route. |
tcpRoutes[].namespace | string | Namespace scoping this route. |
tcpRoutes[].ruleName | string | Specific rule within this route. |
tcpRoutes[].hostnames | []string | Can be a wildcard |
| `tcpRoutes[] | `tcpRoutes[] | `tcpRoutes[] |
| `ui | `ui | `ui |
Was this page helpful?
