diff --git a/VERSION b/VERSION index 828fcfc8b1..804a616da1 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -v1.8.0-rc.1 +v1.8.0 diff --git a/release-notes/current.yaml b/release-notes/current.yaml index 5c2c6edd30..3271a4f907 100644 --- a/release-notes/current.yaml +++ b/release-notes/current.yaml @@ -2,7 +2,6 @@ date: Pending # Changes that are expected to cause an incompatibility with previous versions, such as deletions or modifications to existing APIs. breaking changes: | - Merged SecurityPolicy IR/xDS resource names (OIDC, BasicAuth, ExtAuth, JWT) now derive from the policy that contributes the field (parent or route) rather than always using the route-level policy. EnvoyPatchPolicy users who reference those generated names must update their patch targets. # Updates addressing vulnerabilities, security flaws, or compliance requirements. security updates: | @@ -11,23 +10,12 @@ security updates: | new features: | bug fixes: | - Fixed SecurityPolicy merge using the wrong policy as the owner for resource references and IR generation. - Fixed ListenerSet and its listeners incorrectly setting `Accepted: False` for InvalidCertificateRef and RefNotPermitted, inconsistent with Gateway behavior and the Gateway API spec. - Fixed active HTTP health checks to use Backend endpoint hostnames before falling back to the effective Route hostname. - Fixed HTTPS listeners with overlapping hostnames but disjoint certificate SANs to preserve HTTP/2 ALPN by default. - Fixed Gateway getting stuck at `Programmed=False` after its LoadBalancer Service IP was restored, by ignoring `LastTransitionTime` when comparing status conditions. # Enhancements that improve performance. performance improvements: | - Enabled deferred stat creation to reduce CPU and memory overhead by creating only the subset of metrics that are actually used at runtime, instead of eagerly initializing all possible stats. More information can be found in the Envoy deferred stat creation [documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#config-bootstrap-v3-bootstrap-deferredstatoptions). # Deprecated features or APIs. deprecations: | # Other notable changes not covered by the above sections. Other changes: | - Moved Envoy Gateway CRDs into a sub-chart to avoid the Helm release secret exceeding the 1MB size limit when adding new API fields. Upgrade/Install behavior is unchanged for users. - The maximum number of rules in a RateLimit policy is increased from 128 to 256. - The maximum number of JWT providers allowed in `SecurityPolicy.spec.jwt.providers` is increased from 4 to 16. - Added `runner_event_total` metric to track update and delete events in infrastructure and gateway API runners for improved observability. - Added common Helm labels to Envoy Gateway RBAC resources. diff --git a/release-notes/v1.8.0.yaml b/release-notes/v1.8.0.yaml new file mode 100644 index 0000000000..76f024062e --- /dev/null +++ b/release-notes/v1.8.0.yaml @@ -0,0 +1,113 @@ +date: May 12, 2026 + +# Changes that are expected to cause an incompatibility with previous versions, such as deletions or modifications to existing APIs. +breaking changes: | + The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. Existing configurations including the template syntax (%) will be interpolated. + The `0s` timeout in SecurityPolicy is now treated as infinite timeout instead of immediate timeout. + Fixed EnvoyProxy `samplingFraction` translation to correctly convert the Gateway API fraction into Envoy's percentage-based `random_sampling` field. Existing `samplingFraction` configurations will now sample 100x more frequently than in previous releases; divide previous values by 100 to preserve prior sampling rates. + The controller now uses production logging encoder config by default, which provides better output when using JSON encoder. + SecurityPolicy OIDC now generates a single native `envoy.filters.http.oauth2` HTTP filter in the HCM filter chain and moves route-specific OAuth2 configuration to route `typed_per_filter_config`. This can break existing EnvoyPatchPolicies and extension managers that depend on the previous per-route OAuth2 filter instances or on the old OAuth2 filter configuration shape in the HCM filter chain. + Merged SecurityPolicy IR/xDS resource names (OIDC, BasicAuth, ExtAuth, JWT) now derive from the policy that contributes the field (parent or route) rather than always using the route-level policy. EnvoyPatchPolicy users who reference those generated names must update their patch targets. + +# Updates addressing vulnerabilities, security flaws, or compliance requirements. +security updates: | + +# New features or capabilities added in this release. +new features: | + Added support for optional active health check configuration. + Added support for shadow mode in local rate limiting. + Added support for MergeType in SecurityPolicy to enable route-level policies to merge with parent Gateway/Listener policies, similar to BackendTrafficPolicy. + Added `egctl config envoy-gateway` commands to retrieve Envoy Gateway admin config dumps. + The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. See https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators for more details. + Added HTTP/2 connection keepalive support to ClientTrafficPolicy and BackendTrafficPolicy. + Added RoutingType field for BackendTrafficPolicy. + Added support for configuring weights for locality zones. + Added support for gRPC-Web settings in ClientTrafficPolicy. + Added support for Envoy Dynamic Modules. + Added support for weight in BackendRef API to enable traffic splitting for non-x-route resources. + Added support for removing headers based on matching criteria (Exact, Prefix, Suffix, RegularExpression) in ClientTrafficPolicy EarlyRequestHeaders and LateResponseHeaders. + Added support for priorityClassName in KubernetesPodSpec for Envoy Proxy pods. + Added support for Global rate limit shadow mode. + Added support for specifying both text (body) and attributes in access log format by making the type field optional. + Set warning status condition for deprecated fields in xPolicy CRDs. + Added support for URLRewrite filter on individual backendRefs. + Added support for custom headers on OTLP exports (metrics, tracing, access logs). + Added support for custom TLS configuration when pulling WASM code via HTTP or OCI in EnvoyExtensionPolicy. + Added support for gRPC stats settings in EnvoyProxy. + Added the PostEndpointsModify extension hook, allowing extensions to modify EDS ClusterLoadAssignments generated by Envoy Gateway before they are sent to Envoy. + Added support for stream idle timeout in BackendTrafficPolicy. + Added `namespaceOverride` support to gateway-helm chart. + Added support for configuring statusOnError in ExtAuth settings. + Added support for GeoIP-based authorization on HTTPRoute and GRPCRoute via `SecurityPolicy.spec.authorization.rules[*].principal.clientIPGeoLocations`, backed by shared GeoIP provider settings in `EnvoyProxy.spec.geoIP`. + Added support for retry budget in BackendTrafficPolicy. + Added support for BackendUtilization load balancing policy in BackendTrafficPolicy. + Added support for upstream access logs via the `Upstream` access log type in EnvoyProxy. + Added support for invert match in CIDR match RateLimit API. + Added support for ignoring HTTP/1.1 Upgrade requests in ClientTrafficPolicy via `http1.ignoredUpgradeTypes`. + Added support for OpenTelemetry sampler configuration for tracing. + Added support for multiple ExtensionManagers with sequential chaining via a new `extensionManagers` field in `EnvoyGateway` configuration. + Added support for default EnvoyProxy settings on EnvoyGatewaySpec that can be overridden by GatewayClass or Gateway-level EnvoyProxy configurations. A new MergeType field allows choosing between Replace (default), StrategicMerge, or JSONMerge strategies for combining configurations. + Added support for sending Envoy Gateway route metadata to external authorization backends via `SecurityPolicy.spec.extAuth.includeRouteMetadata`. + Added support for cross-namespace policy attachment for ClientTrafficPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, and SecurityPolicy. + Added `source` field to `responseOverride` rules in BackendTrafficPolicy, allowing rules to target only Envoy-generated responses (`Local`), only upstream responses (`Backend`), or both (`All`, the default). This enables overriding Envoy responses (e.g. auth/rate-limit failures) without affecting legitimate upstream responses with the same status code. + Added support for path override in ExtAuth HTTP service. + Added support for bandwidth limiting in BackendTrafficPolicy. + Added support for defining Envoy Proxy image, pullPolicy, and pullSecrets via the helm chart. Note that to merge these helm-configured values with EnvoyProxy resources, the EnvoyProxy must include `mergeType: StrategicMerge` or `mergeType: JSONMerge`. + Added support for Envoy Admission Control to BackendTrafficPolicy, enabling client-side load shedding based on historical upstream success rates using Envoy's admission control filter. + +bug fixes: | + Fixed local rate limit rules with identical sourceCIDR client selectors producing conflicting descriptors. + Rejected ClientTrafficPolicy if invalid TLS cipher suites are configured. + Fixed ClientTrafficPolicy to disable HTTP/3 and surface a warning on the policy when downstream client TLS validation is configured, instead of generating a rejected QUIC listener. + Fixed validation of XListenerSet certificateRefs. + Fixed XListenerSet not allowing xRoutes from the same namespace when configured to allow them. + Fixed API key authentication dropping non-first client IDs when credential Secrets contain multiple keys. + Fixed `X-ENVOY-ORIGINAL-HOST` not being set when `headers.enableEnvoyHeaders` is enabled and hostname rewrite is configured for DynamicResolver type of Backends. + Fixed standalone mode emitting non-actionable error logs for missing secrets and unsupported ratelimit deletion on every startup. + Fixed local object reference resolution from parent policy in merged BackendTrafficPolicies. + Fixed xPolicy resources being processed from all namespaces when NamespaceSelector watch mode is configured in the Kubernetes provider. + Fixed route and policy status aggregation across multiple GatewayClasses managed by the same controller, so resources preserve status from all relevant parents and ancestors instead of being overwritten by the last processed GatewayClass. + Fixed route status parent aggregation when the number of parents exceeds the Gateway API cap of 32. + Made ConnectionLimit.Value optional so users can configure MaxConnectionDuration, MaxRequestsPerConnection, or MaxStreamDuration without setting a max connections value. + Fixed endpoint hostname not being respected during active health checks. + Fixed ratelimit deployment missing metrics container port (19001), which prevented PodMonitor/ServiceMonitor from targeting the metrics endpoint. + Fixed ratelimit ServiceAccount missing standard Kubernetes app labels. + Fixed GRPCRoute RequestMirror filter backend not being indexed, causing "service not found" errors for mirror targets that exist in the cluster. + Fixed GRPCRoute not detecting conflicting RequestMirror and DirectResponse filters, which caused the mirror to be silently dropped. + Fixed BackendTrafficPolicy `requestBuffer` coexisting with route upgrades by disabling the default WebSocket upgrade on buffered routes and rejecting explicit `requestBuffer` + `httpUpgrade` combinations. + Fixed per-endpoint hostname override not working due to the auto-generated wildcard hostname. + Fixed Basic Authentication failing when htpasswd secrets use CRLF line endings by normalizing to LF before passing to Envoy. + Fixed BackendTLSPolicy being ignored when configuring TLS for telemetry backends (access logs, tracing, metrics). + Fixed client certificate secret never being delivered when exclusively referenced by a SecurityPolicy `extAuth`/`jwt`/`oidc` Backend. + Fixed xRoutes being incorrectly marked unaccepted when a RequestMirror filter referenced a backend with no endpoints; the route now remains accepted with `BackendsAvailable=False`, per Gateway API conformance. + Fixed `ws` and `wss` Backend appProtocols to force HTTP/1.1 upstream connections instead of negotiating HTTP/2, avoiding compatibility issues with WebSocket backends that do not support RFC 8441 extended CONNECT. + Fixed gateway-helm RBAC in GatewayNamespace mode with explicit `watch.namespaces` list by adding controller-namespace secret read permissions to infra-manager. + Fixed a control plane panic caused by concurrent Status mutation racing with the watchable Map coalesce goroutine. + Fixed BackendTrafficPolicy rate limit `requests` values above uint32 max (4294967295) being silently truncated modulo 2^32 by the rate limit service and Envoy token bucket. The field now rejects such values at admission time with a clear schema validation error. + Fixed status conditions not being updated when a route is rejected due to multiple errors. + Fixed spurious development-mode panic log from the gatewayapi translator. + Fixed SecurityPolicy merge using the wrong policy as the owner for resource references and IR generation. + Fixed ListenerSet and its listeners incorrectly setting `Accepted: False` for InvalidCertificateRef and RefNotPermitted, inconsistent with Gateway behavior and the Gateway API spec. + Fixed active HTTP health checks to use Backend endpoint hostnames before falling back to the effective Route hostname. + Fixed HTTPS listeners with overlapping hostnames but disjoint certificate SANs to preserve HTTP/2 ALPN by default. + Removed the spurious cross-namespace policy-attachment warning condition when a ReferenceGrant is missing (#8901). + Fixed an invalid first listener winning hostname/protocol precedence and causing a later valid listener on the same hostname/port to be marked HostnameConflict (#8577). + Increased `RateLimitSelectCondition.headers` MaxItems from 16 to 64, matching the existing `HTTPHeaderFilter` pattern (#8906). + Fixed Gateway getting stuck at `Programmed=False` after its LoadBalancer Service IP was restored, by ignoring `LastTransitionTime` when comparing status conditions. + +# Enhancements that improve performance. +performance improvements: | + Reduced chances of listener drain due to Lua policy updates by migrating to LuaPerRoute. + Reduced Kubernetes API server calls by reusing the cached controller-runtime client from the controller manager for infrastructure reconciliation. In GatewayNamespaceMode, this may slightly increase memory usage due to keeping the infrastructure resources in the cache. + Enabled deferred stat creation to reduce CPU and memory overhead by creating only the subset of metrics that are actually used at runtime, instead of eagerly initializing all possible stats. More information can be found in the Envoy deferred stat creation [documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#config-bootstrap-v3-bootstrap-deferredstatoptions). + +# Deprecated features or APIs. +deprecations: | + +# Other notable changes not covered by the above sections. +Other changes: | + Moved Envoy Gateway CRDs into a sub-chart to avoid the Helm release secret exceeding the 1MB size limit when adding new API fields. Upgrade/Install behavior is unchanged for users. + The maximum number of rules in a RateLimit policy is increased from 128 to 256. + The maximum number of JWT providers allowed in `SecurityPolicy.spec.jwt.providers` is increased from 4 to 16. + Added `runner_event_total` metric to track update and delete events in infrastructure and gateway API runners for improved observability. + Added common Helm labels to Envoy Gateway RBAC resources. diff --git a/site/content/en/latest/api/gateway_api/backendtlspolicy.md b/site/content/en/latest/api/gateway_api/backendtlspolicy.md index 41e95a416d..ee4c07f2ff 100644 --- a/site/content/en/latest/api/gateway_api/backendtlspolicy.md +++ b/site/content/en/latest/api/gateway_api/backendtlspolicy.md @@ -11,7 +11,7 @@ title = "BackendTLSPolicy" of the connection from the Gateway to a backend pod(s) via the Service API object. Implementations may also decide to support the usage of `BackendTLSPolicy` for specifying the TLS configuration -of the connection from the Gateway to services not connected via HTTPRoute, and any +of the connection from the Gateway to services not connected via HTTPRoute, and any other kind of backend like [InferencePool](https://gateway-api-inference-extension.sigs.k8s.io/reference/spec/#inferencepool) ## Background @@ -31,7 +31,7 @@ applied to a Service that accesses a backend, where the BackendTLSPolicy resides Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order to prevent the complications involved with sharing trust across namespace boundaries. -Additionally, implementations may use BackendTLSPolicy for specifying the TLS configuration +Additionally, implementations may use BackendTLSPolicy for specifying the TLS configuration of the connection from the Gateway to services not connected via HTTPRoute, and any other kind of backend, but this behavior is optional and may not be available on all implementations. @@ -45,13 +45,13 @@ The specification of a [BackendTLSPolicy][backendtlspolicy] consists of: - [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and WellKnownCACertificates. - [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend. -- [SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation. A maximum of 5 SANs are allowed. +- [SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation. A maximum of 5 SANs are allowed. - [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates, which are used to establish a TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both. - [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both. -- [Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support. Check your implementation's documentation for details. +- [Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support. Check your implementation's documentation for details. The following chart outlines the object definitions and relationship: ```mermaid @@ -59,7 +59,7 @@ flowchart LR backendTLSPolicy[["backendTLSPolicy
BackendTLSPolicySpec: spec
PolicyStatus: status"]] spec[["spec
PolicyTargetReferenceWithSectionName: targetRefs
BackendTLSPolicyValidation: tls"]] status[["status
[ ]PolicyAncestorStatus: ancestors"]] - validation[["tls
LocalObjectReference: caCertificateRefs
wellKnownCACertificatesType: wellKnownCACertificates
PreciseHostname: hostname
[]SubjectAltName: subjectAltNames"]] + validation[["tls
LocalObjectReference: caCertificateRefs
wellKnownCACertificatesType: wellKnownCACertificates
PreciseHostname: hostname
[]SubjectAltName: subjectAltNames"]] ancestorStatus[["ancestors
AncestorRef: parentReference
GatewayController: controllerName
[]Condition: conditions"]] targetRefs[[targetRefs
]] service["service"] @@ -88,11 +88,17 @@ flowchart LR service --> pod1 & pod2 ``` + + While the diagram above shows an HTTPRoute, BackendTLSPolicy is a + [union feature](https://gateway-api.sigs.k8s.io/guides/implementers#union-feature-conformance) and + works with any route type that forwards traffic to backends, including + GRPCRoute and TLSRoute (when in Terminate mode). + ### Targeting backends A BackendTLSPolicy targets a backend Pod (or set of Pods) via one or more TargetRefs to a Service. This TargetRef is a required object reference that specifies a Service by its Name, Kind (Service), and optionally its Namespace and Group. -TargetRefs identify the Service(s) for which your HTTPRoute requires TLS. +TargetRefs identify the Service(s) for which your Route requires TLS. - Cross-namespace certificate references are not allowed. @@ -119,11 +125,11 @@ Also note: This field was added to BackendTLSPolicy in `v1.2.0` -The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs. -Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen. +The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs. +Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen. - - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). + - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). - Hostname: DNS name format - URI: URI format (e.g., SPIFFE ID) @@ -131,13 +137,13 @@ Subject Alternative Names may contain one of either a Hostname or URI field, and This field was added to BackendTLSPolicy in `v1.2.0` -The options field allows specification of implementation-specific TLS configurations. This can include: +The options field allows specification of implementation-specific TLS configurations. This can include: -- Vendor-specific mutual TLS automation configuration +- Vendor-specific mutual TLS automation configuration - Minimum supported TLS version restrictions - Supported cipher suite configurations -Check your implementation documentation for details. +Check your implementation documentation for details. ### #### Certificates @@ -167,12 +173,12 @@ Status defines the observed state of the BackendTLSPolicy and is not user-config way you do for other Gateway API objects to verify correct operation. Note that the status in BackendTLSPolicy uses `PolicyAncestorStatus` to allow you to know which parentReference set that particular status. -[backendtlspolicy]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicy -[validation]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyvalidation -[caCertificateRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference -[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference -[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#precisehostname +[backendtlspolicy]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicy +[validation]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicyvalidation +[caCertificateRefs]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localobjectreference +[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localobjectreference +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#precisehostname [rfc-3986]: https://tools.ietf.org/html/rfc3986 -[targetRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localpolicytargetreferencewithsectionname -[subjectAltNames]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#subjectaltname -[options]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyspec +[targetRefs]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localpolicytargetreferencewithsectionname +[subjectAltNames]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#subjectaltname +[options]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicyspec diff --git a/site/content/en/latest/api/gateway_api/gateway.md b/site/content/en/latest/api/gateway_api/gateway.md index 67d94d0d8c..b5a5636428 100644 --- a/site/content/en/latest/api/gateway_api/gateway.md +++ b/site/content/en/latest/api/gateway_api/gateway.md @@ -25,7 +25,7 @@ The `Gateway` spec defines the following: If the desired configuration specified in Gateway spec cannot be achieved, the Gateway will be in an error state with details provided by status conditions. -## Deployment models +### Deployment models Depending on the `GatewayClass`, the creation of a `Gateway` could do any of the following actions: diff --git a/site/content/en/latest/api/gateway_api/gatewayclass.md b/site/content/en/latest/api/gateway_api/gatewayclass.md index dc076f7536..8bc136a838 100644 --- a/site/content/en/latest/api/gateway_api/gatewayclass.md +++ b/site/content/en/latest/api/gateway_api/gatewayclass.md @@ -45,7 +45,7 @@ The user of the classes will not need to know *how* `internet` and `private` are implemented. Instead, the user will only need to understand the resulting properties of the class that the `Gateway` was created with. -## GatewayClass parameters +### GatewayClass parameters Providers of the `Gateway` API may need to pass parameters to their controller as part of the class definition. This is done using the @@ -142,5 +142,5 @@ example.net/gateway/v2.1 // Use version 2.1 example.net/gateway // Use the default version ``` -[gatewayclass]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#gatewayclass +[gatewayclass]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#gatewayclass [ingress-class-api]: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class diff --git a/site/content/en/latest/api/gateway_api/grpcroute.md b/site/content/en/latest/api/gateway_api/grpcroute.md index 64477e251a..23dfbb9869 100644 --- a/site/content/en/latest/api/gateway_api/grpcroute.md +++ b/site/content/en/latest/api/gateway_api/grpcroute.md @@ -7,6 +7,10 @@ title = "GRPCRoute" `v1.1.0`. For more information on release channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + If you know you're working with gRPC, prefer using a `GRPCRoute`. An `HTTPRoute` may be sufficient + for basic routing and load balancing, but `GRPCRoute` makes the intent clearer and can unlock + more gRPC-specific functionality. See [When to Use GRPCRoute](#when-to-use-grpcroute). + [GRPCRoute][grpcroute] is a Gateway API type for specifying routing behavior of gRPC requests from a Gateway listener to an API object, i.e. Service. @@ -56,6 +60,50 @@ the only differentiator being URI, the user should use `HTTPRoute` resources for both gRPC and HTTP. This will come at the cost of the improved UX of the `GRPCRoute` resource. +## When to Use GRPCRoute + +gRPC traffic can be routed with either `HTTPRoute` or `GRPCRoute`. For basic +gRPC load balancing, `GRPCRoute` is not technically required because `HTTPRoute` +can do it. The following guidance helps you choose the right resource for your +use case. + +### When HTTPRoute Is Sufficient + +`HTTPRoute` is sufficient when you only need basic routing and load balancing +for gRPC traffic without gRPC-specific features. Use `HTTPRoute` when: + +- You need simple hostname- or path-based routing and load balancing only. +- You do not need gRPC-aware retries or metrics (e.g. retries on gRPC status codes, gRPC-oriented metrics). +- You must serve HTTP and gRPC on the same hostname with URI as the only + differentiator; in that case you must use `HTTPRoute` for both (see [Cross + Serving](#cross-serving) above). + +With `HTTPRoute`, gRPC methods are matched by specifying the gRPC path as a +URI path (e.g. `/package.Service/Method`). With `GRPCRoute`, you match by +service and method fields (e.g. `service: com.example.User`, `method: Login`). + +### When to Prefer GRPCRoute + +Prefer `GRPCRoute` when you need gRPC-specific behavior or better ergonomics +for gRPC users. Use `GRPCRoute` when: + +- You want to match by gRPC service and method names directly (e.g. + `service: com.example.User`, `method: Login`) instead of URI paths. +- You need gRPC-aware policies such as retries conditioned on gRPC status + codes (e.g. `CANCELLED`, `RESOURCE_EXHAUSTED`). +- You need gRPC-oriented metrics or observability from the implementation. + +### Guidance for Controller Implementers + +Controllers that generate Routes on behalf of users (e.g. higher-level APIs +that create Gateway API routes) should consider the following: + +- If you generate `HTTPRoute` for basic gRPC load balancing, consider + offering a `GRPCRoute` option so that users who need gRPC-specific features + can use them without switching to manually managing routes. +- Do not add gRPC-specific policy (such as retries on gRPC status codes) to + `HTTPRoute`. Keep gRPC-aware configuration in `GRPCRoute` only. + ## Spec The specification of a GRPCRoute consists of: @@ -362,12 +410,12 @@ Multiple GRPCRoutes can be attached to a single Gateway resource. Importantly, only one Route rule may match each request. For more information on how conflict resolution applies to merging, refer to the [API specification][grpcrouterule]. -[grpcroute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroute -[grpcrouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcrouterule -[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#hostname +[grpcroute]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroute +[grpcrouterule]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcrouterule +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#hostname [rfc-3986]: https://tools.ietf.org/html/rfc3986 -[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroutematch -[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroutefilter -[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcbackendref -[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#parentreference -[name]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#sectionname +[matches]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroutematch +[filters]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroutefilter +[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcbackendref +[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#parentreference +[name]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#sectionname diff --git a/site/content/en/latest/api/gateway_api/httproute.md b/site/content/en/latest/api/gateway_api/httproute.md index 7feb45397c..7aee7265c8 100644 --- a/site/content/en/latest/api/gateway_api/httproute.md +++ b/site/content/en/latest/api/gateway_api/httproute.md @@ -227,14 +227,14 @@ this configuration error. BackendRefs defines API objects where matching requests should be sent. If unspecified, the rule performs no forwarding. If unspecified and no filters -are specified that would result in a response being sent, a 404 error code +are specified that would result in a response being sent, a 500 error code is returned. The following example forwards HTTP requests for path prefix `/bar` to service -"my-service1" on port `8080`, and HTTP requests fulfilling _all_ four of the +"my-service1" on port `8080`, and HTTP requests fulfilling _all_ four of the following criteria -- header `magic: foo` +- header `magic: foo` - query param `great: example` - path prefix `/some/thing` - method `GET` @@ -464,14 +464,14 @@ only one Route rule may match each request. For more information on how conflict resolution applies to merging, refer to the [API specification][httprouterule]. -[httproute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproute -[httprouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httprouterule -[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#hostname +[httproute]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproute +[httprouterule]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httprouterule +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#hostname [rfc-3986]: https://tools.ietf.org/html/rfc3986 -[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutematch -[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutefilter -[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httpbackendref -[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#parentreference -[timeouts]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutetimeouts +[matches]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutematch +[filters]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutefilter +[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httpbackendref +[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#parentreference +[timeouts]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutetimeouts [appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol -[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#sectionname +[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#sectionname diff --git a/site/content/en/latest/api/gateway_api/referencegrant.md b/site/content/en/latest/api/gateway_api/referencegrant.md index 13b8a50ba0..d90e22c9fc 100644 --- a/site/content/en/latest/api/gateway_api/referencegrant.md +++ b/site/content/en/latest/api/gateway_api/referencegrant.md @@ -64,7 +64,7 @@ spec: - name: bar namespace: bar --- -apiVersion: gateway.networking.k8s.io/v1beta1 +apiVersion: gateway.networking.k8s.io/v1 kind: ReferenceGrant metadata: name: bar @@ -116,7 +116,7 @@ No hints should be provided about whether or not the referenced resource exists. Cross namespace Route -> Gateway binding follows a slightly different pattern where the handshake mechanism is built into the Gateway resource. For more information on that approach, refer to the relevant [Security Model -documentation](https://gateway-api.sigs.k8s.io/concepts/security-model). Although conceptually similar to +documentation](https://gateway-api.sigs.k8s.io/concepts/security). Although conceptually similar to ReferenceGrant, this configuration is built directly into Gateway Listeners, and allows for fine-grained per Listener configuration that would not be possible with ReferenceGrant. diff --git a/site/content/en/news/releases/matrix.md b/site/content/en/news/releases/matrix.md index 0afab3d701..7c5082304f 100644 --- a/site/content/en/news/releases/matrix.md +++ b/site/content/en/news/releases/matrix.md @@ -8,6 +8,7 @@ Envoy Gateway relies on the Envoy Proxy and the Gateway API, and runs within a K | Envoy Gateway version | Envoy Proxy version | Rate Limit version | Gateway API version | Kubernetes version | End of Life | | --------------------- | --------------------------- | ------------------ | ------------------- | -------------------------- | ----------- | | latest | **dev-latest** | **master** | **v1.4.1** | v1.32, v1.33, v1.34, v1.35 | n/a | +| v1.8 | **distroless-v1.38.0** | **fe26676d** | **v1.5.1** | v1.32, v1.33, v1.34, v1.35 | 2026/11/08 | | v1.7 | **distroless-v1.37.0** | **3fb70258** | **v1.4.1** | v1.32, v1.33, v1.34, v1.35 | 2026/08/05 | | v1.6 | **distroless-v1.36.4** | **3fb70258** | **v1.4.0** | v1.30, v1.31, v1.32, v1.33 | 2026/05/13 | | v1.5 | **distroless-v1.35.0** | **a90e0e5d** | **v1.3.0** | v1.30, v1.31, v1.32, v1.33 | 2026/02/13 | diff --git a/site/content/en/news/releases/notes/v1.8.0.md b/site/content/en/news/releases/notes/v1.8.0.md new file mode 100644 index 0000000000..b44edc2349 --- /dev/null +++ b/site/content/en/news/releases/notes/v1.8.0.md @@ -0,0 +1,115 @@ +--- +title: "v1.8.0" +publishdate: 2026-05-12 +--- + +Date: May 12, 2026 + +## Breaking changes +- The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. Existing configurations including the template syntax (%) will be interpolated. +- The `0s` timeout in SecurityPolicy is now treated as infinite timeout instead of immediate timeout. +- Fixed EnvoyProxy `samplingFraction` translation to correctly convert the Gateway API fraction into Envoy's percentage-based `random_sampling` field. Existing `samplingFraction` configurations will now sample 100x more frequently than in previous releases; divide previous values by 100 to preserve prior sampling rates. +- The controller now uses production logging encoder config by default, which provides better output when using JSON encoder. +- SecurityPolicy OIDC now generates a single native `envoy.filters.http.oauth2` HTTP filter in the HCM filter chain and moves route-specific OAuth2 configuration to route `typed_per_filter_config`. This can break existing EnvoyPatchPolicies and extension managers that depend on the previous per-route OAuth2 filter instances or on the old OAuth2 filter configuration shape in the HCM filter chain. +- Merged SecurityPolicy IR/xDS resource names (OIDC, BasicAuth, ExtAuth, JWT) now derive from the policy that contributes the field (parent or route) rather than always using the route-level policy. EnvoyPatchPolicy users who reference those generated names must update their patch targets. + +## Security updates +- + +## New features +- Added support for optional active health check configuration. +- Added support for shadow mode in local rate limiting. +- Added support for MergeType in SecurityPolicy to enable route-level policies to merge with parent Gateway/Listener policies, similar to BackendTrafficPolicy. +- Added `egctl config envoy-gateway` commands to retrieve Envoy Gateway admin config dumps. +- The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. See https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators for more details. +- Added HTTP/2 connection keepalive support to ClientTrafficPolicy and BackendTrafficPolicy. +- Added RoutingType field for BackendTrafficPolicy. +- Added support for configuring weights for locality zones. +- Added support for gRPC-Web settings in ClientTrafficPolicy. +- Added support for Envoy Dynamic Modules. +- Added support for weight in BackendRef API to enable traffic splitting for non-x-route resources. +- Added support for removing headers based on matching criteria (Exact, Prefix, Suffix, RegularExpression) in ClientTrafficPolicy EarlyRequestHeaders and LateResponseHeaders. +- Added support for priorityClassName in KubernetesPodSpec for Envoy Proxy pods. +- Added support for Global rate limit shadow mode. +- Added support for specifying both text (body) and attributes in access log format by making the type field optional. +- Set warning status condition for deprecated fields in xPolicy CRDs. +- Added support for URLRewrite filter on individual backendRefs. +- Added support for custom headers on OTLP exports (metrics, tracing, access logs). +- Added support for custom TLS configuration when pulling WASM code via HTTP or OCI in EnvoyExtensionPolicy. +- Added support for gRPC stats settings in EnvoyProxy. +- Added the PostEndpointsModify extension hook, allowing extensions to modify EDS ClusterLoadAssignments generated by Envoy Gateway before they are sent to Envoy. +- Added support for stream idle timeout in BackendTrafficPolicy. +- Added `namespaceOverride` support to gateway-helm chart. +- Added support for configuring statusOnError in ExtAuth settings. +- Added support for GeoIP-based authorization on HTTPRoute and GRPCRoute via `SecurityPolicy.spec.authorization.rules[*].principal.clientIPGeoLocations`, backed by shared GeoIP provider settings in `EnvoyProxy.spec.geoIP`. +- Added support for retry budget in BackendTrafficPolicy. +- Added support for BackendUtilization load balancing policy in BackendTrafficPolicy. +- Added support for upstream access logs via the `Upstream` access log type in EnvoyProxy. +- Added support for invert match in CIDR match RateLimit API. +- Added support for ignoring HTTP/1.1 Upgrade requests in ClientTrafficPolicy via `http1.ignoredUpgradeTypes`. +- Added support for OpenTelemetry sampler configuration for tracing. +- Added support for multiple ExtensionManagers with sequential chaining via a new `extensionManagers` field in `EnvoyGateway` configuration. +- Added support for default EnvoyProxy settings on EnvoyGatewaySpec that can be overridden by GatewayClass or Gateway-level EnvoyProxy configurations. A new MergeType field allows choosing between Replace (default), StrategicMerge, or JSONMerge strategies for combining configurations. +- Added support for sending Envoy Gateway route metadata to external authorization backends via `SecurityPolicy.spec.extAuth.includeRouteMetadata`. +- Added support for cross-namespace policy attachment for ClientTrafficPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, and SecurityPolicy. +- Added `source` field to `responseOverride` rules in BackendTrafficPolicy, allowing rules to target only Envoy-generated responses (`Local`), only upstream responses (`Backend`), or both (`All`, the default). This enables overriding Envoy responses (e.g. auth/rate-limit failures) without affecting legitimate upstream responses with the same status code. +- Added support for path override in ExtAuth HTTP service. +- Added support for bandwidth limiting in BackendTrafficPolicy. +- Added support for defining Envoy Proxy image, pullPolicy, and pullSecrets via the helm chart. Note that to merge these helm-configured values with EnvoyProxy resources, the EnvoyProxy must include `mergeType: StrategicMerge` or `mergeType: JSONMerge`. +- Added support for Envoy Admission Control to BackendTrafficPolicy, enabling client-side load shedding based on historical upstream success rates using Envoy's admission control filter. + +## Bug fixes +- Fixed local rate limit rules with identical sourceCIDR client selectors producing conflicting descriptors. +- Rejected ClientTrafficPolicy if invalid TLS cipher suites are configured. +- Fixed ClientTrafficPolicy to disable HTTP/3 and surface a warning on the policy when downstream client TLS validation is configured, instead of generating a rejected QUIC listener. +- Fixed validation of XListenerSet certificateRefs. +- Fixed XListenerSet not allowing xRoutes from the same namespace when configured to allow them. +- Fixed API key authentication dropping non-first client IDs when credential Secrets contain multiple keys. +- Fixed `X-ENVOY-ORIGINAL-HOST` not being set when `headers.enableEnvoyHeaders` is enabled and hostname rewrite is configured for DynamicResolver type of Backends. +- Fixed standalone mode emitting non-actionable error logs for missing secrets and unsupported ratelimit deletion on every startup. +- Fixed local object reference resolution from parent policy in merged BackendTrafficPolicies. +- Fixed xPolicy resources being processed from all namespaces when NamespaceSelector watch mode is configured in the Kubernetes provider. +- Fixed route and policy status aggregation across multiple GatewayClasses managed by the same controller, so resources preserve status from all relevant parents and ancestors instead of being overwritten by the last processed GatewayClass. +- Fixed route status parent aggregation when the number of parents exceeds the Gateway API cap of 32. +- Made ConnectionLimit.Value optional so users can configure MaxConnectionDuration, MaxRequestsPerConnection, or MaxStreamDuration without setting a max connections value. +- Fixed endpoint hostname not being respected during active health checks. +- Fixed ratelimit deployment missing metrics container port (19001), which prevented PodMonitor/ServiceMonitor from targeting the metrics endpoint. +- Fixed ratelimit ServiceAccount missing standard Kubernetes app labels. +- Fixed GRPCRoute RequestMirror filter backend not being indexed, causing "service not found" errors for mirror targets that exist in the cluster. +- Fixed GRPCRoute not detecting conflicting RequestMirror and DirectResponse filters, which caused the mirror to be silently dropped. +- Fixed BackendTrafficPolicy `requestBuffer` coexisting with route upgrades by disabling the default WebSocket upgrade on buffered routes and rejecting explicit `requestBuffer` + `httpUpgrade` combinations. +- Fixed per-endpoint hostname override not working due to the auto-generated wildcard hostname. +- Fixed Basic Authentication failing when htpasswd secrets use CRLF line endings by normalizing to LF before passing to Envoy. +- Fixed BackendTLSPolicy being ignored when configuring TLS for telemetry backends (access logs, tracing, metrics). +- Fixed client certificate secret never being delivered when exclusively referenced by a SecurityPolicy `extAuth`/`jwt`/`oidc` Backend. +- Fixed xRoutes being incorrectly marked unaccepted when a RequestMirror filter referenced a backend with no endpoints; the route now remains accepted with `BackendsAvailable=False`, per Gateway API conformance. +- Fixed `ws` and `wss` Backend appProtocols to force HTTP/1.1 upstream connections instead of negotiating HTTP/2, avoiding compatibility issues with WebSocket backends that do not support RFC 8441 extended CONNECT. +- Fixed gateway-helm RBAC in GatewayNamespace mode with explicit `watch.namespaces` list by adding controller-namespace secret read permissions to infra-manager. +- Fixed a control plane panic caused by concurrent Status mutation racing with the watchable Map coalesce goroutine. +- Fixed BackendTrafficPolicy rate limit `requests` values above uint32 max (4294967295) being silently truncated modulo 2^32 by the rate limit service and Envoy token bucket. The field now rejects such values at admission time with a clear schema validation error. +- Fixed status conditions not being updated when a route is rejected due to multiple errors. +- Fixed spurious development-mode panic log from the gatewayapi translator. +- Fixed SecurityPolicy merge using the wrong policy as the owner for resource references and IR generation. +- Fixed ListenerSet and its listeners incorrectly setting `Accepted: False` for InvalidCertificateRef and RefNotPermitted, inconsistent with Gateway behavior and the Gateway API spec. +- Fixed active HTTP health checks to use Backend endpoint hostnames before falling back to the effective Route hostname. +- Fixed HTTPS listeners with overlapping hostnames but disjoint certificate SANs to preserve HTTP/2 ALPN by default. +- Removed the spurious cross-namespace policy-attachment warning condition when a ReferenceGrant is missing (#8901). +- Fixed an invalid first listener winning hostname/protocol precedence and causing a later valid listener on the same hostname/port to be marked HostnameConflict (#8577). +- Increased `RateLimitSelectCondition.headers` MaxItems from 16 to 64, matching the existing `HTTPHeaderFilter` pattern (#8906). +- Fixed Gateway getting stuck at `Programmed=False` after its LoadBalancer Service IP was restored, by ignoring `LastTransitionTime` when comparing status conditions. + +## Performance improvements +- Reduced chances of listener drain due to Lua policy updates by migrating to LuaPerRoute. +- Reduced Kubernetes API server calls by reusing the cached controller-runtime client from the controller manager for infrastructure reconciliation. In GatewayNamespaceMode, this may slightly increase memory usage due to keeping the infrastructure resources in the cache. +- Enabled deferred stat creation to reduce CPU and memory overhead by creating only the subset of metrics that are actually used at runtime, instead of eagerly initializing all possible stats. More information can be found in the Envoy deferred stat creation [documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#config-bootstrap-v3-bootstrap-deferredstatoptions). + +## Deprecations +- + +## Other changes +- Moved Envoy Gateway CRDs into a sub-chart to avoid the Helm release secret exceeding the 1MB size limit when adding new API fields. Upgrade/Install behavior is unchanged for users. +- The maximum number of rules in a RateLimit policy is increased from 128 to 256. +- The maximum number of JWT providers allowed in `SecurityPolicy.spec.jwt.providers` is increased from 4 to 16. +- Added `runner_event_total` metric to track update and delete events in infrastructure and gateway API runners for improved observability. +- Added common Helm labels to Envoy Gateway RBAC resources. + diff --git a/site/content/en/news/releases/v1.8.md b/site/content/en/news/releases/v1.8.md new file mode 100644 index 0000000000..067235b60f --- /dev/null +++ b/site/content/en/news/releases/v1.8.md @@ -0,0 +1,166 @@ +--- +title: Announcing Envoy Gateway v1.8 +subtitle: Minor Update +linktitle: Release v1.8 +description: Envoy Gateway v1.8 release announcement. +publishdate: 2026-05-12 +release: v1.8.0 +skip_list: true +--- + +We are excited to announce the release of Envoy Gateway v1.8.0. + +This release delivers new capabilities across traffic management, security, extensibility, observability, and infrastructure — along with key bug fixes and performance improvements. We extend our thanks to the entire Envoy Gateway community for your ongoing contributions, feedback, and collaboration. Your efforts make each release possible. + +| [Release Notes][] | [Docs][docs] | [Compatibility Matrix][matrix] | [Install][] | +|-------------------|--------------|--------------------------------|--------------| + +## What's New + +Envoy Gateway v1.8.0 introduces powerful enhancements, resolves critical issues, and continues to improve the platform's reliability and performance. + +--- + +## 🚨 Breaking Changes + +- The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. Existing configurations including the template syntax (%) will be interpolated. +- The `0s` timeout in SecurityPolicy is now treated as infinite timeout instead of immediate timeout. +- Fixed EnvoyProxy `samplingFraction` translation to correctly convert the Gateway API fraction into Envoy's percentage-based `random_sampling` field. Existing `samplingFraction` configurations will now sample 100x more frequently than in previous releases; divide previous values by 100 to preserve prior sampling rates. +- The controller now uses production logging encoder config by default, which provides better output when using JSON encoder. +- SecurityPolicy OIDC now generates a single native `envoy.filters.http.oauth2` HTTP filter in the HCM filter chain and moves route-specific OAuth2 configuration to route `typed_per_filter_config`. This can break existing EnvoyPatchPolicies and extension managers that depend on the previous per-route OAuth2 filter instances or on the old OAuth2 filter configuration shape in the HCM filter chain. +- Merged SecurityPolicy IR/xDS resource names (OIDC, BasicAuth, ExtAuth, JWT) now derive from the policy that contributes the field (parent or route) rather than always using the route-level policy. EnvoyPatchPolicy users who reference those generated names must update their patch targets. + +--- + +## ✨ New Features + +### API & Traffic Management + +- Added support for weight in BackendRef API to enable traffic splitting for non-x-route resources. +- Added support for removing headers based on matching criteria (Exact, Prefix, Suffix, RegularExpression) in ClientTrafficPolicy EarlyRequestHeaders and LateResponseHeaders. +- Added support for URLRewrite filter on individual backendRefs. +- Added support for shadow mode in local rate limiting. +- Added support for Global rate limit shadow mode. +- Added support for invert match in CIDR match RateLimit API. +- Added support for ignoring HTTP/1.1 Upgrade requests in ClientTrafficPolicy via `http1.ignoredUpgradeTypes`. +- Added HTTP/2 connection keepalive support to ClientTrafficPolicy and BackendTrafficPolicy. +- Added support for gRPC-Web settings in ClientTrafficPolicy. +- Added RoutingType field for BackendTrafficPolicy. +- Added support for stream idle timeout in BackendTrafficPolicy. +- Added support for retry budget in BackendTrafficPolicy. +- Added support for BackendUtilization load balancing policy in BackendTrafficPolicy. +- Added support for Envoy Admission Control to BackendTrafficPolicy, enabling client-side load shedding based on historical upstream success rates using Envoy's admission control filter. +- Added support for bandwidth limiting in BackendTrafficPolicy. +- Added support for upstream access logs via the `Upstream` access log type in EnvoyProxy. +- Added `source` field to `responseOverride` rules in BackendTrafficPolicy, allowing rules to target only Envoy-generated responses (`Local`), only upstream responses (`Backend`), or both (`All`, the default). This enables overriding Envoy responses (e.g. auth/rate-limit failures) without affecting legitimate upstream responses with the same status code. +- The DirectResponse body in HTTPFilter now supports Envoy command operators for dynamic content. See the [Envoy command operators documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) for details. +- Added support for configuring weights for locality zones. +- Added support for cross-namespace policy attachment for ClientTrafficPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, and SecurityPolicy. + +### Security & Authentication + +- Added support for MergeType in SecurityPolicy to enable route-level policies to merge with parent Gateway/Listener policies, similar to BackendTrafficPolicy. +- Added support for GeoIP-based authorization on HTTPRoute and GRPCRoute via `SecurityPolicy.spec.authorization.rules[*].principal.clientIPGeoLocations`, backed by shared GeoIP provider settings in `EnvoyProxy.spec.geoIP`. +- Added support for configuring statusOnError in ExtAuth settings. +- Added support for sending Envoy Gateway route metadata to external authorization backends via `SecurityPolicy.spec.extAuth.includeRouteMetadata`. +- Added support for path override in ExtAuth HTTP service. +- Added support for custom TLS configuration when pulling WASM code via HTTP or OCI in EnvoyExtensionPolicy. + +### Extensibility + +- Added support for Envoy Dynamic Modules. +- Added the PostEndpointsModify extension hook, allowing extensions to modify EDS ClusterLoadAssignments generated by Envoy Gateway before they are sent to Envoy. +- Added support for multiple ExtensionManagers with sequential chaining via a new `extensionManagers` field in `EnvoyGateway` configuration. +- Added support for default EnvoyProxy settings on EnvoyGatewaySpec that can be overridden by GatewayClass or Gateway-level EnvoyProxy configurations. A new MergeType field allows choosing between Replace (default), StrategicMerge, or JSONMerge strategies for combining configurations. +- Added `egctl config envoy-gateway` commands to retrieve Envoy Gateway admin config dumps. + +### Infrastructure & Helm + +- Added support for priorityClassName in KubernetesPodSpec for Envoy Proxy pods. +- Added `namespaceOverride` support to gateway-helm chart. +- Added support for defining Envoy Proxy image, pullPolicy, and pullSecrets via the helm chart. Note that to merge these helm-configured values with EnvoyProxy resources, the EnvoyProxy must include `mergeType: StrategicMerge` or `mergeType: JSONMerge`. +- Added support for optional active health check configuration. + +### Observability + +- Added support for custom headers on OTLP exports (metrics, tracing, access logs). +- Added support for OpenTelemetry sampler configuration for tracing. +- Added support for gRPC stats settings in EnvoyProxy. +- Added support for specifying both text (body) and attributes in access log format by making the type field optional. + +### Status & Validation + +- Set warning status condition for deprecated fields in xPolicy CRDs. + +--- + +## 🐞 Bug Fixes + +- Fixed local rate limit rules with identical sourceCIDR client selectors producing conflicting descriptors. +- Rejected ClientTrafficPolicy if invalid TLS cipher suites are configured. +- Fixed ClientTrafficPolicy to disable HTTP/3 and surface a warning on the policy when downstream client TLS validation is configured, instead of generating a rejected QUIC listener. +- Fixed validation of XListenerSet certificateRefs. +- Fixed XListenerSet not allowing xRoutes from the same namespace when configured to allow them. +- Fixed API key authentication dropping non-first client IDs when credential Secrets contain multiple keys. +- Fixed `X-ENVOY-ORIGINAL-HOST` not being set when `headers.enableEnvoyHeaders` is enabled and hostname rewrite is configured for DynamicResolver type of Backends. +- Fixed standalone mode emitting non-actionable error logs for missing secrets and unsupported ratelimit deletion on every startup. +- Fixed local object reference resolution from parent policy in merged BackendTrafficPolicies. +- Fixed xPolicy resources being processed from all namespaces when NamespaceSelector watch mode is configured in the Kubernetes provider. +- Fixed route and policy status aggregation across multiple GatewayClasses managed by the same controller, so resources preserve status from all relevant parents and ancestors instead of being overwritten by the last processed GatewayClass. +- Fixed route status parent aggregation when the number of parents exceeds the Gateway API cap of 32. +- Made ConnectionLimit.Value optional so users can configure MaxConnectionDuration, MaxRequestsPerConnection, or MaxStreamDuration without setting a max connections value. +- Fixed endpoint hostname not being respected during active health checks. +- Fixed ratelimit deployment missing metrics container port (19001), which prevented PodMonitor/ServiceMonitor from targeting the metrics endpoint. +- Fixed ratelimit ServiceAccount missing standard Kubernetes app labels. +- Fixed GRPCRoute RequestMirror filter backend not being indexed, causing "service not found" errors for mirror targets that exist in the cluster. +- Fixed GRPCRoute not detecting conflicting RequestMirror and DirectResponse filters, which caused the mirror to be silently dropped. +- Fixed BackendTrafficPolicy `requestBuffer` coexisting with route upgrades by disabling the default WebSocket upgrade on buffered routes and rejecting explicit `requestBuffer` + `httpUpgrade` combinations. +- Fixed per-endpoint hostname override not working due to the auto-generated wildcard hostname. +- Fixed Basic Authentication failing when htpasswd secrets use CRLF line endings by normalizing to LF before passing to Envoy. +- Fixed BackendTLSPolicy being ignored when configuring TLS for telemetry backends (access logs, tracing, metrics). +- Fixed client certificate secret never being delivered when exclusively referenced by a SecurityPolicy `extAuth`/`jwt`/`oidc` Backend. +- Fixed xRoutes being incorrectly marked unaccepted when a RequestMirror filter referenced a backend with no endpoints; the route now remains accepted with `BackendsAvailable=False`, per Gateway API conformance. +- Fixed `ws` and `wss` Backend appProtocols to force HTTP/1.1 upstream connections instead of negotiating HTTP/2, avoiding compatibility issues with WebSocket backends that do not support RFC 8441 extended CONNECT. +- Fixed gateway-helm RBAC in GatewayNamespace mode with explicit `watch.namespaces` list by adding controller-namespace secret read permissions to infra-manager. +- Fixed a control plane panic caused by concurrent Status mutation racing with the watchable Map coalesce goroutine. +- Fixed BackendTrafficPolicy rate limit `requests` values above uint32 max (4294967295) being silently truncated modulo 2^32 by the rate limit service and Envoy token bucket. The field now rejects such values at admission time with a clear schema validation error. +- Fixed status conditions not being updated when a route is rejected due to multiple errors. +- Fixed spurious development-mode panic log from the gatewayapi translator. +- Fixed SecurityPolicy merge using the wrong policy as the owner for resource references and IR generation. +- Fixed ListenerSet and its listeners incorrectly setting `Accepted: False` for InvalidCertificateRef and RefNotPermitted, inconsistent with Gateway behavior and the Gateway API spec. +- Fixed active HTTP health checks to use Backend endpoint hostnames before falling back to the effective Route hostname. +- Fixed HTTPS listeners with overlapping hostnames but disjoint certificate SANs to preserve HTTP/2 ALPN by default. +- Removed the spurious cross-namespace policy-attachment warning condition when a ReferenceGrant is missing. +- Fixed an invalid first listener winning hostname/protocol precedence and causing a later valid listener on the same hostname/port to be marked HostnameConflict. +- Increased `RateLimitSelectCondition.headers` MaxItems from 16 to 64, matching the existing `HTTPHeaderFilter` pattern. +- Fixed Gateway getting stuck at `Programmed=False` after its LoadBalancer Service IP was restored, by ignoring `LastTransitionTime` when comparing status conditions. + +--- + +## 🚀 Performance Improvements + +- Reduced chances of listener drain due to Lua policy updates by migrating to LuaPerRoute. +- Reduced Kubernetes API server calls by reusing the cached controller-runtime client from the controller manager for infrastructure reconciliation. In GatewayNamespaceMode, this may slightly increase memory usage due to keeping the infrastructure resources in the cache. +- Enabled deferred stat creation to reduce CPU and memory overhead by creating only the subset of metrics that are actually used at runtime, instead of eagerly initializing all possible stats. More information can be found in the [Envoy deferred stat creation documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#config-bootstrap-v3-bootstrap-deferredstatoptions). + +--- + +## 📝 Other Changes + +- Moved Envoy Gateway CRDs into a sub-chart to avoid the Helm release secret exceeding the 1MB size limit when adding new API fields. Upgrade/Install behavior is unchanged for users. +- The maximum number of rules in a RateLimit policy is increased from 128 to 256. +- The maximum number of JWT providers allowed in `SecurityPolicy.spec.jwt.providers` is increased from 4 to 16. +- Added `runner_event_total` metric to track update and delete events in infrastructure and gateway API runners for improved observability. +- Added common Helm labels to Envoy Gateway RBAC resources. + +--- + +## 📝 Upgrade Notes + +- We encourage all users to upgrade to v1.8.0 to take advantage of the new features, security improvements, and performance gains. For full details, see the [Release Notes][] and updated [Documentation][docs]. +- See upgrading from previous version via [helm install](../../v1.8/install/install-helm.md#upgrading-from-the-previous-version) or [yaml install](../../v1.8/install/install-yaml.md#upgrading-from-the-previous-version) for more. Note that CRDs should be upgraded first before gateway controller. + +[Release Notes]: ./notes/v1.8.0.md +[docs]: https://gateway.envoyproxy.io +[matrix]: https://gateway.envoyproxy.io/news/releases/matrix/ +[Install]: https://gateway.envoyproxy.io/docs/tasks/quickstart/ diff --git a/site/content/en/v1.8/_index.md b/site/content/en/v1.8/_index.md new file mode 100644 index 0000000000..92ae858688 --- /dev/null +++ b/site/content/en/v1.8/_index.md @@ -0,0 +1,15 @@ ++++ +title = "Welcome to Envoy Gateway" +linktitle = "Documentation" +description = "Envoy Gateway Documents" + +[[cascade]] +type = "docs" ++++ + +Envoy Gateway is an open source project for managing [Envoy Proxy](https://www.envoyproxy.io/) as a standalone or Kubernetes-based application +gateway. [Gateway API](https://gateway-api.sigs.k8s.io/) resources are used to dynamically provision and configure the managed Envoy Proxies. + +![architecture](/img/traffic.png) + +## Ready to get started? diff --git a/site/content/en/v1.8/api/_index.md b/site/content/en/v1.8/api/_index.md new file mode 100644 index 0000000000..a3d06b0cd5 --- /dev/null +++ b/site/content/en/v1.8/api/_index.md @@ -0,0 +1,5 @@ +--- +title: "API References" +description: This section includes API References. +weight: 80 +--- diff --git a/site/content/en/v1.8/api/extension_types.md b/site/content/en/v1.8/api/extension_types.md new file mode 100644 index 0000000000..d2235779eb --- /dev/null +++ b/site/content/en/v1.8/api/extension_types.md @@ -0,0 +1,6676 @@ ++++ +title = "Gateway API Extensions" +weight = 1 +description = "Envoy Gateway provides these extensions to support additional features not available in the Gateway API today" ++++ + + +## Packages +- [gateway.envoyproxy.io/v1alpha1](#gatewayenvoyproxyiov1alpha1) + + +## gateway.envoyproxy.io/v1alpha1 + +Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io +API group. + + +### Resource Types +- [Backend](#backend) +- [BackendTrafficPolicy](#backendtrafficpolicy) +- [ClientTrafficPolicy](#clienttrafficpolicy) +- [EnvoyExtensionPolicy](#envoyextensionpolicy) +- [EnvoyGateway](#envoygateway) +- [EnvoyPatchPolicy](#envoypatchpolicy) +- [EnvoyProxy](#envoyproxy) +- [HTTPRouteFilter](#httproutefilter) +- [SecurityPolicy](#securitypolicy) + + + +#### ALPNProtocol + +_Underlying type:_ _string_ + +ALPNProtocol specifies the protocol to be negotiated using ALPN + +_Appears in:_ +- [BackendTLSConfig](#backendtlsconfig) +- [ClientTLSSettings](#clienttlssettings) +- [TLSSettings](#tlssettings) + +| Value | Description | +| ----- | ----------- | +| `http/1.0` | HTTPProtocolVersion1_0 specifies that HTTP/1.0 should be negotiable with ALPN
| +| `http/1.1` | HTTPProtocolVersion1_1 specifies that HTTP/1.1 should be negotiable with ALPN
| +| `h2` | HTTPProtocolVersion2 specifies that HTTP/2 should be negotiable with ALPN
| + + +#### ALSEnvoyProxyAccessLog + + + +ALSEnvoyProxyAccessLog defines the gRPC Access Log Service (ALS) sink. +The service must implement the Envoy gRPC Access Log Service streaming API: +https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/accesslog/v3/als.proto +Access log format information is passed in the form of gRPC metadata when the +stream is established. + +_Appears in:_ +- [ProxyAccessLogSink](#proxyaccesslogsink) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `logName` | _string_ | false | | LogName defines the friendly name of the access log to be returned in
StreamAccessLogsMessage.Identifier. This allows the access log server
to differentiate between different access logs coming from the same Envoy. | +| `type` | _[ALSEnvoyProxyAccessLogType](#alsenvoyproxyaccesslogtype)_ | true | | Type defines the type of accesslog. Supported types are "HTTP" and "TCP". | +| `http` | _[ALSEnvoyProxyHTTPAccessLogConfig](#alsenvoyproxyhttpaccesslogconfig)_ | false | | HTTP defines additional configuration specific to HTTP access logs. | + + +#### ALSEnvoyProxyAccessLogType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog) + +| Value | Description | +| ----- | ----------- | +| `HTTP` | ALSEnvoyProxyAccessLogTypeHTTP defines the HTTP access log type and will populate StreamAccessLogsMessage.http_logs.
| +| `TCP` | ALSEnvoyProxyAccessLogTypeTCP defines the TCP access log type and will populate StreamAccessLogsMessage.tcp_logs.
| + + +#### ALSEnvoyProxyHTTPAccessLogConfig + + + + + +_Appears in:_ +- [ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `requestHeaders` | _string array_ | false | | RequestHeaders defines request headers to include in log entries sent to the access log service. | +| `responseHeaders` | _string array_ | false | | ResponseHeaders defines response headers to include in log entries sent to the access log service. | +| `responseTrailers` | _string array_ | false | | ResponseTrailers defines response trailers to include in log entries sent to the access log service. | + + +#### APIKeyAuth + + + +APIKeyAuth defines the configuration for the API Key Authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `credentialRefs` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference) array_ | true | | CredentialRefs is the Kubernetes secret which contains the API keys.
This is an Opaque secret.
Each API key is stored in the key representing the client id.
If the secrets have a key for a duplicated client, the first one will be used. | +| `extractFrom` | _[ExtractFrom](#extractfrom) array_ | true | | ExtractFrom is where to fetch the key from the coming request.
The value from the first source that has a key will be used. | +| `forwardClientIDHeader` | _string_ | false | | ForwardClientIDHeader is the name of the header to forward the client identity to the backend
service. The header will be added to the request with the client id as the value. | +| `sanitize` | _boolean_ | false | | Sanitize indicates whether to remove the API key from the request before forwarding it to the backend service. | + + +#### ActiveHealthCheck + + + +ActiveHealthCheck defines the active health check configuration. +EG supports various types of active health checking including HTTP, TCP. + +_Appears in:_ +- [HealthCheck](#healthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `timeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | 1s | Timeout defines the time to wait for a health check response. | +| `interval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | 3s | Interval defines the time between active health checks. | +| `initialJitter` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | InitialJitter defines the maximum time Envoy will wait before the first health check.
Envoy will randomly select a value between 0 and the initial jitter value. | +| `unhealthyThreshold` | _integer_ | false | 3 | UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy.
Without RetriableStatuses configured, any health check failure results in the host being immediately
considered unhealthy. When RetriableStatuses is set, health checks returning those statuses are retried
up to this threshold before the host is marked unhealthy. | +| `healthyThreshold` | _integer_ | false | 1 | HealthyThreshold defines the number of healthy health checks required before a backend host is marked healthy. | +| `type` | _[ActiveHealthCheckerType](#activehealthcheckertype)_ | true | | Type defines the type of health checker. | +| `http` | _[HTTPActiveHealthChecker](#httpactivehealthchecker)_ | false | | HTTP defines the configuration of http health checker.
It's required while the health checker type is HTTP. | +| `tcp` | _[TCPActiveHealthChecker](#tcpactivehealthchecker)_ | false | | TCP defines the configuration of tcp health checker.
It's required while the health checker type is TCP. | +| `grpc` | _[GRPCActiveHealthChecker](#grpcactivehealthchecker)_ | false | | GRPC defines the configuration of the GRPC health checker.
It's optional, and can only be used if the specified type is GRPC. | +| `overrides` | _[HealthCheckOverrides](#healthcheckoverrides)_ | false | | Overrides defines the configuration of the overriding health check settings for all endpoints
in the backend cluster. This allows customization of port and other settings that may differ
from the main service configuration. | + + +#### ActiveHealthCheckPayload + + + +ActiveHealthCheckPayload defines the encoding of the payload bytes in the payload. + +_Appears in:_ +- [HTTPActiveHealthChecker](#httpactivehealthchecker) +- [TCPActiveHealthChecker](#tcpactivehealthchecker) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ActiveHealthCheckPayloadType](#activehealthcheckpayloadtype)_ | true | | Type defines the type of the payload. | +| `text` | _string_ | false | | Text payload in plain text. | +| `binary` | _integer array_ | false | | Binary payload base64 encoded. | + + +#### ActiveHealthCheckPayloadType + +_Underlying type:_ _string_ + +ActiveHealthCheckPayloadType is the type of the payload. + +_Appears in:_ +- [ActiveHealthCheckPayload](#activehealthcheckpayload) + +| Value | Description | +| ----- | ----------- | +| `Text` | ActiveHealthCheckPayloadTypeText defines the Text type payload.
| +| `Binary` | ActiveHealthCheckPayloadTypeBinary defines the Binary type payload.
| + + +#### ActiveHealthCheckerType + +_Underlying type:_ _string_ + +ActiveHealthCheckerType is the type of health checker. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Value | Description | +| ----- | ----------- | +| `HTTP` | ActiveHealthCheckerTypeHTTP defines the HTTP type of health checking.
| +| `TCP` | ActiveHealthCheckerTypeTCP defines the TCP type of health checking.
| +| `GRPC` | ActiveHealthCheckerTypeGRPC defines the GRPC type of health checking.
| + + +#### AdmissionControl + + + +AdmissionControl configures health-based load shedding for upstream backends. + +Envoy tracks recent upstream responses over a sliding sampling window. When the +observed success rate drops below the configured threshold, Envoy +probabilistically rejects new requests before forwarding them upstream. This can +reduce pressure on degraded backends and give them time to recover. + +All fields are optional. When omitted, Envoy's admission control defaults are used. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `samplingWindow` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | SamplingWindow defines the time window over which request success rates are calculated.
Must be at least 1s; Envoy truncates the window to whole seconds and uses it as the
denominator in RPS calculations, so sub-second values would produce a zero denominator.
Defaults to 30s if not specified. | +| `minSuccessRate` | _integer_ | false | | MinSuccessRate is the lowest request success rate, as a percentage in the
range [1, 100], at which the filter will not reject requests. Defaults to 95 if
not specified. Envoy rejects values below 1%, so values lower than 1 are not allowed. | +| `rejectionAggression` | _integer_ | false | | RejectionAggression controls how steeply the rejection probability rises
as the observed success rate falls below MinSuccessRate. A value of 1
produces a linear curve; higher values reject more aggressively for a
given drop in success rate. Must be greater than 0; values below 1 are
clamped to 1. Defaults to 1. | +| `minRequestRate` | _integer_ | false | | MinRequestRate defines the minimum requests per second below which requests will
pass through the filter without rejection. Defaults to 0 if not specified. | +| `maxRejectionPercent` | _integer_ | false | | MaxRejectionPercent represents the upper limit of the rejection probability,
expressed as a percentage in the range [0, 100]. Defaults to 80 if not specified. | +| `successCriteria` | _[AdmissionControlSuccessCriteria](#admissioncontrolsuccesscriteria)_ | false | | SuccessCriteria defines what constitutes a successful request for both HTTP and gRPC. | + + +#### AdmissionControlSuccessCriteria + + + +AdmissionControlSuccessCriteria defines the criteria for determining successful requests. + +_Appears in:_ +- [AdmissionControl](#admissioncontrol) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `http` | _[HTTPSuccessCriteria](#httpsuccesscriteria)_ | false | | HTTP defines success criteria for HTTP requests. | +| `grpc` | _[GRPCSuccessCriteria](#grpcsuccesscriteria)_ | false | | GRPC defines success criteria for gRPC requests. | + + +#### AppProtocolType + +_Underlying type:_ _string_ + +AppProtocolType defines various backend applications protocols supported by Envoy Gateway + +_Appears in:_ +- [BackendSpec](#backendspec) + +| Value | Description | +| ----- | ----------- | +| `gateway.envoyproxy.io/h2c` | AppProtocolTypeH2C defines the HTTP/2 application protocol.
| +| `gateway.envoyproxy.io/ws` | AppProtocolTypeWS defines the WebSocket over HTTP protocol.
| +| `gateway.envoyproxy.io/wss` | AppProtocolTypeWSS defines the WebSocket over HTTPS protocol.
| + + +#### Authorization + + + +Authorization defines the authorization configuration. + +Note: if neither `Rules` nor `DefaultAction` is specified, the default action is to deny all requests. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `rules` | _[AuthorizationRule](#authorizationrule) array_ | false | | Rules defines a list of authorization rules.
These rules are evaluated in order, the first matching rule will be applied,
and the rest will be skipped.
For example, if there are two rules: the first rule allows the request
and the second rule denies it, when a request matches both rules, it will be allowed. | +| `defaultAction` | _[AuthorizationAction](#authorizationaction)_ | false | | DefaultAction defines the default action to be taken if no rules match.
If not specified, the default action is Deny. | + + +#### AuthorizationAction + +_Underlying type:_ _string_ + +AuthorizationAction defines the action to be taken if a rule matches. + +_Appears in:_ +- [Authorization](#authorization) +- [AuthorizationRule](#authorizationrule) + +| Value | Description | +| ----- | ----------- | +| `Allow` | AuthorizationActionAllow is the action to allow the request.
| +| `Deny` | AuthorizationActionDeny is the action to deny the request.
| + + +#### AuthorizationHeaderMatch + + + +AuthorizationHeaderMatch specifies how to match against the value of an HTTP header within a authorization rule. + +_Appears in:_ +- [Principal](#principal) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the HTTP header.
The header name is case-insensitive unless PreserveHeaderCase is set to true.
For example, "Foo" and "foo" are considered the same header. | +| `values` | _string array_ | true | | Values are the values that the header must match.
If multiple values are specified, the rule will match if any of the values match. | + + +#### AuthorizationRule + + + +AuthorizationRule defines a single authorization rule. + +_Appears in:_ +- [Authorization](#authorization) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | false | | Name is a user-friendly name for the rule.
If not specified, Envoy Gateway will generate a unique name for the rule. | +| `action` | _[AuthorizationAction](#authorizationaction)_ | true | | Action defines the action to be taken if the rule matches. | +| `operation` | _[Operation](#operation)_ | false | | Operation specifies the operation of a request, such as HTTP methods.
If not specified, all operations are matched on. | +| `principal` | _[Principal](#principal)_ | true | | Principal specifies the client identity of a request.
If there are multiple principal types, all principals must match for the rule to match.
For example, if there are two principals: one for client IP and one for JWT claim,
the rule will match only if both the client IP and the JWT claim match. | + + +#### BackOffPolicy + + + + + +_Appears in:_ +- [PerRetryPolicy](#perretrypolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `baseInterval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | BaseInterval is the base interval between retries. | +| `maxInterval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxInterval is the maximum interval between retries. This parameter is optional, but must be greater than or equal to the base_interval if set.
The default is 10 times the base_interval | + + +#### Backend + + + +Backend allows the user to configure the endpoints of a backend and +the behavior of the connection from Envoy Proxy to the backend. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`Backend` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[BackendSpec](#backendspec)_ | true | | Spec defines the desired state of Backend. | +| `status` | _[BackendStatus](#backendstatus)_ | true | | Status defines the current status of Backend. | + + +#### BackendCluster + + + +BackendCluster contains all the configuration required for configuring access +to a backend. This can include multiple endpoints, and settings that apply for +managing the connection to all these endpoints. + +_Appears in:_ +- [ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog) +- [ExtProc](#extproc) +- [GRPCExtAuthService](#grpcextauthservice) +- [HTTPExtAuthService](#httpextauthservice) +- [OIDCProvider](#oidcprovider) +- [OpenTelemetryEnvoyProxyAccessLog](#opentelemetryenvoyproxyaccesslog) +- [ProxyOpenTelemetrySink](#proxyopentelemetrysink) +- [RemoteJWKS](#remotejwks) +- [TracingProvider](#tracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | + + + + + + +#### BackendConnection + + + +BackendConnection allows users to configure connection-level settings of backend + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `bufferLimit` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | BufferLimit Soft limit on size of the cluster’s connections read and write buffers.
BufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it's in user space.
If unspecified, an implementation defined default is applied (32768 bytes).
For example, 20Mi, 1Gi, 256Ki etc.
Note: that when the suffix is not provided, the value is interpreted as bytes. | +| `preconnect` | _[PreconnectPolicy](#preconnectpolicy)_ | false | | Preconnect configures proactive upstream connections to reduce latency by establishing
connections before they’re needed and avoiding connection establishment overhead.
If unset, Envoy will fetch connections as needed to serve in-flight requests. | + + +#### BackendEndpoint + + + +BackendEndpoint describes a backend endpoint, which can be either a fully-qualified domain name, IP address or unix domain socket +corresponding to Envoy's Address: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-address + +_Appears in:_ +- [BackendSpec](#backendspec) +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostname` | _string_ | false | | Hostname defines an optional hostname for the backend endpoint. | +| `fqdn` | _[FQDNEndpoint](#fqdnendpoint)_ | false | | FQDN defines a FQDN endpoint | +| `ip` | _[IPEndpoint](#ipendpoint)_ | false | | IP defines an IP endpoint. Supports both IPv4 and IPv6 addresses. | +| `unix` | _[UnixSocket](#unixsocket)_ | false | | Unix defines the unix domain socket endpoint | +| `zone` | _string_ | false | | Zone defines the service zone of the backend endpoint. | + + +#### BackendMetrics + + + + + +_Appears in:_ +- [BackendTelemetry](#backendtelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `routeStatName` | _string_ | false | | RouteStatName defines the value of the Route stat_prefix, determining how the route stats are named.
For more details, see envoy docs: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-route
The supported operators for this pattern are:
%ROUTE_NAME%: name of Gateway API xRoute resource
%ROUTE_NAMESPACE%: namespace of Gateway API xRoute resource
%ROUTE_KIND%: kind of Gateway API xRoute resource
Example: %ROUTE_KIND%/%ROUTE_NAMESPACE%/%ROUTE_NAME% => httproute/my-ns/my-route
Disabled by default. | + + +#### BackendRef + + + +BackendRef defines how an ObjectReference that is specific to BackendRef. + +_Appears in:_ +- [ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog) +- [BackendCluster](#backendcluster) +- [ExtProc](#extproc) +- [GRPCExtAuthService](#grpcextauthservice) +- [HTTPExtAuthService](#httpextauthservice) +- [OIDCProvider](#oidcprovider) +- [OpenTelemetryEnvoyProxyAccessLog](#opentelemetryenvoyproxyaccesslog) +- [ProxyOpenTelemetrySink](#proxyopentelemetrysink) +- [RemoteJWKS](#remotejwks) +- [TracingProvider](#tracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `group` | _[Group](#group)_ | false | | Group is the group of the referent. For example, "gateway.networking.k8s.io".
When unspecified or empty string, core API group is inferred. | +| `kind` | _[Kind](#kind)_ | false | Service | Kind is the Kubernetes resource kind of the referent. For example
"Service".
Defaults to "Service" when not specified.
ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations SHOULD NOT
support ExternalName Services.
Support: Core (Services with a type other than ExternalName)
Support: Implementation-specific (Services with type ExternalName) | +| `name` | _[ObjectName](#objectname)_ | true | | Name is the name of the referent. | +| `namespace` | _[Namespace](#namespace)_ | false | | Namespace is the namespace of the backend. When unspecified, the local
namespace is inferred.
Note that when a namespace different than the local namespace is specified,
a ReferenceGrant object is required in the referent namespace to allow that
namespace's owner to accept the reference. See the ReferenceGrant
documentation for details.
Support: Core | +| `port` | _[PortNumber](#portnumber)_ | false | | Port specifies the destination port number to use for this resource.
Port is required when the referent is a Kubernetes Service. In this
case, the port number is the service port number, not the target port.
For other resources, destination port might be derived from the referent
resource or this field. | +| `weight` | _integer_ | false | 1 | Weight specifies the proportion of requests forwarded to the referenced
backend. This is computed as weight/(sum of all weights in this
BackendRefs list). For non-zero values, there may be some epsilon from
the exact proportion defined here depending on the precision an
implementation supports. Weight is not a percentage and the sum of
weights does not need to equal 100.
If only one backend is specified and it has a weight greater than 0, 100%
of the traffic is forwarded to that backend. If weight is set to 0, no
traffic should be forwarded for this entry. If unspecified, weight
defaults to 1.
Support for this field varies based on the context where used. | +| `fallback` | _boolean_ | false | | Fallback indicates whether the backend is designated as a fallback.
Multiple fallback backends can be configured.
It is highly recommended to configure active or passive health checks to ensure that failover can be detected
when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
the health of the active backends falls below 72%. | + + +#### BackendSpec + + + +BackendSpec describes the desired state of BackendSpec. + +_Appears in:_ +- [Backend](#backend) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[BackendType](#backendtype)_ | false | Endpoints | Type defines the type of the backend. Defaults to "Endpoints" | +| `endpoints` | _[BackendEndpoint](#backendendpoint) array_ | true | | Endpoints defines the endpoints to be used when connecting to the backend. | +| `appProtocols` | _[AppProtocolType](#appprotocoltype) array_ | false | | AppProtocols defines the application protocols to be supported when connecting to the backend. | +| `fallback` | _boolean_ | false | | Fallback indicates whether the backend is designated as a fallback.
It is highly recommended to configure active or passive health checks to ensure that failover can be detected
when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
the health of the active backends falls below 72%. | +| `tls` | _[BackendTLSSettings](#backendtlssettings)_ | false | | TLS defines the TLS settings for the backend.
If TLS is specified here and a BackendTLSPolicy is also configured for the backend, the final TLS settings will
be a merge of both configurations. In case of overlapping fields, the values defined in the BackendTLSPolicy will
take precedence. | + + +#### BackendStatus + + + +BackendStatus defines the state of Backend + +_Appears in:_ +- [Backend](#backend) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `conditions` | _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | false | | Conditions describe the current conditions of the Backend. | + + +#### BackendTLSConfig + + + +BackendTLSConfig describes the BackendTLS configuration for Envoy Proxy. + +_Appears in:_ +- [BackendTLSSettings](#backendtlssettings) +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `clientCertificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | false | | ClientCertificateRef defines the reference to a Kubernetes Secret that contains
the client certificate and private key for Envoy to use when connecting to
backend services and external services, such as ExtAuth, ALS, OpenTelemetry, etc.
This secret should be located within the same namespace as the Envoy proxy resource that references it. | +| `minVersion` | _[TLSVersion](#tlsversion)_ | false | | Min specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified. | +| `maxVersion` | _[TLSVersion](#tlsversion)_ | false | | Max specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified. | +| `ciphers` | _string array_ | false | | Ciphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
For the list of supported ciphers, please refer to the Envoy documentation:
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlsparameters
In non-FIPS Envoy Proxy builds the default cipher list is:
- [ECDHE-ECDSA-AES128-GCM-SHA256\|ECDHE-ECDSA-CHACHA20-POLY1305]
- [ECDHE-RSA-AES128-GCM-SHA256\|ECDHE-RSA-CHACHA20-POLY1305]
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
In builds using BoringSSL FIPS the default cipher list is:
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384 | +| `ecdhCurves` | _string array_ | false | | ECDHCurves specifies the set of supported ECDH curves.
In non-FIPS Envoy Proxy builds the default curves are:
- X25519
- P-256
In builds using BoringSSL FIPS the default curve is:
- P-256 | +| `signatureAlgorithms` | _string array_ | false | | SignatureAlgorithms specifies which signature algorithms the listener should
support. | +| `alpnProtocols` | _[ALPNProtocol](#alpnprotocol) array_ | false | | ALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener or used by the proxy to connect to the backend.
Defaults:
1. HTTPS Routes: h2 and http/1.1 are enabled in listener context.
2. Other Routes: ALPN is disabled.
3. Backends: proxy uses the appropriate ALPN options for the backend protocol.
When an empty list is provided, the ALPN TLS extension is disabled.
Defaults to [h2, http/1.1] if not specified.
Typical Supported values are:
- http/1.0
- http/1.1
- h2 | +| `fingerprints` | _[TLSFingerprintType](#tlsfingerprinttype) array_ | false | | Fingerprints specifies TLS client fingerprinting.
When specified, a JAX fingerprint derived from the client’s TLS handshake
is generated. The fingerprint can be logged in access logs or
forwarded to upstream services using request headers.
Fingerprinting is disabled if not specified.
Supported values are:
- JA3
- JA4 | + + +#### BackendTLSSettings + + + +BackendTLSSettings holds the TLS settings for the backend. + +_Appears in:_ +- [BackendSpec](#backendspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `caCertificateRefs` | _[LocalObjectReference](#localobjectreference) array_ | false | | CACertificateRefs contains one or more references to Kubernetes objects that
contain TLS certificates of the Certificate Authorities that can be used
as a trust anchor to validate the certificates presented by the backend.
A single reference to a Kubernetes ConfigMap or a Kubernetes Secret,
with the CA certificate in a key named `ca.crt` is currently supported.
If CACertificateRefs is empty or unspecified, then WellKnownCACertificates must be
specified. Only one of CACertificateRefs or WellKnownCACertificates may be specified,
not both. | +| `wellKnownCACertificates` | _[WellKnownCACertificatesType](#wellknowncacertificatestype)_ | false | | WellKnownCACertificates specifies whether system CA certificates may be used in
the TLS handshake between the gateway and backend pod.
If WellKnownCACertificates is unspecified or empty (""), then CACertificateRefs
must be specified with at least one entry for a valid configuration. Only one of
CACertificateRefs or WellKnownCACertificates may be specified, not both. | +| `insecureSkipVerify` | _boolean_ | false | false | InsecureSkipVerify indicates whether the upstream's certificate verification
should be skipped. Defaults to "false". | +| `sni` | _[PreciseHostname](#precisehostname)_ | false | | SNI is specifies the SNI value used when establishing an upstream TLS connection to the backend.
Envoy Gateway will use the HTTP host header value for SNI, when all resources referenced in BackendRefs are:
1. Backend resources that do not set SNI, or
2. Service/ServiceImport resources that do not have a BackendTLSPolicy attached to them
When a BackendTLSPolicy attaches to a Backend resource, the BackendTLSPolicy's Hostname value takes precedence
over this value. | + + +#### BackendTelemetry + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `tracing` | _[Tracing](#tracing)_ | false | | Tracing configures the tracing settings for the backend or HTTPRoute.
This takes precedence over EnvoyProxy tracing when set. | +| `metrics` | _[BackendMetrics](#backendmetrics)_ | false | | Metrics defines metrics configuration for the backend or Route. | + + +#### BackendTrafficPolicy + + + +BackendTrafficPolicy allows the user to configure the behavior of the connection +between the Envoy Proxy listener and the backend service. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`BackendTrafficPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | true | | spec defines the desired state of BackendTrafficPolicy. | +| `status` | _[PolicyStatus](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#policystatus)_ | true | | status defines the current status of BackendTrafficPolicy. | + + +#### BackendTrafficPolicySpec + + + +BackendTrafficPolicySpec defines the desired state of BackendTrafficPolicy. + +_Appears in:_ +- [BackendTrafficPolicy](#backendtrafficpolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `targetRef` | _[LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname)_ | true | | TargetRef is the name of the resource this policy is being attached to.
This policy and the TargetRef MUST be in the same namespace for this
Policy to have effect
Deprecated: use targetRefs/targetSelectors instead | +| `targetRefs` | _LocalPolicyTargetReferenceWithSectionName array_ | true | | TargetRefs are the names of the Gateway resources this policy
is being attached to. | +| `targetSelectors` | _[TargetSelector](#targetselector) array_ | true | | TargetSelectors allow targeting resources for this policy based on labels | +| `loadBalancer` | _[LoadBalancer](#loadbalancer)_ | false | | LoadBalancer policy to apply when routing traffic from the gateway to
the backend endpoints. Defaults to `LeastRequest`. | +| `retry` | _[Retry](#retry)_ | false | | Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions.
If not set, retry will be disabled. | +| `proxyProtocol` | _[ProxyProtocol](#proxyprotocol)_ | false | | ProxyProtocol enables the Proxy Protocol when communicating with the backend. | +| `tcpKeepalive` | _[TCPKeepalive](#tcpkeepalive)_ | false | | TcpKeepalive settings associated with the upstream client connection.
Disabled by default. | +| `healthCheck` | _[HealthCheck](#healthcheck)_ | false | | HealthCheck allows gateway to perform active health checking on backends. | +| `circuitBreaker` | _[CircuitBreaker](#circuitbreaker)_ | false | | Circuit Breaker settings for the upstream connections and requests.
If not set, circuit breakers will be enabled with the default thresholds | +| `timeout` | _[Timeout](#timeout)_ | false | | Timeout settings for the backend connections. | +| `connection` | _[BackendConnection](#backendconnection)_ | false | | Connection includes backend connection settings. | +| `dns` | _[DNS](#dns)_ | false | | DNS includes dns resolution settings. | +| `http2` | _[HTTP2Settings](#http2settings)_ | false | | HTTP2 provides HTTP/2 configuration for backend connections. | +| `mergeType` | _[MergeType](#mergetype)_ | false | | MergeType determines how this configuration is merged with existing BackendTrafficPolicy
configurations targeting a parent resource. When set, this configuration will be merged
into a parent BackendTrafficPolicy (i.e. the one targeting a Gateway or Listener).
This field cannot be set when targeting a parent resource (Gateway).
If unset, no merging occurs, and only the most specific configuration takes effect. | +| `rateLimit` | _[RateLimitSpec](#ratelimitspec)_ | false | | RateLimit allows the user to limit the number of incoming requests
to a predefined value based on attributes within the traffic flow. | +| `bandwidthLimit` | _[BandwidthLimitSpec](#bandwidthlimitspec)_ | false | | BandwidthLimit allows the user to limit the bandwidth of traffic
sent to and received from the backend. | +| `faultInjection` | _[FaultInjection](#faultinjection)_ | false | | FaultInjection defines the fault injection policy to be applied. This configuration can be used to
inject delays and abort requests to mimic failure scenarios such as service failures and overloads | +| `admissionControl` | _[AdmissionControl](#admissioncontrol)_ | false | | AdmissionControl defines the admission control policy to be applied. This configuration
probabilistically rejects requests based on the success rate of previous requests in a
configurable sliding time window. | +| `useClientProtocol` | _boolean_ | false | | UseClientProtocol configures Envoy to prefer sending requests to backends using
the same HTTP protocol that the incoming request used. Defaults to false, which means
that Envoy will use the protocol indicated by the attached BackendRef. | +| `compression` | _[Compression](#compression) array_ | false | | The compression config for the http streams.
Deprecated: Use Compressor instead. | +| `compressor` | _[Compression](#compression) array_ | false | | The compressor config for the http streams.
This provides more granular control over compression configuration.
Order matters: The first compressor in the list is preferred when q-values in Accept-Encoding are equal. | +| `responseOverride` | _[ResponseOverride](#responseoverride) array_ | false | | ResponseOverride defines the configuration to override specific responses with a custom one.
If multiple configurations are specified, the first one to match wins. | +| `httpUpgrade` | _[ProtocolUpgradeConfig](#protocolupgradeconfig) array_ | false | | HTTPUpgrade defines the configuration for HTTP protocol upgrades.
If not specified, the default upgrade configuration (websocket) will be used.
However, if requestBuffer is configured, the default upgrade configuration
will be ignored. | +| `requestBuffer` | _[RequestBuffer](#requestbuffer)_ | false | | RequestBuffer allows the gateway to buffer and fully receive each request from a client before continuing to send the request
upstream to the backends. This can be helpful to shield your backend servers from slow clients, and also to enforce a maximum size per request
as any requests larger than the buffer size will be rejected.
This can have a negative performance impact so should only be enabled when necessary.
When enabling this option, you should also configure your connection buffer size to account for these request buffers. There will also be an
increase in memory usage for Envoy that should be accounted for in your deployment settings.
Request buffering is incompatible with streaming APIs and protocol upgrades such as gRPC streaming and WebSocket. Do not enable this option
on routes that need those protocols, because requests can hang instead of being forwarded upstream. | +| `telemetry` | _[BackendTelemetry](#backendtelemetry)_ | false | | Telemetry configures the telemetry settings for the policy target (Gateway or xRoute).
This will override the telemetry settings in the EnvoyProxy resource. | +| `routingType` | _[RoutingType](#routingtype)_ | false | | RoutingType can be set to "Service" to use the Service Cluster IP for routing to the backend,
or it can be set to "Endpoint" to use Endpoint routing.
When specified, this overrides the EnvoyProxy-level setting for the relevant targetRefs.
If not specified, the EnvoyProxy-level setting is used. | + + +#### BackendType + +_Underlying type:_ _string_ + +BackendType defines the type of the Backend. + +_Appears in:_ +- [BackendSpec](#backendspec) + +| Value | Description | +| ----- | ----------- | +| `Endpoints` | BackendTypeEndpoints defines the type of the backend as Endpoints.
| +| `DynamicResolver` | BackendTypeDynamicResolver defines the type of the backend as DynamicResolver.
When a backend is of type DynamicResolver, the Envoy will resolve the upstream
ip address and port from the host header of the incoming request. If the ip address
is directly set in the host header, the Envoy will use the ip address and port as the
upstream address. If the hostname is set in the host header, the Envoy will resolve the
ip address and port from the hostname using the DNS resolver.
| + + +#### BackendUtilization + + + +BackendUtilization defines configuration for Envoy's Backend Utilization policy. +It uses Open Resource Cost Application (ORCA) load metrics reported by endpoints to make load balancing decisions. +These metrics are typically sent by the backend service in response headers or trailers. + +The backend should report these metrics in header/trailer as one of the following formats: +- Binary: `endpoint-load-metrics-bin` with base64-encoded serialized `OrcaLoadReport` proto. +- JSON: `endpoint-load-metrics` with JSON-encoded `OrcaLoadReport` proto, e.g., `JSON {"cpu_utilization": 0.3}`. +- TEXT: `endpoint-load-metrics` with comma-separated key-value pairs, e.g., `TEXT cpu=0.3,mem=0.8`. + +By default, Envoy Gateway removes these ORCA response headers/trailers before sending the response to the client +(see KeepResponseHeaders). If you need the downstream client to see them, set KeepResponseHeaders to true. + +See Envoy proto: envoy.extensions.load_balancing_policies.client_side_weighted_round_robin.v3.ClientSideWeightedRoundRobin +See ORCA Load Report proto: xds.data.orca.v3.orca_load_report.proto + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `blackoutPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | A given endpoint must report load metrics continuously for at least this long before the endpoint weight will be used.
Default is 10s. | +| `weightExpirationPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | If a given endpoint has not reported load metrics in this long, stop using the reported weight. Defaults to 3m. | +| `weightUpdatePeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | How often endpoint weights are recalculated. Values less than 100ms are capped at 100ms. Default 1s. | +| `errorUtilizationPenaltyPercent` | _integer_ | false | | ErrorUtilizationPenaltyPercent adjusts endpoint weights based on the error rate (eps/qps).
This is expressed as a percentage-based integer where 100 represents 1.0, 150 represents 1.5, etc.
For example:
- 100 => 1.0x
- 120 => 1.2x
- 200 => 2.0x
Must be non-negative. | +| `metricNamesForComputingUtilization` | _string array_ | false | | Metric names used to compute utilization if application_utilization is not set.
For map fields in ORCA proto, use the form ".", e.g., "named_metrics.foo". | +| `keepResponseHeaders` | _boolean_ | false | false | KeepResponseHeaders keeps the ORCA load report headers/trailers before sending the response to the client.
Defaults to false. | + + +#### BandwidthLimitRequestConfig + + + +BandwidthLimitRequestConfig defines the bandwidth limit configuration for the request direction. + +_Appears in:_ +- [BandwidthLimitSpec](#bandwidthlimitspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `limit` | _[BandwidthLimitValue](#bandwidthlimitvalue)_ | true | | Limit specifies the bandwidth limit as a bytes-per-unit throughput rate. | + + +#### BandwidthLimitResponseConfig + + + +BandwidthLimitResponseConfig defines the bandwidth limit configuration for the response direction. + +_Appears in:_ +- [BandwidthLimitSpec](#bandwidthlimitspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `limit` | _[BandwidthLimitValue](#bandwidthlimitvalue)_ | true | | Limit specifies the bandwidth limit as a bytes-per-unit throughput rate. | +| `responseTrailers` | _[BandwidthLimitResponseTrailers](#bandwidthlimitresponsetrailers)_ | false | | ResponseTrailers configures the trailer headers appended to responses
when bandwidth limiting introduces delays. | + + +#### BandwidthLimitResponseTrailers + + + +BandwidthLimitResponseTrailers defines the trailer headers appended to responses. + +_Appears in:_ +- [BandwidthLimitResponseConfig](#bandwidthlimitresponseconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `prefix` | _string_ | false | | Prefix is prepended to each trailer header name.
If not set, no prefix is added and the trailers are named as-is.
For example, setting "x-eg" produces trailers such as "x-eg-bandwidth-request-delay-ms",
while leaving it unset produces "bandwidth-request-delay-ms".
The following four trailers can be added:
"bandwidth-request-delay-ms" is delay time in milliseconds it took for the request stream transfer
including request body transfer time and the time added by the filter.
"bandwidth-response-delay-ms" is delay time in milliseconds it took for the response stream transfer
including response body transfer time and the time added by the filter.
"bandwidth-request-filter-delay-ms" is delay time in milliseconds in request stream transfer added by the filter.
"bandwidth-response-filter-delay-ms" is delay time in milliseconds that added by the filter. | + + +#### BandwidthLimitSpec + + + +BandwidthLimitSpec defines the desired state of BandwidthLimit. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `request` | _[BandwidthLimitRequestConfig](#bandwidthlimitrequestconfig)_ | false | | Request configures bandwidth limits for traffic sent to the backend. | +| `response` | _[BandwidthLimitResponseConfig](#bandwidthlimitresponseconfig)_ | false | | Response configures bandwidth limits for traffic sent from the backend. | + + +#### BandwidthLimitUnit + +_Underlying type:_ _string_ + +BandwidthLimitUnit specifies the intervals for setting bandwidth limits. +Valid BandwidthLimitUnit values are "Second", "Minute", "Hour". + +_Appears in:_ +- [BandwidthLimitValue](#bandwidthlimitvalue) + +| Value | Description | +| ----- | ----------- | +| `Second` | BandwidthLimitUnitSecond specifies the bandwidth limit interval to be 1 second.
| +| `Minute` | BandwidthLimitUnitMinute specifies the bandwidth limit interval to be 1 minute.
| +| `Hour` | BandwidthLimitUnitHour specifies the bandwidth limit interval to be 1 hour.
| + + +#### BandwidthLimitValue + + + +BandwidthLimitValue defines the bandwidth limit value and its time unit. + +_Appears in:_ +- [BandwidthLimitRequestConfig](#bandwidthlimitrequestconfig) +- [BandwidthLimitResponseConfig](#bandwidthlimitresponseconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `value` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | true | | Value specifies the bandwidth limit. | +| `unit` | _[BandwidthLimitUnit](#bandwidthlimitunit)_ | true | | Unit specifies the time unit for the bandwidth limit (e.g. Second, Minute, Hour). | + + +#### BasicAuth + + + +BasicAuth defines the configuration for the HTTP Basic Authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `users` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | true | | The Kubernetes secret which contains the username-password pairs in
htpasswd format, used to verify user credentials in the "Authorization"
header.
This is an Opaque secret. The username-password pairs should be stored in
the key ".htpasswd". As the key name indicates, the value needs to be the
htpasswd format, for example: "user1:\{SHA\}hashed_user1_password".
Right now, only SHA hash algorithm is supported.
Reference to https://httpd.apache.org/docs/2.4/programs/htpasswd.html
for more details. | +| `forwardUsernameHeader` | _string_ | false | | This field specifies the header name to forward a successfully authenticated user to
the backend. The header will be added to the request with the username as the value.
If it is not specified, the username will not be forwarded. | + + +#### BodyToExtAuth + + + +BodyToExtAuth defines the Body to Ext Auth configuration + +_Appears in:_ +- [ExtAuth](#extauth) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `maxRequestBytes` | _integer_ | true | | MaxRequestBytes is the maximum size of a message body that the filter will hold in memory.
Envoy will return HTTP 413 and will not initiate the authorization process when buffer
reaches the number set in this field.
Note that this setting will have precedence over failOpen mode. | + + +#### BootstrapType + +_Underlying type:_ _string_ + +BootstrapType defines the types of bootstrap supported by Envoy Gateway. + +_Appears in:_ +- [ProxyBootstrap](#proxybootstrap) + +| Value | Description | +| ----- | ----------- | +| `Merge` | Merge merges the provided bootstrap with the default one. The provided bootstrap can add or override a value
within a map, or add a new value to a list.
Please note that the provided bootstrap can't override a value within a list.
| +| `Replace` | Replace replaces the default bootstrap with the provided one.
| +| `JSONPatch` | JSONPatch applies the provided JSONPatches to the default bootstrap.
| + + +#### BrotliCompressor + + + +BrotliCompressor defines the config for the Brotli compressor. +The default values can be found here: +https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/compression/brotli/compressor/v3/brotli.proto#extension-envoy-compression-brotli-compressor + +_Appears in:_ +- [Compression](#compression) + + + +#### CIDR + +_Underlying type:_ _string_ + +CIDR defines a CIDR Address range. +A CIDR can be an IPv4 address range such as "192.168.1.0/24" or an IPv6 address range such as "2001:0db8:11a3:09d7::/64". + +_Appears in:_ +- [Principal](#principal) +- [XForwardedForSettings](#xforwardedforsettings) + + + +#### CORS + + + +CORS defines the configuration for Cross-Origin Resource Sharing (CORS). + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `allowOrigins` | _[Origin](#origin) array_ | false | | AllowOrigins defines the origins that are allowed to make requests.
It specifies the allowed origins in the Access-Control-Allow-Origin CORS response header.
The value "*" allows any origin to make requests. | +| `allowMethods` | _string array_ | false | | AllowMethods defines the methods that are allowed to make requests.
It specifies the allowed methods in the Access-Control-Allow-Methods CORS response header..
The value "*" allows any method to be used. | +| `allowHeaders` | _string array_ | false | | AllowHeaders defines the headers that are allowed to be sent with requests.
It specifies the allowed headers in the Access-Control-Allow-Headers CORS response header..
The value "*" allows any header to be sent. | +| `exposeHeaders` | _string array_ | false | | ExposeHeaders defines which response headers should be made accessible to
scripts running in the browser.
It specifies the headers in the Access-Control-Expose-Headers CORS response header..
The value "*" allows any header to be exposed. | +| `maxAge` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxAge defines how long the results of a preflight request can be cached.
It specifies the value in the Access-Control-Max-Age CORS response header.. | +| `allowCredentials` | _boolean_ | false | | AllowCredentials indicates whether a request can include user credentials
like cookies, authentication headers, or TLS client certificates.
It specifies the value in the Access-Control-Allow-Credentials CORS response header. | + + +#### CircuitBreaker + + + +CircuitBreaker defines the Circuit Breaker configuration. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `maxConnections` | _integer_ | false | 1024 | The maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule. | +| `maxPendingRequests` | _integer_ | false | 1024 | The maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule. | +| `maxParallelRequests` | _integer_ | false | 1024 | The maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule. | +| `maxParallelRetries` | _integer_ | false | 1024 | The maximum number of parallel retries that Envoy will make to the referenced backend defined within a xRoute rule. | +| `maxRequestsPerConnection` | _integer_ | false | | The maximum number of requests that Envoy will make over a single connection to the referenced backend defined within a xRoute rule.
Default: unlimited. | +| `perEndpoint` | _[PerEndpointCircuitBreakers](#perendpointcircuitbreakers)_ | false | | PerEndpoint defines Circuit Breakers that will apply per-endpoint for an upstream cluster | +| `retryBudget` | _[RetryBudget](#retrybudget)_ | false | | RetryBudget provides settings for retry budget, which limits the number of retries in a given percentage.
RetryBudget take precedence over maxParallelRetries. | + + +#### ClaimToHeader + + + +ClaimToHeader defines a configuration to convert JWT claims into HTTP headers + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `header` | _string_ | true | | Header defines the name of the HTTP request header that the JWT Claim will be saved into. | +| `claim` | _string_ | true | | Claim is the JWT Claim that should be saved into the header : it can be a nested claim of type
(eg. "claim.nested.key", "sub"). The nested claim name must use dot "."
to separate the JSON name path. | + + +#### ClientConnection + + + +ClientConnection allows users to configure connection-level settings of client + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `connectionLimit` | _[ConnectionLimit](#connectionlimit)_ | false | | ConnectionLimit defines limits related to connections | +| `bufferLimit` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | BufferLimit provides configuration for the maximum buffer size in bytes for each incoming connection.
BufferLimit applies to connection streaming (maybe non-streaming) channel between processes, it's in user space.
For example, 20Mi, 1Gi, 256Ki etc.
Note that when the suffix is not provided, the value is interpreted as bytes.
Default: 32768 bytes. | +| `maxAcceptPerSocketEvent` | _integer_ | false | 1 | MaxAcceptPerSocketEvent provides configuration for the maximum number of connections to accept from the kernel
per socket event. If there are more than MaxAcceptPerSocketEvent connections pending accept, connections over
this threshold will be accepted in later event loop iterations.
Defaults to 1 and can be disabled by setting to 0 for allowing unlimited accepted connections. | + + +#### ClientIPDetectionSettings + + + +ClientIPDetectionSettings provides configuration for determining the original client IP address for requests. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `xForwardedFor` | _[XForwardedForSettings](#xforwardedforsettings)_ | false | | XForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address. | +| `customHeader` | _[CustomHeaderExtensionSettings](#customheaderextensionsettings)_ | false | | CustomHeader provides configuration for determining the client IP address for a request based on
a trusted custom HTTP header. This uses the custom_header original IP detection extension.
Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto
for more details. | + + +#### ClientIPGeoLocation + + + +ClientIPGeoLocation specifies geolocation-based match criteria for authorization. + +_Appears in:_ +- [Principal](#principal) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `country` | _string_ | false | | Country is the country ISO code associated with the client IP. | +| `region` | _string_ | false | | Region is the region ISO code associated with the client IP. | +| `city` | _string_ | false | | City is the city associated with the client IP. | +| `asn` | _integer_ | false | | ASN is the autonomous system number associated with the client IP. | +| `isp` | _string_ | false | | ISP is the internet service provider associated with the client IP. | +| `anonymous` | _[GeoIPAnonymousMatch](#geoipanonymousmatch)_ | false | | Anonymous matches anonymous network detection signals. | + + +#### ClientTLSSettings + + + + + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `clientValidation` | _[ClientValidationContext](#clientvalidationcontext)_ | false | | ClientValidation specifies the configuration to validate the client
initiating the TLS connection to the Gateway listener. | +| `minVersion` | _[TLSVersion](#tlsversion)_ | false | | Min specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified. | +| `maxVersion` | _[TLSVersion](#tlsversion)_ | false | | Max specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified. | +| `ciphers` | _string array_ | false | | Ciphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
For the list of supported ciphers, please refer to the Envoy documentation:
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlsparameters
In non-FIPS Envoy Proxy builds the default cipher list is:
- [ECDHE-ECDSA-AES128-GCM-SHA256\|ECDHE-ECDSA-CHACHA20-POLY1305]
- [ECDHE-RSA-AES128-GCM-SHA256\|ECDHE-RSA-CHACHA20-POLY1305]
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
In builds using BoringSSL FIPS the default cipher list is:
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384 | +| `ecdhCurves` | _string array_ | false | | ECDHCurves specifies the set of supported ECDH curves.
In non-FIPS Envoy Proxy builds the default curves are:
- X25519
- P-256
In builds using BoringSSL FIPS the default curve is:
- P-256 | +| `signatureAlgorithms` | _string array_ | false | | SignatureAlgorithms specifies which signature algorithms the listener should
support. | +| `alpnProtocols` | _[ALPNProtocol](#alpnprotocol) array_ | false | | ALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener or used by the proxy to connect to the backend.
Defaults:
1. HTTPS Routes: h2 and http/1.1 are enabled in listener context.
2. Other Routes: ALPN is disabled.
3. Backends: proxy uses the appropriate ALPN options for the backend protocol.
When an empty list is provided, the ALPN TLS extension is disabled.
Defaults to [h2, http/1.1] if not specified.
Typical Supported values are:
- http/1.0
- http/1.1
- h2 | +| `fingerprints` | _[TLSFingerprintType](#tlsfingerprinttype) array_ | false | | Fingerprints specifies TLS client fingerprinting.
When specified, a JAX fingerprint derived from the client’s TLS handshake
is generated. The fingerprint can be logged in access logs or
forwarded to upstream services using request headers.
Fingerprinting is disabled if not specified.
Supported values are:
- JA3
- JA4 | +| `session` | _[Session](#session)_ | false | | Session defines settings related to TLS session management. | + + +#### ClientTimeout + + + + + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `tcp` | _[TCPClientTimeout](#tcpclienttimeout)_ | false | | Timeout settings for TCP. | +| `http` | _[HTTPClientTimeout](#httpclienttimeout)_ | false | | Timeout settings for HTTP. | + + +#### ClientTrafficPolicy + + + +ClientTrafficPolicy allows the user to configure the behavior of the connection +between the downstream client and Envoy Proxy listener. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`ClientTrafficPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[ClientTrafficPolicySpec](#clienttrafficpolicyspec)_ | true | | Spec defines the desired state of ClientTrafficPolicy. | +| `status` | _[PolicyStatus](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#policystatus)_ | true | | Status defines the current status of ClientTrafficPolicy. | + + +#### ClientTrafficPolicySpec + + + +ClientTrafficPolicySpec defines the desired state of ClientTrafficPolicy. + +_Appears in:_ +- [ClientTrafficPolicy](#clienttrafficpolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `targetRef` | _[LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname)_ | true | | TargetRef is the name of the resource this policy is being attached to.
This policy and the TargetRef MUST be in the same namespace for this
Policy to have effect
Deprecated: use targetRefs/targetSelectors instead | +| `targetRefs` | _LocalPolicyTargetReferenceWithSectionName array_ | true | | TargetRefs are the names of the Gateway resources this policy
is being attached to. | +| `targetSelectors` | _[TargetSelector](#targetselector) array_ | true | | TargetSelectors allow targeting resources for this policy based on labels | +| `tcpKeepalive` | _[TCPKeepalive](#tcpkeepalive)_ | false | | TcpKeepalive settings associated with the downstream client connection.
If defined, sets SO_KEEPALIVE on the listener socket to enable TCP Keepalives.
Disabled by default. | +| `enableProxyProtocol` | _boolean_ | false | | EnableProxyProtocol interprets the ProxyProtocol header and adds the
Client Address into the X-Forwarded-For header.
Note Proxy Protocol must be present when this field is set, else the connection
is closed.
Deprecated: Use ProxyProtocol instead. | +| `proxyProtocol` | _[ProxyProtocolSettings](#proxyprotocolsettings)_ | false | | ProxyProtocol configures the Proxy Protocol settings. When configured,
the Proxy Protocol header will be interpreted and the Client Address
will be added into the X-Forwarded-For header.
If both EnableProxyProtocol and ProxyProtocol are set, ProxyProtocol takes precedence. | +| `clientIPDetection` | _[ClientIPDetectionSettings](#clientipdetectionsettings)_ | false | | ClientIPDetectionSettings provides configuration for determining the original client IP address for requests. | +| `tls` | _[ClientTLSSettings](#clienttlssettings)_ | false | | TLS settings configure TLS termination settings with the downstream client. | +| `path` | _[PathSettings](#pathsettings)_ | false | | Path enables managing how the incoming path set by clients can be normalized. | +| `headers` | _[HeaderSettings](#headersettings)_ | false | | HeaderSettings provides configuration for header management. | +| `timeout` | _[ClientTimeout](#clienttimeout)_ | false | | Timeout settings for the client connections. | +| `connection` | _[ClientConnection](#clientconnection)_ | false | | Connection includes client connection settings. | +| `http1` | _[HTTP1Settings](#http1settings)_ | false | | HTTP1 provides HTTP/1 configuration on the listener. | +| `http2` | _[HTTP2Settings](#http2settings)_ | false | | HTTP2 provides HTTP/2 configuration on the listener. | +| `http3` | _[HTTP3Settings](#http3settings)_ | false | | HTTP3 provides HTTP/3 configuration on the listener. | +| `grpc` | _[GRPCSettings](#grpcsettings)_ | false | | GRPC provides gRPC configuration on the listener. | +| `healthCheck` | _[HealthCheckSettings](#healthchecksettings)_ | false | | HealthCheck provides configuration for determining whether the HTTP/HTTPS listener is healthy. | +| `scheme` | _[SchemeHeaderTransform](#schemeheadertransform)_ | false | | Scheme configures how the :scheme pseudo-header is set for requests forwarded to backends.
- Preserve (default): Preserves the :scheme from the original client request.
Use this when backends need to know the original client scheme for URL generation or redirects.
- MatchBackend: Sets the :scheme to match the backend transport protocol.
If the backend uses TLS, the scheme is "https", otherwise "http".
Use this when backends require the scheme to match the actual transport protocol,
such as strictly HTTPS services that validate the :scheme header. | + + +#### ClientValidationContext + + + +ClientValidationContext holds configuration that can be used to validate the client initiating the TLS connection +to the Gateway. +By default, no client specific configuration is validated. + +_Appears in:_ +- [ClientTLSSettings](#clienttlssettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `optional` | _boolean_ | false | | Optional set to true accepts connections even when a client doesn't present a certificate.
Defaults to false, which rejects connections without a valid client certificate.
Deprecated: Use Mode instead. | +| `mode` | _[ClientValidationModeType](#clientvalidationmodetype)_ | false | | Mode defines how the Gateway or Listener validates client certificates.
If not specified, defaults to RequireAndVerify. | +| `caCertificateRefs` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference) array_ | false | | CACertificateRefs contains one or more references to
Kubernetes objects that contain TLS certificates of
the Certificate Authorities that can be used
as a trust anchor to validate the certificates presented by the client.
A single reference to a Kubernetes ConfigMap or a Kubernetes Secret,
with the CA certificate in a key named `ca.crt` is currently supported.
References to a resource in different namespace are invalid UNLESS there
is a ReferenceGrant in the target namespace that allows the certificate
to be attached. | +| `spkiHashes` | _string array_ | false | | An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will
verify that the SHA-256 of the DER-encoded Subject Public Key Information
(SPKI) of the presented certificate matches one of the specified values. | +| `certificateHashes` | _string array_ | false | | An optional list of hex-encoded SHA-256 hashes. If specified, Envoy will
verify that the SHA-256 of the DER-encoded presented certificate matches
one of the specified values. | +| `subjectAltNames` | _[SubjectAltNames](#subjectaltnames)_ | false | | An optional list of Subject Alternative name matchers. If specified, Envoy
will verify that the Subject Alternative Name of the presented certificate
matches one of the specified matchers | +| `crl` | _[CrlContext](#crlcontext)_ | false | | Crl specifies the crl configuration that can be used to validate the client initiating the TLS connection | + + +#### ClientValidationModeType + +_Underlying type:_ _string_ + +ClientValidationModeType defines how a Gateway or Listener validates client certificates. + +_Appears in:_ +- [ClientValidationContext](#clientvalidationcontext) + +| Value | Description | +| ----- | ----------- | +| `Request` | Request indicates that a client certificate is requested
during the TLS handshake but does not require one.
| +| `RequireAny` | RequireAny indicates that a client certificate is required during
the handshake, but the connection is permitted even when the
client certificate verification fails.
| +| `VerifyIfGiven` | VerifyIfGiven indicates that a client certificate is requested
but not required. If presented, the certificate must be valid.
| +| `RequireAndVerify` | RequireAndVerify indicates that a valid client certificate must be
presented during the handshake and validated
using CA certificates defined in CACertificateRefs.
| + + +#### ClusterSettings + + + +ClusterSettings provides the various knobs that can be set to control how traffic to a given +backend will be configured. + +_Appears in:_ +- [ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog) +- [BackendCluster](#backendcluster) +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ExtProc](#extproc) +- [GRPCExtAuthService](#grpcextauthservice) +- [HTTPExtAuthService](#httpextauthservice) +- [OIDCProvider](#oidcprovider) +- [OpenTelemetryEnvoyProxyAccessLog](#opentelemetryenvoyproxyaccesslog) +- [ProxyOpenTelemetrySink](#proxyopentelemetrysink) +- [RemoteJWKS](#remotejwks) +- [TracingProvider](#tracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `loadBalancer` | _[LoadBalancer](#loadbalancer)_ | false | | LoadBalancer policy to apply when routing traffic from the gateway to
the backend endpoints. Defaults to `LeastRequest`. | +| `retry` | _[Retry](#retry)_ | false | | Retry provides more advanced usage, allowing users to customize the number of retries, retry fallback strategy, and retry triggering conditions.
If not set, retry will be disabled. | +| `proxyProtocol` | _[ProxyProtocol](#proxyprotocol)_ | false | | ProxyProtocol enables the Proxy Protocol when communicating with the backend. | +| `tcpKeepalive` | _[TCPKeepalive](#tcpkeepalive)_ | false | | TcpKeepalive settings associated with the upstream client connection.
Disabled by default. | +| `healthCheck` | _[HealthCheck](#healthcheck)_ | false | | HealthCheck allows gateway to perform active health checking on backends. | +| `circuitBreaker` | _[CircuitBreaker](#circuitbreaker)_ | false | | Circuit Breaker settings for the upstream connections and requests.
If not set, circuit breakers will be enabled with the default thresholds | +| `timeout` | _[Timeout](#timeout)_ | false | | Timeout settings for the backend connections. | +| `connection` | _[BackendConnection](#backendconnection)_ | false | | Connection includes backend connection settings. | +| `dns` | _[DNS](#dns)_ | false | | DNS includes dns resolution settings. | +| `http2` | _[HTTP2Settings](#http2settings)_ | false | | HTTP2 provides HTTP/2 configuration for backend connections. | + + +#### ClusterTranslationConfig + + + + + +_Appears in:_ +- [TranslationConfig](#translationconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `includeAll` | _boolean_ | false | | IncludeAll defines whether all clusters should be included in the translation hook.
Default is true for backward compatibility. | + + +#### Compression + + + +Compression defines the config of enabling compression. +This can help reduce the bandwidth at the expense of higher CPU. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ProxyPrometheusProvider](#proxyprometheusprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[CompressorType](#compressortype)_ | true | | CompressorType defines the compressor type to use for compression. | +| `brotli` | _[BrotliCompressor](#brotlicompressor)_ | false | | The configuration for Brotli compressor. | +| `gzip` | _[GzipCompressor](#gzipcompressor)_ | false | | The configuration for GZIP compressor. | +| `zstd` | _[ZstdCompressor](#zstdcompressor)_ | false | | The configuration for Zstd compressor. | +| `minContentLength` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | MinContentLength defines the minimum response size in bytes to apply compression.
Responses smaller than this threshold will not be compressed.
Must be at least 30 bytes as enforced by Envoy Proxy.
Note that when the suffix is not provided, the value is interpreted as bytes.
Default: 30 bytes | + + +#### CompressorType + +_Underlying type:_ _string_ + +CompressorType defines the types of compressor library supported by Envoy Gateway. + +_Appears in:_ +- [Compression](#compression) + +| Value | Description | +| ----- | ----------- | +| `Gzip` | | +| `Brotli` | | +| `Zstd` | | + + +#### ConnectConfig + + + + + +_Appears in:_ +- [ProtocolUpgradeConfig](#protocolupgradeconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `terminate` | _boolean_ | false | | Terminate the CONNECT request, and forwards the payload as raw TCP data. | + + +#### ConnectionLimit + + + + + +_Appears in:_ +- [ClientConnection](#clientconnection) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `value` | _integer_ | false | | Value of the maximum concurrent connections limit.
When the limit is reached, incoming connections will be closed after the CloseDelay duration. | +| `closeDelay` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | CloseDelay defines the delay to use before closing connections that are rejected
once the limit value is reached.
Default: none. | +| `maxConnectionDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxConnectionDuration is the maximum amount of time a connection can remain established
(usually via TCP/HTTP Keepalive packets) before being drained and/or closed.
If not specified, there is no limit. | +| `maxRequestsPerConnection` | _integer_ | false | | MaxRequestsPerConnection defines the maximum number of requests allowed over a single connection.
If not specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive. | +| `maxStreamDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxStreamDuration is the maximum amount of time to keep alive an http stream. When the limit is reached
the stream will be reset independent of any other timeouts. If not specified, no value is set. | + + +#### ConsistentHash + + + +ConsistentHash defines the configuration related to the consistent hash +load balancer policy. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ConsistentHashType](#consistenthashtype)_ | true | | ConsistentHashType defines the type of input to hash on. Valid Type values are
"SourceIP",
"Header",
"Headers",
"Cookie".
"QueryParams". | +| `header` | _[Header](#header)_ | false | | Header configures the header hash policy when the consistent hash type is set to Header.
Deprecated: use Headers instead | +| `headers` | _[Header](#header) array_ | false | | Headers configures the header hash policy for each header, when the consistent hash type is set to Headers. | +| `cookie` | _[Cookie](#cookie)_ | false | | Cookie configures the cookie hash policy when the consistent hash type is set to Cookie. | +| `queryParams` | _[QueryParam](#queryparam) array_ | false | | QueryParams configures the query parameter hash policy when the consistent hash type is set to QueryParams. | +| `tableSize` | _integer_ | false | 65537 | The table size for consistent hashing, must be prime number limited to 5000011. | + + +#### ConsistentHashType + +_Underlying type:_ _string_ + +ConsistentHashType defines the type of input to hash on. + +_Appears in:_ +- [ConsistentHash](#consistenthash) + +| Value | Description | +| ----- | ----------- | +| `SourceIP` | SourceIPConsistentHashType hashes based on the source IP address.
| +| `Header` | HeaderConsistentHashType hashes based on a request header.
Deprecated: use HeadersConsistentHashType instead
| +| `Headers` | HeadersConsistentHashType hashes based on multiple request headers.
| +| `Cookie` | CookieConsistentHashType hashes based on a cookie.
| +| `QueryParams` | QueryParamsConsistentHashType hashes based on a multiple query parameter.
| + + +#### ContextExtension + + + +ContextExtension is analogous to http_request.headers, however these +contents will not be sent to the upstream server. This provides an +extension mechanism for sending additional information to the auth server +without modifying the proto definition. It maps to the internal opaque +context in the filter chain. + +_Appears in:_ +- [ExtAuth](#extauth) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the context extension. | +| `type` | _[ContextExtensionValueType](#contextextensionvaluetype)_ | true | Value | Type is the type of method to use to read the ContextExtension value.
Valid values are Value and ValueRef, default is Value. | +| `value` | _string_ | false | | Value of the context extension. | +| `valueRef` | _[LocalObjectKeyReference](#localobjectkeyreference)_ | false | | ValueRef for the context extension's value. | + + +#### ContextExtensionValueType + +_Underlying type:_ _string_ + +ContextExtensionValueType defines the types of values for ContextExtension supported by Envoy Gateway. + +_Appears in:_ +- [ContextExtension](#contextextension) + +| Value | Description | +| ----- | ----------- | +| `Value` | ContextExtensionValueTypeValue defines the "Value" ContextExtension type.
| +| `ValueRef` | ContextExtensionValueTypeValueRef defines the "ValueRef" ContextExtension type.
| + + +#### Cookie + + + +Cookie defines the cookie hashing configuration for consistent hash based +load balancing. + +_Appears in:_ +- [ConsistentHash](#consistenthash) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the cookie to hash.
If this cookie does not exist in the request, Envoy will generate a cookie and set
the TTL on the response back to the client based on Layer 4
attributes of the backend endpoint, to ensure that these future requests
go to the same backend endpoint. Make sure to set the TTL field for this case. | +| `ttl` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | TTL of the generated cookie if the cookie is not present. This value sets the
Max-Age attribute value. | +| `attributes` | _object (keys:string, values:string)_ | false | | Additional Attributes to set for the generated cookie. | + + +#### CookieMatchType + +_Underlying type:_ _string_ + +CookieMatchType specifies the semantics of how cookie values should be compared. +Valid CookieMatchType values are "Exact" and "RegularExpression". + +_Appears in:_ +- [HTTPCookieMatch](#httpcookiematch) + +| Value | Description | +| ----- | ----------- | +| `Exact` | CookieMatchExact matches the exact value of the cookie.
| +| `RegularExpression` | CookieMatchRegularExpression matches a regular expression against the value of the cookie.
The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax.
| + + +#### CrlContext + + + +CrlContext holds certificate revocation list configuration that can be used to validate the client initiating the TLS connection + +_Appears in:_ +- [ClientValidationContext](#clientvalidationcontext) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `refs` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference) array_ | true | | Refs contains one or more references to a Kubernetes ConfigMap or a Kubernetes Secret,
containing the certificate revocation list in PEM format
Expects the content in a key named `ca.crl`.
References to a resource in different namespace are invalid UNLESS there
is a ReferenceGrant in the target namespace that allows the crl
to be attached. | +| `onlyVerifyLeafCertificate` | _boolean_ | false | | If this option is set to true, Envoy will only verify the certificate at the end of the certificate chain against the CRL.
Defaults to false, which will verify the entire certificate chain against the CRL. | + + +#### CustomHeaderExtensionSettings + + + +CustomHeaderExtensionSettings provides configuration for determining the client IP address for a request based on +a trusted custom HTTP header. This uses the the custom_header original IP detection extension. +Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto +for more details. + +_Appears in:_ +- [ClientIPDetectionSettings](#clientipdetectionsettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the header containing the original downstream remote address, if present. | +| `failClosed` | _boolean_ | false | | FailClosed is a switch used to control the flow of traffic when client IP detection
fails. If set to true, the listener will respond with 403 Forbidden when the client
IP address cannot be determined. | + + +#### CustomRedirect + + + +CustomRedirect contains configuration for returning a custom redirect. + +_Appears in:_ +- [ResponseOverride](#responseoverride) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `scheme` | _string_ | false | | Scheme is the scheme to be used in the value of the `Location` header in
the response. When empty, the scheme of the request is used. | +| `hostname` | _[PreciseHostname](#precisehostname)_ | false | | Hostname is the hostname to be used in the value of the `Location`
header in the response.
When empty, the hostname in the `Host` header of the request is used. | +| `path` | _[HTTPPathModifier](#httppathmodifier)_ | false | | Path defines parameters used to modify the path of the incoming request.
The modified path is then used to construct the `Location` header. When
empty, the request path is used as-is.
Only ReplaceFullPath path modifier is supported currently. | +| `port` | _[PortNumber](#portnumber)_ | false | | Port is the port to be used in the value of the `Location`
header in the response.
If redirect scheme is not-empty, the well-known port associated with the redirect scheme will be used.
Specifically "http" to port 80 and "https" to port 443. If the redirect scheme does not have a
well-known port or redirect scheme is empty, the listener port of the Gateway will be used.
Port will not be added in the 'Location' header if scheme is HTTP and port is 80
or scheme is HTTPS and port is 443. | +| `statusCode` | _integer_ | false | 302 | StatusCode is the HTTP status code to be used in response. | + + +#### CustomResponse + + + +CustomResponse defines the configuration for returning a custom response. + +_Appears in:_ +- [ResponseOverride](#responseoverride) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `contentType` | _string_ | false | | Content Type of the response. This will be set in the Content-Type header. | +| `body` | _[CustomResponseBody](#customresponsebody)_ | false | | Body of the Custom Response
Supports Envoy command operators for dynamic content (see https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators). | +| `statusCode` | _integer_ | false | | Status Code of the Custom Response
If unset, does not override the status of response. | +| `header` | _[HTTPHeaderFilter](#httpheaderfilter)_ | false | | Header defines headers to add, set or remove from the response.
This allows the response policy to append, add or override headers
of the final response before it is sent to a downstream client.
Note: Header removal is not supported for responseOverride. | + + +#### CustomResponseBody + + + +CustomResponseBody + +_Appears in:_ +- [CustomResponse](#customresponse) +- [HTTPDirectResponseFilter](#httpdirectresponsefilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ResponseValueType](#responsevaluetype)_ | true | Inline | Type is the type of method to use to read the body value.
Valid values are Inline and ValueRef, default is Inline. | +| `inline` | _string_ | false | | Inline contains the value as an inline string. | +| `valueRef` | _[LocalObjectReference](#localobjectreference)_ | false | | ValueRef contains the contents of the body
specified as a local object reference.
Only a reference to ConfigMap is supported.
The value of key `response.body` in the ConfigMap will be used as the response body.
If the key is not found, the first value in the ConfigMap will be used. | + + +#### CustomResponseMatch + + + +CustomResponseMatch defines the configuration for matching a user response to return a custom one. + +_Appears in:_ +- [ResponseOverride](#responseoverride) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `statusCodes` | _[StatusCodeMatch](#statuscodematch) array_ | true | | Status code to match on. The match evaluates to true if any of the matches are successful. | + + +#### CustomTag + + + + + +_Appears in:_ +- [ProxyTracing](#proxytracing) +- [Tracing](#tracing) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[CustomTagType](#customtagtype)_ | true | Literal | Type defines the type of custom tag. | +| `literal` | _[LiteralCustomTag](#literalcustomtag)_ | true | | Literal adds hard-coded value to each span.
It's required when the type is "Literal". | +| `environment` | _[EnvironmentCustomTag](#environmentcustomtag)_ | true | | Environment adds value from environment variable to each span.
It's required when the type is "Environment". | +| `requestHeader` | _[RequestHeaderCustomTag](#requestheadercustomtag)_ | true | | RequestHeader adds value from request header to each span.
It's required when the type is "RequestHeader". | + + +#### CustomTagType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [CustomTag](#customtag) + +| Value | Description | +| ----- | ----------- | +| `Literal` | CustomTagTypeLiteral adds hard-coded value to each span.
| +| `Environment` | CustomTagTypeEnvironment adds value from environment variable to each span.
| +| `RequestHeader` | CustomTagTypeRequestHeader adds value from request header to each span.
| + + +#### DNS + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `dnsRefreshRate` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | DNSRefreshRate specifies the rate at which DNS records should be refreshed.
Defaults to 30 seconds. | +| `respectDnsTtl` | _boolean_ | false | | RespectDNSTTL indicates whether the DNS Time-To-Live (TTL) should be respected.
If the value is set to true, the DNS refresh rate will be set to the resource record’s TTL.
Defaults to true. | +| `lookupFamily` | _[DNSLookupFamily](#dnslookupfamily)_ | false | | LookupFamily determines how Envoy would resolve DNS for Routes where the backend is specified as a fully qualified domain name (FQDN).
If set, this configuration overrides other defaults. | + + +#### DNSLookupFamily + +_Underlying type:_ _string_ + +DNSLookupFamily defines the behavior of Envoy when resolving DNS for hostnames + +_Appears in:_ +- [DNS](#dns) + +| Value | Description | +| ----- | ----------- | +| `IPv4` | IPv4DNSLookupFamily means the DNS resolver will first perform a lookup for addresses in the IPv4 family.
| +| `IPv6` | IPv6DNSLookupFamily means the DNS resolver will first perform a lookup for addresses in the IPv6 family.
| +| `IPv4Preferred` | IPv4PreferredDNSLookupFamily means the DNS resolver will first perform a lookup for addresses in the IPv4 family and fallback
to a lookup for addresses in the IPv6 family.
| +| `IPv6Preferred` | IPv6PreferredDNSLookupFamily means the DNS resolver will first perform a lookup for addresses in the IPv6 family and fallback
to a lookup for addresses in the IPv4 family.
| +| `IPv4AndIPv6` | IPv4AndIPv6DNSLookupFamily mean the DNS resolver will perform a lookup for both IPv4 and IPv6 families, and return all resolved
addresses. When this is used, Happy Eyeballs will be enabled for upstream connections.
| + + +#### DynamicModule + + + +DynamicModule defines a dynamic module HTTP filter to be loaded by Envoy. +The module must be registered in the EnvoyProxy resource's dynamicModules +allowlist by the infrastructure operator. + +_Appears in:_ +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name references a dynamic module registered in the EnvoyProxy resource's
dynamicModules list. The referenced module must exist in the registry;
otherwise, the policy will be rejected. | +| `filterName` | _string_ | false | | FilterName identifies a specific filter implementation within the dynamic
module. A single shared library can contain multiple filter implementations.
This value is passed to the module's HTTP filter config init function to
select the appropriate implementation.
If not specified, defaults to an empty string. | +| `config` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ | false | | Config is the configuration for the dynamic module filter.
This is serialized as JSON and passed to the module's initialization function. | +| `terminalFilter` | _boolean_ | false | false | TerminalFilter indicates that this dynamic module handles requests without
requiring an upstream backend. The module is responsible for generating and
sending the response to downstream directly.
Defaults to false. | + + +#### DynamicModuleEntry + + + +DynamicModuleEntry defines a dynamic module that is registered and allowed +for use by EnvoyExtensionPolicy resources. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name is the logical name for this module. EnvoyExtensionPolicy resources
reference modules by this name. | +| `source` | _[DynamicModuleSource](#dynamicmodulesource)_ | true | | Source defines where the dynamic module code is loaded from. | +| `doNotClose` | _boolean_ | false | false | DoNotClose prevents the module from being unloaded with dlclose when no
more references exist. This is useful for modules that maintain global
state that should not be destroyed on configuration updates.
Defaults to false. | +| `loadGlobally` | _boolean_ | false | false | LoadGlobally loads the dynamic module with the RTLD_GLOBAL flag.
By default, modules are loaded with RTLD_LOCAL to avoid symbol conflicts.
Set this to true when the module needs to share symbols with other
dynamic libraries it loads.
Defaults to false. | + + +#### DynamicModuleLBPolicy + + + +DynamicModuleLBPolicy configures a custom load balancing algorithm +implemented as a dynamic module (runtime-loaded shared library). +The module must be registered in the EnvoyProxy resource's dynamicModules allowlist. + +See https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/dynamic_modules/v3/dynamic_modules.proto + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name references a dynamic module registered in the EnvoyProxy resource's
dynamicModules list. The referenced module must exist in the registry;
otherwise, the policy will be rejected. | +| `lbPolicyName` | _string_ | true | | LBPolicyName identifies a specific load balancer implementation within
the dynamic module. A single shared library can contain multiple LB
policy implementations. This value is passed to the module's
initialization function to select the appropriate implementation. | +| `config` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ | false | | Config is optional configuration for the module's load balancer
implementation. This is serialized and passed to the module's
initialization function. | + + +#### DynamicModuleSource + + + +DynamicModuleSource defines the source of the dynamic module code. + +_Appears in:_ +- [DynamicModuleEntry](#dynamicmoduleentry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[DynamicModuleSourceType](#dynamicmodulesourcetype)_ | false | Local | Type is the type of the source of the dynamic module code.
Defaults to Local. | +| `local` | _[LocalDynamicModuleSource](#localdynamicmodulesource)_ | false | | Local specifies a module loaded from the proxy's local filesystem
by absolute path. | +| `remote` | _[RemoteDynamicModuleSource](#remotedynamicmodulesource)_ | false | | Remote specifies a module fetched from a remote source.
The module binary is downloaded and cached by Envoy. | + + +#### DynamicModuleSourceType + +_Underlying type:_ _string_ + +DynamicModuleSourceType specifies the types of sources for dynamic module code. + +_Appears in:_ +- [DynamicModuleSource](#dynamicmodulesource) + +| Value | Description | +| ----- | ----------- | +| `Local` | LocalDynamicModuleSourceType specifies a module loaded from the local filesystem.
| +| `Remote` | RemoteDynamicModuleSourceType specifies a module fetched from a remote source.
| + + +#### EndpointOverride + + + +EndpointOverride defines the configuration for endpoint override. +This allows endpoint picking to be implemented based on request headers or metadata. +It extracts selected override endpoints from the specified sources (request headers, metadata, etc.). +If no valid endpoint in the override list, then the configured load balancing policy is used as fallback. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `extractFrom` | _[EndpointOverrideExtractFrom](#endpointoverrideextractfrom) array_ | true | | ExtractFrom defines the sources to extract endpoint override information from. | + + +#### EndpointOverrideExtractFrom + + + +EndpointOverrideExtractFrom defines a source to extract endpoint override information from. + +_Appears in:_ +- [EndpointOverride](#endpointoverride) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `header` | _string_ | false | | Header defines the header to get the override endpoint addresses.
The header value must specify at least one endpoint in `IP:Port` format or multiple endpoints in `IP:Port,IP:Port,...` format.
For example `10.0.0.5:8080` or `[2600:4040:5204::1574:24ae]:80`.
The IPv6 address is enclosed in square brackets. | + + +#### EnvironmentCustomTag + + + +EnvironmentCustomTag adds value from environment variable to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name defines the name of the environment variable which to extract the value from. | +| `defaultValue` | _string_ | false | | DefaultValue defines the default value to use if the environment variable is not set. | + + +#### EnvoyExtensionPolicy + + + +EnvoyExtensionPolicy allows the user to configure various envoy extensibility options for the Gateway. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyExtensionPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[EnvoyExtensionPolicySpec](#envoyextensionpolicyspec)_ | true | | Spec defines the desired state of EnvoyExtensionPolicy. | +| `status` | _[PolicyStatus](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#policystatus)_ | true | | Status defines the current status of EnvoyExtensionPolicy. | + + +#### EnvoyExtensionPolicySpec + + + +EnvoyExtensionPolicySpec defines the desired state of EnvoyExtensionPolicy. + +_Appears in:_ +- [EnvoyExtensionPolicy](#envoyextensionpolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `targetRef` | _[LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname)_ | true | | TargetRef is the name of the resource this policy is being attached to.
This policy and the TargetRef MUST be in the same namespace for this
Policy to have effect
Deprecated: use targetRefs/targetSelectors instead | +| `targetRefs` | _LocalPolicyTargetReferenceWithSectionName array_ | true | | TargetRefs are the names of the Gateway resources this policy
is being attached to. | +| `targetSelectors` | _[TargetSelector](#targetselector) array_ | true | | TargetSelectors allow targeting resources for this policy based on labels | +| `wasm` | _[Wasm](#wasm) array_ | false | | Wasm is a list of Wasm extensions to be loaded by the Gateway.
Order matters, as the extensions will be loaded in the order they are
defined in this list. | +| `extProc` | _[ExtProc](#extproc) array_ | false | | ExtProc is an ordered list of external processing filters
that should be added to the envoy filter chain | +| `lua` | _[Lua](#lua) array_ | false | | Lua is an ordered list of Lua filters
that should be added to the envoy filter chain | +| `dynamicModule` | _[DynamicModule](#dynamicmodule) array_ | false | | DynamicModule is an ordered list of dynamic module HTTP filters
that should be added to the envoy filter chain.
Each module must be registered in the EnvoyProxy resource's dynamicModules
allowlist.
Order matters, as the filters will be loaded in the order they are
defined in this list. | + + +#### EnvoyFilter + +_Underlying type:_ _string_ + +EnvoyFilter defines the type of Envoy HTTP filter. + +_Appears in:_ +- [FilterPosition](#filterposition) + +| Value | Description | +| ----- | ----------- | +| `envoy.filters.http.custom_response` | EnvoyFilterCustomResponse defines the Envoy HTTP custom response filter.
| +| `envoy.filters.http.health_check` | EnvoyFilterHealthCheck defines the Envoy HTTP health check filter.
| +| `envoy.filters.http.fault` | EnvoyFilterFault defines the Envoy HTTP fault filter.
| +| `envoy.filters.http.cors` | EnvoyFilterCORS defines the Envoy HTTP CORS filter.
| +| `envoy.filters.http.header_mutation` | EnvoyFilterHeaderMutation defines the Envoy HTTP header mutation filter
| +| `envoy.filters.http.ext_authz` | EnvoyFilterExtAuthz defines the Envoy HTTP external authorization filter.
| +| `envoy.filters.http.api_key_auth` | EnvoyFilterAPIKeyAuth defines the Envoy HTTP api key authentication filter.
| +| `envoy.filters.http.basic_auth` | EnvoyFilterBasicAuth defines the Envoy HTTP basic authentication filter.
| +| `envoy.filters.http.oauth2` | EnvoyFilterOAuth2 defines the Envoy HTTP OAuth2 filter.
| +| `envoy.filters.http.jwt_authn` | EnvoyFilterJWTAuthn defines the Envoy HTTP JWT authentication filter.
| +| `envoy.filters.http.stateful_session` | EnvoyFilterSessionPersistence defines the Envoy HTTP session persistence filter.
| +| `envoy.filters.http.buffer` | EnvoyFilterBuffer defines the Envoy HTTP buffer filter
| +| `envoy.filters.http.lua` | EnvoyFilterLua defines the Envoy HTTP Lua filter.
| +| `envoy.filters.http.ext_proc` | EnvoyFilterExtProc defines the Envoy HTTP external process filter.
| +| `envoy.filters.http.wasm` | EnvoyFilterWasm defines the Envoy HTTP WebAssembly filter.
| +| `envoy.filters.http.dynamic_modules` | EnvoyFilterDynamicModules defines the Envoy HTTP dynamic modules filter.
| +| `envoy.filters.http.geoip` | EnvoyFilterGeoIP defines the Envoy HTTP GeoIP filter.
| +| `envoy.filters.http.rbac` | EnvoyFilterRBAC defines the Envoy RBAC filter.
| +| `envoy.filters.http.local_ratelimit` | EnvoyFilterLocalRateLimit defines the Envoy HTTP local rate limit filter.
| +| `envoy.filters.http.ratelimit` | EnvoyFilterRateLimit defines the Envoy HTTP rate limit filter.
| +| `envoy.filters.http.bandwidth_limit` | EnvoyFilterBandwidthLimit defines the Envoy HTTP bandwidth limit filter.
| +| `envoy.filters.http.grpc_web` | EnvoyFilterGRPCWeb defines the Envoy HTTP gRPC-web filter.
| +| `envoy.filters.http.grpc_stats` | EnvoyFilterGRPCStats defines the Envoy HTTP gRPC stats filter.
| +| `envoy.filters.http.credential_injector` | EnvoyFilterCredentialInjector defines the Envoy HTTP credential injector filter.
| +| `envoy.filters.http.compressor` | EnvoyFilterCompressor defines the Envoy HTTP compressor filter.
| +| `envoy.filters.http.dynamic_forward_proxy` | EnvoyFilterDynamicForwardProxy defines the Envoy HTTP dynamic forward proxy filter.
| +| `envoy.filters.http.router` | EnvoyFilterRouter defines the Envoy HTTP router filter.
| + + +#### EnvoyGateway + + + +EnvoyGateway is the schema for the envoygateways API. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyGateway` +| `gateway` | _[Gateway](#gateway)_ | false | | Gateway defines desired Gateway API specific configuration. If unset,
default configuration parameters will apply. | +| `provider` | _[EnvoyGatewayProvider](#envoygatewayprovider)_ | false | | Provider defines the desired provider and provider-specific configuration.
If unspecified, the Kubernetes provider is used with default configuration
parameters. | +| `logging` | _[EnvoyGatewayLogging](#envoygatewaylogging)_ | false | \{ default:info \} | Logging defines logging parameters for Envoy Gateway. | +| `admin` | _[EnvoyGatewayAdmin](#envoygatewayadmin)_ | false | | Admin defines the desired admin related abilities.
If unspecified, the Admin is used with default configuration
parameters. | +| `telemetry` | _[EnvoyGatewayTelemetry](#envoygatewaytelemetry)_ | false | | Telemetry defines the desired control plane telemetry related abilities.
If unspecified, the telemetry is used with default configuration. | +| `xdsServer` | _[XDSServer](#xdsserver)_ | false | | XDSServer defines the configuration for the Envoy Gateway xDS gRPC server.
If unspecified, default connection keepalive settings will be used. | +| `rateLimit` | _[RateLimit](#ratelimit)_ | false | | RateLimit defines the configuration associated with the Rate Limit service
deployed by Envoy Gateway required to implement the Global Rate limiting
functionality. The specific rate limit service used here is the reference
implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
This configuration is unneeded for "Local" rate limiting. | +| `extensionManager` | _[ExtensionManager](#extensionmanager)_ | false | | ExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane.
Warning: Enabling an Extension Server may lead to complete security compromise of your system.
Users that control the Extension Server can inject arbitrary configuration to proxies,
leading to high Confidentiality, Integrity and Availability risks. | +| `extensionManagers` | _[ExtensionManager](#extensionmanager) array_ | false | | ExtensionManagers defines multiple extension managers to register for the Envoy Gateway Control Plane.
Each extension's output becomes the next extension's input, enabling sequential chaining.
Each entry must have a unique Name field for identification.
This field is mutually exclusive with ExtensionManager.
Warning: Enabling Extension Servers may lead to complete security compromise of your system.
Users that control Extension Servers can inject arbitrary configuration to proxies,
leading to high Confidentiality, Integrity and Availability risks. | +| `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ | false | | ExtensionAPIs defines the settings related to specific Gateway API Extensions
implemented by Envoy Gateway | +| `gatewayAPI` | _[GatewayAPISettings](#gatewayapisettings)_ | false | | GatewayAPI defines feature flags for experimental Gateway API resources.
These APIs live under the gateway.networking.x-k8s.io group and are opt-in. | +| `runtimeFlags` | _[RuntimeFlags](#runtimeflags)_ | true | | RuntimeFlags defines the runtime flags for Envoy Gateway.
Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the related features are stable. | +| `envoyProxy` | _[EnvoyProxySpec](#envoyproxyspec)_ | false | | EnvoyProxy defines the default EnvoyProxy configuration that applies
to all managed Envoy Proxy fleet. This is an optional field and when
provided, the settings from this EnvoyProxySpec serve as the base
defaults for all Envoy Proxy instances.
The hierarchy for EnvoyProxy configuration is (highest to lowest priority):
1. Gateway-level EnvoyProxy (referenced via Gateway.spec.infrastructure.parametersRef)
2. GatewayClass-level EnvoyProxy (referenced via GatewayClass.spec.parametersRef)
3. This EnvoyProxy default spec
The merge strategy for a more specific EnvoyProxy is controlled by its
spec.mergeType field. If mergeType is unset, the more specific EnvoyProxy
completely replaces less specific settings.
Note: mergeType has no effect in this default EnvoyProxySpec. | + + +#### EnvoyGatewayAdmin + + + +EnvoyGatewayAdmin defines the Envoy Gateway Admin configuration. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `address` | _[EnvoyGatewayAdminAddress](#envoygatewayadminaddress)_ | false | | Address defines the address of Envoy Gateway Admin Server. | +| `enableDumpConfig` | _boolean_ | false | | EnableDumpConfig defines if enable dump config in Envoy Gateway logs. | +| `enablePprof` | _boolean_ | false | | EnablePprof defines if enable pprof in Envoy Gateway Admin Server. | + + +#### EnvoyGatewayAdminAddress + + + +EnvoyGatewayAdminAddress defines the Envoy Gateway Admin Address configuration. + +_Appears in:_ +- [EnvoyGatewayAdmin](#envoygatewayadmin) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `port` | _integer_ | false | 19000 | Port defines the port the admin server is exposed on. | +| `host` | _string_ | false | 127.0.0.1 | Host defines the admin server hostname. | + + +#### EnvoyGatewayCustomProvider + + + +EnvoyGatewayCustomProvider defines configuration for the Custom provider. + +_Appears in:_ +- [EnvoyGatewayProvider](#envoygatewayprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `resource` | _[EnvoyGatewayResourceProvider](#envoygatewayresourceprovider)_ | true | | Resource defines the desired resource provider.
This provider is used to specify the provider to be used
to retrieve the resource configurations such as Gateway API
resources | +| `infrastructure` | _[EnvoyGatewayInfrastructureProvider](#envoygatewayinfrastructureprovider)_ | false | | Infrastructure defines the desired infrastructure provider.
This provider is used to specify the provider to be used
to provide an environment to deploy the out resources like
the Envoy Proxy data plane.
Infrastructure is optional, if provider is not specified,
No infrastructure provider is available. | + + +#### EnvoyGatewayFileResourceProvider + + + +EnvoyGatewayFileResourceProvider defines configuration for the File Resource provider. + +_Appears in:_ +- [EnvoyGatewayResourceProvider](#envoygatewayresourceprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `paths` | _string array_ | true | | Paths are the paths to a directory or file containing the resource configuration.
Recursive subdirectories are not currently supported. | + + +#### EnvoyGatewayHostInfrastructureProvider + + + +EnvoyGatewayHostInfrastructureProvider defines configuration for the Host Infrastructure provider. + +_Appears in:_ +- [EnvoyGatewayInfrastructureProvider](#envoygatewayinfrastructureprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `configHome` | _string_ | false | | ConfigHome is the directory for configuration files.
Defaults to ~/.config/envoy-gateway | +| `dataHome` | _string_ | false | | DataHome is the directory for persistent data (Envoy binaries).
Defaults to ~/.local/share/envoy-gateway | +| `stateHome` | _string_ | false | | StateHome is the directory for persistent state (logs).
Defaults to ~/.local/state/envoy-gateway | +| `runtimeDir` | _string_ | false | | RuntimeDir is the directory for ephemeral runtime files.
Defaults to /tmp/envoy-gateway-$\{UID\} | + + +#### EnvoyGatewayInfrastructureProvider + + + +EnvoyGatewayInfrastructureProvider defines configuration for the Custom Infrastructure provider. + +_Appears in:_ +- [EnvoyGatewayCustomProvider](#envoygatewaycustomprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[InfrastructureProviderType](#infrastructureprovidertype)_ | true | | Type is the type of infrastructure providers to use. Supported types are "Host". | +| `host` | _[EnvoyGatewayHostInfrastructureProvider](#envoygatewayhostinfrastructureprovider)_ | false | | Host defines the configuration of the Host provider. Host provides runtime
deployment of the data plane as a child process on the host environment. | + + +#### EnvoyGatewayKubernetesProvider + + + +EnvoyGatewayKubernetesProvider defines configuration for the Kubernetes provider. + +_Appears in:_ +- [EnvoyGatewayProvider](#envoygatewayprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `rateLimitDeployment` | _[KubernetesDeploymentSpec](#kubernetesdeploymentspec)_ | false | | RateLimitDeployment defines the desired state of the Envoy ratelimit deployment resource.
If unspecified, default settings for the managed Envoy ratelimit deployment resource
are applied. | +| `rateLimitHpa` | _[KubernetesHorizontalPodAutoscalerSpec](#kuberneteshorizontalpodautoscalerspec)_ | false | | RateLimitHpa defines the Horizontal Pod Autoscaler settings for Envoy ratelimit Deployment.
If the HPA is set, Replicas field from RateLimitDeployment will be ignored. | +| `rateLimitPDB` | _[KubernetesPodDisruptionBudgetSpec](#kubernetespoddisruptionbudgetspec)_ | false | | RateLimitPDB allows to control the pod disruption budget of rate limit service. | +| `watch` | _[KubernetesWatchMode](#kuberneteswatchmode)_ | false | | Watch holds configuration of which input resources should be watched and reconciled. | +| `deploy` | _[KubernetesDeployMode](#kubernetesdeploymode)_ | false | | Deploy holds configuration of how output managed resources such as the Envoy Proxy data plane
should be deployed | +| `leaderElection` | _[LeaderElection](#leaderelection)_ | false | | LeaderElection specifies the configuration for leader election.
If it's not set up, leader election will be active by default, using Kubernetes' standard settings. | +| `shutdownManager` | _[ShutdownManager](#shutdownmanager)_ | false | | ShutdownManager defines the configuration for the shutdown manager. | +| `client` | _[KubernetesClient](#kubernetesclient)_ | true | | Client holds the configuration for the Kubernetes client. | +| `proxyTopologyInjector` | _[EnvoyGatewayTopologyInjector](#envoygatewaytopologyinjector)_ | false | | TopologyInjector defines the configuration for topology injector MutatatingWebhookConfiguration | +| `cacheSyncPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | CacheSyncPeriod determines the minimum frequency at which watched resources are synced.
Note that a sync in the provider layer will not lead to a full reconciliation (including translation),
unless there are actual changes in the provider resources.
This option can be used to protect against missed events or issues in Envoy Gateway where resources
are not requeued when they should be, at the cost of increased resource consumption.
Learn more about the implications of this option: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#Options
Default: 10 hours | + + +#### EnvoyGatewayLogComponent + +_Underlying type:_ _string_ + +EnvoyGatewayLogComponent defines a component that supports a configured logging level. + +_Appears in:_ +- [EnvoyGatewayLogging](#envoygatewaylogging) + +| Value | Description | +| ----- | ----------- | +| `default` | LogComponentGatewayDefault defines the "default"-wide logging component. When specified,
all other logging components are ignored.
| +| `provider` | LogComponentProviderRunner defines the "provider" runner component.
| +| `gateway-api` | LogComponentGatewayAPIRunner defines the "gateway-api" runner component.
| +| `xds-translator` | LogComponentXdsTranslatorRunner defines the "xds-translator" runner component.
| +| `xds-server` | LogComponentXdsServerRunner defines the "xds-server" runner component.
| +| `xds` | LogComponentXdsRunner defines the "xds" runner component.
| +| `infrastructure` | LogComponentInfrastructureRunner defines the "infrastructure" runner component.
| +| `global-ratelimit` | LogComponentGlobalRateLimitRunner defines the "global-ratelimit" runner component.
| + + +#### EnvoyGatewayLogEncoder + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [EnvoyGatewayLogging](#envoygatewaylogging) + +| Value | Description | +| ----- | ----------- | +| `Text` | EnvoyGatewayLogEncoderText defines the "Text" log encoder.
| +| `JSON` | EnvoyGatewayLogEncoderJSON defines the "JSON" log encoder.
| + + +#### EnvoyGatewayLogging + + + +EnvoyGatewayLogging defines logging for Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `level` | _object (keys:[EnvoyGatewayLogComponent](#envoygatewaylogcomponent), values:[LogLevel](#loglevel))_ | true | \{ default:info \} | Level is the logging level. If unspecified, defaults to "info".
EnvoyGatewayLogComponent options: default/provider/gateway-api/xds-translator/xds-server/infrastructure/global-ratelimit.
LogLevel options: debug/info/error/warn. | +| `encoder` | _[EnvoyGatewayLogEncoder](#envoygatewaylogencoder)_ | false | | Encoder defines the log encoder format.
If unspecified, defaults to "Text". | + + +#### EnvoyGatewayMetricSink + + + +EnvoyGatewayMetricSink defines control plane +metric sinks where metrics are sent to. + +_Appears in:_ +- [EnvoyGatewayMetrics](#envoygatewaymetrics) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[MetricSinkType](#metricsinktype)_ | true | OpenTelemetry | Type defines the metric sink type.
EG control plane currently supports OpenTelemetry. | +| `openTelemetry` | _[EnvoyGatewayOpenTelemetrySink](#envoygatewayopentelemetrysink)_ | true | | OpenTelemetry defines the configuration for OpenTelemetry sink.
It's required if the sink type is OpenTelemetry. | + + +#### EnvoyGatewayMetrics + + + +EnvoyGatewayMetrics defines control plane push/pull metrics configurations. + +_Appears in:_ +- [EnvoyGatewayTelemetry](#envoygatewaytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `sinks` | _[EnvoyGatewayMetricSink](#envoygatewaymetricsink) array_ | true | | Sinks defines the metric sinks where metrics are sent to. | +| `prometheus` | _[EnvoyGatewayPrometheusProvider](#envoygatewayprometheusprovider)_ | true | | Prometheus defines the configuration for prometheus endpoint. | + + +#### EnvoyGatewayOpenTelemetrySink + + + + + +_Appears in:_ +- [EnvoyGatewayMetricSink](#envoygatewaymetricsink) +- [EnvoyGatewayTraceSink](#envoygatewaytracesink) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `host` | _string_ | true | | Host define the sink service hostname. | +| `protocol` | _string_ | true | | Protocol define the sink service protocol. | +| `port` | _integer_ | false | 4317 | Port defines the port the sink service is exposed on. | +| `exportInterval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | true | | ExportInterval configures the intervening time between exports for a
Sink. This option overrides any value set for the
OTEL_METRIC_EXPORT_INTERVAL environment variable.
If ExportInterval is less than or equal to zero, 60 seconds
is used as the default. | +| `exportTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | true | | ExportTimeout configures the time a Sink waits for an export to
complete before canceling it. This option overrides any value set for the
OTEL_METRIC_EXPORT_TIMEOUT environment variable.
If ExportTimeout is less than or equal to zero, 30 seconds
is used as the default. | + + +#### EnvoyGatewayPrometheusProvider + + + +EnvoyGatewayPrometheusProvider will expose prometheus endpoint in pull mode. + +_Appears in:_ +- [EnvoyGatewayMetrics](#envoygatewaymetrics) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `disable` | _boolean_ | true | | Disable defines if disables the prometheus metrics in pull mode. | + + +#### EnvoyGatewayProvider + + + +EnvoyGatewayProvider defines the desired configuration of a provider. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ProviderType](#providertype)_ | true | | Type is the type of provider to use. Supported types are "Kubernetes", "Custom". | +| `kubernetes` | _[EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider)_ | false | | Kubernetes defines the configuration of the Kubernetes provider. Kubernetes
provides runtime configuration via the Kubernetes API. | +| `custom` | _[EnvoyGatewayCustomProvider](#envoygatewaycustomprovider)_ | false | | Custom defines the configuration for the Custom provider. This provider
allows you to define a specific resource provider and an infrastructure
provider. | + + +#### EnvoyGatewayResourceProvider + + + +EnvoyGatewayResourceProvider defines configuration for the Custom Resource provider. + +_Appears in:_ +- [EnvoyGatewayCustomProvider](#envoygatewaycustomprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ResourceProviderType](#resourceprovidertype)_ | true | | Type is the type of resource provider to use. Supported types are "File". | +| `file` | _[EnvoyGatewayFileResourceProvider](#envoygatewayfileresourceprovider)_ | false | | File defines the configuration of the File provider. File provides runtime
configuration defined by one or more files. | + + +#### EnvoyGatewaySpec + + + +EnvoyGatewaySpec defines the desired state of Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `gateway` | _[Gateway](#gateway)_ | false | | Gateway defines desired Gateway API specific configuration. If unset,
default configuration parameters will apply. | +| `provider` | _[EnvoyGatewayProvider](#envoygatewayprovider)_ | false | | Provider defines the desired provider and provider-specific configuration.
If unspecified, the Kubernetes provider is used with default configuration
parameters. | +| `logging` | _[EnvoyGatewayLogging](#envoygatewaylogging)_ | false | \{ default:info \} | Logging defines logging parameters for Envoy Gateway. | +| `admin` | _[EnvoyGatewayAdmin](#envoygatewayadmin)_ | false | | Admin defines the desired admin related abilities.
If unspecified, the Admin is used with default configuration
parameters. | +| `telemetry` | _[EnvoyGatewayTelemetry](#envoygatewaytelemetry)_ | false | | Telemetry defines the desired control plane telemetry related abilities.
If unspecified, the telemetry is used with default configuration. | +| `xdsServer` | _[XDSServer](#xdsserver)_ | false | | XDSServer defines the configuration for the Envoy Gateway xDS gRPC server.
If unspecified, default connection keepalive settings will be used. | +| `rateLimit` | _[RateLimit](#ratelimit)_ | false | | RateLimit defines the configuration associated with the Rate Limit service
deployed by Envoy Gateway required to implement the Global Rate limiting
functionality. The specific rate limit service used here is the reference
implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
This configuration is unneeded for "Local" rate limiting. | +| `extensionManager` | _[ExtensionManager](#extensionmanager)_ | false | | ExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane.
Warning: Enabling an Extension Server may lead to complete security compromise of your system.
Users that control the Extension Server can inject arbitrary configuration to proxies,
leading to high Confidentiality, Integrity and Availability risks. | +| `extensionManagers` | _[ExtensionManager](#extensionmanager) array_ | false | | ExtensionManagers defines multiple extension managers to register for the Envoy Gateway Control Plane.
Each extension's output becomes the next extension's input, enabling sequential chaining.
Each entry must have a unique Name field for identification.
This field is mutually exclusive with ExtensionManager.
Warning: Enabling Extension Servers may lead to complete security compromise of your system.
Users that control Extension Servers can inject arbitrary configuration to proxies,
leading to high Confidentiality, Integrity and Availability risks. | +| `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ | false | | ExtensionAPIs defines the settings related to specific Gateway API Extensions
implemented by Envoy Gateway | +| `gatewayAPI` | _[GatewayAPISettings](#gatewayapisettings)_ | false | | GatewayAPI defines feature flags for experimental Gateway API resources.
These APIs live under the gateway.networking.x-k8s.io group and are opt-in. | +| `runtimeFlags` | _[RuntimeFlags](#runtimeflags)_ | true | | RuntimeFlags defines the runtime flags for Envoy Gateway.
Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the related features are stable. | +| `envoyProxy` | _[EnvoyProxySpec](#envoyproxyspec)_ | false | | EnvoyProxy defines the default EnvoyProxy configuration that applies
to all managed Envoy Proxy fleet. This is an optional field and when
provided, the settings from this EnvoyProxySpec serve as the base
defaults for all Envoy Proxy instances.
The hierarchy for EnvoyProxy configuration is (highest to lowest priority):
1. Gateway-level EnvoyProxy (referenced via Gateway.spec.infrastructure.parametersRef)
2. GatewayClass-level EnvoyProxy (referenced via GatewayClass.spec.parametersRef)
3. This EnvoyProxy default spec
The merge strategy for a more specific EnvoyProxy is controlled by its
spec.mergeType field. If mergeType is unset, the more specific EnvoyProxy
completely replaces less specific settings.
Note: mergeType has no effect in this default EnvoyProxySpec. | + + +#### EnvoyGatewayTelemetry + + + +EnvoyGatewayTelemetry defines telemetry configurations for envoy gateway control plane. +Control plane will focus on metrics observability telemetry and tracing telemetry later. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `metrics` | _[EnvoyGatewayMetrics](#envoygatewaymetrics)_ | true | | Metrics defines metrics configuration for envoy gateway. | +| `traces` | _[EnvoyGatewayTraces](#envoygatewaytraces)_ | true | | Traces defines traces configuration for envoy gateway. | + + +#### EnvoyGatewayTopologyInjector + + + +EnvoyGatewayTopologyInjector defines the configuration for topology injector MutatatingWebhookConfiguration + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | _boolean_ | false | | | + + +#### EnvoyGatewayTraceSink + + + +EnvoyGatewayTraceSink defines control plane +trace sinks where traces are sent to. + +_Appears in:_ +- [EnvoyGatewayTraces](#envoygatewaytraces) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[TraceSinkType](#tracesinktype)_ | true | OpenTelemetry | Type defines the trace sink type.
EG control plane currently supports OpenTelemetry. | +| `openTelemetry` | _[EnvoyGatewayOpenTelemetrySink](#envoygatewayopentelemetrysink)_ | true | | OpenTelemetry defines the configuration for OpenTelemetry sink.
It's required if the sink type is OpenTelemetry. | + + +#### EnvoyGatewayTraces + + + +EnvoyGatewayTraces defines control plane tracing configurations. + +_Appears in:_ +- [EnvoyGatewayTelemetry](#envoygatewaytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `sink` | _[EnvoyGatewayTraceSink](#envoygatewaytracesink)_ | true | | Sink defines the trace sink where traces are sent to. | +| `samplingRate` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | false | | SamplingRate controls the fraction of traces that are sampled.
The value is expressed as a Gateway API Fraction (numerator/denominator).
If denominator is omitted, it defaults to 100. | + + +#### EnvoyJSONPatchConfig + + + +EnvoyJSONPatchConfig defines the configuration for patching a Envoy xDS Resource +using JSONPatch semantic + +_Appears in:_ +- [EnvoyPatchPolicySpec](#envoypatchpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[EnvoyResourceType](#envoyresourcetype)_ | true | | Type is the typed URL of the Envoy xDS Resource | +| `name` | _string_ | true | | Name is the name of the resource | +| `operation` | _[JSONPatchOperation](#jsonpatchoperation)_ | true | | Patch defines the JSON Patch Operation | + + +#### EnvoyPatchPolicy + + + +EnvoyPatchPolicy allows the user to modify the generated Envoy xDS +resources by Envoy Gateway using this patch API + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyPatchPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[EnvoyPatchPolicySpec](#envoypatchpolicyspec)_ | true | | Spec defines the desired state of EnvoyPatchPolicy. | +| `status` | _[PolicyStatus](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#policystatus)_ | true | | Status defines the current status of EnvoyPatchPolicy. | + + +#### EnvoyPatchPolicySpec + + + +EnvoyPatchPolicySpec defines the desired state of EnvoyPatchPolicy. + +_Appears in:_ +- [EnvoyPatchPolicy](#envoypatchpolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[EnvoyPatchType](#envoypatchtype)_ | true | | Type decides the type of patch.
Valid EnvoyPatchType values are "JSONPatch". | +| `jsonPatches` | _[EnvoyJSONPatchConfig](#envoyjsonpatchconfig) array_ | false | | JSONPatch defines the JSONPatch configuration. | +| `targetRef` | _[LocalPolicyTargetReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localpolicytargetreference)_ | true | | TargetRef is the name of the Gateway API resource this policy
is being attached to.
By default, attaching to Gateway is supported and
when mergeGateways is enabled it should attach to GatewayClass.
This Policy and the TargetRef MUST be in the same namespace
for this Policy to have effect and be applied to the Gateway
TargetRef | +| `priority` | _integer_ | true | | Priority of the EnvoyPatchPolicy.
If multiple EnvoyPatchPolicies are applied to the same
TargetRef, they will be applied in the ascending order of
the priority i.e. int32.min has the highest priority and
int32.max has the lowest priority.
Defaults to 0. | + + +#### EnvoyPatchType + +_Underlying type:_ _string_ + +EnvoyPatchType specifies the types of Envoy patching mechanisms. + +_Appears in:_ +- [EnvoyPatchPolicySpec](#envoypatchpolicyspec) + +| Value | Description | +| ----- | ----------- | +| `JSONPatch` | JSONPatchEnvoyPatchType allows the user to patch the generated xDS resources using JSONPatch semantics.
For more details on the semantics, please refer to https://datatracker.ietf.org/doc/html/rfc6902
| + + +#### EnvoyProxy + + + +EnvoyProxy is the schema for the envoyproxies API. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyProxy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | false | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[EnvoyProxySpec](#envoyproxyspec)_ | true | | EnvoyProxySpec defines the desired state of EnvoyProxy. | +| `status` | _[EnvoyProxyStatus](#envoyproxystatus)_ | false | | EnvoyProxyStatus defines the actual state of EnvoyProxy. | + + +#### EnvoyProxyAncestorStatus + + + + + +_Appears in:_ +- [EnvoyProxyStatus](#envoyproxystatus) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `conditions` | _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | false | | Conditions describes the status of the Policy with respect to the given Ancestor. | +| `ancestorRef` | _[ParentReference](#parentreference)_ | true | | AncestorRef corresponds a GatewayClass or Gateway use this EnvoyProxy with ParametersReference. | + + + + + + +#### EnvoyProxyGeoIP + + + +EnvoyProxyGeoIP defines shared GeoIP provider settings for EnvoyProxy. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `provider` | _[GeoIPProvider](#geoipprovider)_ | true | | Provider defines the GeoIP provider configuration used by GeoIP filter instances. | + + +#### EnvoyProxyHostProvider + + + +EnvoyProxyHostProvider defines configuration for the "Host" resource provider. + +_Appears in:_ +- [EnvoyProxyProvider](#envoyproxyprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `envoyVersion` | _string_ | false | | EnvoyVersion is the version of Envoy to use. If unspecified, the version
against which Envoy Gateway is built will be used. | + + +#### EnvoyProxyKubernetesProvider + + + +EnvoyProxyKubernetesProvider defines configuration for the Kubernetes resource +provider. + +_Appears in:_ +- [EnvoyProxyProvider](#envoyproxyprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `envoyDeployment` | _[KubernetesDeploymentSpec](#kubernetesdeploymentspec)_ | false | | EnvoyDeployment defines the desired state of the Envoy deployment resource.
If unspecified, default settings for the managed Envoy deployment resource
are applied. | +| `envoyDaemonSet` | _[KubernetesDaemonSetSpec](#kubernetesdaemonsetspec)_ | false | | EnvoyDaemonSet defines the desired state of the Envoy daemonset resource.
Disabled by default, a deployment resource is used instead to provision the Envoy Proxy fleet | +| `envoyService` | _[KubernetesServiceSpec](#kubernetesservicespec)_ | false | | EnvoyService defines the desired state of the Envoy service resource.
If unspecified, default settings for the managed Envoy service resource
are applied. | +| `envoyHpa` | _[KubernetesHorizontalPodAutoscalerSpec](#kuberneteshorizontalpodautoscalerspec)_ | false | | EnvoyHpa defines the Horizontal Pod Autoscaler settings for Envoy Proxy Deployment. | +| `useListenerPortAsContainerPort` | _boolean_ | false | | UseListenerPortAsContainerPort disables the port shifting feature in the Envoy Proxy.
When set to false (default value), if the service port is a privileged port (1-1023), add a constant to the value converting it into an ephemeral port.
This allows the container to bind to the port without needing a CAP_NET_BIND_SERVICE capability. | +| `envoyPDB` | _[KubernetesPodDisruptionBudgetSpec](#kubernetespoddisruptionbudgetspec)_ | false | | EnvoyPDB allows to control the pod disruption budget of an Envoy Proxy. | +| `envoyServiceAccount` | _[KubernetesServiceAccountSpec](#kubernetesserviceaccountspec)_ | true | | EnvoyServiceAccount defines the desired state of the Envoy service account resource. | + + +#### EnvoyProxyProvider + + + +EnvoyProxyProvider defines the desired state of a resource provider. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[EnvoyProxyProviderType](#envoyproxyprovidertype)_ | true | | Type is the type of resource provider to use. A resource provider provides
infrastructure resources for running the data plane, e.g. Envoy proxy, and
optional auxiliary control planes. Supported types are "Kubernetes"and "Host". | +| `kubernetes` | _[EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider)_ | false | | Kubernetes defines the desired state of the Kubernetes resource provider.
Kubernetes provides infrastructure resources for running the data plane,
e.g. Envoy proxy. If unspecified and type is "Kubernetes", default settings
for managed Kubernetes resources are applied. | +| `host` | _[EnvoyProxyHostProvider](#envoyproxyhostprovider)_ | false | | Host provides runtime deployment of the data plane as a child process on the
host environment.
If unspecified and type is "Host", default settings for the custom provider
are applied. | + + +#### EnvoyProxyProviderType + +_Underlying type:_ _string_ + +EnvoyProxyProviderType defines the types of providers supported by Envoy Proxy. + +_Appears in:_ +- [EnvoyProxyProvider](#envoyproxyprovider) + +| Value | Description | +| ----- | ----------- | +| `Kubernetes` | EnvoyProxyProviderTypeKubernetes defines the "Kubernetes" provider.
| +| `Host` | EnvoyProxyProviderTypeHost defines the "Host" provider.
| + + +#### EnvoyProxySpec + + + +EnvoyProxySpec defines the desired state of EnvoyProxy. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) +- [EnvoyProxy](#envoyproxy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `provider` | _[EnvoyProxyProvider](#envoyproxyprovider)_ | false | | Provider defines the desired resource provider and provider-specific configuration.
If unspecified, the "Kubernetes" resource provider is used with default configuration
parameters. | +| `logging` | _[ProxyLogging](#proxylogging)_ | true | \{ level:map[default:warn] \} | Logging defines logging parameters for managed proxies. | +| `telemetry` | _[ProxyTelemetry](#proxytelemetry)_ | false | | Telemetry defines telemetry parameters for managed proxies. | +| `bootstrap` | _[ProxyBootstrap](#proxybootstrap)_ | false | | Bootstrap defines the Envoy Bootstrap as a YAML string.
Visit https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-msg-config-bootstrap-v3-bootstrap
to learn more about the syntax.
If set, this is the Bootstrap configuration used for the managed Envoy Proxy fleet instead of the default Bootstrap configuration
set by Envoy Gateway.
Some fields within the Bootstrap that are required to communicate with the xDS Server (Envoy Gateway) and receive xDS resources
from it are not configurable and will result in the `EnvoyProxy` resource being rejected.
Backward compatibility across minor versions is not guaranteed.
We strongly recommend using `egctl x translate` to generate a `EnvoyProxy` resource with the `Bootstrap` field set to the default
Bootstrap configuration used. You can edit this configuration, and rerun `egctl x translate` to ensure there are no validation errors. | +| `concurrency` | _integer_ | false | | Concurrency defines the number of worker threads to run. If unset, it defaults to
the number of cpuset threads on the platform. | +| `routingType` | _[RoutingType](#routingtype)_ | false | | RoutingType can be set to "Service" to use the Service Cluster IP for routing to the backend,
or it can be set to "Endpoint" to use Endpoint routing. The default is "Endpoint". | +| `extraArgs` | _string array_ | false | | ExtraArgs defines additional command line options that are provided to Envoy.
More info: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#command-line-options
Note: some command line options are used internally(e.g. --log-level) so they cannot be provided here. | +| `mergeGateways` | _boolean_ | false | | MergeGateways defines if Gateway resources should be merged onto the same Envoy Proxy Infrastructure.
Setting this field to true would merge all Gateway Listeners under the parent Gateway Class.
This means that the port, protocol and hostname tuple must be unique for every listener.
If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a "Accepted=False" condition. | +| `shutdown` | _[ShutdownConfig](#shutdownconfig)_ | false | | Shutdown defines configuration for graceful envoy shutdown process. | +| `filterOrder` | _[FilterPosition](#filterposition) array_ | false | | FilterOrder defines the order of filters in the Envoy proxy's HTTP filter chain.
The FilterPosition in the list will be applied in the order they are defined.
If unspecified, the default filter order is applied.
Default filter order is:
- envoy.filters.http.custom_response
- envoy.filters.http.health_check
- envoy.filters.http.fault
- envoy.filters.http.cors
- envoy.filters.http.header_mutation
- envoy.filters.http.ext_authz
- envoy.filters.http.api_key_auth
- envoy.filters.http.basic_auth
- envoy.filters.http.oauth2
- envoy.filters.http.jwt_authn
- envoy.filters.http.stateful_session
- envoy.filters.http.buffer
- envoy.filters.http.lua
- envoy.filters.http.ext_proc
- envoy.filters.http.wasm
- envoy.filters.http.dynamic_modules
- envoy.filters.http.geoip
- envoy.filters.http.rbac
- envoy.filters.http.local_ratelimit
- envoy.filters.http.ratelimit
- envoy.filters.http.bandwidth_limit
- envoy.filters.http.grpc_web
- envoy.filters.http.grpc_stats
- envoy.filters.http.credential_injector
- envoy.filters.http.compressor
- envoy.filters.http.dynamic_forward_proxy
- envoy.filters.http.router
Note: "envoy.filters.http.router" cannot be reordered, it's always the last filter in the chain. | +| `backendTLS` | _[BackendTLSConfig](#backendtlsconfig)_ | false | | BackendTLS is the TLS configuration for the Envoy proxy to use when connecting to backends.
These settings are applied on backends for which TLS policies are specified. | +| `ipFamily` | _[IPFamily](#ipfamily)_ | false | | IPFamily specifies the IP family for the EnvoyProxy fleet.
This setting only affects the Gateway listener port and does not impact
other aspects of the Envoy proxy configuration.
If not specified, the system will operate as follows:
- It defaults to IPv4 only.
- IPv6 and dual-stack environments are not supported in this default configuration.
Note: To enable IPv6 or dual-stack functionality, explicit configuration is required. | +| `preserveRouteOrder` | _boolean_ | false | | PreserveRouteOrder determines if the order of matching for HTTPRoutes is determined by Gateway-API
specification (https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httprouterule)
or preserves the order defined by users in the HTTPRoute's HTTPRouteRule list.
Default: False | +| `luaValidation` | _[LuaValidation](#luavalidation)_ | false | | LuaValidation determines strictness of the Lua script validation for Lua EnvoyExtensionPolicies
Default: Strict | +| `dynamicModules` | _[DynamicModuleEntry](#dynamicmoduleentry) array_ | false | | DynamicModules defines the set of dynamic modules that are allowed to be
used by EnvoyExtensionPolicy resources and dynamic module load balancer
policies. Each entry registers a module by a logical name and specifies
the shared library that Envoy will load.
The EnvoyProxy owner is responsible for ensuring the module .so files are available
on the proxy container's filesystem (e.g., via init containers, custom images,
or shared volumes). | +| `geoIP` | _[EnvoyProxyGeoIP](#envoyproxygeoip)_ | false | | GeoIP defines shared GeoIP provider configuration for this EnvoyProxy fleet. | +| `mergeType` | _[MergeType](#mergetype)_ | false | | MergeType controls how this EnvoyProxy merges with less specific configurations
in the hierarchy (EnvoyGateway defaults < GatewayClass < Gateway).
If unset, this EnvoyProxy completely replaces less specific settings.
Note: this field has no effect when set in EnvoyGateway's default EnvoyProxySpec. | + + +#### EnvoyProxyStatus + + + +EnvoyProxyStatus defines the observed state of EnvoyProxy. + +_Appears in:_ +- [EnvoyProxy](#envoyproxy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | + + +#### EnvoyResourceType + +_Underlying type:_ _string_ + +EnvoyResourceType specifies the type URL of the Envoy resource. + +_Appears in:_ +- [EnvoyJSONPatchConfig](#envoyjsonpatchconfig) + +| Value | Description | +| ----- | ----------- | +| `type.googleapis.com/envoy.config.listener.v3.Listener` | ListenerEnvoyResourceType defines the Type URL of the Listener resource
| +| `type.googleapis.com/envoy.config.route.v3.RouteConfiguration` | RouteConfigurationEnvoyResourceType defines the Type URL of the RouteConfiguration resource
| +| `type.googleapis.com/envoy.config.cluster.v3.Cluster` | ClusterEnvoyResourceType defines the Type URL of the Cluster resource
| +| `type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment` | ClusterLoadAssignmentEnvoyResourceType defines the Type URL of the ClusterLoadAssignment resource
| +| `type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret` | SecretEnvoyResourceType defines the Type URL of the Secret resource
| + + +#### ExtAuth + + + +ExtAuth defines the configuration for External Authorization. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `grpc` | _[GRPCExtAuthService](#grpcextauthservice)_ | true | | GRPC defines the gRPC External Authorization service.
Either GRPCService or HTTPService must be specified,
and only one of them can be provided. | +| `http` | _[HTTPExtAuthService](#httpextauthservice)_ | true | | HTTP defines the HTTP External Authorization service.
Either GRPCService or HTTPService must be specified,
and only one of them can be provided. | +| `headersToExtAuth` | _string array_ | false | | HeadersToExtAuth defines the client request headers that will be included
in the request to the external authorization service.
Note: If not specified, the default behavior for gRPC and HTTP external
authorization services is different due to backward compatibility reasons.
All headers will be included in the check request to a gRPC authorization server.
Only the following headers will be included in the check request to an HTTP
authorization server: Host, Method, Path, Content-Length, and Authorization.
And these headers will always be included to the check request to an HTTP
authorization server by default, no matter whether they are specified
in HeadersToExtAuth or not. | +| `bodyToExtAuth` | _[BodyToExtAuth](#bodytoextauth)_ | false | | BodyToExtAuth defines the Body to Ext Auth configuration. | +| `timeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | Timeout defines the timeout for requests to the external authorization service.
If not specified, defaults to 10 seconds. | +| `failOpen` | _boolean_ | false | false | FailOpen is a switch used to control the behavior when a response from the External Authorization service cannot be obtained.
If FailOpen is set to true, the system allows the traffic to pass through.
Otherwise, if it is set to false or not set (defaulting to false),
the system blocks the traffic and returns a HTTP 5xx error, reflecting a fail-closed approach.
This setting determines whether to prioritize accessibility over strict security in case of authorization service failure.
If set to true, the External Authorization will also be bypassed if its configuration is invalid. | +| `recomputeRoute` | _boolean_ | false | | RecomputeRoute clears the route cache and recalculates the routing decision.
This field must be enabled if the headers added or modified by the ExtAuth are used for
route matching decisions. If the recomputation selects a new route, features targeting
the new matched route will be applied. | +| `includeRouteMetadata` | _boolean_ | false | | IncludeRouteMetadata sends Envoy Gateway's built-in route metadata to the
external authorization service as context.
This includes Envoy Gateway's built-in metadata for the selected route in
the "envoy-gateway" metadata namespace.
The metadata is exposed under the "resources" field as a list of route
resource objects. For example:
envoy-gateway:
resources:
- kind: HTTPRoute
name: backend
namespace: default
annotations:
foo: bar
The resource object may include fields such as kind, namespace, name,
sectionName, and supported route annotations. | +| `contextExtensions` | _[ContextExtension](#contextextension) array_ | false | | ContextExtensions are analogous to http_request.headers, however these
contents will not be sent to the upstream server. This provides an
extension mechanism for sending additional information to the auth server
without modifying the proto definition. It maps to the internal opaque
context in the filter chain. | +| `statusOnError` | _integer_ | false | | Sets the HTTP status that is returned when the authorization service returns an error
or cannot be reached. Defaults to 403 Forbidden.
Only 4xx and 5xx status codes are supported. | + + +#### ExtProc + + + +ExtProc defines the configuration for External Processing filter. + +_Appears in:_ +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `messageTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MessageTimeout is the timeout for a response to be returned from the external processor
Default: 200ms | +| `failOpen` | _boolean_ | false | false | FailOpen is a switch used to control the behavior when failing to call the external processor.
If FailOpen is set to true, the system bypasses the ExtProc extension and
allows the traffic to pass through. If it is set to false or
not set (defaulting to false), the system blocks the traffic and returns
an HTTP 5xx error.
If set to true, the ExtProc extension will also be bypassed if the configuration is invalid. | +| `processingMode` | _[ExtProcProcessingMode](#extprocprocessingmode)_ | false | | ProcessingMode defines how request and response body is processed
Default: header and body are not sent to the external processor | +| `metadata` | _[ExtProcMetadata](#extprocmetadata)_ | false | | Refer to Kubernetes API documentation for fields of `metadata`. | + + +#### ExtProcBodyProcessingMode + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [ProcessingModeOptions](#processingmodeoptions) + +| Value | Description | +| ----- | ----------- | +| `Streamed` | StreamedExtProcBodyProcessingMode will stream the body to the server in pieces as they arrive at the proxy.
| +| `Buffered` | BufferedExtProcBodyProcessingMode will buffer the message body in memory and send the entire body at once. If the body exceeds the configured buffer limit, then the downstream system will receive an error.
| +| `FullDuplexStreamed` | FullDuplexStreamedExtBodyProcessingMode will send the body in pieces, to be read in a stream. When enabled, trailers are also sent, and failOpen must be false.
Full details here: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/processing_mode.proto.html#enum-extensions-filters-http-ext-proc-v3-processingmode-bodysendmode
| +| `BufferedPartial` | BufferedPartialExtBodyHeaderProcessingMode will buffer the message body in memory and send the entire body in one chunk. If the body exceeds the configured buffer limit, then the body contents up to the buffer limit will be sent.
| + + +#### ExtProcMetadata + + + +ExtProcMetadata defines options related to the sending and receiving of dynamic metadata to and from the +external processor service + +_Appears in:_ +- [ExtProc](#extproc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `accessibleNamespaces` | _string array_ | false | | AccessibleNamespaces are metadata namespaces that are sent to the external processor as context | +| `writableNamespaces` | _string array_ | false | | WritableNamespaces are metadata namespaces that the external processor can write to | + + +#### ExtProcProcessingMode + + + +ExtProcProcessingMode defines if and how headers and bodies are sent to the service. +https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_proc/v3/processing_mode.proto#envoy-v3-api-msg-extensions-filters-http-ext-proc-v3-processingmode + +_Appears in:_ +- [ExtProc](#extproc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `request` | _[ProcessingModeOptions](#processingmodeoptions)_ | false | | Defines processing mode for requests. If present, request headers are sent. Request body is processed according
to the specified mode. | +| `response` | _[ProcessingModeOptions](#processingmodeoptions)_ | false | | Defines processing mode for responses. If present, response headers are sent. Response body is processed according
to the specified mode. | +| `allowModeOverride` | _boolean_ | false | | AllowModeOverride allows the external processor to override the processing mode set via the
`mode_override` field in the gRPC response message. This defaults to false. | + + +#### ExtensionAPISettings + + + +ExtensionAPISettings defines the settings specific to Gateway API Extensions. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enableEnvoyPatchPolicy` | _boolean_ | true | | EnableEnvoyPatchPolicy enables Envoy Gateway to
reconcile and implement the EnvoyPatchPolicy resources.
Warning: Enabling `EnvoyPatchPolicy` may lead to complete security compromise of your system.
Users with `EnvoyPatchPolicy` permissions can inject arbitrary configuration to proxies,
leading to high Confidentiality, Integrity and Availability risks. | +| `enableBackend` | _boolean_ | true | | EnableBackend enables Envoy Gateway to
reconcile and implement the Backend resources. | +| `disableLua` | _boolean_ | true | | DisableLua determines if Lua EnvoyExtensionPolicies should be disabled.
If set to true, the Lua EnvoyExtensionPolicy feature will be disabled. | +| `enableSDSSecretRef` | _boolean_ | true | | EnableSDSSecretRef enables read SDS(Secret Discovery Service) settings from a secret(with type gateway.envoyproxy.io/sds). | + + +#### ExtensionHooks + + + +ExtensionHooks defines extension hooks across all supported runners + +_Appears in:_ +- [ExtensionManager](#extensionmanager) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `xdsTranslator` | _[XDSTranslatorHooks](#xdstranslatorhooks)_ | true | | XDSTranslator defines all the supported extension hooks for the xds-translator runner | + + +#### ExtensionManager + + + +ExtensionManager defines the configuration for registering an extension manager to +the Envoy Gateway control plane. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | false | | Name is a unique identifier for this extension manager. Required when using
the plural ExtensionManagers field. Used for logging, metrics, and error identification. | +| `resources` | _[GroupVersionKind](#groupversionkind) array_ | false | | Resources defines the set of K8s resources the extension will handle as route
filter resources | +| `policyResources` | _[GroupVersionKind](#groupversionkind) array_ | false | | PolicyResources defines the set of K8S resources the extension server will handle
as directly attached Gateway API policies. Only policies in the same namespace as
the target Gateway resources are supported. Cross-namespace attachments are not supported. | +| `backendResources` | _[GroupVersionKind](#groupversionkind) array_ | false | | BackendResources defines the set of K8s resources the extension will handle as
custom backendRef resources. These resources can be referenced in HTTPRoute
backendRefs to enable support for custom backend types (e.g., S3, Lambda, etc.)
that are not natively supported by Envoy Gateway. | +| `hooks` | _[ExtensionHooks](#extensionhooks)_ | true | | Hooks defines the set of hooks the extension supports | +| `service` | _[ExtensionService](#extensionservice)_ | true | | Service defines the configuration of the extension service that the Envoy
Gateway Control Plane will call through extension hooks. | +| `failOpen` | _boolean_ | false | | FailOpen defines if Envoy Gateway should ignore errors returned from the Extension Service hooks.
When set to false, Envoy Gateway does not ignore extension Service hook errors. As a result,
xDS updates are skipped for the relevant envoy proxy fleet and the previous state is preserved.
When set to true, if the Extension Service hooks return an error, no changes will be applied to the
source of the configuration which was sent to the extension server. The errors are ignored and the resulting
xDS configuration is updated in the xDS snapshot.
Default: false | +| `maxMessageSize` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | MaxMessageSize defines the maximum message size in bytes that can be
sent to or received from the Extension Service.
Default: 4M | + + +#### ExtensionService + + + +ExtensionService defines the configuration for connecting to a registered extension service. + +_Appears in:_ +- [ExtensionManager](#extensionmanager) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostname` | _string_ | false | | Hostname defines an optional hostname for the backend endpoint. | +| `fqdn` | _[FQDNEndpoint](#fqdnendpoint)_ | false | | FQDN defines a FQDN endpoint | +| `ip` | _[IPEndpoint](#ipendpoint)_ | false | | IP defines an IP endpoint. Supports both IPv4 and IPv6 addresses. | +| `unix` | _[UnixSocket](#unixsocket)_ | false | | Unix defines the unix domain socket endpoint | +| `zone` | _string_ | false | | Zone defines the service zone of the backend endpoint. | +| `host` | _string_ | false | | Host define the extension service hostname.
Deprecated: use the appropriate transport attribute instead (FQDN,IP,Unix) | +| `port` | _integer_ | false | 80 | Port defines the port the extension service is exposed on.
Deprecated: use the appropriate transport attribute instead (FQDN,IP,Unix) | +| `tls` | _[ExtensionTLS](#extensiontls)_ | false | | TLS defines TLS configuration for communication between Envoy Gateway and
the extension service. | +| `retry` | _[ExtensionServiceRetry](#extensionserviceretry)_ | false | | Retry defines the retry policy for to use when errors are encountered in communication with
the extension service. | + + +#### ExtensionServiceRetry + + + +ExtensionServiceRetry defines the retry policy for to use when errors are encountered in communication with the extension service. + +_Appears in:_ +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `maxAttempts` | _integer_ | false | | MaxAttempts defines the maximum number of retry attempts.
Default: 4 | +| `initialBackoff` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | InitialBackoff defines the initial backoff in seconds for retries, details: https://github.com/grpc/proposal/blob/master/A6-client-retries.md#integration-with-service-config.
Default: 0.1s | +| `maxBackoff` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxBackoff defines the maximum backoff in seconds for retries.
Default: 1s | +| `backoffMultiplier` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | false | | BackoffMultiplier defines the multiplier to use for exponential backoff for retries.
Default: 2.0 | +| `RetryableStatusCodes` | _[RetryableGRPCStatusCode](#retryablegrpcstatuscode) array_ | false | | RetryableStatusCodes defines the grpc status code for which retries will be attempted.
Default: [ "UNAVAILABLE" ] | + + +#### ExtensionTLS + + + +ExtensionTLS defines the TLS configuration when connecting to an extension service. + +_Appears in:_ +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `certificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | true | | CertificateRef is a reference to a Kubernetes Secret with a CA certificate in a key named "tls.crt".
The CA certificate is used by Envoy Gateway to verify the server certificate presented by the extension server. | +| `clientCertificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | false | | ClientCertificateRef is a reference to a Kubernetes Secret with a client certificate and key
for client certificate authentication (mTLS). The secret must contain both "tls.crt" and "tls.key" keys.
When specified, Envoy Gateway will present this client certificate to the extension server
for mTLS authentication. If not specified, only server certificate validation is performed. | + + +#### ExtractFrom + + + +ExtractFrom is where to fetch the key from the coming request. +Only one of header, param or cookie is supposed to be specified. + +_Appears in:_ +- [APIKeyAuth](#apikeyauth) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `headers` | _string array_ | false | | Headers is the names of the header to fetch the key from.
If multiple headers are specified, envoy will look for the api key in the order of the list.
This field is optional, but only one of headers, params or cookies is supposed to be specified. | +| `params` | _string array_ | false | | Params is the names of the query parameter to fetch the key from.
If multiple params are specified, envoy will look for the api key in the order of the list.
This field is optional, but only one of headers, params or cookies is supposed to be specified. | +| `cookies` | _string array_ | false | | Cookies is the names of the cookie to fetch the key from.
If multiple cookies are specified, envoy will look for the api key in the order of the list.
This field is optional, but only one of headers, params or cookies is supposed to be specified. | + + +#### FQDNEndpoint + + + +FQDNEndpoint describes TCP/UDP socket address, corresponding to Envoy's Socket Address +https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-socketaddress + +_Appears in:_ +- [BackendEndpoint](#backendendpoint) +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostname` | _string_ | true | | Hostname defines the FQDN hostname of the backend endpoint. | +| `port` | _integer_ | true | | Port defines the port of the backend endpoint. | + + +#### FaultInjection + + + +FaultInjection defines the fault injection policy to be applied. This configuration can be used to +inject delays and abort requests to mimic failure scenarios such as service failures and overloads + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `delay` | _[FaultInjectionDelay](#faultinjectiondelay)_ | false | | If specified, a delay will be injected into the request. | +| `abort` | _[FaultInjectionAbort](#faultinjectionabort)_ | false | | If specified, the request will be aborted if it meets the configuration criteria. | + + +#### FaultInjectionAbort + + + +FaultInjectionAbort defines the abort fault injection configuration + +_Appears in:_ +- [FaultInjection](#faultinjection) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `httpStatus` | _integer_ | false | | StatusCode specifies the HTTP status code to be returned | +| `grpcStatus` | _integer_ | false | | GrpcStatus specifies the GRPC status code to be returned | +| `percentage` | _float_ | false | 100 | Percentage specifies the percentage of requests to be aborted. Default 100%, if set 0, no requests will be aborted. Accuracy to 0.0001%. | + + +#### FaultInjectionDelay + + + +FaultInjectionDelay defines the delay fault injection configuration + +_Appears in:_ +- [FaultInjection](#faultinjection) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `fixedDelay` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | true | | FixedDelay specifies the fixed delay duration | +| `percentage` | _float_ | false | 100 | Percentage specifies the percentage of requests to be delayed. Default 100%, if set 0, no requests will be delayed. Accuracy to 0.0001%. | + + +#### FileEnvoyProxyAccessLog + + + + + +_Appears in:_ +- [ProxyAccessLogSink](#proxyaccesslogsink) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `path` | _string_ | true | | Path defines the file path used to expose envoy access log(e.g. /dev/stdout). | + + +#### FilterPosition + + + +FilterPosition defines the position of an Envoy HTTP filter in the filter chain. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _[EnvoyFilter](#envoyfilter)_ | true | | Name of the filter. | +| `before` | _[EnvoyFilter](#envoyfilter)_ | true | | Before defines the filter that should come before the filter.
Only one of Before or After must be set. | +| `after` | _[EnvoyFilter](#envoyfilter)_ | true | | After defines the filter that should come after the filter.
Only one of Before or After must be set. | + + +#### ForceLocalZone + + + +ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior +which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally. + +_Appears in:_ +- [PreferLocalZone](#preferlocalzone) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `minEndpointsInZoneThreshold` | _integer_ | false | | MinEndpointsInZoneThreshold is the minimum number of upstream endpoints in the local zone required to honor the forceLocalZone
override. This is useful for protecting zones with fewer endpoints. | + + +#### GRPCActiveHealthChecker + + + +GRPCActiveHealthChecker defines the settings of the GRPC health check. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `service` | _string_ | false | | Service to send in the health check request.
If this is not specified, then the health check request applies to the entire
server and not to a specific service. | + + +#### GRPCExtAuthService + + + +GRPCExtAuthService defines the gRPC External Authorization service +The authorization request message is defined in +https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto + +_Appears in:_ +- [ExtAuth](#extauth) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | + + +#### GRPCSettings + + + +GRPCSettings provides gRPC configuration for listeners. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enableWeb` | _boolean_ | false | | EnableWeb configures the gRPC-web filter on the listener.
The gRPC-web filter allows clients (typically browsers) to make gRPC calls
using HTTP/1.1 or HTTP/2.
This is enabled by default for GRPCRoute and opt-in for HTTPRoute.
In general, gRPC traffic should be handled via GRPCRoute, but there are cases where
users want to route gRPC using HTTPRoute for its richer matching capabilities.
Therefore, we enable this behavior only when it is explicitly opted in. | + + +#### GRPCSuccessCode + +_Underlying type:_ _string_ + +GRPCSuccessCode defines gRPC status codes as defined in +https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc. + +_Appears in:_ +- [GRPCSuccessCriteria](#grpcsuccesscriteria) + +| Value | Description | +| ----- | ----------- | +| `Ok` | | +| `Cancelled` | | +| `Unknown` | | +| `InvalidArgument` | | +| `DeadlineExceeded` | | +| `NotFound` | | +| `AlreadyExists` | | +| `PermissionDenied` | | +| `ResourceExhausted` | | +| `FailedPrecondition` | | +| `Aborted` | | +| `OutOfRange` | | +| `Unimplemented` | | +| `Internal` | | +| `Unavailable` | | +| `DataLoss` | | +| `Unauthenticated` | | + + +#### GRPCSuccessCriteria + + + +GRPCSuccessCriteria defines success criteria for gRPC requests. + +_Appears in:_ +- [AdmissionControlSuccessCriteria](#admissioncontrolsuccesscriteria) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `statusCodes` | _[GRPCSuccessCode](#grpcsuccesscode) array_ | false | | StatusCodes defines gRPC status codes that are considered successful.
Status codes are defined in https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc. | + + +#### Gateway + + + +Gateway defines the desired Gateway API configuration of Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `controllerName` | _string_ | false | | ControllerName defines the name of the Gateway API controller. If unspecified,
defaults to "gateway.envoyproxy.io/gatewayclass-controller". See the following
for additional details:
https://gateway-api.sigs.k8s.io/reference/1.4/spec/#gatewayclass | + + +#### GatewayAPI + +_Underlying type:_ _string_ + +GatewayAPI defines an experimental Gateway API resource that can be enabled. + +_Appears in:_ +- [GatewayAPISettings](#gatewayapisettings) + + + +#### GatewayAPISettings + + + +GatewayAPISettings provides a mechanism to opt into experimental Gateway API resources. +These APIs are experimental today and are subject to change or removal as they mature. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enabled` | _[GatewayAPI](#gatewayapi) array_ | true | | | + + +#### GeoIPAnonymousMatch + + + +GeoIPAnonymousMatch matches anonymous network signals emitted by the GeoIP provider. +If multiple fields are specified, all specified fields must match. +These signals are not mutually exclusive. A single IP may satisfy multiple +flags at the same time (for example, a commercial VPN exit IP may also be +classified as a public proxy, so both IsVPN and IsProxy can be true). + +_Appears in:_ +- [ClientIPGeoLocation](#clientipgeolocation) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `isAnonymous` | _boolean_ | false | | IsAnonymous matches whether the client IP is considered anonymous. | +| `isVPN` | _boolean_ | false | | IsVPN matches whether the client IP is detected as VPN. | +| `isHosting` | _boolean_ | false | | IsHosting matches whether the client IP belongs to a hosting provider. | +| `isTor` | _boolean_ | false | | IsTor matches whether the client IP belongs to a Tor exit node. | +| `isProxy` | _boolean_ | false | | IsProxy matches whether the client IP belongs to a public proxy. | + + +#### GeoIPDBSource + + + +GeoIPDBSource defines where a GeoIP .mmdb database can be loaded from. + +_Appears in:_ +- [GeoIPMaxMind](#geoipmaxmind) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `local` | _[LocalGeoIPDBSource](#localgeoipdbsource)_ | true | | Local is a database source from a local file. | + + +#### GeoIPMaxMind + + + +GeoIPMaxMind configures the MaxMind provider. +These database files are expected to be mounted into the Envoy container, and a sidecar container can be used to update the database files. + +_Appears in:_ +- [GeoIPProvider](#geoipprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `cityDbSource` | _[GeoIPDBSource](#geoipdbsource)_ | false | | CityDBSource configures the City database source. | +| `countryDbSource` | _[GeoIPDBSource](#geoipdbsource)_ | false | | CountryDBSource configures the Country database source. | +| `asnDbSource` | _[GeoIPDBSource](#geoipdbsource)_ | false | | ASNDBSource configures the ASN database source. | +| `ispDbSource` | _[GeoIPDBSource](#geoipdbsource)_ | false | | ISPDBSource configures the ISP database source. | +| `anonymousIpDbSource` | _[GeoIPDBSource](#geoipdbsource)_ | false | | AnonymousIPDBSource configures the Anonymous IP database source. | + + +#### GeoIPProvider + + + +GeoIPProvider defines provider-specific settings. + +_Appears in:_ +- [EnvoyProxyGeoIP](#envoyproxygeoip) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[GeoIPProviderType](#geoipprovidertype)_ | true | | | +| `maxMind` | _[GeoIPMaxMind](#geoipmaxmind)_ | false | | MaxMind configures the MaxMind provider. | + + +#### GeoIPProviderType + +_Underlying type:_ _string_ + +GeoIPProviderType enumerates GeoIP providers supported by Envoy Gateway. + +_Appears in:_ +- [GeoIPProvider](#geoipprovider) + +| Value | Description | +| ----- | ----------- | +| `MaxMind` | GeoIPProviderTypeMaxMind configures Envoy with the MaxMind provider pointing to local files.
| + + +#### GlobalRateLimit + + + +GlobalRateLimit defines global rate limit configuration. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `rules` | _[RateLimitRule](#ratelimitrule) array_ | true | | Rules are a list of RateLimit selectors and limits. Each rule and its
associated limit is applied in a mutually exclusive way. If a request
matches multiple rules, each of their associated limits get applied, so a
single request might increase the rate limit counters for multiple rules
if selected. The rate limit service will return a logical OR of the individual
rate limit decisions of all matching rules. For example, if a request
matches two rules, one rate limited and one not, the final decision will be
to rate limit the request. | + + +#### GroupVersionKind + + + +GroupVersionKind unambiguously identifies a Kind. +It can be converted to k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind + +_Appears in:_ +- [ExtensionManager](#extensionmanager) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `group` | _string_ | true | | | +| `version` | _string_ | true | | | +| `kind` | _string_ | true | | | + + +#### GzipCompressor + + + +GzipCompressor defines the config for the Gzip compressor. +The default values can be found here: +https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/compression/gzip/compressor/v3/gzip.proto#extension-envoy-compression-gzip-compressor + +_Appears in:_ +- [Compression](#compression) + + + +#### HTTP10Settings + + + +HTTP10Settings provides HTTP/1.0 configuration on the listener. + +_Appears in:_ +- [HTTP1Settings](#http1settings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `useDefaultHost` | _boolean_ | false | | UseDefaultHost specifies whether a default Host header should be injected
into HTTP/1.0 requests that do not include one.
When set to true, Envoy Gateway injects the hostname associated with the
listener or route into the request, in the following order:
1. If the targeted listener has a non-wildcard hostname, use that hostname.
2. If there is exactly one HTTPRoute with a non-wildcard hostname under
the targeted listener, use that hostname.
Note: Setting this field to true without a non-wildcard hostname makes the
ClientTrafficPolicy invalid. | + + +#### HTTP1Settings + + + +HTTP1Settings provides HTTP/1 configuration on the listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enableTrailers` | _boolean_ | false | | EnableTrailers defines if HTTP/1 trailers should be proxied by Envoy. | +| `preserveHeaderCase` | _boolean_ | false | | PreserveHeaderCase defines if Envoy should preserve the letter case of headers.
By default, Envoy will lowercase all the headers. | +| `http10` | _[HTTP10Settings](#http10settings)_ | false | | HTTP10 turns on support for HTTP/1.0 and HTTP/0.9 requests. | +| `disableSafeMaxConnectionDuration` | _boolean_ | false | | DisableSafeMaxConnectionDuration controls the close behavior for HTTP/1 connections.
By default, connection closure is delayed until the next request arrives after maxConnectionDuration is exceeded.
It then adds a Connection: close header and gracefully closes the connection after the response completes.
When set to true (disabled), Envoy uses its default drain behavior, closing the connection shortly after maxConnectionDuration elapses.
Has no effect unless maxConnectionDuration is set. | +| `ignoredUpgradeTypes` | _[StringMatch](#stringmatch) array_ | false | | IgnoredUpgradeTypes specifies a list of upgrade types for which
HTTP/1.1 Upgrade requests should be ignored by Envoy instead of being
rejected with a 403 response. When a client sends an HTTP/1.1 request
with Connection: Upgrade and an Upgrade header matching one of these
matchers, Envoy will strip the upgrade headers and process the request
as a normal HTTP/1.1 request.
Example: To ignore TLS upgrade requests (RFC 2817), use a Prefix match with value "TLS/". | + + +#### HTTP2KeepaliveSettings + + + +HTTP2KeepaliveSettings configures HTTP/2 PING-based keepalive settings. + +_Appears in:_ +- [HTTP2Settings](#http2settings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `interval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | Interval specifies how often to send HTTP/2 PING frames to keep the connection alive. | +| `timeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | Timeout specifies how long to wait for a PING response before considering the connection dead. | +| `intervalJitter` | _integer_ | false | | IntervalJitter specifies a random jitter percentage added to each interval.
Defaults to 15% if not specified. | +| `idleInterval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | IdleInterval specifies how long a connection must be idle before a PING is sent. | + + +#### HTTP2Settings + + + +HTTP2Settings provides HTTP/2 configuration for listeners and backends. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `initialStreamWindowSize` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | InitialStreamWindowSize sets the initial window size for HTTP/2 streams.
If not set, the default value is 64 KiB(64*1024). | +| `initialConnectionWindowSize` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | false | | InitialConnectionWindowSize sets the initial window size for HTTP/2 connections.
If not set, the default value is 1 MiB. | +| `maxConcurrentStreams` | _integer_ | false | | MaxConcurrentStreams sets the maximum number of concurrent streams allowed per connection.
If not set, the default value is 100. | +| `onInvalidMessage` | _[InvalidMessageAction](#invalidmessageaction)_ | false | | OnInvalidMessage determines if Envoy will terminate the connection or just the offending stream in the event of HTTP messaging error
It's recommended for L2 Envoy deployments to set this value to TerminateStream.
https://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/level_two
Default: TerminateConnection | +| `connectionKeepalive` | _[HTTP2KeepaliveSettings](#http2keepalivesettings)_ | false | | ConnectionKeepalive configures HTTP/2 connection keepalive using PING frames. | + + +#### HTTP3Settings + + + +HTTP3Settings provides HTTP/3 configuration on the listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + + + +#### HTTPActiveHealthChecker + + + +HTTPActiveHealthChecker defines the settings of http health check. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostname` | _string_ | false | | Hostname defines the HTTP Host header used for active HTTP health checks.
Host selection uses this order: this field, the associated Backend endpoint
hostname if available, then the effective Route hostname. | +| `path` | _string_ | true | | Path defines the HTTP path that will be requested during health checking. | +| `method` | _string_ | false | | Method defines the HTTP method used for health checking.
Defaults to GET | +| `expectedStatuses` | _[HTTPStatus](#httpstatus) array_ | false | | ExpectedStatuses defines a list of HTTP response statuses considered healthy.
Defaults to 200 only | +| `retriableStatuses` | _[HTTPStatus](#httpstatus) array_ | false | | RetriableStatuses defines a list of HTTP response statuses considered retriable.
Responses matching these statuses count towards the unhealthy threshold but
do not result in the host being considered immediately unhealthy.
The expected statuses take precedence for any range overlaps with this field. | +| `expectedResponse` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | | ExpectedResponse defines a list of HTTP expected responses to match. | + + +#### HTTPClientTimeout + + + + + +_Appears in:_ +- [ClientTimeout](#clienttimeout) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `requestReceivedTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | RequestReceivedTimeout is the duration envoy waits for the complete request reception. This timer starts upon request
initiation and stops when either the last byte of the request is sent upstream or when the response begins. | +| `idleTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | IdleTimeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.
Default: 1 hour. | +| `streamIdleTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The stream idle timeout defines the amount of time a stream can exist without any upstream or downstream activity.
Default: 5 minutes. | + + +#### HTTPCookieMatch + + + +HTTPCookieMatch defines how to match a single cookie. + +_Appears in:_ +- [HTTPRouteMatchFilter](#httproutematchfilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[CookieMatchType](#cookiematchtype)_ | false | Exact | Type specifies how to match against the value of the cookie. | +| `name` | _string_ | true | | Name is the cookie name to evaluate. | +| `value` | _string_ | true | | Value is the cookie value to be matched. | + + +#### HTTPCredentialInjectionFilter + + + +HTTPCredentialInjectionFilter defines the configuration to inject credentials into the request. +This is useful when the backend service requires credentials in the request, and the original +request does not contain them. The filter can inject credentials into the request before forwarding +it to the backend service. + +_Appears in:_ +- [HTTPRouteFilterSpec](#httproutefilterspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `header` | _string_ | false | | Header is the name of the header where the credentials are injected.
If not specified, the credentials are injected into the Authorization header. | +| `overwrite` | _boolean_ | false | | Whether to overwrite the value or not if the injected headers already exist.
If not specified, the default value is false. | +| `credential` | _[InjectedCredential](#injectedcredential)_ | true | | Credential is the credential to be injected. | + + +#### HTTPDirectResponseFilter + + + +HTTPDirectResponseFilter defines the configuration to return a fixed response. + +_Appears in:_ +- [HTTPRouteFilterSpec](#httproutefilterspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `contentType` | _string_ | false | | Content Type of the direct response. This will be set in the Content-Type header. | +| `body` | _[CustomResponseBody](#customresponsebody)_ | false | | Body of the direct response.
Supports Envoy command operators for dynamic content (see https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators). | +| `statusCode` | _integer_ | false | | Status Code of the HTTP response
If unset, defaults to 200. | +| `header` | _[HTTPHeaderFilter](#httpheaderfilter)_ | false | | Header defines the headers of the direct response. | + + +#### HTTPExtAuthService + + + +HTTPExtAuthService defines the HTTP External Authorization service + +_Appears in:_ +- [ExtAuth](#extauth) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `path` | _string_ | false | | Path is the path of the HTTP External Authorization service.
If path is specified, the authorization request will be sent to that path,
or else the authorization request will use the path of the original request.
Please note that the original request path will be appended to the path specified here.
For example, if the original request path is "/hello", and the path specified here is "/auth",
then the path of the authorization request will be "/auth/hello". If the path is not specified,
the path of the authorization request will be "/hello".
Only one of Path or PathOverride can be set. | +| `pathOverride` | _string_ | false | | PathOverride replaces the original request path in the authorization request.
If set, the path will be overridden to this value during authorization.
For example, if the original request path is "/hello", and PathOverride is set to "/auth",
then the path of the authorization request will be "/auth".
Only one of Path or PathOverride can be set. | +| `headersToBackend` | _string array_ | false | | HeadersToBackend are the authorization response headers that will be added
to the original client request before sending it to the backend server.
Note that coexisting headers will be overridden.
If not specified, no authorization response headers will be added to the
original client request. | + + +#### HTTPHeaderFilter + + + +HTTPHeaderFilter defines a filter that modifies the headers of an HTTP +request or response. Only one action for a given header name is +permitted. Filters specifying multiple actions of the same or different +type for any one header name are invalid. Configuration to set or add +multiple values for a header must use RFC 7230 header value formatting, +separating each value with a comma. + +_Appears in:_ +- [HeaderSettings](#headersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `set` | _[HTTPHeader](#httpheader) array_ | false | | Set overwrites the request with the given header (name, value)
before the action.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
set:
- name: "my-header"
value: "bar"
Output:
GET /foo HTTP/1.1
my-header: bar | +| `add` | _[HTTPHeader](#httpheader) array_ | false | | Add adds the given header(s) (name, value) to the request
before the action. It appends to any existing values associated
with the header name.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
add:
- name: "my-header"
value: "bar,baz"
Output:
GET /foo HTTP/1.1
my-header: foo,bar,baz | +| `addIfAbsent` | _[HTTPHeader](#httpheader) array_ | false | | AddIfAbsent adds the given header(s) (name, value) to the request/response
only if the header does not already exist. Unlike Add which appends to
existing values, this is a no-op if the header is already present.
Input:
GET /foo HTTP/1.1
my-header: foo
Config:
addIfAbsent:
- name: "my-header"
value: "bar"
Output:
GET /foo HTTP/1.1
my-header: foo | +| `remove` | _string array_ | false | | Remove the given header(s) from the HTTP request before the action. The
value of Remove is a list of HTTP header names. Note that the header
names are case-insensitive (see
https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
Input:
GET /foo HTTP/1.1
my-header1: foo
my-header2: bar
my-header3: baz
Config:
remove: ["my-header1", "my-header3"]
Output:
GET /foo HTTP/1.1
my-header2: bar | +| `removeOnMatch` | _[StringMatch](#stringmatch) array_ | false | | RemoveOnMatch removes headers whose names match the specified string matchers.
Matching is performed on the header name (case-insensitive). | + + +#### HTTPHostnameModifier + + + + + +_Appears in:_ +- [HTTPURLRewriteFilter](#httpurlrewritefilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[HTTPHostnameModifierType](#httphostnamemodifiertype)_ | true | | | +| `header` | _string_ | false | | Header is the name of the header whose value would be used to rewrite the Host header | + + +#### HTTPHostnameModifierType + +_Underlying type:_ _string_ + +HTTPPathModifierType defines the type of Hostname rewrite. + +_Appears in:_ +- [HTTPHostnameModifier](#httphostnamemodifier) + +| Value | Description | +| ----- | ----------- | +| `Header` | HeaderHTTPHostnameModifier indicates that the Host header value would be replaced with the value of the header specified in header.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-host-rewrite-header
| +| `Backend` | BackendHTTPHostnameModifier indicates that the Host header value would be replaced by the DNS name of the backend if it exists.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-auto-host-rewrite
| + + +#### HTTPPathModifier + + + + + +_Appears in:_ +- [HTTPURLRewriteFilter](#httpurlrewritefilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[HTTPPathModifierType](#httppathmodifiertype)_ | true | | | +| `replaceRegexMatch` | _[ReplaceRegexMatch](#replaceregexmatch)_ | false | | ReplaceRegexMatch defines a path regex rewrite. The path portions matched by the regex pattern are replaced by the defined substitution.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-regex-rewrite
Some examples:
(1) replaceRegexMatch:
pattern: ^/service/([^/]+)(/.*)$
substitution: \2/instance/\1
Would transform /service/foo/v1/api into /v1/api/instance/foo.
(2) replaceRegexMatch:
pattern: one
substitution: two
Would transform /xxx/one/yyy/one/zzz into /xxx/two/yyy/two/zzz.
(3) replaceRegexMatch:
pattern: ^(.*?)one(.*)$
substitution: \1two\2
Would transform /xxx/one/yyy/one/zzz into /xxx/two/yyy/one/zzz.
(3) replaceRegexMatch:
pattern: (?i)/xxx/
substitution: /yyy/
Would transform path /aaa/XxX/bbb into /aaa/yyy/bbb (case-insensitive). | + + +#### HTTPPathModifierType + +_Underlying type:_ _string_ + +HTTPPathModifierType defines the type of path redirect or rewrite. + +_Appears in:_ +- [HTTPPathModifier](#httppathmodifier) + +| Value | Description | +| ----- | ----------- | +| `ReplaceRegexMatch` | RegexHTTPPathModifier This type of modifier indicates that the portions of the path that match the specified
regex would be substituted with the specified substitution value
https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/matcher/v3/regex.proto#type-matcher-v3-regexmatchandsubstitute
| + + +#### HTTPRouteFilter + + + +HTTPRouteFilter is a custom Envoy Gateway HTTPRouteFilter which provides extended +traffic processing options such as path regex rewrite, direct response and more. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`HTTPRouteFilter` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[HTTPRouteFilterSpec](#httproutefilterspec)_ | true | | Spec defines the desired state of HTTPRouteFilter. | + + +#### HTTPRouteFilterSpec + + + +HTTPRouteFilterSpec defines the desired state of HTTPRouteFilter. + +_Appears in:_ +- [HTTPRouteFilter](#httproutefilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `urlRewrite` | _[HTTPURLRewriteFilter](#httpurlrewritefilter)_ | false | | | +| `directResponse` | _[HTTPDirectResponseFilter](#httpdirectresponsefilter)_ | false | | | +| `credentialInjection` | _[HTTPCredentialInjectionFilter](#httpcredentialinjectionfilter)_ | false | | | +| `matches` | _[HTTPRouteMatchFilter](#httproutematchfilter) array_ | false | | Matches defines additional matching criteria for the HTTPRoute rule.
As with HTTPRouteRule.Matches, the rule is matched if any one match applies.
When both HTTPRouteRule.Matches and HTTPRouteFilter.Matches are set, the
effective matching is the logical AND of the two sets. | + + +#### HTTPRouteMatchFilter + + + +HTTPRouteMatchFilter defines additional matching criteria for the HTTPRoute rule. +At least one matcher must be specified. + +_Appears in:_ +- [HTTPRouteFilterSpec](#httproutefilterspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `cookies` | _[HTTPCookieMatch](#httpcookiematch) array_ | true | | Cookies is a list of cookie matchers evaluated against the HTTP request.
All specified matchers must match. | + + +#### HTTPStatus + +_Underlying type:_ _integer_ + +HTTPStatus defines the http status code. + +_Appears in:_ +- [HTTPActiveHealthChecker](#httpactivehealthchecker) +- [HTTPSuccessCriteria](#httpsuccesscriteria) +- [RetryOn](#retryon) + + + +#### HTTPSuccessCriteria + + + +HTTPSuccessCriteria defines success criteria for HTTP requests. + +_Appears in:_ +- [AdmissionControlSuccessCriteria](#admissioncontrolsuccesscriteria) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `statusCodes` | _[HTTPStatus](#httpstatus) array_ | false | | StatusCodes defines HTTP status codes that are considered successful. | + + +#### HTTPTimeout + + + + + +_Appears in:_ +- [Timeout](#timeout) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `connectionIdleTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The idle timeout for an HTTP connection. Idle time is defined as a period in which there are no active requests in the connection.
Default: 1 hour. | +| `maxConnectionDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The maximum duration of an HTTP connection.
Default: unlimited. | +| `requestTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | RequestTimeout is the time until which entire response is received from the upstream. | +| `maxStreamDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxStreamDuration is the maximum duration for a stream to complete. This timeout measures the time
from when the request is sent until the response stream is fully consumed and does not apply to
non-streaming requests.
When set to "0s", no max duration is applied and streams can run indefinitely. | +| `streamIdleTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The stream idle timeout defines the amount of time a stream can exist without any upstream or downstream activity.
If not specified, StreamIdleTimeout is inherited from the listener-level setting, which can be configured via ClientTrafficPolicy. | + + +#### HTTPURLRewriteFilter + + + +HTTPURLRewriteFilter define rewrites of HTTP URL components such as path and host + +_Appears in:_ +- [HTTPRouteFilterSpec](#httproutefilterspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostname` | _[HTTPHostnameModifier](#httphostnamemodifier)_ | false | | Hostname is the value to be used to replace the Host header value during
forwarding. | +| `path` | _[HTTPPathModifier](#httppathmodifier)_ | false | | Path defines a path rewrite. | +| `appendXForwardedHost` | _boolean_ | false | | AppendXForwardedHost controls whether the original Host header value is
appended to the X-Forwarded-Host header when hostname rewriting is configured.
Defaults to true for backward compatibility. | + + +#### HTTPWasmCodeSource + + + +HTTPWasmCodeSource defines the HTTP URL containing the Wasm code. + +_Appears in:_ +- [WasmCodeSource](#wasmcodesource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `url` | _string_ | true | | URL is the URL containing the Wasm code. | +| `sha256` | _string_ | false | | SHA256 checksum that will be used to verify the Wasm code.
If not specified, Envoy Gateway will not verify the downloaded Wasm code.
kubebuilder:validation:Pattern=`^[a-f0-9]\{64\}$` | +| `tls` | _[WasmCodeSourceTLSConfig](#wasmcodesourcetlsconfig)_ | false | | TLS configuration when connecting to the Wasm code source. | + + +#### Header + + + +Header defines the header hashing configuration for consistent hash based +load balancing. + +_Appears in:_ +- [ConsistentHash](#consistenthash) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the header to hash. | + + +#### HeaderMatch + + + +HeaderMatch defines the match attributes within the HTTP Headers of the request. + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[HeaderMatchType](#headermatchtype)_ | false | Exact | Type specifies how to match against the value of the header. | +| `name` | _string_ | true | | Name of the HTTP header.
The header name is case-insensitive unless PreserveHeaderCase is set to true.
For example, "Foo" and "foo" are considered the same header. | +| `value` | _string_ | false | | Value within the HTTP header.
Do not set this field when Type="Distinct", implying matching on any/all unique
values within the header. | +| `invert` | _boolean_ | false | false | Invert specifies whether the value match result will be inverted.
Do not set this field when Type="Distinct", implying matching on any/all unique
values within the header. | + + +#### HeaderMatchType + +_Underlying type:_ _string_ + +HeaderMatchType specifies the semantics of how HTTP header values should be compared. +Valid HeaderMatchType values are "Exact", "RegularExpression", and "Distinct". + +_Appears in:_ +- [HeaderMatch](#headermatch) + +| Value | Description | +| ----- | ----------- | +| `Exact` | HeaderMatchExact matches the exact value of the Value field against the value of
the specified HTTP Header.
| +| `RegularExpression` | HeaderMatchRegularExpression matches a regular expression against the value of the
specified HTTP Header. The regex string must adhere to the syntax documented in
https://github.com/google/re2/wiki/Syntax.
| +| `Distinct` | HeaderMatchDistinct matches any and all possible unique values encountered in the
specified HTTP Header. Note that each unique value will receive its own rate limit
bucket.
| + + +#### HeaderSettings + + + +HeaderSettings provides configuration options for headers on the listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enableEnvoyHeaders` | _boolean_ | false | | EnableEnvoyHeaders configures Envoy Proxy to add the "X-Envoy-" headers to requests
and responses. | +| `disableRateLimitHeaders` | _boolean_ | false | | DisableRateLimitHeaders configures Envoy Proxy to omit the "X-RateLimit-" response headers
when rate limiting is enabled. | +| `xForwardedClientCert` | _[XForwardedClientCert](#xforwardedclientcert)_ | false | | XForwardedClientCert configures how Envoy Proxy handle the x-forwarded-client-cert (XFCC) HTTP header.
x-forwarded-client-cert (XFCC) is an HTTP header used to forward the certificate
information of part or all of the clients or proxies that a request has flowed through,
on its way from the client to the server.
Envoy proxy may choose to sanitize/append/forward the XFCC header before proxying the request.
If not set, the default behavior is sanitizing the XFCC header. | +| `withUnderscoresAction` | _[WithUnderscoresAction](#withunderscoresaction)_ | false | | WithUnderscoresAction configures the action to take when an HTTP header with underscores
is encountered. The default action is to reject the request. | +| `preserveXRequestID` | _boolean_ | false | | PreserveXRequestID configures Envoy to keep the X-Request-ID header if passed for a request that is edge
(Edge request is the request from external clients to front Envoy) and not reset it, which is the current Envoy behaviour.
Defaults to false and cannot be combined with RequestID.
Deprecated: use RequestID=PreserveOrGenerate instead | +| `requestID` | _[RequestIDAction](#requestidaction)_ | false | | RequestID configures Envoy's behavior for handling the `X-Request-ID` header.
When omitted default behavior is `Generate` which builds the `X-Request-ID` for every request
and ignores pre-existing values from the edge.
(An "edge request" refers to a request from an external client to the Envoy entrypoint.) | +| `earlyRequestHeaders` | _[HTTPHeaderFilter](#httpheaderfilter)_ | false | | EarlyRequestHeaders defines settings for early request header modification, before envoy performs
routing, tracing and built-in header manipulation. | +| `lateResponseHeaders` | _[HTTPHeaderFilter](#httpheaderfilter)_ | false | | LateResponseHeaders defines settings for global response header modification. | + + +#### HealthCheck + + + +HealthCheck configuration to decide which endpoints +are healthy and can be used for routing. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `active` | _[ActiveHealthCheck](#activehealthcheck)_ | false | | Active health check configuration | +| `passive` | _[PassiveHealthCheck](#passivehealthcheck)_ | false | | Passive passive check configuration | +| `panicThreshold` | _integer_ | false | | When number of unhealthy endpoints for a backend reaches this threshold
Envoy will disregard health status and balance across all endpoints.
It's designed to prevent a situation in which host failures cascade throughout the cluster
as load increases. If not set, the default value is 50%. To disable panic mode, set value to `0`. | + + +#### HealthCheckOverrides + + + +HealthCheckOverrides allows overriding default health check behavior for specific use cases. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `port` | _integer_ | false | | Port overrides the health check port.
If not set, the endpoint's serving port is used for health checks.
This is useful when health checks are served on a different port than
the main service port (e.g., port 443 for service, port 9090 for health checks). | + + +#### HealthCheckSettings + + + +HealthCheckSettings provides HealthCheck configuration on the HTTP/HTTPS listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `path` | _string_ | true | | Path specifies the HTTP path to match on for health check requests. | + + +#### IPEndpoint + + + +IPEndpoint describes TCP/UDP socket address, corresponding to Envoy's Socket Address +https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-socketaddress + +_Appears in:_ +- [BackendEndpoint](#backendendpoint) +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `address` | _string_ | true | | Address defines the IP address of the backend endpoint.
Supports both IPv4 and IPv6 addresses. | +| `port` | _integer_ | true | | Port defines the port of the backend endpoint. | + + +#### IPFamily + +_Underlying type:_ _string_ + +IPFamily defines the IP family to use for the Envoy proxy. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Value | Description | +| ----- | ----------- | +| `IPv4` | IPv4 defines the IPv4 family.
| +| `IPv6` | IPv6 defines the IPv6 family.
| +| `DualStack` | DualStack defines the dual-stack family.
When set to DualStack, Envoy proxy will listen on both IPv4 and IPv6 addresses
for incoming client traffic, enabling support for both IP protocol versions.
| + + +#### ImagePullPolicy + +_Underlying type:_ _string_ + +ImagePullPolicy defines the policy to use when pulling an OIC image. + +_Appears in:_ +- [WasmCodeSource](#wasmcodesource) + +| Value | Description | +| ----- | ----------- | +| `IfNotPresent` | ImagePullPolicyIfNotPresent will only pull the image if it does not already exist in the EG cache.
| +| `Always` | ImagePullPolicyAlways will pull the image when the EnvoyExtension resource version changes.
Note: EG does not update the Wasm module every time an Envoy proxy requests the Wasm module.
| + + +#### ImageWasmCodeSource + + + +ImageWasmCodeSource defines the OCI image containing the Wasm code. + +_Appears in:_ +- [WasmCodeSource](#wasmcodesource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `url` | _string_ | true | | URL is the URL of the OCI image.
URL can be in the format of `registry/image:tag` or `registry/image@sha256:digest`. | +| `sha256` | _string_ | false | | SHA256 checksum that will be used to verify the OCI image.
It must match the digest of the OCI image.
If not specified, Envoy Gateway will not verify the downloaded OCI image.
kubebuilder:validation:Pattern=`^[a-f0-9]\{64\}$` | +| `pullSecretRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | false | | PullSecretRef is a reference to the secret containing the credentials to pull the image. | +| `tls` | _[WasmCodeSourceTLSConfig](#wasmcodesourcetlsconfig)_ | false | | TLS configuration when connecting to the Wasm code source. | + + +#### InfrastructureProviderType + +_Underlying type:_ _string_ + +InfrastructureProviderType defines the types of custom infrastructure providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayInfrastructureProvider](#envoygatewayinfrastructureprovider) + +| Value | Description | +| ----- | ----------- | +| `Host` | InfrastructureProviderTypeHost defines the "Host" provider.
| + + +#### InjectedCredential + + + +InjectedCredential defines the credential to be injected. + +_Appears in:_ +- [HTTPCredentialInjectionFilter](#httpcredentialinjectionfilter) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `valueRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | true | | ValueRef is a reference to the secret containing the credentials to be injected.
This is an Opaque secret. The credential should be stored in the key
"credential", and the value should be the credential to be injected.
For example, for basic authentication, the value should be "Basic ".
for bearer token, the value should be "Bearer ". | + + +#### InvalidMessageAction + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [HTTP2Settings](#http2settings) + +| Value | Description | +| ----- | ----------- | +| `TerminateConnection` | | +| `TerminateStream` | | + + +#### JSONPatchOperation + + + +JSONPatchOperation defines the JSON Patch Operation as defined in +https://datatracker.ietf.org/doc/html/rfc6902 + +_Appears in:_ +- [EnvoyJSONPatchConfig](#envoyjsonpatchconfig) +- [ProxyBootstrap](#proxybootstrap) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `op` | _[JSONPatchOperationType](#jsonpatchoperationtype)_ | true | | Op is the type of operation to perform | +| `path` | _string_ | false | | Path is a JSONPointer expression. Refer to https://datatracker.ietf.org/doc/html/rfc6901 for more details.
It specifies the location of the target document/field where the operation will be performed | +| `jsonPath` | _string_ | false | | JSONPath is a JSONPath expression. Refer to https://datatracker.ietf.org/doc/rfc9535/ for more details.
It produces one or more JSONPointer expressions based on the given JSON document.
If no JSONPointer is found, it will result in an error.
If the 'Path' property is also set, it will be appended to the resulting JSONPointer expressions from the JSONPath evaluation.
This is useful when creating a property that does not yet exist in the JSON document.
The final JSONPointer expressions specifies the locations in the target document/field where the operation will be applied. | +| `from` | _string_ | false | | From is the source location of the value to be copied or moved. Only valid
for move or copy operations
Refer to https://datatracker.ietf.org/doc/html/rfc6901 for more details. | +| `value` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ | false | | Value is the new value of the path location. The value is only used by
the `add` and `replace` operations. | + + +#### JSONPatchOperationType + +_Underlying type:_ _string_ + +JSONPatchOperationType specifies the JSON Patch operations that can be performed. + +_Appears in:_ +- [JSONPatchOperation](#jsonpatchoperation) + + + +#### JWT + + + +JWT defines the configuration for JSON Web Token (JWT) authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `optional` | _boolean_ | true | | Optional determines whether a missing JWT is acceptable, defaulting to false if not specified.
Note: Even if optional is set to true, JWT authentication will still fail if an invalid JWT is presented. | +| `providers` | _[JWTProvider](#jwtprovider) array_ | true | | Providers defines the JSON Web Token (JWT) authentication provider type.
When multiple JWT providers are specified, the JWT is considered valid if
any of the providers successfully validate the JWT. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html. | + + +#### JWTClaim + + + +JWTClaim specifies a claim in a JWT token. + +_Appears in:_ +- [JWTPrincipal](#jwtprincipal) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name is the name of the claim.
If it is a nested claim, use a dot (.) separated string as the name to
represent the full path to the claim.
For example, if the claim is in the "department" field in the "organization" field,
the name should be "organization.department". | +| `valueType` | _[JWTClaimValueType](#jwtclaimvaluetype)_ | false | String | ValueType is the type of the claim value.
Only String and StringArray types are supported for now. | +| `values` | _string array_ | true | | Values are the values that the claim must match.
If the claim is a string type, the specified value must match exactly.
If the claim is a string array type, the specified value must match one of the values in the array.
If multiple values are specified, one of the values must match for the rule to match. | + + +#### JWTClaimValueType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [JWTClaim](#jwtclaim) + +| Value | Description | +| ----- | ----------- | +| `String` | | +| `StringArray` | | + + +#### JWTExtractor + + + +JWTExtractor defines a custom JWT token extraction from HTTP request. +If specified, Envoy will extract the JWT token from the listed extractors (headers, cookies, or params) and validate each of them. +If any value extracted is found to be an invalid JWT, a 401 error will be returned. + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `headers` | _[JWTHeaderExtractor](#jwtheaderextractor) array_ | false | | Headers represents a list of HTTP request headers to extract the JWT token from. | +| `cookies` | _string array_ | false | | Cookies represents a list of cookie names to extract the JWT token from. | +| `params` | _string array_ | false | | Params represents a list of query parameters to extract the JWT token from. | + + +#### JWTHeaderExtractor + + + +JWTHeaderExtractor defines an HTTP header location to extract JWT token + +_Appears in:_ +- [JWTExtractor](#jwtextractor) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name is the HTTP header name to retrieve the token | +| `valuePrefix` | _string_ | false | | ValuePrefix is the prefix that should be stripped before extracting the token.
The format would be used by Envoy like "\{ValuePrefix\}".
For example, "Authorization: Bearer ", then the ValuePrefix="Bearer " with a space at the end. | + + +#### JWTPrincipal + + + +JWTPrincipal specifies the client identity of a request based on the JWT claims and scopes. +At least one of the claims or scopes must be specified. +Claims and scopes are And-ed together if both are specified. + +_Appears in:_ +- [Principal](#principal) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `provider` | _string_ | true | | Provider is the name of the JWT provider that used to verify the JWT token.
In order to use JWT claims for authorization, you must configure the JWT
authentication with the same provider in the same `SecurityPolicy`. | +| `claims` | _[JWTClaim](#jwtclaim) array_ | false | | Claims are the claims in a JWT token.
If multiple claims are specified, all claims must match for the rule to match.
For example, if there are two claims: one for the audience and one for the issuer,
the rule will match only if both the audience and the issuer match. | +| `scopes` | _[JWTScope](#jwtscope) array_ | false | | Scopes are a special type of claim in a JWT token that represents the permissions of the client.
The value of the scopes field should be a space delimited string that is expected in the
scope (or scp) claim, as defined in RFC 6749: https://datatracker.ietf.org/doc/html/rfc6749#page-23.
If multiple scopes are specified, all scopes must match for the rule to match. | + + +#### JWTProvider + + + +JWTProvider defines how a JSON Web Token (JWT) can be verified. + +_Appears in:_ +- [JWT](#jwt) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name defines a unique name for the JWT provider. A name can have a variety of forms,
including RFC1123 subdomains, RFC 1123 labels, or RFC 1035 labels. | +| `issuer` | _string_ | false | | Issuer is the principal that issued the JWT and takes the form of a URL or email address.
For additional details, see https://tools.ietf.org/html/rfc7519#section-4.1.1 for
URL format and https://rfc-editor.org/rfc/rfc5322.html for email format. If not provided,
the JWT issuer is not checked. | +| `audiences` | _string array_ | false | | Audiences is a list of JWT audiences allowed access. For additional details, see
https://tools.ietf.org/html/rfc7519#section-4.1.3. If not provided, JWT audiences
are not checked. | +| `remoteJWKS` | _[RemoteJWKS](#remotejwks)_ | false | | RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote
HTTP/HTTPS endpoint. | +| `localJWKS` | _[LocalJWKS](#localjwks)_ | false | | LocalJWKS defines how to get the JSON Web Key Sets (JWKS) from a local source. | +| `claimToHeaders` | _[ClaimToHeader](#claimtoheader) array_ | false | | ClaimToHeaders is a list of JWT claims that must be extracted into HTTP request headers
For examples, following config:
The claim must be of type; string, int, double, bool. Array type claims are not supported | +| `recomputeRoute` | _boolean_ | false | | RecomputeRoute clears the route cache and recalculates the routing decision.
This field must be enabled if the headers generated from the claim are used for
route matching decisions. If the recomputation selects a new route, features targeting
the new matched route will be applied. | +| `extractFrom` | _[JWTExtractor](#jwtextractor)_ | false | | ExtractFrom defines different ways to extract the JWT token from HTTP request.
If empty, it defaults to extract JWT token from the Authorization HTTP request header using Bearer schema
or access_token from query parameters. | + + +#### JWTScope + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [JWTPrincipal](#jwtprincipal) + + + +#### KubernetesClient + + + + + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `rateLimit` | _[KubernetesClientRateLimit](#kubernetesclientratelimit)_ | true | | RateLimit defines the rate limit settings for the Kubernetes client. | + + +#### KubernetesClientRateLimit + + + +KubernetesClientRateLimit defines the rate limit settings for the Kubernetes client. + +_Appears in:_ +- [KubernetesClient](#kubernetesclient) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `qps` | _integer_ | false | 50 | QPS defines the queries per second limit for the Kubernetes client. | +| `burst` | _integer_ | false | 100 | Burst defines the maximum burst of requests allowed when tokens have accumulated. | + + +#### KubernetesContainerSpec + + + +KubernetesContainerSpec defines the desired state of the Kubernetes container resource. + +_Appears in:_ +- [KubernetesDaemonSetSpec](#kubernetesdaemonsetspec) +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `env` | _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | false | | List of environment variables to set in the container. | +| `resources` | _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | false | | Resources required by this container.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | +| `securityContext` | _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#securitycontext-v1-core)_ | false | | SecurityContext defines the security options the container should be run with.
If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext.
More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | +| `image` | _string_ | false | | Image specifies the EnvoyProxy container image to be used including a tag, instead of the default image.
This field is mutually exclusive with ImageRepository. | +| `imageRepository` | _string_ | false | | ImageRepository specifies the container image repository to be used without specifying a tag.
The default tag will be used.
This field is mutually exclusive with Image. | +| `volumeMounts` | _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#volumemount-v1-core) array_ | false | | VolumeMounts are volumes to mount into the container's filesystem.
Cannot be updated. | + + +#### KubernetesDaemonSetSpec + + + +KubernetesDaemonSetSpec defines the desired state of the Kubernetes daemonset resource. + +_Appears in:_ +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `patch` | _[KubernetesPatchSpec](#kubernetespatchspec)_ | false | | Patch defines how to perform the patch operation to daemonset | +| `strategy` | _[DaemonSetUpdateStrategy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#daemonsetupdatestrategy-v1-apps)_ | false | | The daemonset strategy to use to replace existing pods with new ones. | +| `pod` | _[KubernetesPodSpec](#kubernetespodspec)_ | false | | Pod defines the desired specification of pod. | +| `container` | _[KubernetesContainerSpec](#kubernetescontainerspec)_ | false | | Container defines the desired specification of main container. | +| `name` | _string_ | false | | Name of the daemonSet.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesDeployMode + + + +KubernetesDeployMode holds configuration for how to deploy managed resources such as the Envoy Proxy +data plane fleet. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[KubernetesDeployModeType](#kubernetesdeploymodetype)_ | false | ControllerNamespace | Type indicates what deployment mode to use. "ControllerNamespace" and
"GatewayNamespace" are currently supported.
By default, when this field is unset or empty, Envoy Gateway will deploy Envoy Proxy fleet in the Controller namespace. | + + +#### KubernetesDeployModeType + +_Underlying type:_ _string_ + +KubernetesDeployModeType defines the type of KubernetesDeployMode + +_Appears in:_ +- [KubernetesDeployMode](#kubernetesdeploymode) + +| Value | Description | +| ----- | ----------- | +| `ControllerNamespace` | KubernetesDeployModeTypeControllerNamespace indicates that the controller namespace is used for the infra proxy deployments.
| +| `GatewayNamespace` | KubernetesDeployModeTypeGatewayNamespace indicates that the gateway namespace is used for the infra proxy deployments.
| + + +#### KubernetesDeploymentSpec + + + +KubernetesDeploymentSpec defines the desired state of the Kubernetes deployment resource. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `patch` | _[KubernetesPatchSpec](#kubernetespatchspec)_ | false | | Patch defines how to perform the patch operation to deployment | +| `replicas` | _integer_ | false | | Replicas is the number of desired pods. Defaults to 1. | +| `strategy` | _[DeploymentStrategy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#deploymentstrategy-v1-apps)_ | false | | The deployment strategy to use to replace existing pods with new ones. | +| `pod` | _[KubernetesPodSpec](#kubernetespodspec)_ | false | | Pod defines the desired specification of pod. | +| `container` | _[KubernetesContainerSpec](#kubernetescontainerspec)_ | false | | Container defines the desired specification of main container. | +| `initContainers` | _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#container-v1-core) array_ | false | | List of initialization containers belonging to the pod.
More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ | +| `name` | _string_ | false | | Name of the deployment.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesHorizontalPodAutoscalerSpec + + + +KubernetesHorizontalPodAutoscalerSpec defines Kubernetes Horizontal Pod Autoscaler settings of Envoy Proxy Deployment. +When HPA is enabled, it is recommended that the value in `KubernetesDeploymentSpec.replicas` be removed, otherwise +Envoy Gateway will revert back to this value every time reconciliation occurs. +See k8s.io.autoscaling.v2.HorizontalPodAutoScalerSpec. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `minReplicas` | _integer_ | false | | minReplicas is the lower limit for the number of replicas to which the autoscaler
can scale down. It defaults to 1 replica. | +| `maxReplicas` | _integer_ | true | | maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up.
It cannot be less that minReplicas. | +| `metrics` | _[MetricSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#metricspec-v2-autoscaling) array_ | false | | metrics contains the specifications for which to use to calculate the
desired replica count (the maximum replica count across all metrics will
be used).
If left empty, it defaults to being based on CPU utilization with average on 80% usage. | +| `behavior` | _[HorizontalPodAutoscalerBehavior](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#horizontalpodautoscalerbehavior-v2-autoscaling)_ | false | | behavior configures the scaling behavior of the target
in both Up and Down directions (scaleUp and scaleDown fields respectively).
If not set, the default HPAScalingRules for scale up and scale down are used.
See k8s.io.autoscaling.v2.HorizontalPodAutoScalerBehavior. | +| `patch` | _[KubernetesPatchSpec](#kubernetespatchspec)_ | false | | Patch defines how to perform the patch operation to the HorizontalPodAutoscaler | +| `name` | _string_ | false | | Name of the horizontalPodAutoScaler.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesPatchSpec + + + +KubernetesPatchSpec defines how to perform the patch operation. +Note that `value` can be an in-line YAML document, as can be seen in e.g. (the example of patching the Envoy proxy Deployment)[https://gateway.envoyproxy.io/docs/tasks/operations/customize-envoyproxy/#patching-deployment-for-envoyproxy]. +Note also that, currently, strings containing literal JSON are _rejected_. + +_Appears in:_ +- [KubernetesDaemonSetSpec](#kubernetesdaemonsetspec) +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) +- [KubernetesHorizontalPodAutoscalerSpec](#kuberneteshorizontalpodautoscalerspec) +- [KubernetesPodDisruptionBudgetSpec](#kubernetespoddisruptionbudgetspec) +- [KubernetesServiceSpec](#kubernetesservicespec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[MergeType](#mergetype)_ | false | | Type is the type of merge operation to perform
By default, StrategicMerge is used as the patch type. | +| `value` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ | true | | Object contains the raw configuration for merged object | + + +#### KubernetesPodDisruptionBudgetSpec + + + +KubernetesPodDisruptionBudgetSpec defines Kubernetes PodDisruptionBudget settings of Envoy Proxy Deployment. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `minAvailable` | _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#intorstring-intstr-util)_ | false | | MinAvailable specifies the minimum amount of pods (can be expressed as integers or as a percentage) that must be available at all times during voluntary disruptions,
such as node drains or updates. This setting ensures that your envoy proxy maintains a certain level of availability
and resilience during maintenance operations. Cannot be combined with maxUnavailable. | +| `maxUnavailable` | _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#intorstring-intstr-util)_ | false | | MaxUnavailable specifies the maximum amount of pods (can be expressed as integers or as a percentage) that can be unavailable at all times during voluntary disruptions,
such as node drains or updates. This setting ensures that your envoy proxy maintains a certain level of availability
and resilience during maintenance operations. Cannot be combined with minAvailable. | +| `patch` | _[KubernetesPatchSpec](#kubernetespatchspec)_ | false | | Patch defines how to perform the patch operation to the PodDisruptionBudget | +| `name` | _string_ | false | | Name of the podDisruptionBudget.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesPodSpec + + + +KubernetesPodSpec defines the desired state of the Kubernetes pod resource. + +_Appears in:_ +- [KubernetesDaemonSetSpec](#kubernetesdaemonsetspec) +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `annotations` | _object (keys:string, values:string)_ | false | | Annotations are the annotations that should be appended to the pods.
By default, no pod annotations are appended. | +| `labels` | _object (keys:string, values:string)_ | false | | Labels are the additional labels that should be tagged to the pods.
By default, no additional pod labels are tagged. | +| `securityContext` | _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podsecuritycontext-v1-core)_ | false | | SecurityContext holds pod-level security attributes and common container settings.
Optional: Defaults to empty. See type description for default values of each field. | +| `affinity` | _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#affinity-v1-core)_ | false | | If specified, the pod's scheduling constraints. | +| `tolerations` | _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#toleration-v1-core) array_ | false | | If specified, the pod's tolerations. | +| `volumes` | _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#volume-v1-core) array_ | false | | Volumes that can be mounted by containers belonging to the pod.
More info: https://kubernetes.io/docs/concepts/storage/volumes | +| `imagePullSecrets` | _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#localobjectreference-v1-core) array_ | false | | ImagePullSecrets is an optional list of references to secrets
in the same namespace to use for pulling any of the images used by this PodSpec.
If specified, these secrets will be passed to individual puller implementations for them to use.
More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod | +| `nodeSelector` | _object (keys:string, values:string)_ | false | | NodeSelector is a selector which must be true for the pod to fit on a node.
Selector which must match a node's labels for the pod to be scheduled on that node.
More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ | +| `topologySpreadConstraints` | _[TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#topologyspreadconstraint-v1-core) array_ | false | | TopologySpreadConstraints describes how a group of pods ought to spread across topology
domains. Scheduler will schedule pods in a way which abides by the constraints.
All topologySpreadConstraints are ANDed. | +| `priorityClassName` | _string_ | false | | PriorityClassName indicates the importance of a Pod relative to other Pods.
If a PriorityClassName is not specified, the pod priority will be default or zero if there is no default.
More info: https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/ | + + +#### KubernetesServiceAccountSpec + + + + + +_Appears in:_ +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | false | | Name of the Service Account.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesServiceSpec + + + +KubernetesServiceSpec defines the desired state of the Kubernetes service resource. + +_Appears in:_ +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `annotations` | _object (keys:string, values:string)_ | false | | Annotations that should be appended to the service.
By default, no annotations are appended. | +| `labels` | _object (keys:string, values:string)_ | false | | Labels that should be appended to the service.
By default, no labels are appended. | +| `type` | _[ServiceType](#servicetype)_ | false | LoadBalancer | Type determines how the Service is exposed. Defaults to LoadBalancer.
Valid options are ClusterIP, LoadBalancer and NodePort.
"LoadBalancer" means a service will be exposed via an external load balancer (if the cloud provider supports it).
"ClusterIP" means a service will only be accessible inside the cluster, via the cluster IP.
"NodePort" means a service will be exposed on a static Port on all Nodes of the cluster. | +| `loadBalancerClass` | _string_ | false | | LoadBalancerClass, when specified, allows for choosing the LoadBalancer provider
implementation if more than one are available or is otherwise expected to be specified | +| `allocateLoadBalancerNodePorts` | _boolean_ | false | | AllocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for
services with type LoadBalancer. Default is "true". It may be set to "false" if the cluster
load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a
value), those requests will be respected, regardless of this field. This field may only be set for
services with type LoadBalancer and will be cleared if the type is changed to any other type. | +| `loadBalancerSourceRanges` | _string array_ | false | | LoadBalancerSourceRanges defines a list of allowed IP addresses which will be configured as
firewall rules on the platform providers load balancer. This is not guaranteed to be working as
it happens outside of kubernetes and has to be supported and handled by the platform provider.
This field may only be set for services with type LoadBalancer and will be cleared if the type
is changed to any other type. | +| `loadBalancerIP` | _string_ | false | | LoadBalancerIP defines the IP Address of the underlying load balancer service. This field
may be ignored if the load balancer provider does not support this feature.
This field has been deprecated in Kubernetes, but it is still used for setting the IP Address in some cloud
providers such as GCP. | +| `externalTrafficPolicy` | _[ServiceExternalTrafficPolicy](#serviceexternaltrafficpolicy)_ | false | Local | ExternalTrafficPolicy determines the externalTrafficPolicy for the Envoy Service. Valid options
are Local and Cluster. Default is "Local". "Local" means traffic will only go to pods on the node
receiving the traffic. "Cluster" means connections are loadbalanced to all pods in the cluster. | +| `patch` | _[KubernetesPatchSpec](#kubernetespatchspec)_ | false | | Patch defines how to perform the patch operation to the service | +| `name` | _string_ | false | | Name of the service.
When unset, this defaults to an autogenerated name. | + + +#### KubernetesWatchMode + + + +KubernetesWatchMode holds the configuration for which input resources to watch and reconcile. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[KubernetesWatchModeType](#kuberneteswatchmodetype)_ | true | | Type indicates what watch mode to use. KubernetesWatchModeTypeNamespaces and
KubernetesWatchModeTypeNamespaceSelector are currently supported
By default, when this field is unset or empty, Envoy Gateway will watch for input namespaced resources
from all namespaces. | +| `namespaces` | _string array_ | true | | Namespaces holds the list of namespaces that Envoy Gateway will watch for namespaced scoped
resources such as Gateway, HTTPRoute and Service.
Note that Envoy Gateway will continue to reconcile relevant cluster scoped resources such as
GatewayClass that it is linked to. Precisely one of Namespaces and NamespaceSelector must be set. | +| `namespaceSelector` | _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#labelselector-v1-meta)_ | true | | NamespaceSelector holds the label selector used to dynamically select namespaces.
Envoy Gateway will watch for namespaces matching the specified label selector.
Precisely one of Namespaces and NamespaceSelector must be set. | + + +#### KubernetesWatchModeType + +_Underlying type:_ _string_ + +KubernetesWatchModeType defines the type of KubernetesWatchMode + +_Appears in:_ +- [KubernetesWatchMode](#kuberneteswatchmode) + + + +#### LeaderElection + + + +LeaderElection defines the desired leader election settings. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `leaseDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | LeaseDuration defines the time non-leader contenders will wait before attempting to claim leadership.
It's based on the timestamp of the last acknowledged signal.
The default setting is 15 seconds. | +| `renewDeadline` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | RenewDeadline represents the time frame within which the current leader will attempt to renew its leadership
status before relinquishing its position.
The default setting is 10 seconds. | +| `retryPeriod` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | RetryPeriod denotes the interval at which LeaderElector clients should perform action retries.
The default setting is 2 seconds. | +| `disable` | _boolean_ | true | | Disable provides the option to turn off leader election, which is enabled by default. | + + +#### ListenerTranslationConfig + + + + + +_Appears in:_ +- [TranslationConfig](#translationconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `includeAll` | _boolean_ | false | | IncludeAll defines whether all listeners should be included in the translation hook.
Default is false. | + + +#### LiteralCustomTag + + + +LiteralCustomTag adds hard-coded value to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `value` | _string_ | true | | Value defines the hard-coded value to add to each span. | + + +#### LoadBalancer + + + +LoadBalancer defines the load balancer policy to be applied. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[LoadBalancerType](#loadbalancertype)_ | true | | Type decides the type of Load Balancer policy.
Valid LoadBalancerType values are
"ConsistentHash",
"LeastRequest",
"Random",
"RoundRobin",
"BackendUtilization",
"DynamicModule". | +| `consistentHash` | _[ConsistentHash](#consistenthash)_ | false | | ConsistentHash defines the configuration when the load balancer type is
set to ConsistentHash | +| `backendUtilization` | _[BackendUtilization](#backendutilization)_ | false | | BackendUtilization defines the configuration when the load balancer type is
set to BackendUtilization. | +| `endpointOverride` | _[EndpointOverride](#endpointoverride)_ | false | | EndpointOverride defines the configuration for endpoint override.
When specified, the load balancer will attempt to route requests to endpoints
based on the override information extracted from request headers or metadata.
If the override endpoints are not available, the configured load balancer policy will be used as fallback. | +| `slowStart` | _[SlowStart](#slowstart)_ | false | | SlowStart defines the configuration related to the slow start load balancer policy.
If set, during slow start window, traffic sent to the newly added hosts will gradually increase.
Supported for RoundRobin, LeastRequest, and BackendUtilization load balancers. | +| `zoneAware` | _[ZoneAware](#zoneaware)_ | false | | ZoneAware defines the configuration related to the distribution of requests between locality zones. | + + +#### LoadBalancerType + +_Underlying type:_ _string_ + +LoadBalancerType specifies the types of LoadBalancer. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Value | Description | +| ----- | ----------- | +| `ConsistentHash` | ConsistentHashLoadBalancerType load balancer policy.
| +| `LeastRequest` | LeastRequestLoadBalancerType load balancer policy.
| +| `Random` | RandomLoadBalancerType load balancer policy.
| +| `RoundRobin` | RoundRobinLoadBalancerType load balancer policy.
| +| `BackendUtilization` | BackendUtilizationLoadBalancerType load balancer policy.
| +| `DynamicModule` | DynamicModuleLoadBalancerType load balancer policy.
+notImplementedHide
| + + +#### LocalDynamicModuleSource + + + +LocalDynamicModuleSource defines a dynamic module loaded from the local filesystem. + +_Appears in:_ +- [DynamicModuleSource](#dynamicmodulesource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `path` | _string_ | true | | Path is the absolute filesystem path to the dynamic module shared library (.so file). | + + +#### LocalGeoIPDBSource + + + +LocalGeoIPDBSource configures a GeoIP database from a local file path. + +_Appears in:_ +- [GeoIPDBSource](#geoipdbsource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `path` | _string_ | true | | Path is the path to the database file. | + + +#### LocalJWKS + + + +LocalJWKS defines how to load a JSON Web Key Sets (JWKS) from a local source, either inline or from a reference to a ConfigMap. + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[LocalJWKSType](#localjwkstype)_ | true | Inline | Type is the type of method to use to read the body value.
Valid values are Inline and ValueRef, default is Inline. | +| `inline` | _string_ | false | | Inline contains the value as an inline string. | +| `valueRef` | _[LocalObjectReference](#localobjectreference)_ | false | | ValueRef is a reference to a local ConfigMap that contains the JSON Web Key Sets (JWKS).
The value of key `jwks` in the ConfigMap will be used.
If the key is not found, the first value in the ConfigMap will be used. | + + +#### LocalJWKSType + +_Underlying type:_ _string_ + +LocalJWKSType defines the types of values for Local JWKS. + +_Appears in:_ +- [LocalJWKS](#localjwks) + +| Value | Description | +| ----- | ----------- | +| `Inline` | LocalJWKSTypeInline defines the "Inline" LocalJWKS type.
| +| `ValueRef` | LocalJWKSTypeValueRef defines the "ValueRef" LocalJWKS type.
| + + +#### LocalObjectKeyReference + + + +LocalObjectKeyReference selects a key from a local object. + +_Appears in:_ +- [ContextExtension](#contextextension) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `group` | _[Group](#group)_ | true | | Group is the group of the referent. For example, "gateway.networking.k8s.io".
When unspecified or empty string, core API group is inferred. | +| `kind` | _[Kind](#kind)_ | true | | Kind is kind of the referent. For example "HTTPRoute" or "Service". | +| `name` | _[ObjectName](#objectname)_ | true | | Name is the name of the referent. | +| `key` | _string_ | true | | The key to select. | + + +#### LocalRateLimit + + + +LocalRateLimit defines local rate limit configuration. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `rules` | _[RateLimitRule](#ratelimitrule) array_ | false | | Rules are a list of RateLimit selectors and limits. If a request matches
multiple rules, the strictest limit is applied. For example, if a request
matches two rules, one with 10rps and one with 20rps, the final limit will
be based on the rule with 10rps. | + + +#### LogLevel + +_Underlying type:_ _string_ + +LogLevel defines a log level for Envoy Gateway and EnvoyProxy system logs. + +_Appears in:_ +- [EnvoyGatewayLogging](#envoygatewaylogging) +- [ProxyLogging](#proxylogging) + +| Value | Description | +| ----- | ----------- | +| `trace` | LogLevelTrace defines the "Trace" logging level.
| +| `debug` | LogLevelDebug defines the "debug" logging level.
| +| `info` | LogLevelInfo defines the "Info" logging level.
| +| `warn` | LogLevelWarn defines the "Warn" logging level.
| +| `error` | LogLevelError defines the "Error" logging level.
| + + +#### Lua + + + +Lua defines a Lua extension +Only one of Inline or ValueRef must be set + +_Appears in:_ +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[LuaValueType](#luavaluetype)_ | true | Inline | Type is the type of method to use to read the Lua value.
Valid values are Inline and ValueRef, default is Inline. | +| `inline` | _string_ | false | | Inline contains the source code as an inline string. | +| `valueRef` | _[LocalObjectReference](#localobjectreference)_ | false | | ValueRef has the source code specified as a local object reference.
Only a reference to ConfigMap is supported.
The value of key `lua` in the ConfigMap will be used.
If the key is not found, the first value in the ConfigMap will be used. | + + +#### LuaValidation + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Value | Description | +| ----- | ----------- | +| `Strict` | LuaValidationStrict is the default level and checks for issues during script execution.
Recommended if your scripts only use the standard Envoy Lua stream handle API and no external libraries.
For supported APIs, see: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter#stream-handle-api
INFO: This validation mode executes Lua scripts from EnvoyExtensionPolicy (EEP) resources in the gateway controller.
Since the Gateway controller watches EEPs across all namespaces (or namespaces matching the configured selector),
unprivileged users can create EEPs in their namespaces and cause arbitrary Lua code to execute in the Gateway controller process.
Security measures are in place to prevent unsafe Lua code from accessing critical system resources on the controller
and fail validation, preventing the unsafe code from flowing to the data plane proxy.
| +| `InsecureSyntax` | LuaValidationInsecureSyntax checks for Lua syntax errors only.
Useful if your scripts use external libraries other than the standard Envoy Lua stream handle API.
WARNING: This mode does NOT offer any runtime validations, so no security measures are applied to validate Lua code safety.
Not recommended unless you completely trust all EnvoyExtensionPolicy resources.
| +| `Disabled` | LuaValidationDisabled disables all Lua script validations.
WARNING: This mode does NOT offer any runtime or syntax validations, so no security measures are applied to validate Lua code safety.
Not recommended unless you completely trust all EnvoyExtensionPolicy resources.
| + + +#### LuaValueType + +_Underlying type:_ _string_ + +LuaValueType defines the types of values for Lua supported by Envoy Gateway. + +_Appears in:_ +- [Lua](#lua) + +| Value | Description | +| ----- | ----------- | +| `Inline` | LuaValueTypeInline defines the "Inline" Lua type.
| +| `ValueRef` | LuaValueTypeValueRef defines the "ValueRef" Lua type.
| + + +#### MergeType + +_Underlying type:_ _string_ + +MergeType defines the type of merge operation + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [EnvoyProxySpec](#envoyproxyspec) +- [KubernetesPatchSpec](#kubernetespatchspec) +- [SecurityPolicySpec](#securitypolicyspec) + +| Value | Description | +| ----- | ----------- | +| `StrategicMerge` | StrategicMerge indicates a strategic merge patch type
| +| `JSONMerge` | JSONMerge indicates a JSON merge patch type
| +| `Replace` | Replace type - ie no merging
| + + +#### MethodMatch + + + +MethodMatch defines the matching criteria for the HTTP method of a request. + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `value` | _[HTTPMethod](#httpmethod)_ | true | | Value specifies the HTTP method. | +| `invert` | _boolean_ | false | false | Invert specifies whether the value match result will be inverted. | + + +#### MetricSinkType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [EnvoyGatewayMetricSink](#envoygatewaymetricsink) +- [ProxyMetricSink](#proxymetricsink) + +| Value | Description | +| ----- | ----------- | +| `OpenTelemetry` | | + + +#### OIDC + + + +OIDC defines the configuration for the OpenID Connect (OIDC) authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `provider` | _[OIDCProvider](#oidcprovider)_ | true | | The OIDC Provider configuration. | +| `clientID` | _string_ | false | | The client ID to be used in the OIDC
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
Only one of clientID or clientIDRef must be set. | +| `clientIDRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | false | | The Kubernetes secret which contains the client ID to be used in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
Exactly one of clientID or clientIDRef must be set.
This is an Opaque secret. The client ID should be stored in the key "client-id".
Only one of clientID or clientIDRef must be set. | +| `clientSecret` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | true | | The Kubernetes secret which contains the OIDC client secret to be used in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
This is an Opaque secret. The client secret should be stored in the key
"client-secret". | +| `cookieNames` | _[OIDCCookieNames](#oidccookienames)_ | false | | The optional cookie name overrides to be used for Bearer and IdToken cookies in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
If not specified, uses a randomly generated suffix | +| `cookieConfig` | _[OIDCCookieConfig](#oidccookieconfig)_ | false | | CookieConfigs allows setting the SameSite attribute for OIDC cookies.
By default, its unset. | +| `cookieDomain` | _string_ | false | | The optional domain to set the access and ID token cookies on.
If not set, the cookies will default to the host of the request, not including the subdomains.
If set, the cookies will be set on the specified domain and all subdomains.
This means that requests to any subdomain will not require reauthentication after users log in to the parent domain. | +| `scopes` | _string array_ | false | | The OIDC scopes to be used in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
The "openid" scope is always added to the list of scopes if not already
specified. | +| `resources` | _string array_ | false | | The OIDC resources to be used in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). | +| `redirectURL` | _string_ | true | | The redirect URL to be used in the OIDC
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
If not specified, uses the default redirect URI "%REQ(x-forwarded-proto)%://%REQ(:authority)%/oauth2/callback" | +| `denyRedirect` | _[OIDCDenyRedirect](#oidcdenyredirect)_ | false | | 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.
This behavior can be useful for AJAX or machine requests. | +| `logoutPath` | _string_ | true | | The path to log a user out, clearing their credential cookies.
If not specified, uses a default logout path "/logout" | +| `forwardAccessToken` | _boolean_ | false | | ForwardAccessToken indicates whether the Envoy should forward the access token
via the Authorization header Bearer scheme to the upstream.
If not specified, defaults to false. | +| `forwardIDToken` | _[OIDCTokenForwarding](#oidctokenforwarding)_ | false | | ForwardIDToken configures forwarding of the OIDC ID token to the upstream.
If the configured header is "Authorization", EG forwards the ID token using
the "Bearer " prefix. For any other header, EG forwards the raw token value.
If not specified, the ID token will not be forwarded. | +| `defaultTokenTTL` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | DefaultTokenTTL is the default lifetime of the id token and access token.
Please note that Envoy will always use the expiry time from the response
of the authorization server if it is provided. This field is only used when
the expiry time is not provided by the authorization.
If not specified, defaults to 0. In this case, the "expires_in" field in
the authorization response must be set by the authorization server, or the
OAuth flow will fail. | +| `refreshToken` | _boolean_ | false | true | RefreshToken indicates whether the Envoy should automatically refresh the
id token and access token when they expire.
When set to true, the Envoy will use the refresh token to get a new id token
and access token when they expire.
If not specified, defaults to true. | +| `defaultRefreshTokenTTL` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | DefaultRefreshTokenTTL is the default lifetime of the refresh token.
This field is only used when the exp (expiration time) claim is omitted in
the refresh token or the refresh token is not JWT.
If not specified, defaults to 604800s (one week).
Note: this field is only applicable when the "refreshToken" field is set to true. | +| `csrfTokenTTL` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | CSRFTokenTTL defines how long the CSRF token generated during the OAuth2 authorization flow remains valid.
This duration determines the lifetime of the CSRF cookie, which is validated against the CSRF token
in the "state" parameter when the provider redirects back to the callback endpoint.
If omitted, Envoy Gateway defaults the token expiration to 10 minutes. | +| `disableTokenEncryption` | _boolean_ | false | | Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text.
This option should only be used in secure environments where token encryption is not required.
Default is false (tokens are encrypted). | +| `passThroughAuthHeader` | _boolean_ | false | | Skips OIDC authentication when the request contains a header that will be extracted by the JWT filter. Unless
explicitly stated otherwise in the extractFrom field, this will be the "Authorization: Bearer ..." header.
The passThroughAuthHeader option is typically used for non-browser clients that may not be able to handle OIDC
redirects and wish to directly supply a token instead.
If not specified, defaults to false. | + + +#### OIDCCookieConfig + + + +OIDCCookieConfig defines the cookie configuration for OAuth2 cookies. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `sameSite` | _string_ | false | | | + + +#### OIDCCookieNames + + + +OIDCCookieNames defines the names of cookies to use in the Envoy OIDC filter. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `accessToken` | _string_ | false | | The name of the cookie used to store the AccessToken in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
If not specified, defaults to "AccessToken-(randomly generated uid)" | +| `idToken` | _string_ | false | | The name of the cookie used to store the IdToken in the
[Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
If not specified, defaults to "IdToken-(randomly generated uid)" | + + +#### OIDCDenyRedirect + + + +OIDCDenyRedirect defines headers to match against the request to deny redirect to the OIDC Provider. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `headers` | _[OIDCDenyRedirectHeader](#oidcdenyredirectheader) array_ | true | | Defines the headers to match against the request to deny redirect to the OIDC Provider. | + + +#### OIDCDenyRedirectHeader + + + +OIDCDenyRedirectHeader defines how a header is matched + +_Appears in:_ +- [OIDCDenyRedirect](#oidcdenyredirect) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Specifies the name of the header in the request. | +| `type` | _[StringMatchType](#stringmatchtype)_ | false | Exact | Type specifies how to match against a string. | +| `value` | _string_ | true | | Value specifies the string value that the match must have. | + + +#### OIDCProvider + + + +OIDCProvider defines the OIDC Provider configuration. + +BackendRefs is used to specify the address of the OIDC Provider. +If the BackendRefs is not specified, The host and port of the OIDC Provider's token endpoint +will be used as the address of the OIDC Provider. + +TLS configuration can be specified in a BackendTLSConfig resource and target the BackendRefs. + +Other settings for the connection to the OIDC Provider can be specified in the BackendSettings resource. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `issuer` | _string_ | true | | The OIDC Provider's [issuer identifier](https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery).
Issuer MUST be a URI RFC 3986 [RFC3986] with a scheme component that MUST
be https, a host component, and optionally, port and path components and
no query or fragment components. | +| `authorizationEndpoint` | _string_ | false | | The OIDC Provider's [authorization endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
If 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). | +| `tokenEndpoint` | _string_ | false | | The OIDC Provider's [token endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint).
If 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). | +| `endSessionEndpoint` | _string_ | false | | The OIDC Provider's [end session endpoint](https://openid.net/specs/openid-connect-core-1_0.html#RPLogout).
If 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.
EG 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. | + + +#### OIDCTokenForwarding + + + +OIDCTokenForwarding defines how an OIDC token is forwarded upstream. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `header` | _string_ | true | | Header is the upstream request header that will carry the ID token. | + + +#### OTelSampler + + + +OTelSampler configures the OpenTelemetry sampler. +Type maps to OTEL_TRACES_SAMPLER. + +_Appears in:_ +- [OpenTelemetryTracingProvider](#opentelemetrytracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[OTelSamplerType](#otelsamplertype)_ | true | AlwaysOn | Type is the sampler type. | +| `samplingPercentage` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | false | | SamplingPercentage controls the percentage of traces to sample.
Defaults to 100% when not set. | + + +#### OTelSamplerType + +_Underlying type:_ _string_ + +OTelSamplerType specifies the sampler type. +Values correspond to the OTEL_TRACES_SAMPLER environment variable. + +_Appears in:_ +- [OTelSampler](#otelsampler) + +| Value | Description | +| ----- | ----------- | +| `AlwaysOn` | OTelSamplerTypeAlwaysOn exports all spans.
| +| `AlwaysOff` | OTelSamplerTypeAlwaysOff drops all spans.
| +| `TraceIdRatio` | OTelSamplerTypeTraceIDRatio exports a percentage of spans based on trace ID.
| +| `ParentBasedAlwaysOn` | OTelSamplerTypeParentBasedAlwaysOn respects the parent span's sampling decision, sampling when no parent exists.
| +| `ParentBasedAlwaysOff` | OTelSamplerTypeParentBasedAlwaysOff respects the parent span's sampling decision, dropping when no parent exists.
| +| `ParentBasedTraceIdRatio` | OTelSamplerTypeParentBasedTraceIDRatio respects the parent span's sampling decision, using trace ID ratio when no parent exists.
| + + +#### OpenTelemetryEnvoyProxyAccessLog + + + +OpenTelemetryEnvoyProxyAccessLog defines the OpenTelemetry access log sink. + +_Appears in:_ +- [ProxyAccessLogSink](#proxyaccesslogsink) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `host` | _string_ | false | | Host define the extension service hostname.
Deprecated: Use BackendRefs instead. | +| `port` | _integer_ | false | 4317 | Port defines the port the extension service is exposed on.
Deprecated: Use BackendRefs instead. | +| `resources` | _object (keys:string, values:string)_ | false | | Resources is a set of labels that describe the source of a log entry, including envoy node info.
It's recommended to follow [semantic conventions](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/).
Deprecated: Use ResourceAttributes instead. | +| `resourceAttributes` | _object (keys:string, values:string)_ | false | | ResourceAttributes is a set of labels that describe the source of a log entry, including envoy node info.
It's recommended to follow [semantic conventions](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/). | +| `headers` | _[HTTPHeader](#httpheader) array_ | false | | Headers is a list of additional headers to send with OTLP export requests.
These headers are added as gRPC initial metadata for the OTLP gRPC service. | + + +#### OpenTelemetryTracingProvider + + + +OpenTelemetryTracingProvider defines the OpenTelemetry tracing provider configuration. + +_Appears in:_ +- [TracingProvider](#tracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `headers` | _[HTTPHeader](#httpheader) array_ | false | | Headers is a list of additional headers to send with OTLP export requests.
These headers are added as gRPC initial metadata for the OTLP gRPC service. | +| `resourceAttributes` | _object (keys:string, values:string)_ | false | | ResourceAttributes is a set of labels that describe the source of traces.
It's recommended to follow semantic conventions: https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/ | +| `sampler` | _[OTelSampler](#otelsampler)_ | false | | Sampler controls whether spans are exported. | + + +#### Operation + + + +Operation specifies the operation of a request. + +_Appears in:_ +- [AuthorizationRule](#authorizationrule) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `methods` | _[HTTPMethod](#httpmethod) array_ | true | | Methods are the HTTP methods of the request.
If multiple methods are specified, all specified methods are allowed or denied, based on the action of the rule. | + + +#### Origin + +_Underlying type:_ _string_ + +Origin is defined by the scheme (protocol), hostname (domain), and port of +the URL used to access it. The hostname can be "precise" which is just the +domain name or "wildcard" which is a domain name prefixed with a single +wildcard label such as "*.example.com". +In addition to that a single wildcard (with or without scheme) can be +configured to match any origin. + +For example, the following are valid origins: +- https://foo.example.com +- https://*.example.com +- http://foo.example.com:8080 +- http://*.example.com:8080 +- https://* + +_Appears in:_ +- [CORS](#cors) + + + +#### OtherSANMatch + + + + + +_Appears in:_ +- [SubjectAltNames](#subjectaltnames) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `oid` | _string_ | true | | OID Value | +| `type` | _[StringMatchType](#stringmatchtype)_ | false | Exact | Type specifies how to match against a string. | +| `value` | _string_ | true | | Value specifies the string value that the match must have. | + + +#### PassiveHealthCheck + + + +PassiveHealthCheck defines the configuration for passive health checks in the context of Envoy's Outlier Detection, +see https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/outlier + +_Appears in:_ +- [HealthCheck](#healthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `splitExternalLocalOriginErrors` | _boolean_ | false | false | SplitExternalLocalOriginErrors enables splitting of errors between external and local origin. | +| `interval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | 3s | Interval defines the time between passive health checks. | +| `consecutiveLocalOriginFailures` | _integer_ | false | 5 | ConsecutiveLocalOriginFailures sets the number of consecutive local origin failures triggering ejection.
Parameter takes effect only when split_external_local_origin_errors is set to true. | +| `consecutiveGatewayErrors` | _integer_ | false | | ConsecutiveGatewayErrors sets the number of consecutive gateway errors triggering ejection. | +| `consecutive5XxErrors` | _integer_ | false | 5 | Consecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection. | +| `baseEjectionTime` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | 30s | BaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures. | +| `maxEjectionPercent` | _integer_ | false | 10 | MaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected. | +| `failurePercentageThreshold` | _integer_ | false | | FailurePercentageThreshold sets the failure percentage threshold for outlier detection.
If the failure percentage of a given host is greater than or equal to this value, it will be ejected.
Defaults to 85. | +| `alwaysEjectOneEndpoint` | _boolean_ | false | false | AlwaysEjectOneEndpoint defines whether at least one host should be ejected,
regardless of MaxEjectionPercent. | + + +#### PathEscapedSlashAction + +_Underlying type:_ _string_ + +PathEscapedSlashAction determines the action for requests that contain %2F, %2f, %5C, or %5c +sequences in the URI path. + +_Appears in:_ +- [PathSettings](#pathsettings) + +| Value | Description | +| ----- | ----------- | +| `KeepUnchanged` | KeepUnchangedAction keeps escaped slashes as they arrive without changes
| +| `RejectRequest` | RejectRequestAction rejects client requests containing escaped slashes
with a 400 status. gRPC requests will be rejected with the INTERNAL (13)
error code.
The "httpN.downstream_rq_failed_path_normalization" counter is incremented
for each rejected request.
| +| `UnescapeAndRedirect` | UnescapeAndRedirect unescapes %2F and %5C sequences and redirects to the new path
if these sequences were present.
Redirect occurs after path normalization and merge slashes transformations if
they were configured. gRPC requests will be rejected with the INTERNAL (13)
error code.
This option minimizes possibility of path confusion exploits by forcing request
with unescaped slashes to traverse all parties: downstream client, intermediate
proxies, Envoy and upstream server.
The “httpN.downstream_rq_redirected_with_normalized_path” counter is incremented
for each redirected request.
| +| `UnescapeAndForward` | UnescapeAndForward unescapes %2F and %5C sequences and forwards the request.
Note: this option should not be enabled if intermediaries perform path based access
control as it may lead to path confusion vulnerabilities.
| + + +#### PathMatch + + + +PathMatch defines the matching criteria for the HTTP path of a request. + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[PathMatchType](#pathmatchtype)_ | false | PathPrefix | Type specifies how to match against the value of the path. | +| `value` | _string_ | true | / | Value specifies the HTTP path. | +| `invert` | _boolean_ | false | false | Invert specifies whether the value match result will be inverted. | + + +#### PathSettings + + + +PathSettings provides settings that managing how the incoming path set by clients is handled. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `escapedSlashesAction` | _[PathEscapedSlashAction](#pathescapedslashaction)_ | false | | EscapedSlashesAction determines how %2f, %2F, %5c, or %5C sequences in the path URI
should be handled.
The default is UnescapeAndRedirect. | +| `disableMergeSlashes` | _boolean_ | false | | DisableMergeSlashes allows disabling the default configuration of merging adjacent
slashes in the path.
Note that slash merging is not part of the HTTP spec and is provided for convenience. | + + +#### PerEndpointCircuitBreakers + + + +PerEndpointCircuitBreakers defines Circuit Breakers that will apply per-endpoint for an upstream cluster + +_Appears in:_ +- [CircuitBreaker](#circuitbreaker) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `maxConnections` | _integer_ | false | 1024 | MaxConnections configures the maximum number of connections that Envoy will establish per-endpoint to the referenced backend defined within a xRoute rule. | + + +#### PerRetryPolicy + + + + + +_Appears in:_ +- [Retry](#retry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `timeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | Timeout is the timeout per retry attempt. | +| `backOff` | _[BackOffPolicy](#backoffpolicy)_ | false | | Backoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential
back-off algorithm for retries. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries | + + +#### PolicyTargetReferences + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `targetRef` | _[LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname)_ | true | | TargetRef is the name of the resource this policy is being attached to.
This policy and the TargetRef MUST be in the same namespace for this
Policy to have effect
Deprecated: use targetRefs/targetSelectors instead | +| `targetRefs` | _LocalPolicyTargetReferenceWithSectionName array_ | true | | TargetRefs are the names of the Gateway resources this policy
is being attached to. | +| `targetSelectors` | _[TargetSelector](#targetselector) array_ | true | | TargetSelectors allow targeting resources for this policy based on labels | + + +#### PreconnectPolicy + + + +Preconnect configures proactive upstream connections to avoid +connection establishment overhead and reduce latency. + +_Appears in:_ +- [BackendConnection](#backendconnection) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `perEndpointPercent` | _integer_ | false | | PerEndpointPercent configures how many additional connections to maintain per
upstream endpoint, useful for high-QPS or latency sensitive services. Expressed as a
percentage of the connections required by active streams
(e.g. 100 = preconnect disabled, 105 = 1.05x connections per-endpoint, 200 = 2.00×).
Allowed value range is between 100-300. When both PerEndpointPercent and
PredictivePercent are set, Envoy ensures both are satisfied (max of the two). | +| `predictivePercent` | _integer_ | false | | PredictivePercent configures how many additional connections to maintain
across the cluster by anticipating which upstream endpoint the load balancer
will select next, useful for low-QPS services. Relies on deterministic
loadbalancing and is only supported with Random or RoundRobin.
Expressed as a percentage of the connections required by active streams
(e.g. 100 = 1.0 (no preconnect), 105 = 1.05× connections across the cluster, 200 = 2.00×).
Minimum allowed value is 100. When both PerEndpointPercent and PredictivePercent are
set Envoy ensures both are satisfied per host (max of the two). | + + +#### PreferLocalZone + + + +PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone. + +_Appears in:_ +- [ZoneAware](#zoneaware) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `force` | _[ForceLocalZone](#forcelocalzone)_ | false | | ForceLocalZone defines override configuration for forcing all traffic to stay within the local zone instead of the default behavior
which maintains equal distribution among upstream endpoints while sending as much traffic as possible locally. | +| `minEndpointsThreshold` | _integer_ | false | | MinEndpointsThreshold is the minimum number of total upstream endpoints across all zones required to enable zone-aware routing. | +| `percentageEnabled` | _integer_ | false | | 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%. | + + +#### Principal + + + +Principal specifies the client identity of a request. +A client identity can be a client IP, a JWT claim, username from the Authorization header, +or any other identity that can be extracted from a custom header. +If there are multiple principal types, all principals must match for the rule to match. + +_Appears in:_ +- [AuthorizationRule](#authorizationrule) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `clientCIDRs` | _[CIDR](#cidr) array_ | false | | ClientCIDRs are the IP CIDR ranges of the client.
Valid examples are "192.168.1.0/24" or "2001:db8::/64"
If multiple CIDR ranges are specified, one of the CIDR ranges must match
the client IP for the rule to match.
The client IP is inferred from the X-Forwarded-For header, a custom header,
or the proxy protocol.
You can use the `ClientIPDetection` or the `ProxyProtocol` field in
the `ClientTrafficPolicy` to configure how the client IP is detected.
For TCPRoute targets (raw TCP connections), HTTP headers such as
X-Forwarded-For are not available. The client IP is obtained from the
TCP connection's peer address. If intermediaries (load balancers, NAT)
terminate or proxy TCP, the original client IP will only be available
if the intermediary preserves the source address (for example by
enabling the PROXY protocol or avoiding SNAT). Ensure your L4 proxy is
configured to preserve the source IP to enable correct client-IP
matching for TCPRoute targets. | +| `jwt` | _[JWTPrincipal](#jwtprincipal)_ | false | | JWT authorize the request based on the JWT claims and scopes.
Note: in order to use JWT claims for authorization, you must configure the
JWT authentication in the same `SecurityPolicy`. | +| `headers` | _[AuthorizationHeaderMatch](#authorizationheadermatch) array_ | false | | Headers authorize the request based on user identity extracted from custom headers.
If multiple headers are specified, all headers must match for the rule to match. | +| `clientIPGeoLocations` | _[ClientIPGeoLocation](#clientipgeolocation) array_ | false | | ClientIPGeoLocations authorizes the request based on geolocation metadata derived from the client IP.
This field is supported for HTTPRoute and GRPCRoute authorization.
It is not supported for TCPRoute targets.
If multiple entries are specified, one of the ClientIPGeoLocation entries must match for the rule to match.
The client IP is inferred from the X-Forwarded-For header or a custom header.
You can use the `ClientIPDetection` field in the `ClientTrafficPolicy` to configure the client IP detection. | + + +#### ProcessingModeOptions + + + +ProcessingModeOptions defines if headers or body should be processed by the external service +and which attributes are sent to the processor + +_Appears in:_ +- [ExtProcProcessingMode](#extprocprocessingmode) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `body` | _[ExtProcBodyProcessingMode](#extprocbodyprocessingmode)_ | false | | Defines body processing mode | +| `attributes` | _string array_ | false | | Defines which attributes are sent to the external processor. Envoy Gateway currently
supports only the following attribute prefixes: connection, source, destination,
request, response, upstream and xds.route.
https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/attributes | + + +#### ProtocolUpgradeConfig + + + +ProtocolUpgradeConfig specifies the configuration for protocol upgrades. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _string_ | true | | Type is the case-insensitive type of protocol upgrade.
e.g. `websocket`, `CONNECT`, `spdy/3.1` etc. | +| `connect` | _[ConnectConfig](#connectconfig)_ | false | | Connect specifies the configuration for the CONNECT config.
This is allowed only when type is CONNECT. | + + +#### ProviderType + +_Underlying type:_ _string_ + +ProviderType defines the types of providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayProvider](#envoygatewayprovider) + +| Value | Description | +| ----- | ----------- | +| `Kubernetes` | ProviderTypeKubernetes defines the "Kubernetes" provider.
| +| `Custom` | ProviderTypeCustom defines the "Custom" provider.
| + + +#### ProxyAccessLog + + + + + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `disable` | _boolean_ | false | | Disable disables access logging for managed proxies if set to true. | +| `settings` | _[ProxyAccessLogSetting](#proxyaccesslogsetting) array_ | false | | Settings defines accesslog settings for managed proxies.
If unspecified, will send default format to stdout. | + + +#### ProxyAccessLogFormat + + + +ProxyAccessLogFormat defines the format of accesslog. +By default, accesslogs are written to standard output. + +_Appears in:_ +- [ProxyAccessLogSetting](#proxyaccesslogsetting) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ProxyAccessLogFormatType](#proxyaccesslogformattype)_ | false | | Type defines the type of accesslog format.
When unset, both text and json can be specified. | +| `text` | _string_ | false | | Text defines the text accesslog format, following Envoy accesslog formatting,
It's required when the format type is "Text".
Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the format.
The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information. | +| `json` | _object (keys:string, values:string)_ | false | | JSON is additional attributes that describe the specific event occurrence.
Structured format for the envoy access logs. Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators)
can be used as values for fields within the Struct.
It's required when the format type is "JSON". | + + +#### ProxyAccessLogFormatType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [ProxyAccessLogFormat](#proxyaccesslogformat) + +| Value | Description | +| ----- | ----------- | +| `Text` | ProxyAccessLogFormatTypeText defines the text accesslog format.
| +| `JSON` | ProxyAccessLogFormatTypeJSON defines the JSON accesslog format.
| + + +#### ProxyAccessLogSetting + + + + + +_Appears in:_ +- [ProxyAccessLog](#proxyaccesslog) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `format` | _[ProxyAccessLogFormat](#proxyaccesslogformat)_ | false | | Format defines the format of accesslog.
This will be ignored if sink type is ALS. | +| `matches` | _string array_ | true | | Matches defines the match conditions for accesslog in CEL expression.
An accesslog will be emitted only when one or more match conditions are evaluated to true.
Invalid [CEL](https://www.envoyproxy.io/docs/envoy/latest/xds/type/v3/cel.proto.html#common-expression-language-cel-proto) expressions will be ignored. | +| `sinks` | _[ProxyAccessLogSink](#proxyaccesslogsink) array_ | true | | Sinks defines the sinks of accesslog. | +| `type` | _[ProxyAccessLogType](#proxyaccesslogtype)_ | false | | Type defines the component emitting the accesslog, such as Listener and Route.
If type not defined, the setting would apply to:
(1) All Routes.
(2) Listeners if and only if Envoy does not find a matching route for a request.
If type is defined, the accesslog settings would apply to the relevant component (as-is). | + + +#### ProxyAccessLogSink + + + +ProxyAccessLogSink defines the sink of accesslog. + +_Appears in:_ +- [ProxyAccessLogSetting](#proxyaccesslogsetting) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[ProxyAccessLogSinkType](#proxyaccesslogsinktype)_ | true | | Type defines the type of accesslog sink. | +| `als` | _[ALSEnvoyProxyAccessLog](#alsenvoyproxyaccesslog)_ | false | | ALS defines the gRPC Access Log Service (ALS) sink. | +| `file` | _[FileEnvoyProxyAccessLog](#fileenvoyproxyaccesslog)_ | false | | File defines the file accesslog sink. | +| `openTelemetry` | _[OpenTelemetryEnvoyProxyAccessLog](#opentelemetryenvoyproxyaccesslog)_ | false | | OpenTelemetry defines the OpenTelemetry accesslog sink. | + + +#### ProxyAccessLogSinkType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [ProxyAccessLogSink](#proxyaccesslogsink) + +| Value | Description | +| ----- | ----------- | +| `ALS` | ProxyAccessLogSinkTypeALS defines the gRPC Access Log Service (ALS) sink.
The service must implement the Envoy gRPC Access Log Service streaming API:
https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/accesslog/v3/als.proto
| +| `File` | ProxyAccessLogSinkTypeFile defines the file accesslog sink.
| +| `OpenTelemetry` | ProxyAccessLogSinkTypeOpenTelemetry defines the OpenTelemetry accesslog sink.
When the provider is Kubernetes, EnvoyGateway always sends `k8s.namespace.name`
and `k8s.pod.name` as additional attributes.
| + + +#### ProxyAccessLogType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [ProxyAccessLogSetting](#proxyaccesslogsetting) + +| Value | Description | +| ----- | ----------- | +| `Listener` | ProxyAccessLogTypeListener defines the accesslog for Listeners.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-access-log
| +| `Route` | ProxyAccessLogTypeRoute defines the accesslog for HTTP, GRPC, UDP and TCP Routes.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/udp/udp_proxy/v3/udp_proxy.proto#envoy-v3-api-field-extensions-filters-udp-udp-proxy-v3-udpproxyconfig-access-log
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/tcp_proxy/v3/tcp_proxy.proto#envoy-v3-api-field-extensions-filters-network-tcp-proxy-v3-tcpproxy-access-log
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-access-log
| +| `Upstream` | ProxyAccessLogTypeUpstream defines the accesslog for upstream.
| + + +#### ProxyBootstrap + + + +ProxyBootstrap defines Envoy Bootstrap configuration. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[BootstrapType](#bootstraptype)_ | false | Replace | Type is the type of the bootstrap configuration, it should be either **Replace**, **Merge**, or **JSONPatch**.
If unspecified, it defaults to Replace. | +| `value` | _string_ | false | | Value is a YAML string of the bootstrap. | +| `jsonPatches` | _[JSONPatchOperation](#jsonpatchoperation) array_ | true | | JSONPatches is an array of JSONPatches to be applied to the default bootstrap. Patches are
applied in the order in which they are defined. | + + +#### ProxyLogComponent + +_Underlying type:_ _string_ + +ProxyLogComponent defines a component that supports a configured logging level. + +_Appears in:_ +- [ProxyLogging](#proxylogging) + +| Value | Description | +| ----- | ----------- | +| `default` | LogComponentDefault defines the default logging component.
See more details: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-l
| +| `upstream` | LogComponentUpstream defines the "upstream" logging component.
| +| `http` | LogComponentHTTP defines the "http" logging component.
| +| `connection` | LogComponentConnection defines the "connection" logging component.
| +| `admin` | LogComponentAdmin defines the "admin" logging component.
| +| `client` | LogComponentClient defines the "client" logging component.
| +| `filter` | LogComponentFilter defines the "filter" logging component.
| +| `main` | LogComponentMain defines the "main" logging component.
| +| `router` | LogComponentRouter defines the "router" logging component.
| +| `runtime` | LogComponentRuntime defines the "runtime" logging component.
| + + +#### ProxyLogging + + + +ProxyLogging defines logging parameters for managed proxies. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `level` | _object (keys:[ProxyLogComponent](#proxylogcomponent), values:[LogLevel](#loglevel))_ | true | \{ default:warn \} | Level is a map of logging level per component, where the component is the key
and the log level is the value. If unspecified, defaults to "default: warn". | + + +#### ProxyMetricSink + + + +ProxyMetricSink defines the sink of metrics. +Default metrics sink is OpenTelemetry. + +_Appears in:_ +- [ProxyMetrics](#proxymetrics) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[MetricSinkType](#metricsinktype)_ | true | OpenTelemetry | Type defines the metric sink type.
EG currently only supports OpenTelemetry. | +| `openTelemetry` | _[ProxyOpenTelemetrySink](#proxyopentelemetrysink)_ | false | | OpenTelemetry defines the configuration for OpenTelemetry sink.
It's required if the sink type is OpenTelemetry. | + + +#### ProxyMetrics + + + + + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `prometheus` | _[ProxyPrometheusProvider](#proxyprometheusprovider)_ | true | | Prometheus defines the configuration for Admin endpoint `/stats/prometheus`. | +| `sinks` | _[ProxyMetricSink](#proxymetricsink) array_ | true | | Sinks defines the metric sinks where metrics are sent to. | +| `matches` | _[StringMatch](#stringmatch) array_ | true | | Matches defines configuration for selecting specific metrics instead of generating all metrics stats
that are enabled by default. This helps reduce CPU and memory overhead in Envoy, but eliminating some stats
may after critical functionality. Here are the stats that we strongly recommend not disabling:
`cluster_manager.warming_clusters`, `cluster..membership_total`,`cluster..membership_healthy`,
`cluster..membership_degraded`，reference https://github.com/envoyproxy/envoy/issues/9856,
https://github.com/envoyproxy/envoy/issues/14610 | +| `enableVirtualHostStats` | _boolean_ | false | | EnableVirtualHostStats enables envoy stat metrics for virtual hosts. | +| `enablePerEndpointStats` | _boolean_ | false | | EnablePerEndpointStats enables per endpoint envoy stats metrics.
Please use with caution. | +| `enableRequestResponseSizesStats` | _boolean_ | false | | EnableRequestResponseSizesStats enables publishing of histograms tracking header and body sizes of requests and responses. | +| `enableGRPCStats` | _boolean_ | false | | EnableGRPCStats enables the gRPC stats filter on listeners.
This is enabled by default for GRPCRoute and opt-in for HTTPRoute.
In general, gRPC traffic should be handled via GRPCRoute, but there are cases where
users want to route gRPC using HTTPRoute for its richer matching capabilities.
Therefore, we enable this behavior only when it is explicitly opted in. | +| `clusterStatName` | _string_ | false | | ClusterStatName defines the value of cluster alt_stat_name, determining how cluster stats are named.
For more details, see envoy docs: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html
The supported operators for this pattern are:
`%ROUTE_NAME%`: name of Gateway API xRoute resource
`%ROUTE_NAMESPACE%`: namespace of Gateway API xRoute resource
`%ROUTE_KIND%`: kind of Gateway API xRoute resource
`%ROUTE_RULE_NAME%`: name of the Gateway API xRoute section
`%ROUTE_RULE_NUMBER%`: name of the Gateway API xRoute section
`%BACKEND_REFS%`: names of all backends referenced in `/\|/\|...` format
Only xDS Clusters created for HTTPRoute and GRPCRoute are currently supported.
Default: `%ROUTE_KIND%/%ROUTE_NAMESPACE%/%ROUTE_NAME%/rule/%ROUTE_RULE_NUMBER%`
Example: `httproute/my-ns/my-route/rule/0` | + + +#### ProxyOpenTelemetrySink + + + +ProxyOpenTelemetrySink defines the configuration for OpenTelemetry sink. + +_Appears in:_ +- [ProxyMetricSink](#proxymetricsink) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `host` | _string_ | false | | Host define the service hostname.
Deprecated: Use BackendRefs instead. | +| `port` | _integer_ | false | 4317 | Port defines the port the service is exposed on.
Deprecated: Use BackendRefs instead. | +| `reportCountersAsDeltas` | _boolean_ | false | | ReportCountersAsDeltas configures the OpenTelemetry sink to report
counters as delta temporality instead of cumulative. | +| `reportHistogramsAsDeltas` | _boolean_ | false | | ReportHistogramsAsDeltas configures the OpenTelemetry sink to report
histograms as delta temporality instead of cumulative.
Required for backends like Elastic that drop cumulative histograms. | +| `headers` | _[HTTPHeader](#httpheader) array_ | false | | Headers is a list of additional headers to send with OTLP export requests.
These headers are added as gRPC initial metadata for the OTLP gRPC service. | +| `resourceAttributes` | _object (keys:string, values:string)_ | false | | ResourceAttributes is a set of labels that describe the source of metrics.
It's recommended to follow semantic conventions: https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/ | + + +#### ProxyPrometheusProvider + + + + + +_Appears in:_ +- [ProxyMetrics](#proxymetrics) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `disable` | _boolean_ | true | | Disable the Prometheus endpoint. | +| `compression` | _[Compression](#compression)_ | false | | Configure the compression on Prometheus endpoint. Compression is useful in situations when bandwidth is scarce and large payloads can be effectively compressed at the expense of higher CPU load. | + + +#### ProxyProtocol + + + +ProxyProtocol defines the configuration related to the proxy protocol +when communicating with the backend. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `version` | _[ProxyProtocolVersion](#proxyprotocolversion)_ | true | | Version of ProxyProtocol
Valid ProxyProtocolVersion values are
"V1"
"V2" | + + +#### ProxyProtocolSettings + + + +ProxyProtocolSettings configures the Proxy Protocol settings. When configured, +the Proxy Protocol header will be interpreted and the Client Address +will be added into the X-Forwarded-For header. +If both EnableProxyProtocol and ProxyProtocol are set, ProxyProtocol takes precedence. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `optional` | _boolean_ | false | | Optional allows requests without a Proxy Protocol header to be proxied.
If set to true, the listener will accept requests without a Proxy Protocol header.
If set to false, the listener will reject requests without a Proxy Protocol header.
If not set, the default behavior is to reject requests without a Proxy Protocol header.
Warning: Optional breaks conformance with the specification. Only enable if ALL traffic to the listener comes from a trusted source.
For more information on security implications, see haproxy.org/download/2.1/doc/proxy-protocol.txt | + + +#### ProxyProtocolVersion + +_Underlying type:_ _string_ + +ProxyProtocolVersion defines the version of the Proxy Protocol to use. + +_Appears in:_ +- [ProxyProtocol](#proxyprotocol) + +| Value | Description | +| ----- | ----------- | +| `V1` | ProxyProtocolVersionV1 is the PROXY protocol version 1 (human readable format).
| +| `V2` | ProxyProtocolVersionV2 is the PROXY protocol version 2 (binary format).
| + + +#### ProxyTelemetry + + + + + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `accessLog` | _[ProxyAccessLog](#proxyaccesslog)_ | false | | AccessLogs defines accesslog parameters for managed proxies.
If unspecified, will send default format to stdout. | +| `tracing` | _[ProxyTracing](#proxytracing)_ | false | | Tracing defines tracing configuration for managed proxies.
If unspecified, will not send tracing data. | +| `metrics` | _[ProxyMetrics](#proxymetrics)_ | true | | Metrics defines metrics configuration for managed proxies. | +| `requestID` | _[RequestIDSettings](#requestidsettings)_ | false | | RequestID configures Envoy request ID behavior. | + + +#### ProxyTracing + + + +ProxyTracing defines the tracing configuration for a proxy. + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | false | | SamplingFraction represents the fraction of requests that should be
selected for tracing if no prior sampling decision has been made. | +| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ | false | | CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Deprecated: Use Tags instead. | +| `tags` | _object (keys:string, values:string)_ | false | | Tags defines the custom tags to add to each span.
Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.
The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.
If provider is kubernetes, pod name and namespace are added by default.
Same keys take precedence over CustomTags. | +| `spanName` | _[TracingSpanName](#tracingspanname)_ | false | | SpanName defines the name of the span which will be used for tracing.
Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.
The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.
If not set, the span name is provider specific.
e.g. Datadog use `ingress` as the default client span name,
and `router egress` as the server span name. | +| `samplingRate` | _integer_ | false | | SamplingRate controls the rate at which traffic will be
selected for tracing if no prior sampling decision has been made.
Defaults to 100, valid values [0-100]. 100 indicates 100% sampling.
Only one of SamplingRate or SamplingFraction may be specified.
If neither field is specified, all requests will be sampled. | +| `provider` | _[TracingProvider](#tracingprovider)_ | true | | Provider defines the tracing provider. | + + +#### QueryParam + + + +QueryParam defines the query parameter name hashing configuration for consistent hash based +load balancing. + +_Appears in:_ +- [ConsistentHash](#consistenthash) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name of the query param to hash. | + + +#### QueryParamMatch + + + +QueryParamMatch defines the match attributes within the query parameters of the request. + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[QueryParamMatchType](#queryparammatchtype)_ | false | Exact | Type specifies how to match against the value of the query parameter. | +| `name` | _string_ | true | | Name of the query parameter. | +| `value` | _string_ | false | | Value of the query parameter.
Do not set this field when Type="Distinct", implying matching on any/all unique
values within the query parameter. | +| `invert` | _boolean_ | false | false | Invert specifies whether the value match result will be inverted.
Do not set this field when Type="Distinct", implying matching on any/all unique
values within the query parameter. | + + +#### QueryParamMatchType + +_Underlying type:_ _string_ + +QueryParamMatchType specifies the semantics of how query parameter values should be compared. +Valid QueryParamMatchType values are "Exact", "RegularExpression", and "Distinct". + +_Appears in:_ +- [QueryParamMatch](#queryparammatch) + +| Value | Description | +| ----- | ----------- | +| `Exact` | QueryParamMatchExact matches the exact value of the Value field against the value of
the specified query parameter.
| +| `RegularExpression` | QueryParamMatchRegularExpression matches a regular expression against the value of the
specified query parameter. The regex string must adhere to the syntax documented in
https://github.com/google/re2/wiki/Syntax.
| +| `Distinct` | QueryParamMatchDistinct matches any and all possible unique values encountered in the
specified query parameter. Note that each unique value will receive its own rate limit
bucket.
| + + +#### RateLimit + + + +RateLimit defines the configuration associated with the Rate Limit Service +used for Global Rate Limiting. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backend` | _[RateLimitDatabaseBackend](#ratelimitdatabasebackend)_ | true | | Backend holds the configuration associated with the
database backend used by the rate limit service to store
state associated with global ratelimiting. | +| `timeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | Timeout specifies the timeout period for the proxy to access the ratelimit server
If not set, timeout is 20ms. | +| `failClosed` | _boolean_ | true | | FailClosed is a switch used to control the flow of traffic
when the response from the ratelimit server cannot be obtained.
If FailClosed is false, let the traffic pass,
otherwise, don't let the traffic pass and return 500.
If not set, FailClosed is False. | +| `telemetry` | _[RateLimitTelemetry](#ratelimittelemetry)_ | false | | Telemetry defines telemetry configuration for RateLimit. | + + +#### RateLimitCost + + + + + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `request` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ | false | | Request specifies the number to reduce the rate limit counters
on the request path. If this is not specified, the default behavior
is to reduce the rate limit counters by 1.
When Envoy receives a request that matches the rule, it tries to reduce the
rate limit counters by the specified number. If the counter doesn't have
enough capacity, the request is rate limited. | +| `response` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ | false | | Response specifies the number to reduce the rate limit counters
after the response is sent back to the client or the request stream is closed.
The cost is used to reduce the rate limit counters for the matching requests.
Since the reduction happens after the request stream is complete, the rate limit
won't be enforced for the current request, but for the subsequent matching requests.
This is optional and if not specified, the rate limit counters are not reduced
on the response path.
Currently, this is only supported for HTTP Global Rate Limits. | + + +#### RateLimitCostFrom + +_Underlying type:_ _string_ + +RateLimitCostFrom specifies the source of the rate limit cost. +Valid RateLimitCostType values are "Number" and "Metadata". + +_Appears in:_ +- [RateLimitCostSpecifier](#ratelimitcostspecifier) + +| Value | Description | +| ----- | ----------- | +| `Number` | RateLimitCostFromNumber specifies the rate limit cost to be a fixed number.
| +| `Metadata` | RateLimitCostFromMetadata specifies the rate limit cost to be retrieved from the per-request dynamic metadata.
| + + +#### RateLimitCostMetadata + + + +RateLimitCostMetadata specifies the filter metadata to retrieve the usage number from. + +_Appears in:_ +- [RateLimitCostSpecifier](#ratelimitcostspecifier) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `namespace` | _string_ | true | | Namespace is the namespace of the dynamic metadata. | +| `key` | _string_ | true | | Key is the key to retrieve the usage number from the filter metadata. | + + +#### RateLimitCostSpecifier + + + +RateLimitCostSpecifier specifies where the Envoy retrieves the number to reduce the rate limit counters. + +_Appears in:_ +- [RateLimitCost](#ratelimitcost) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `from` | _[RateLimitCostFrom](#ratelimitcostfrom)_ | true | | From specifies where to get the rate limit cost. Currently, only "Number" and "Metadata" are supported. | +| `number` | _integer_ | false | | Number specifies the fixed usage number to reduce the rate limit counters.
Using zero can be used to only check the rate limit counters without reducing them. | +| `metadata` | _[RateLimitCostMetadata](#ratelimitcostmetadata)_ | false | | Refer to Kubernetes API documentation for fields of `metadata`. | + + +#### RateLimitDatabaseBackend + + + +RateLimitDatabaseBackend defines the configuration associated with +the database backend used by the rate limit service. + +_Appears in:_ +- [RateLimit](#ratelimit) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[RateLimitDatabaseBackendType](#ratelimitdatabasebackendtype)_ | true | | Type is the type of database backend to use. Supported types are:
* Redis: Connects to a Redis database. | +| `redis` | _[RateLimitRedisSettings](#ratelimitredissettings)_ | false | | Redis defines the settings needed to connect to a Redis database. | + + +#### RateLimitDatabaseBackendType + +_Underlying type:_ _string_ + +RateLimitDatabaseBackendType specifies the types of database backend +to be used by the rate limit service. + +_Appears in:_ +- [RateLimitDatabaseBackend](#ratelimitdatabasebackend) + +| Value | Description | +| ----- | ----------- | +| `Redis` | RedisBackendType uses a redis database for the rate limit service.
| + + +#### RateLimitMetrics + + + + + +_Appears in:_ +- [RateLimitTelemetry](#ratelimittelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `prometheus` | _[RateLimitMetricsPrometheusProvider](#ratelimitmetricsprometheusprovider)_ | true | | Prometheus defines the configuration for prometheus endpoint. | + + +#### RateLimitMetricsPrometheusProvider + + + + + +_Appears in:_ +- [RateLimitMetrics](#ratelimitmetrics) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `disable` | _boolean_ | true | | Disable the Prometheus endpoint. | + + +#### RateLimitRedisSettings + + + +RateLimitRedisSettings defines the configuration for connecting to redis database. + +_Appears in:_ +- [RateLimitDatabaseBackend](#ratelimitdatabasebackend) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `url` | _string_ | true | | URL of the Redis Database.
This can reference a single Redis host or a comma delimited list for Sentinel and Cluster deployments of Redis. | +| `tls` | _[RedisTLSSettings](#redistlssettings)_ | false | | TLS defines TLS configuration for connecting to redis database. | + + +#### RateLimitRule + + + +RateLimitRule defines the semantics for matching attributes +from the incoming requests, and setting limits for them. + +_Appears in:_ +- [GlobalRateLimit](#globalratelimit) +- [LocalRateLimit](#localratelimit) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `clientSelectors` | _[RateLimitSelectCondition](#ratelimitselectcondition) array_ | false | | ClientSelectors holds the list of select conditions to select
specific clients using attributes from the traffic flow.
All individual select conditions must hold True for this rule
and its limit to be applied.
If no client selectors are specified, the rule applies to all traffic of
the targeted Route.
If the policy targets a Gateway, the rule applies to each Route of the Gateway.
Please note that each Route has its own rate limit counters. For example,
if a Gateway has two Routes, and the policy has a rule with limit 10rps,
each Route will have its own 10rps limit. | +| `limit` | _[RateLimitValue](#ratelimitvalue)_ | true | | Limit holds the rate limit values.
This limit is applied for traffic flows when the selectors
compute to True, causing the request to be counted towards the limit.
The limit is enforced and the request is ratelimited, i.e. a response with
429 HTTP status code is sent back to the client when
the selected requests have reached the limit. | +| `cost` | _[RateLimitCost](#ratelimitcost)_ | false | | Cost specifies the cost of requests and responses for the rule.
This is optional and if not specified, the default behavior is to reduce the rate limit counters by 1 on
the request path and do not reduce the rate limit counters on the response path. | +| `shared` | _boolean_ | false | | Shared determines whether this rate limit rule applies across all the policy targets.
If set to true, the rule is treated as a common bucket and is shared across all policy targets (xRoutes).
Default: false. | +| `shadowMode` | _boolean_ | false | | ShadowMode indicates whether this rate-limit rule runs in shadow mode.
When enabled, all rate-limiting operations are performed (cache lookups,
counter updates, telemetry generation), but the outcome is never enforced.
The request always succeeds, even if the configured limit is exceeded.
Only supported for Global Rate Limits. | +| `xRateLimitHeaders` | _[XRateLimitHeadersOption](#xratelimitheadersoption)_ | false | | XRateLimitHeaders controls whether X-RateLimit response headers are emitted for this rate limit rule.
When set, this overrides the global DisableRateLimitHeaders setting in ClientTrafficPolicy for this rule.
If not set, the rule inherits the listener-level setting (default behavior). | + + +#### RateLimitSelectCondition + + + +RateLimitSelectCondition specifies the attributes within the traffic flow that can +be used to select a subset of clients to be ratelimited. +All the individual conditions must hold True for the overall condition to hold True. +And, at least one of headers or methods or path or sourceCIDR or queryParams condition must be specified. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `headers` | _[HeaderMatch](#headermatch) array_ | false | | Headers is a list of request headers to match. Multiple header values are ANDed together,
meaning, a request MUST match all the specified headers. | +| `methods` | _[MethodMatch](#methodmatch) array_ | false | | Methods is a list of request methods to match. Multiple method values are ORed together,
meaning, a request can match any one of the specified methods. If not specified, it matches all methods. | +| `path` | _[PathMatch](#pathmatch)_ | false | | Path is the request path to match.
Support Exact, PathPrefix and RegularExpression match types. | +| `sourceCIDR` | _[SourceMatch](#sourcematch)_ | false | | SourceCIDR is the client IP Address range to match on. | +| `queryParams` | _[QueryParamMatch](#queryparammatch) array_ | false | | QueryParams is a list of query parameters to match. Multiple query parameter values are ANDed together,
meaning, a request MUST match all the specified query parameters. | + + +#### RateLimitSpec + + + +RateLimitSpec defines the desired state of RateLimitSpec. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[RateLimitType](#ratelimittype)_ | false | | Type decides the scope for the RateLimits.
Valid RateLimitType values are "Global" or "Local".
Deprecated: Use Global and/or Local fields directly instead. Both can be specified simultaneously for combined rate limiting. | +| `global` | _[GlobalRateLimit](#globalratelimit)_ | false | | Global defines global rate limit configuration. | +| `local` | _[LocalRateLimit](#localratelimit)_ | false | | Local defines local rate limit configuration. | + + +#### RateLimitTelemetry + + + + + +_Appears in:_ +- [RateLimit](#ratelimit) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `metrics` | _[RateLimitMetrics](#ratelimitmetrics)_ | true | | Metrics defines metrics configuration for RateLimit. | +| `tracing` | _[RateLimitTracing](#ratelimittracing)_ | true | | Tracing defines traces configuration for RateLimit. | + + +#### RateLimitTracing + + + + + +_Appears in:_ +- [RateLimitTelemetry](#ratelimittelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `samplingRate` | _integer_ | false | | SamplingRate controls the rate at which traffic will be
selected for tracing if no prior sampling decision has been made.
Defaults to 100, valid values [0-100]. 100 indicates 100% sampling. | +| `provider` | _[RateLimitTracingProvider](#ratelimittracingprovider)_ | true | | Provider defines the rateLimit tracing provider.
Only OpenTelemetry is supported currently. | + + +#### RateLimitTracingProvider + + + +RateLimitTracingProvider defines the tracing provider configuration of RateLimit + +_Appears in:_ +- [RateLimitTracing](#ratelimittracing) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[RateLimitTracingProviderType](#ratelimittracingprovidertype)_ | true | | Type defines the tracing provider type.
Since to RateLimit Exporter currently using OpenTelemetry, only OpenTelemetry is supported | +| `url` | _string_ | true | | URL is the endpoint of the trace collector that supports the OTLP protocol | + + +#### RateLimitTracingProviderType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [RateLimitTracingProvider](#ratelimittracingprovider) + + + +#### RateLimitType + +_Underlying type:_ _string_ + +RateLimitType specifies the types of RateLimiting. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + +| Value | Description | +| ----- | ----------- | +| `Global` | GlobalRateLimitType allows the rate limits to be applied across all Envoy
proxy instances.
| +| `Local` | LocalRateLimitType allows the rate limits to be applied on a per Envoy
proxy instance basis.
| + + +#### RateLimitUnit + +_Underlying type:_ _string_ + +RateLimitUnit specifies the intervals for setting rate limits. +Valid RateLimitUnit values are "Second", "Minute", "Hour", "Day", "Month" and "Year". + +_Appears in:_ +- [RateLimitValue](#ratelimitvalue) + +| Value | Description | +| ----- | ----------- | +| `Second` | RateLimitUnitSecond specifies the rate limit interval to be 1 second.
| +| `Minute` | RateLimitUnitMinute specifies the rate limit interval to be 1 minute.
| +| `Hour` | RateLimitUnitHour specifies the rate limit interval to be 1 hour.
| +| `Day` | RateLimitUnitDay specifies the rate limit interval to be 1 day.
| +| `Month` | RateLimitUnitMonth specifies the rate limit interval to be 1 month.
| +| `Year` | RateLimitUnitYear specifies the rate limit interval to be 1 year.
| + + +#### RateLimitValue + + + +RateLimitValue defines the limits for rate limiting. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `requests` | _integer_ | true | | Requests is the number of requests (or cost units, when used with
cost-based rate limiting) allowed per Unit. | +| `unit` | _[RateLimitUnit](#ratelimitunit)_ | true | | | + + +#### RedisTLSSettings + + + +RedisTLSSettings defines the TLS configuration for connecting to redis database. + +_Appears in:_ +- [RateLimitRedisSettings](#ratelimitredissettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `certificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | false | | CertificateRef defines the client certificate reference for TLS connections.
Currently only a Kubernetes Secret of type TLS is supported. | + + +#### RemoteDynamicModuleSource + + + +RemoteDynamicModuleSource defines a dynamic module fetched from a remote HTTP source. + +_Appears in:_ +- [DynamicModuleSource](#dynamicmodulesource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `url` | _string_ | true | | URL is the HTTP or HTTPS URL of the dynamic module shared library (.so file). | +| `sha256` | _string_ | true | | SHA256 checksum that Envoy will use to verify the downloaded module binary. | + + +#### RemoteJWKS + + + +RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. + +BackendRefs is used to specify the address of the Remote JWKS. +If the BackendRefs is not specified, the URI field is used to determine the address of the Remote JWKS. + +TLS configuration can be specified in a BackendTLSConfig resource and target the BackendRefs. + +Other settings for the connection to the remote JWKS can be specified in the BackendSettings resource. + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `uri` | _string_ | true | | URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.
If a custom trust bundle is needed, it can be specified in a BackendTLSConfig resource and target the BackendRefs. | +| `cacheDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | 300s | | + + +#### ReplaceRegexMatch + + + + + +_Appears in:_ +- [HTTPPathModifier](#httppathmodifier) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `pattern` | _string_ | true | | Pattern matches a regular expression against the value of the HTTP Path.The regex string must
adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax. | +| `substitution` | _string_ | true | | Substitution is an expression that replaces the matched portion.The expression may include numbered
capture groups that adhere to syntax documented in https://github.com/google/re2/wiki/Syntax. | + + +#### RequestBuffer + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `limit` | _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#quantity-resource-api)_ | true | | Limit specifies the maximum allowed size in bytes for each incoming request buffer.
If exceeded, the request will be rejected with HTTP 413 Content Too Large.
Accepts values in resource.Quantity format (e.g., "10Mi", "500Ki"). | + + +#### RequestHeaderCustomTag + + + +RequestHeaderCustomTag adds value from request header to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | true | | Name defines the name of the request header which to extract the value from. | +| `defaultValue` | _string_ | false | | DefaultValue defines the default value to use if the request header is not set. | + + +#### RequestIDAction + +_Underlying type:_ _string_ + +RequestIDAction configures Envoy's behavior for handling the `X-Request-ID` header at the edge. +An "edge request" refers to a request from an external client to the Envoy entrypoint. + +_Appears in:_ +- [HeaderSettings](#headersettings) + +| Value | Description | +| ----- | ----------- | +| `PreserveOrGenerate` | Preserve `X-Request-ID` if already present or generate if empty
| +| `Preserve` | Preserve `X-Request-ID` if already present, do not generate when empty
| +| `Generate` | Always generate `X-Request-ID` header, do not preserve `X-Request-ID`
header if it exists. This is the default behavior.
| +| `Disable` | Do not preserve or generate `X-Request-ID` header
| + + +#### RequestIDExtensionAction + +_Underlying type:_ _string_ + +RequestIDExtensionAction defines how the UUID request ID extension behaves +with respect to packing the trace reason into the UUID and using the +request ID for trace sampling decisions. + +_Appears in:_ +- [RequestIDSettings](#requestidsettings) + +| Value | Description | +| ----- | ----------- | +| `PackAndSample` | PackAndSample enables both behaviors:
- Alters the UUID to contain the trace sampling decision
- Uses `X-Request-ID` for trace sampling
| +| `Sample` | Sample uses `X-Request-ID` for trace sampling decisions, but does NOT alter
the UUID to pack the trace sampling decision.
| +| `Pack` | Pack alters the UUID to contain the trace sampling decision, but does NOT
use `X-Request-ID` for trace sampling decisions.
| +| `Disable` | Disable disables both behaviors:
- Does not alter the UUID
- Does not use `X-Request-ID` for trace sampling
| + + +#### RequestIDSettings + + + +RequestIDSettings defines configuration for Envoy's UUID request ID extension. + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `tracing` | _[RequestIDExtensionAction](#requestidextensionaction)_ | false | | Tracing configures Envoy's behavior for the UUID request ID extension,
including whether the trace sampling decision is packed into the UUID and
whether `X-Request-ID` is used for trace sampling decisions.
When omitted, the default behavior is `PackAndSample`, which alters the UUID
to contain the trace sampling decision and uses `X-Request-ID` for stable
trace sampling. | + + +#### ResourceProviderType + +_Underlying type:_ _string_ + +ResourceProviderType defines the types of custom resource providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayResourceProvider](#envoygatewayresourceprovider) + +| Value | Description | +| ----- | ----------- | +| `File` | ResourceProviderTypeFile defines the "File" provider.
| + + +#### ResponseOverride + + + +ResponseOverride defines the configuration to override specific responses with a custom one. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `match` | _[CustomResponseMatch](#customresponsematch)_ | true | | Match configuration. | +| `response` | _[CustomResponse](#customresponse)_ | true | | Response configuration. | +| `redirect` | _[CustomRedirect](#customredirect)_ | true | | Redirect configuration | +| `source` | _[ResponseOverrideSource](#responseoverridesource)_ | false | | Source specifies which responses this rule applies to.
Local overrides only Envoy-generated responses (e.g. auth failures).
Backend overrides only upstream responses.
All (default) overrides both. | + + +#### ResponseOverrideSource + +_Underlying type:_ _string_ + +ResponseOverrideSource specifies the source of responses to override. + +_Appears in:_ +- [ResponseOverride](#responseoverride) + +| Value | Description | +| ----- | ----------- | +| `All` | ResponseOverrideSourceAll overrides both Envoy-generated and upstream responses.
| +| `Local` | ResponseOverrideSourceLocal overrides only Envoy-generated responses (e.g. auth failures, rate limits).
| +| `Backend` | ResponseOverrideSourceBackend overrides only upstream/backend responses.
| + + +#### ResponseValueType + +_Underlying type:_ _string_ + +ResponseValueType defines the types of values for the response body supported by Envoy Gateway. + +_Appears in:_ +- [CustomResponseBody](#customresponsebody) + +| Value | Description | +| ----- | ----------- | +| `Inline` | ResponseValueTypeInline defines the "Inline" response body type.
| +| `ValueRef` | ResponseValueTypeValueRef defines the "ValueRef" response body type.
| + + +#### Retry + + + +Retry defines the retry strategy to be applied. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `numRetries` | _integer_ | false | 2 | NumRetries is the number of retries to be attempted. Defaults to 2. | +| `numAttemptsPerPriority` | _integer_ | false | | NumAttemptsPerPriority defines the number of requests (initial attempt + retries)
that should be sent to the same priority before switching to a different one.
If not specified or set to 0, all requests are sent to the highest priority that is healthy. | +| `retryOn` | _[RetryOn](#retryon)_ | false | | RetryOn specifies the retry trigger condition.
If not specified, the default is to retry on connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes(503). | +| `perRetry` | _[PerRetryPolicy](#perretrypolicy)_ | false | | PerRetry is the retry policy to be applied per retry attempt. | + + +#### RetryBudget + + + +RetryBudget specifies the details of the retry budget configuration, like +the percentage of requests in the budget, and the min retry concurrency. + +_Appears in:_ +- [CircuitBreaker](#circuitbreaker) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `percent` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | true | | Percent specifies the limit on concurrent retries as a percentage [0, 100] of
the sum of active requests and active pending requests. | +| `minRetryConcurrency` | _integer_ | false | | MinRetryConcurrency specifies the minimum retry concurrency allowed for the retry budget.
For example, a budget of 20% with a minimum retry concurrency of 3
will allow 5 active retries while there are 25 active requests.
If there are 2 active requests, there are still 3 active retries
allowed because of the minimum retry concurrency.
Defaults to 3. | + + +#### RetryOn + + + + + +_Appears in:_ +- [Retry](#retry) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `triggers` | _[TriggerEnum](#triggerenum) array_ | false | | Triggers specifies the retry trigger condition(Http/Grpc). | +| `httpStatusCodes` | _[HTTPStatus](#httpstatus) array_ | false | | HttpStatusCodes specifies the http status codes to be retried.
The retriable-status-codes trigger must also be configured for these status codes to trigger a retry. | + + +#### RetryableGRPCStatusCode + +_Underlying type:_ _string_ + +GRPCStatus defines grpc status codes as defined in https://github.com/grpc/grpc/blob/master/doc/statuscodes.md. + +_Appears in:_ +- [ExtensionServiceRetry](#extensionserviceretry) + + + +#### RouteTranslationConfig + + + + + +_Appears in:_ +- [TranslationConfig](#translationconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `includeAll` | _boolean_ | false | | IncludeAll defines whether all routes should be included in the translation hook.
Default is false. | + + +#### RoutingType + +_Underlying type:_ _string_ + +RoutingType defines the type of routing of this Envoy proxy. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [EnvoyProxySpec](#envoyproxyspec) + +| Value | Description | +| ----- | ----------- | +| `Service` | ServiceRoutingType is the RoutingType for Service Cluster IP routing.
| +| `Endpoint` | EndpointRoutingType is the RoutingType for Endpoint routing.
| + + +#### RuntimeFlag + +_Underlying type:_ _string_ + +RuntimeFlag defines a runtime flag used to guard breaking changes or risky experimental features in new Envoy Gateway releases. +A runtime flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource. + +_Appears in:_ +- [RuntimeFlags](#runtimeflags) + +| Value | Description | +| ----- | ----------- | +| `XDSNameSchemeV2` | XDSNameSchemeV2 indicates that the xds name scheme v2 is used.
* The listener name will be generated using the protocol and port of the listener.
| + + +#### RuntimeFlags + + + +RuntimeFlags provide a mechanism to guard breaking changes or risky experimental features in new Envoy Gateway releases. +Each flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource. +The names of these flags will be included in the release notes alongside an explanation of the change. +Please note that these flags are temporary and will be removed in future releases once the related features are stable. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enabled` | _[RuntimeFlag](#runtimeflag) array_ | true | | | +| `disabled` | _[RuntimeFlag](#runtimeflag) array_ | true | | | + + + + +#### SchemeHeaderTransform + +_Underlying type:_ _string_ + +SchemeHeaderTransform defines how the :scheme pseudo-header is set for requests forwarded to backends. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Value | Description | +| ----- | ----------- | +| `Preserve` | SchemeHeaderTransformPreserve preserves the :scheme from the original client request.
This is the default behavior.
| +| `MatchBackend` | SchemeHeaderTransformMatchBackend sets the :scheme to match the backend transport protocol.
If the backend uses TLS, the scheme is "https", otherwise "http".
| + + +#### SecretTranslationConfig + + + + + +_Appears in:_ +- [TranslationConfig](#translationconfig) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `includeAll` | _boolean_ | false | | IncludeAll defines whether all secrets should be included in the translation hook.
Default is true for backward compatibility. | + + +#### SecurityPolicy + + + +SecurityPolicy allows the user to configure various security settings for a +Gateway. + + + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`SecurityPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | true | | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[SecurityPolicySpec](#securitypolicyspec)_ | true | | Spec defines the desired state of SecurityPolicy. | +| `status` | _[PolicyStatus](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#policystatus)_ | true | | Status defines the current status of SecurityPolicy. | + + +#### SecurityPolicySpec + + + +SecurityPolicySpec defines the desired state of SecurityPolicy. + +NOTE: SecurityPolicy can target Gateway, HTTPRoute, GRPCRoute, and TCPRoute. +When a SecurityPolicy targets a TCPRoute, only client-IP CIDR based authorization +(Authorization rules that use Principal.ClientCIDRs) is applied. Other +authentication/authorization features such as JWT, API Key, Basic Auth, +OIDC, External Authorization, or GeoIP based authorization are not applicable +to TCPRoute targets. + +_Appears in:_ +- [SecurityPolicy](#securitypolicy) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `targetRef` | _[LocalPolicyTargetReferenceWithSectionName](#localpolicytargetreferencewithsectionname)_ | true | | TargetRef is the name of the resource this policy is being attached to.
This policy and the TargetRef MUST be in the same namespace for this
Policy to have effect
Deprecated: use targetRefs/targetSelectors instead | +| `targetRefs` | _LocalPolicyTargetReferenceWithSectionName array_ | true | | TargetRefs are the names of the Gateway resources this policy
is being attached to. | +| `targetSelectors` | _[TargetSelector](#targetselector) array_ | true | | TargetSelectors allow targeting resources for this policy based on labels | +| `mergeType` | _[MergeType](#mergetype)_ | false | | MergeType determines how this configuration is merged with existing SecurityPolicy
configurations targeting a parent resource. When set, this configuration will be merged
into a parent SecurityPolicy (i.e. the one targeting a Gateway or Listener).
This field cannot be set when targeting a parent resource (Gateway).
If unset, no merging occurs, and only the most specific configuration takes effect. | +| `apiKeyAuth` | _[APIKeyAuth](#apikeyauth)_ | false | | APIKeyAuth defines the configuration for the API Key Authentication. | +| `cors` | _[CORS](#cors)_ | false | | CORS defines the configuration for Cross-Origin Resource Sharing (CORS). | +| `basicAuth` | _[BasicAuth](#basicauth)_ | false | | BasicAuth defines the configuration for the HTTP Basic Authentication. | +| `jwt` | _[JWT](#jwt)_ | false | | JWT defines the configuration for JSON Web Token (JWT) authentication. | +| `oidc` | _[OIDC](#oidc)_ | false | | OIDC defines the configuration for the OpenID Connect (OIDC) authentication. | +| `extAuth` | _[ExtAuth](#extauth)_ | false | | ExtAuth defines the configuration for External Authorization. | +| `authorization` | _[Authorization](#authorization)_ | false | | Authorization defines the authorization configuration. | + + +#### ServiceExternalTrafficPolicy + +_Underlying type:_ _string_ + +ServiceExternalTrafficPolicy describes how nodes distribute service traffic they +receive on one of the Service's "externally-facing" addresses (NodePorts, ExternalIPs, +and LoadBalancer IPs. + +_Appears in:_ +- [KubernetesServiceSpec](#kubernetesservicespec) + +| Value | Description | +| ----- | ----------- | +| `Cluster` | ServiceExternalTrafficPolicyCluster routes traffic to all endpoints.
| +| `Local` | ServiceExternalTrafficPolicyLocal preserves the source IP of the traffic by
routing only to endpoints on the same node as the traffic was received on
(dropping the traffic if there are no local endpoints).
| + + +#### ServiceType + +_Underlying type:_ _string_ + +ServiceType string describes ingress methods for a service + +_Appears in:_ +- [KubernetesServiceSpec](#kubernetesservicespec) + +| Value | Description | +| ----- | ----------- | +| `ClusterIP` | ServiceTypeClusterIP means a service will only be accessible inside the
cluster, via the cluster IP.
| +| `LoadBalancer` | ServiceTypeLoadBalancer means a service will be exposed via an
external load balancer (if the cloud provider supports it).
| +| `NodePort` | ServiceTypeNodePort means a service will be exposed on each Kubernetes Node
at a static Port, common across all Nodes.
| + + +#### Session + + + +Session defines settings related to TLS session management. + +_Appears in:_ +- [ClientTLSSettings](#clienttlssettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `resumption` | _[SessionResumption](#sessionresumption)_ | false | | Resumption determines the proxy's supported TLS session resumption option.
By default, Envoy Gateway does not enable session resumption. Use sessionResumption to
enable stateful and stateless session resumption. Users should consider security impacts
of different resumption methods. Performance gains from resumption are diminished when
Envoy proxy is deployed with more than one replica. | + + +#### SessionResumption + + + +SessionResumption defines supported tls session resumption methods and their associated configuration. + +_Appears in:_ +- [Session](#session) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `stateless` | _[StatelessTLSSessionResumption](#statelesstlssessionresumption)_ | false | | Stateless defines setting for stateless (session-ticket based) session resumption | +| `stateful` | _[StatefulTLSSessionResumption](#statefultlssessionresumption)_ | false | | Stateful defines setting for stateful (session-id based) session resumption | + + +#### ShutdownConfig + + + +ShutdownConfig defines configuration for graceful envoy shutdown process. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `drainTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | DrainTimeout defines the graceful drain timeout. This should be less than the pod's terminationGracePeriodSeconds.
If unspecified, defaults to 60 seconds. | +| `minDrainDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MinDrainDuration defines the minimum drain duration allowing time for endpoint deprogramming to complete.
If unspecified, defaults to 10 seconds. | + + +#### ShutdownManager + + + +ShutdownManager defines the configuration for the shutdown manager. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `image` | _string_ | true | | Image specifies the ShutdownManager container image to be used, instead of the default image. | + + +#### SlowStart + + + +SlowStart defines the configuration related to the slow start load balancer policy. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `window` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | true | | Window defines the duration of the warm up period for newly added host.
During slow start window, traffic sent to the newly added hosts will gradually increase.
Currently only supports linear growth of traffic. For additional details,
see https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#config-cluster-v3-cluster-slowstartconfig | + + +#### SourceMatch + + + + + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[SourceMatchType](#sourcematchtype)_ | false | Exact | | +| `value` | _string_ | true | | Value is the IP CIDR that represents the range of Source IP Addresses of the client.
These could also be the intermediate addresses through which the request has flown through and is part of the `X-Forwarded-For` header.
For example, `192.168.0.1/32`, `192.168.0.0/24`, `001:db8::/64`. | +| `invert` | _boolean_ | false | false | Invert specifies whether the source range match result will be inverted.
When true, the rule matches when the client IP is not in the specified range(s). | + + +#### SourceMatchType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [SourceMatch](#sourcematch) + +| Value | Description | +| ----- | ----------- | +| `Exact` | SourceMatchExact All IP Addresses within the specified Source IP CIDR are treated as a single client selector
and share the same rate limit bucket.
| +| `Distinct` | SourceMatchDistinct Each IP Address within the specified Source IP CIDR is treated as a distinct client selector
and uses a separate rate limit bucket/counter.
| + + +#### StatefulTLSSessionResumption + + + +StatefulTLSSessionResumption defines the stateful (session-id based) type of TLS session resumption. +Note: When Envoy Proxy is deployed with more than one replica, session caches are not synchronized +between instances, possibly leading to resumption failures. +Envoy does not re-validate client certificates upon session resumption. +https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-routematch-tlscontextmatchoptions + +_Appears in:_ +- [SessionResumption](#sessionresumption) + + + +#### StatelessTLSSessionResumption + + + +StatelessTLSSessionResumption defines the stateless (session-ticket based) type of TLS session resumption. +Note: When Envoy Proxy is deployed with more than one replica, session ticket encryption keys are not +synchronized between instances, possibly leading to resumption failures. +In-memory session ticket encryption keys are rotated every 48 hours. +https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys +https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Session-tickets + +_Appears in:_ +- [SessionResumption](#sessionresumption) + + + +#### StatusCodeMatch + + + +StatusCodeMatch defines the configuration for matching a status code. + +_Appears in:_ +- [CustomResponseMatch](#customresponsematch) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[StatusCodeValueType](#statuscodevaluetype)_ | true | Value | Type is the type of value.
Valid values are Value and Range, default is Value. | +| `value` | _integer_ | false | | Value contains the value of the status code. | +| `range` | _[StatusCodeRange](#statuscoderange)_ | false | | Range contains the range of status codes. | + + +#### StatusCodeRange + + + +StatusCodeRange defines the configuration for define a range of status codes. + +_Appears in:_ +- [StatusCodeMatch](#statuscodematch) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `start` | _integer_ | true | | Start of the range, including the start value. | +| `end` | _integer_ | true | | End of the range, including the end value. | + + +#### StatusCodeValueType + +_Underlying type:_ _string_ + +StatusCodeValueType defines the types of values for the status code match supported by Envoy Gateway. + +_Appears in:_ +- [StatusCodeMatch](#statuscodematch) + +| Value | Description | +| ----- | ----------- | +| `Value` | StatusCodeValueTypeValue defines the "Value" status code match type.
| +| `Range` | StatusCodeValueTypeRange defines the "Range" status code match type.
| + + +#### StringMatch + + + +StringMatch defines how to match any strings. +This is a general purpose match condition that can be used by other EG APIs +that need to match against a string. + +_Appears in:_ +- [HTTP1Settings](#http1settings) +- [HTTPHeaderFilter](#httpheaderfilter) +- [OIDCDenyRedirectHeader](#oidcdenyredirectheader) +- [OtherSANMatch](#othersanmatch) +- [ProxyMetrics](#proxymetrics) +- [SubjectAltNames](#subjectaltnames) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[StringMatchType](#stringmatchtype)_ | false | Exact | Type specifies how to match against a string. | +| `value` | _string_ | true | | Value specifies the string value that the match must have. | + + +#### StringMatchType + +_Underlying type:_ _string_ + +StringMatchType specifies the semantics of how a string value should be compared. +Valid MatchType values are "Exact", "Prefix", "Suffix", "RegularExpression". + +_Appears in:_ +- [OIDCDenyRedirectHeader](#oidcdenyredirectheader) +- [OtherSANMatch](#othersanmatch) +- [StringMatch](#stringmatch) + +| Value | Description | +| ----- | ----------- | +| `Exact` | StringMatchExact :the input string must match exactly the match value.
| +| `Prefix` | StringMatchPrefix :the input string must start with the match value.
| +| `Suffix` | StringMatchSuffix :the input string must end with the match value.
| +| `RegularExpression` | StringMatchRegularExpression :The input string must match the regular expression
specified in the match value.
The regex string must adhere to the syntax documented in
https://github.com/google/re2/wiki/Syntax.
| + + +#### SubjectAltNames + + + + + +_Appears in:_ +- [ClientValidationContext](#clientvalidationcontext) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `dnsNames` | _[StringMatch](#stringmatch) array_ | false | | DNS names matchers | +| `emailAddresses` | _[StringMatch](#stringmatch) array_ | false | | Email addresses matchers | +| `ipAddresses` | _[StringMatch](#stringmatch) array_ | false | | IP addresses matchers | +| `uris` | _[StringMatch](#stringmatch) array_ | false | | URIs matchers | +| `otherNames` | _[OtherSANMatch](#othersanmatch) array_ | false | | Other names matchers | + + +#### TCPActiveHealthChecker + + + +TCPActiveHealthChecker defines the settings of tcp health check. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `send` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | | Send defines the request payload. | +| `receive` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | | Receive defines the expected response payload. | + + +#### TCPClientTimeout + + + +TCPClientTimeout only provides timeout configuration on the listener whose protocol is TCP or TLS. + +_Appears in:_ +- [ClientTimeout](#clienttimeout) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `idleTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | IdleTimeout for a TCP connection. Idle time is defined as a period in which there are no
bytes sent or received on either the upstream or downstream connection.
Default: 1 hour. | + + +#### TCPKeepalive + + + +TCPKeepalive define the TCP Keepalive configuration. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `probes` | _integer_ | false | | The total number of unacknowledged probes to send before deciding
the connection is dead.
Defaults to 9. | +| `idleTime` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The duration a connection needs to be idle before keep-alive
probes start being sent.
The duration format is
Defaults to `7200s`. | +| `interval` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The duration between keep-alive probes.
Defaults to `75s`. | + + +#### TCPTimeout + + + + + +_Appears in:_ +- [Timeout](#timeout) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `connectTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | The timeout for network connection establishment, including TCP and TLS handshakes.
Default: 10 seconds. | + + +#### TLSFingerprintType + +_Underlying type:_ _string_ + +TLSFingerprintType specifies the TLS client fingerprinting mode. + +_Appears in:_ +- [BackendTLSConfig](#backendtlsconfig) +- [ClientTLSSettings](#clienttlssettings) +- [TLSSettings](#tlssettings) + +| Value | Description | +| ----- | ----------- | +| `JA3` | Enable JA3 TLS fingerprinting only.
The fingerprint will be available as %TLS_JA3_FINGERPRINT%.
| +| `JA4` | Enable JA4 TLS fingerprinting only.
The fingerprint will be available as %TLS_JA4_FINGERPRINT%.
| + + +#### TLSSettings + + + + + +_Appears in:_ +- [BackendTLSConfig](#backendtlsconfig) +- [ClientTLSSettings](#clienttlssettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `minVersion` | _[TLSVersion](#tlsversion)_ | false | | Min specifies the minimal TLS protocol version to allow.
The default is TLS 1.2 if this is not specified. | +| `maxVersion` | _[TLSVersion](#tlsversion)_ | false | | Max specifies the maximal TLS protocol version to allow
The default is TLS 1.3 if this is not specified. | +| `ciphers` | _string array_ | false | | Ciphers specifies the set of cipher suites supported when
negotiating TLS 1.0 - 1.2. This setting has no effect for TLS 1.3.
For the list of supported ciphers, please refer to the Envoy documentation:
https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlsparameters
In non-FIPS Envoy Proxy builds the default cipher list is:
- [ECDHE-ECDSA-AES128-GCM-SHA256\|ECDHE-ECDSA-CHACHA20-POLY1305]
- [ECDHE-RSA-AES128-GCM-SHA256\|ECDHE-RSA-CHACHA20-POLY1305]
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
In builds using BoringSSL FIPS the default cipher list is:
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384 | +| `ecdhCurves` | _string array_ | false | | ECDHCurves specifies the set of supported ECDH curves.
In non-FIPS Envoy Proxy builds the default curves are:
- X25519
- P-256
In builds using BoringSSL FIPS the default curve is:
- P-256 | +| `signatureAlgorithms` | _string array_ | false | | SignatureAlgorithms specifies which signature algorithms the listener should
support. | +| `alpnProtocols` | _[ALPNProtocol](#alpnprotocol) array_ | false | | ALPNProtocols supplies the list of ALPN protocols that should be
exposed by the listener or used by the proxy to connect to the backend.
Defaults:
1. HTTPS Routes: h2 and http/1.1 are enabled in listener context.
2. Other Routes: ALPN is disabled.
3. Backends: proxy uses the appropriate ALPN options for the backend protocol.
When an empty list is provided, the ALPN TLS extension is disabled.
Defaults to [h2, http/1.1] if not specified.
Typical Supported values are:
- http/1.0
- http/1.1
- h2 | +| `fingerprints` | _[TLSFingerprintType](#tlsfingerprinttype) array_ | false | | Fingerprints specifies TLS client fingerprinting.
When specified, a JAX fingerprint derived from the client’s TLS handshake
is generated. The fingerprint can be logged in access logs or
forwarded to upstream services using request headers.
Fingerprinting is disabled if not specified.
Supported values are:
- JA3
- JA4 | + + +#### TLSVersion + +_Underlying type:_ _string_ + +TLSVersion specifies the TLS version + +_Appears in:_ +- [BackendTLSConfig](#backendtlsconfig) +- [ClientTLSSettings](#clienttlssettings) +- [TLSSettings](#tlssettings) + +| Value | Description | +| ----- | ----------- | +| `Auto` | TLSAuto allows Envoy to choose the optimal TLS Version
| +| `1.0` | TLS1.0 specifies TLS version 1.0
| +| `1.1` | TLS1.1 specifies TLS version 1.1
| +| `1.2` | TLSv1.2 specifies TLS version 1.2
| +| `1.3` | TLSv1.3 specifies TLS version 1.3
| + + +#### TargetNamespaceFrom + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [TargetSelectorNamespaces](#targetselectornamespaces) + +| Value | Description | +| ----- | ----------- | +| `Same` | TargetNamespaceFromSame limits target selection to the policy's namespace.
| +| `All` | TargetNamespaceFromAll allows target selection from all watched namespaces.
| +| `Selector` | TargetNamespaceFromSelector allows target selection from watched namespaces matching the selector.
| + + +#### TargetSelector + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) +- [PolicyTargetReferences](#policytargetreferences) +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `group` | _[Group](#group)_ | true | gateway.networking.k8s.io | Group is the group that this selector targets. Defaults to gateway.networking.k8s.io | +| `kind` | _[Kind](#kind)_ | true | | Kind is the resource kind that this selector targets. | +| `namespaces` | _[TargetSelectorNamespaces](#targetselectornamespaces)_ | false | | Namespaces determines which namespaces are considered for target selection.
If unspecified, only targets in the same namespace as this policy are considered.
When specified, the effective set of namespaces is always constrained to the
namespaces watched by Envoy Gateway.
Selecting targets across namespaces requires a ReferenceGrant in the target
namespace that allows this policy kind to reference the selected target kind.
Cross-namespace targets without a matching ReferenceGrant are ignored. | +| `matchLabels` | _object (keys:string, values:string)_ | false | | MatchLabels are the set of label selectors for identifying the targeted resource. | +| `matchExpressions` | _[LabelSelectorRequirement](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#labelselectorrequirement-v1-meta) array_ | false | | MatchExpressions is a list of label selector requirements. The requirements are ANDed. | + + +#### TargetSelectorNamespaces + + + +TargetSelectorNamespaces determines which namespaces are considered for target selection. + +_Appears in:_ +- [TargetSelector](#targetselector) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `from` | _[TargetNamespaceFrom](#targetnamespacefrom)_ | true | Same | From indicates how namespaces are selected for this target selector.
All means all namespaces watched by Envoy Gateway.
Selector means namespaces watched by Envoy Gateway that match Selector. | +| `selector` | _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#labelselector-v1-meta)_ | false | | Selector selects namespaces when From is set to Selector. | + + +#### Timeout + + + +Timeout defines configuration for timeouts related to connections. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClusterSettings](#clustersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `tcp` | _[TCPTimeout](#tcptimeout)_ | false | | Timeout settings for TCP. | +| `http` | _[HTTPTimeout](#httptimeout)_ | false | | Timeout settings for HTTP. | + + +#### TraceSinkType + +_Underlying type:_ _string_ + +TraceSinkType specifies the types of trace sinks supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayTraceSink](#envoygatewaytracesink) + +| Value | Description | +| ----- | ----------- | +| `OpenTelemetry` | TraceSinkTypeOpenTelemetry captures traces for the OpenTelemetry sink.
| + + +#### Tracing + + + +Tracing defines the configuration for tracing. + +_Appears in:_ +- [BackendTelemetry](#backendtelemetry) +- [ProxyTracing](#proxytracing) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `samplingFraction` | _[Fraction](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#fraction)_ | false | | SamplingFraction represents the fraction of requests that should be
selected for tracing if no prior sampling decision has been made. | +| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ | false | | CustomTags defines the custom tags to add to each span.
If provider is kubernetes, pod name and namespace are added by default.
Deprecated: Use Tags instead. | +| `tags` | _object (keys:string, values:string)_ | false | | Tags defines the custom tags to add to each span.
Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.
The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.
If provider is kubernetes, pod name and namespace are added by default.
Same keys take precedence over CustomTags. | +| `spanName` | _[TracingSpanName](#tracingspanname)_ | false | | SpanName defines the name of the span which will be used for tracing.
Envoy [command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) may be used in the value.
The [format string documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) provides more information.
If not set, the span name is provider specific.
e.g. Datadog use `ingress` as the default client span name,
and `router egress` as the server span name. | + + +#### TracingProvider + + + +TracingProvider defines the tracing provider configuration. + +_Appears in:_ +- [ProxyTracing](#proxytracing) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendobjectreference)_ | false | | BackendRef references a Kubernetes object that represents the
backend server to which the authorization request will be sent.
Deprecated: Use BackendRefs instead. | +| `backendRefs` | _[BackendRef](#backendref) array_ | false | | BackendRefs references a Kubernetes object that represents the
backend server to which the authorization request will be sent. | +| `backendSettings` | _[ClusterSettings](#clustersettings)_ | false | | BackendSettings holds configuration for managing the connection
to the backend. | +| `type` | _[TracingProviderType](#tracingprovidertype)_ | true | OpenTelemetry | Type defines the tracing provider type. | +| `host` | _string_ | false | | Host define the provider service hostname.
Deprecated: Use BackendRefs instead. | +| `port` | _integer_ | false | 4317 | Port defines the port the provider service is exposed on.
Deprecated: Use BackendRefs instead. | +| `serviceName` | _string_ | false | | ServiceName defines the service name to use in tracing configuration.
If not set, Envoy Gateway will use a default service name set as
"name.namespace" (e.g., "my-gateway.default").
Note: This field is only supported for OpenTelemetry and Datadog tracing providers.
For Zipkin, the service name in traces is always derived from the Envoy --service-cluster flag
(typically "namespace/name" format). Setting this field has no effect for Zipkin. | +| `zipkin` | _[ZipkinTracingProvider](#zipkintracingprovider)_ | false | | Zipkin defines the Zipkin tracing provider configuration | +| `openTelemetry` | _[OpenTelemetryTracingProvider](#opentelemetrytracingprovider)_ | false | | OpenTelemetry defines the OpenTelemetry tracing provider configuration | + + +#### TracingProviderType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [TracingProvider](#tracingprovider) + +| Value | Description | +| ----- | ----------- | +| `OpenTelemetry` | | +| `OpenTelemetry` | | +| `Zipkin` | | +| `Datadog` | | + + +#### TracingSpanName + + + + + +_Appears in:_ +- [ProxyTracing](#proxytracing) +- [Tracing](#tracing) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `client` | _string_ | true | | Client defines operation name of the span which will be used for tracing. | +| `server` | _string_ | true | | Server defines the operation name of the upstream span which will be used for tracing. | + + +#### TranslationConfig + + + +TranslationConfig defines the configuration for the translation hook. + +_Appears in:_ +- [XDSTranslatorHooks](#xdstranslatorhooks) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `listener` | _[ListenerTranslationConfig](#listenertranslationconfig)_ | false | | Listener defines the configuration for the listener translation hook. | +| `route` | _[RouteTranslationConfig](#routetranslationconfig)_ | false | | Route defines the configuration for the route translation hook. | +| `cluster` | _[ClusterTranslationConfig](#clustertranslationconfig)_ | false | | Cluster defines the configuration for the cluster translation hook. | +| `secret` | _[SecretTranslationConfig](#secrettranslationconfig)_ | false | | Secret defines the configuration for the secret translation hook. | + + +#### TriggerEnum + +_Underlying type:_ _string_ + +TriggerEnum specifies the conditions that trigger retries. + +_Appears in:_ +- [RetryOn](#retryon) + +| Value | Description | +| ----- | ----------- | +| `5xx` | The upstream server responds with any 5xx response code, or does not respond at all (disconnect/reset/read timeout).
Includes connect-failure and refused-stream.
| +| `gateway-error` | The response is a gateway error (502,503 or 504).
| +| `reset` | The upstream server does not respond at all (disconnect/reset/read timeout.)
| +| `reset-before-request` | Like reset, but only retry if the request headers have not been sent to the upstream server.
| +| `connect-failure` | Connection failure to the upstream server (connect timeout, etc.). (Included in *5xx*)
| +| `retriable-4xx` | The upstream server responds with a retriable 4xx response code.
Currently, the only response code in this category is 409.
| +| `refused-stream` | The upstream server resets the stream with a REFUSED_STREAM error code.
| +| `retriable-status-codes` | The upstream server responds with any response code matching one defined in the RetriableStatusCodes.
| +| `cancelled` | The gRPC status code in the response headers is “cancelled”.
| +| `deadline-exceeded` | The gRPC status code in the response headers is “deadline-exceeded”.
| +| `internal` | The gRPC status code in the response headers is “internal”.
| +| `resource-exhausted` | The gRPC status code in the response headers is “resource-exhausted”.
| +| `unavailable` | The gRPC status code in the response headers is “unavailable”.
| + + +#### UnixSocket + + + +UnixSocket describes TCP/UDP unix domain socket address, corresponding to Envoy's Pipe +https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#config-core-v3-pipe + +_Appears in:_ +- [BackendEndpoint](#backendendpoint) +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `path` | _string_ | true | | Path defines the unix domain socket path of the backend endpoint.
The path length must not exceed 108 characters. | + + +#### Wasm + + + +Wasm defines a Wasm extension. + +Note: at the moment, Envoy Gateway does not support configuring Wasm runtime. +v8 is used as the VM runtime for the Wasm extensions. + +_Appears in:_ +- [EnvoyExtensionPolicySpec](#envoyextensionpolicyspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `name` | _string_ | false | | Name is a unique name for this Wasm extension. It is used to identify the
Wasm extension if multiple extensions are handled by the same vm_id and root_id.
It's also used for logging/debugging.
If not specified, EG will generate a unique name for the Wasm extension. | +| `rootID` | _string_ | true | | RootID is a unique ID for a set of extensions in a VM which will share a
RootContext and Contexts if applicable (e.g., an Wasm HttpFilter and an Wasm AccessLog).
If left blank, all extensions with a blank root_id with the same vm_id will share Context(s).
Note: RootID must match the root_id parameter used to register the Context in the Wasm code. | +| `code` | _[WasmCodeSource](#wasmcodesource)_ | true | | Code is the Wasm code for the extension. | +| `config` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ | false | | Config is the configuration for the Wasm extension.
This configuration will be passed as a JSON string to the Wasm extension. | +| `failOpen` | _boolean_ | false | false | FailOpen is a switch used to control the behavior when a fatal error occurs
during the initialization or the execution of the Wasm extension.
If FailOpen is set to true, the system bypasses the Wasm extension and
allows the traffic to pass through. If it is set to false or
not set (defaulting to false), the system blocks the traffic and returns
an HTTP 5xx error.
If set to true, the Wasm extension will also be bypassed if the configuration is invalid. | +| `env` | _[WasmEnv](#wasmenv)_ | false | | Env configures the environment for the Wasm extension | + + +#### WasmCodeSource + + + +WasmCodeSource defines the source of the Wasm code. + +_Appears in:_ +- [Wasm](#wasm) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `type` | _[WasmCodeSourceType](#wasmcodesourcetype)_ | true | | Type is the type of the source of the Wasm code.
Valid WasmCodeSourceType values are "HTTP" or "Image". | +| `http` | _[HTTPWasmCodeSource](#httpwasmcodesource)_ | false | | HTTP is the HTTP URL containing the Wasm code.
Note that the HTTP server must be accessible from the Envoy proxy. | +| `image` | _[ImageWasmCodeSource](#imagewasmcodesource)_ | false | | Image is the OCI image containing the Wasm code.
Note that the image must be accessible from the Envoy Gateway. | +| `pullPolicy` | _[ImagePullPolicy](#imagepullpolicy)_ | false | | PullPolicy is the policy to use when pulling the Wasm module by either the HTTP or Image source.
This field is only applicable when the SHA256 field is not set.
If not specified, the default policy is IfNotPresent except for OCI images whose tag is latest.
Note: EG does not update the Wasm module every time an Envoy proxy requests
the Wasm module even if the pull policy is set to Always.
It only updates the Wasm module when the EnvoyExtension resource version changes. | + + +#### WasmCodeSourceTLSConfig + + + +WasmCodeSourceTLSConfig defines the TLS configuration when connecting to the Wasm code source. + +_Appears in:_ +- [HTTPWasmCodeSource](#httpwasmcodesource) +- [ImageWasmCodeSource](#imagewasmcodesource) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `caCertificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#secretobjectreference)_ | true | | CACertificateRef contains a reference to
Kubernetes objects that contain TLS certificates of
the Certificate Authorities that can be used
as a trust anchor to validate the certificates presented by the Wasm code source.
Kubernetes ConfigMap, Kubernetes Secret, and Kubernetes ClusterTrustBundle are supported. | + + +#### WasmCodeSourceType + +_Underlying type:_ _string_ + +WasmCodeSourceType specifies the types of sources for the Wasm code. + +_Appears in:_ +- [WasmCodeSource](#wasmcodesource) + +| Value | Description | +| ----- | ----------- | +| `HTTP` | HTTPWasmCodeSourceType allows the user to specify the Wasm code in an HTTP URL.
| +| `Image` | ImageWasmCodeSourceType allows the user to specify the Wasm code in an OCI image.
| + + +#### WasmEnv + + + +WasmEnv defines the environment variables for the VM of a Wasm extension + +_Appears in:_ +- [Wasm](#wasm) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `hostKeys` | _string array_ | false | | HostKeys is a list of keys for environment variables from the host envoy process
that should be passed into the Wasm VM. This is useful for passing secrets to to Wasm extensions. | + + +#### WeightedZoneConfig + + + +WeightedZoneConfig defines the weight for a specific locality zone. + +_Appears in:_ +- [ZoneAware](#zoneaware) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `zone` | _string_ | true | | Zone specifies the topology zone this weight applies to.
The value should match the topology.kubernetes.io/zone label
of the nodes where endpoints are running.
Zones not listed in the configuration receive a default weight of 1. | +| `weight` | _integer_ | true | | Weight defines the weight for this locality.
Higher values receive more traffic. The actual traffic distribution
is proportional to this value relative to other localities. | + + +#### WithUnderscoresAction + +_Underlying type:_ _string_ + +WithUnderscoresAction configures the action to take when an HTTP header with underscores +is encountered. + +_Appears in:_ +- [HeaderSettings](#headersettings) + +| Value | Description | +| ----- | ----------- | +| `Allow` | WithUnderscoresActionAllow allows headers with underscores to be passed through.
| +| `RejectRequest` | WithUnderscoresActionRejectRequest rejects the client request. HTTP/1 requests are rejected with
the 400 status. HTTP/2 requests end with the stream reset.
| +| `DropHeader` | WithUnderscoresActionDropHeader drops the client header with name containing underscores. The header
is dropped before the filter chain is invoked and as such filters will not see
dropped headers.
| + + +#### XDSServer + + + +XDSServer defines configuration values for the xDS gRPC server. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `maxConnectionAge` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxConnectionAge is the maximum age of an active connection before Envoy Gateway will initiate a graceful close.
If unspecified, Envoy Gateway randomly selects a value between 10h and 12h to stagger reconnects across replicas. | +| `maxConnectionAgeGrace` | _[Duration](https://gateway-api.sigs.k8s.io/reference/1.5/spec/#duration)_ | false | | MaxConnectionAgeGrace is the grace period granted after reaching MaxConnectionAge before the connection is forcibly closed.
The default grace period is 2m. | + + +#### XDSTranslatorHook + +_Underlying type:_ _string_ + +XDSTranslatorHook defines the types of hooks that an Envoy Gateway extension may support +for the xds-translator + +_Appears in:_ +- [XDSTranslatorHooks](#xdstranslatorhooks) + +| Value | Description | +| ----- | ----------- | +| `VirtualHost` | | +| `Route` | | +| `HTTPListener` | | +| `Cluster` | | +| `Endpoints` | | +| `Translation` | | + + +#### XDSTranslatorHooks + + + +XDSTranslatorHooks contains all the pre and post hooks for the xds-translator runner. + +_Appears in:_ +- [ExtensionHooks](#extensionhooks) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `pre` | _[XDSTranslatorHook](#xdstranslatorhook) array_ | true | | | +| `post` | _[XDSTranslatorHook](#xdstranslatorhook) array_ | true | | | +| `translation` | _[TranslationConfig](#translationconfig)_ | true | | Translation defines the configuration for the translation hook. | + + +#### XFCCCertData + +_Underlying type:_ _string_ + +XFCCCertData specifies the fields in the client certificate to be forwarded in the XFCC header. + +_Appears in:_ +- [XForwardedClientCert](#xforwardedclientcert) + +| Value | Description | +| ----- | ----------- | +| `Subject` | XFCCCertDataSubject is the Subject field of the current client certificate.
| +| `Cert` | XFCCCertDataCert is the entire client certificate in URL encoded PEM format.
| +| `Chain` | XFCCCertDataChain is the entire client certificate chain (including the leaf certificate) in URL encoded PEM format.
| +| `DNS` | XFCCCertDataDNS is the DNS type Subject Alternative Name field of the current client certificate.
| +| `URI` | XFCCCertDataURI is the URI type Subject Alternative Name field of the current client certificate.
| + + +#### XFCCForwardMode + +_Underlying type:_ _string_ + +XFCCForwardMode defines how XFCC header is handled by Envoy Proxy. + +_Appears in:_ +- [XForwardedClientCert](#xforwardedclientcert) + +| Value | Description | +| ----- | ----------- | +| `Sanitize` | XFCCForwardModeSanitize removes the XFCC header from the request. This is the default mode.
| +| `ForwardOnly` | XFCCForwardModeForwardOnly forwards the XFCC header in the request if the client connection is mTLS.
| +| `AppendForward` | XFCCForwardModeAppendForward appends the client certificate information to the request’s XFCC header and forward it if the client connection is mTLS.
| +| `SanitizeSet` | XFCCForwardModeSanitizeSet resets the XFCC header with the client certificate information and forward it if the client connection is mTLS.
The existing certificate information in the XFCC header is removed.
| +| `AlwaysForwardOnly` | XFCCForwardModeAlwaysForwardOnly always forwards the XFCC header in the request, regardless of whether the client connection is mTLS.
| + + +#### XForwardedClientCert + + + +XForwardedClientCert configures how Envoy Proxy handle the x-forwarded-client-cert (XFCC) HTTP header. + +_Appears in:_ +- [HeaderSettings](#headersettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `mode` | _[XFCCForwardMode](#xfccforwardmode)_ | false | | Mode defines how XFCC header is handled by Envoy Proxy.
If not set, the default mode is `Sanitize`. | +| `certDetailsToAdd` | _[XFCCCertData](#xfcccertdata) array_ | false | | CertDetailsToAdd specifies the fields in the client certificate to be forwarded in the XFCC header.
Hash(the SHA 256 digest of the current client certificate) and By(the Subject Alternative Name)
are always included if the client certificate is forwarded.
This field is only applicable when the mode is set to `AppendForward` or
`SanitizeSet` and the client connection is mTLS. | + + +#### XForwardedForSettings + + + +XForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address. +Refer to https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for +for more details. + +_Appears in:_ +- [ClientIPDetectionSettings](#clientipdetectionsettings) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `numTrustedHops` | _integer_ | false | | NumTrustedHops specifies how many trusted hops to count from the rightmost side of
the X-Forwarded-For (XFF) header when determining the original client’s IP address.
If NumTrustedHops is set to N, the client IP is taken from the Nth address from the
right end of the XFF header.
Example:
XFF = "203.0.113.128, 203.0.113.10, 203.0.113.1"
NumTrustedHops = 2
→ Trusted client address = 203.0.113.10
Only one of NumTrustedHops or TrustedCIDRs should be configured. | +| `trustedCIDRs` | _[CIDR](#cidr) array_ | false | | TrustedCIDRs is a list of CIDR ranges to trust when evaluating
the remote IP address to determine the original client’s IP address.
When the remote IP address matches a trusted CIDR and the x-forwarded-for header was sent,
each entry in the x-forwarded-for header is evaluated from right to left
and the first public non-trusted address is used as the original client address.
If all addresses in x-forwarded-for are within the trusted list, the first (leftmost) entry is used.
Only one of NumTrustedHops and TrustedCIDRs must be set. | + + +#### XRateLimitHeadersOption + +_Underlying type:_ _string_ + +XRateLimitHeadersOption controls whether X-RateLimit response headers are sent for a rate limit rule. +Valid values are "Off" and "DraftVersion03". +This allows per-rule override of the global X-RateLimit header setting in ClientTrafficPolicy. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Value | Description | +| ----- | ----------- | +| `Disabled` | XRateLimitHeadersOptionDisabled disables X-RateLimit headers for this rate limit rule,
regardless of the global ClientTrafficPolicy setting.
| +| `DraftVersion03` | XRateLimitHeadersOptionDraftVersion03 enables X-RateLimit headers using RFC draft version 03
for this rate limit rule, regardless of the global ClientTrafficPolicy setting.
| + + +#### ZipkinTracingProvider + + + +ZipkinTracingProvider defines the Zipkin tracing provider configuration. + +_Appears in:_ +- [TracingProvider](#tracingprovider) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `enable128BitTraceId` | _boolean_ | false | | Enable128BitTraceID determines whether a 128bit trace id will be used
when creating a new trace instance. If set to false, a 64bit trace
id will be used. | +| `disableSharedSpanContext` | _boolean_ | false | | DisableSharedSpanContext determines whether the default Envoy behaviour of
client and server spans sharing the same span context should be disabled. | + + +#### ZoneAware + + + +ZoneAware defines the configuration related to the distribution of requests between locality zones. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `preferLocal` | _[PreferLocalZone](#preferlocalzone)_ | false | | PreferLocalZone configures zone-aware routing to prefer sending traffic to the local locality zone. | +| `weightedZones` | _[WeightedZoneConfig](#weightedzoneconfig) array_ | false | | WeightedZones configures weight-based traffic distribution across locality zones.
Traffic is distributed proportionally based on the sum of all zone weights. | + + +#### ZstdCompressor + + + +ZstdCompressor defines the config for the Zstd compressor. +The default values can be found here: +https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/compression/zstd/compressor/v3/zstd.proto#extension-envoy-compression-zstd-compressor + +_Appears in:_ +- [Compression](#compression) + + + diff --git a/site/content/en/v1.8/api/gateway_api/_index.md b/site/content/en/v1.8/api/gateway_api/_index.md new file mode 100644 index 0000000000..7602d7143f --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/_index.md @@ -0,0 +1,5 @@ +--- +title: "Kubernetes Gateway API" +description: This section includes APIs of Kubernetes Gateway API. +weight: 80 +--- diff --git a/site/content/en/v1.8/api/gateway_api/backendtlspolicy.md b/site/content/en/v1.8/api/gateway_api/backendtlspolicy.md new file mode 100644 index 0000000000..ee4c07f2ff --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/backendtlspolicy.md @@ -0,0 +1,184 @@ ++++ +title = "BackendTLSPolicy" ++++ + + + The `BackendTLSPolicy` resource is GA and has been part of the Standard + Channel since `v1.4.0`. For more information on release channels, refer + to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +[BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration +of the connection from the Gateway to a backend pod(s) via the Service API object. + +Implementations may also decide to support the usage of `BackendTLSPolicy` for specifying the TLS configuration +of the connection from the Gateway to services not connected via HTTPRoute, and any +other kind of backend like [InferencePool](https://gateway-api-inference-extension.sigs.k8s.io/reference/spec/#inferencepool) + +## Background + +`BackendTLSPolicy` specifically addresses the configuration of TLS in order to convey HTTPS from the Gateway +dataplane to the backend. This is referred to as "backend TLS termination" and enables the Gateway to know +how to connect to a backend pod that has its own certificate. + +While there are other API objects provided for TLS to be configured for **passthrough** and **edge** termination, +this API object allows users to specifically configure **backend** TLS termination. For more information on TLS +configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls). + +![Image showing three TLS Termination Types](https://gateway-api.sigs.k8s.io/images/tls-termination-types.png) + +BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment) without defaults or overrides, +applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the +Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order +to prevent the complications involved with sharing trust across namespace boundaries. + +Additionally, implementations may use BackendTLSPolicy for specifying the TLS configuration +of the connection from the Gateway to services not connected via HTTPRoute, and any other +kind of backend, but this behavior is optional and may not be available on all implementations. + +All Gateway API Routes that point to a referenced Service should respect a configured BackendTLSPolicy. + +## Spec + +The specification of a [BackendTLSPolicy][backendtlspolicy] consists of: + +- [TargetRefs][targetRefs] - Defines the targeted API object of the policy. +- [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and +WellKnownCACertificates. +- [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend. +- [SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation. A maximum of 5 SANs are allowed. +- [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates, +which are used to establish a TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or +WellKnownCACertificates may be specified, but not both. +- [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS +handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both. +- [Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support. Check your implementation's documentation for details. + +The following chart outlines the object definitions and relationship: +```mermaid +flowchart LR + backendTLSPolicy[["backendTLSPolicy
BackendTLSPolicySpec: spec
PolicyStatus: status"]] + spec[["spec
PolicyTargetReferenceWithSectionName: targetRefs
BackendTLSPolicyValidation: tls"]] + status[["status
[ ]PolicyAncestorStatus: ancestors"]] + validation[["tls
LocalObjectReference: caCertificateRefs
wellKnownCACertificatesType: wellKnownCACertificates
PreciseHostname: hostname
[]SubjectAltName: subjectAltNames"]] + ancestorStatus[["ancestors
AncestorRef: parentReference
GatewayController: controllerName
[]Condition: conditions"]] + targetRefs[[targetRefs
]] + service["service"] + backendTLSPolicy -->spec + backendTLSPolicy -->status + spec -->targetRefs & validation + status -->ancestorStatus + targetRefs -->service + note[choose only one
caCertificateRefs OR wellKnownCACertificates] + style note fill:#fff + validation -.- note +``` + +The following illustrates a BackendTLSPolicy that configures TLS for a Service serving a backend: +```mermaid +flowchart LR + client(["client"]) + gateway["Gateway"] + httproute["HTTP
Route"] + service["Service"] + pod1["Pod"] + pod2["Pod"] + client -.->|HTTP
request| gateway + gateway --> httproute + httproute -.->|BackendTLSPolicy|service + service --> pod1 & pod2 +``` + + + While the diagram above shows an HTTPRoute, BackendTLSPolicy is a + [union feature](https://gateway-api.sigs.k8s.io/guides/implementers#union-feature-conformance) and + works with any route type that forwards traffic to backends, including + GRPCRoute and TLSRoute (when in Terminate mode). + +### Targeting backends + +A BackendTLSPolicy targets a backend Pod (or set of Pods) via one or more TargetRefs to a Service. This TargetRef is a +required object reference that specifies a Service by its Name, Kind (Service), and optionally its Namespace and Group. +TargetRefs identify the Service(s) for which your Route requires TLS. + + + - Cross-namespace certificate references are not allowed. + +### BackendTLSPolicyValidation + +A BackendTLSPolicyValidation is the specification for the BackendTLSPolicy and defines the configuration for TLS, +including hostname (for server name indication) and certificates. + +#### Hostname + +Hostname defines the server name indication (SNI) the Gateway should use in order to connect to the backend, and must +match the certificate served by the backend pod. A hostname is the fully qualified domain name of a network host, as +defined by [RFC 3986][rfc-3986]. Note the following deviations from the “host” part of the URI as defined in the RFC: + +- IP addresses are not allowed. + +Also note: + + + - Wildcard hostnames are not allowed. + +#### Subject Alternative Names + + + This field was added to BackendTLSPolicy in `v1.2.0` +The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs. +Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen. + + + - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). + - Hostname: DNS name format + - URI: URI format (e.g., SPIFFE ID) + +#### TLS Options + + + This field was added to BackendTLSPolicy in `v1.2.0` +The options field allows specification of implementation-specific TLS configurations. This can include: + +- Vendor-specific mutual TLS automation configuration +- Minimum supported TLS version restrictions +- Supported cipher suite configurations + +Check your implementation documentation for details. + +### +#### Certificates + +The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the +certificate to use for backend TLS, CACertificateRefs and WellKnownCACertificates. Only one of these may be used per +BackendTLSPolicyValidation. + +##### CACertificateRefs + +CACertificateRefs refer to one or more PEM-encoded TLS certificates. + + + - Cross-namespace certificate references are not allowed. + +##### WellKnownCACertificates + +If you are working in an environment where specific TLS certificates are not required, and your Gateway API +implementation allows system or default certificates to be used, e.g. in a development environment, you may +set WellKnownCACertificates to "System" to tell the Gateway to use a set of trusted CA Certificates. There may be +some variation in which system certificates are used by each implementation. Refer to documentation from your +implementation of choice for more information. + +### PolicyStatus + +Status defines the observed state of the BackendTLSPolicy and is not user-configurable. Check status in the same +way you do for other Gateway API objects to verify correct operation. Note that the status in BackendTLSPolicy +uses `PolicyAncestorStatus` to allow you to know which parentReference set that particular status. + +[backendtlspolicy]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicy +[validation]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicyvalidation +[caCertificateRefs]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localobjectreference +[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localobjectreference +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#precisehostname +[rfc-3986]: https://tools.ietf.org/html/rfc3986 +[targetRefs]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#localpolicytargetreferencewithsectionname +[subjectAltNames]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#subjectaltname +[options]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#backendtlspolicyspec diff --git a/site/content/en/v1.8/api/gateway_api/gateway.md b/site/content/en/v1.8/api/gateway_api/gateway.md new file mode 100644 index 0000000000..b5a5636428 --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/gateway.md @@ -0,0 +1,54 @@ ++++ +title = "Gateway" ++++ + + + The `Gateway` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +A `Gateway` is 1:1 with the lifecycle of the configuration of infrastructure. +When a user creates a `Gateway`, some load balancing infrastructure is +provisioned or configured (see below for details) by the `GatewayClass` +controller. `Gateway` is the resource that triggers actions in this API. Other +resources in this API are configuration snippets until a Gateway has been +created to link the resources together. + +The `Gateway` spec defines the following: + +* `GatewayClassName`- Defines the name of a `GatewayClass` object used by + this Gateway. +* `Listeners`- Define the hostnames, ports, protocol, termination, TLS + settings and which routes can be attached to a listener. +* `Addresses`- Define the network addresses requested for this gateway. + +If the desired configuration specified in Gateway spec cannot be achieved, the +Gateway will be in an error state with details provided by status conditions. + +### Deployment models + +Depending on the `GatewayClass`, the creation of a `Gateway` could do any of +the following actions: + +* Use cloud APIs to create an LB instance. +* Spawn a new instance of a software LB (in this or another cluster). +* Add a configuration stanza to an already instantiated LB to handle the new + routes. +* Program the SDN to implement the configuration. +* Something else we haven’t thought of yet... + +The API does not specify which one of these actions will be taken. + +### Gateway Status + +`GatewayStatus` is used to surface the status of a `Gateway` relative to the +desired state represented in `spec`. `GatewayStatus` consists of the following: + +- `Addresses`- Lists the IP addresses that have actually been bound to the + Gateway. +- `Listeners`- Provide status for each unique listener defined in `spec`. +- `Conditions`- Describe the current status conditions of the Gateway. + +Both `Conditions` and `Listeners.conditions` follow the conditions pattern used +elsewhere in Kubernetes. This is a list that includes a type of condition, the +status of the condition and the last time this condition changed. diff --git a/site/content/en/v1.8/api/gateway_api/gatewayclass.md b/site/content/en/v1.8/api/gateway_api/gatewayclass.md new file mode 100644 index 0000000000..8bc136a838 --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/gatewayclass.md @@ -0,0 +1,146 @@ ++++ +title = "GatewayClass" ++++ + + + The `GatewayClass` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +[GatewayClass][gatewayclass] is cluster-scoped resource defined by the +infrastructure provider. This resource represents a class of Gateways that can +be instantiated. + +> Note: GatewayClass serves the same function as the +> [`networking.IngressClass` resource][ingress-class-api]. + +```yaml +kind: GatewayClass +metadata: + name: cluster-gateway +spec: + controllerName: "example.net/gateway-controller" +``` + +We expect that one or more `GatewayClasses` will be created by the +infrastructure provider for the user. It allows decoupling of which mechanism +(e.g. controller) implements the `Gateways` from the user. For instance, an +infrastructure provider may create two `GatewayClasses` named `internet` and +`private` to reflect `Gateways` that define Internet-facing vs private, internal +applications. + +```yaml +kind: GatewayClass +metadata: + name: internet + ... +--- +kind: GatewayClass +metadata: + name: private + ... +``` + +The user of the classes will not need to know *how* `internet` and `private` are +implemented. Instead, the user will only need to understand the resulting +properties of the class that the `Gateway` was created with. + +### GatewayClass parameters + +Providers of the `Gateway` API may need to pass parameters to their controller +as part of the class definition. This is done using the +`GatewayClass.spec.parametersRef` field: + +```yaml +# GatewayClass for Gateways that define Internet-facing applications. +kind: GatewayClass +metadata: + name: internet +spec: + controllerName: "example.net/gateway-controller" + parametersRef: + group: example.net + kind: Config + name: internet-gateway-config +--- +apiVersion: example.net/v1alpha1 +kind: Config +metadata: + name: internet-gateway-config +spec: + ip-address-pool: internet-vips + ... +``` + +Using a Custom Resource for `GatewayClass.spec.parametersRef` is encouraged +but implementations may resort to using a ConfigMap if needed. + +### GatewayClass status + +`GatewayClasses` MUST be validated by the provider to ensure that the configured +parameters are valid. The validity of the class will be signaled to the user via +`GatewayClass.status`: + +```yaml +kind: GatewayClass +... +status: + conditions: + - type: Accepted + status: False + ... +``` + +A new `GatewayClass` will start with the `Accepted` condition set to +`False`. At this point the controller has not seen the configuration. Once the +controller has processed the configuration, the condition will be set to +`True`: + +```yaml +kind: GatewayClass +... +status: + conditions: + - type: Accepted + status: True + ... +``` + +If there is an error in the `GatewayClass.spec`, the conditions will be +non-empty and contain information about the error. + +```yaml +kind: GatewayClass +... +status: + conditions: + - type: Accepted + status: False + Reason: BadFooBar + Message: "foobar" is an FooBar. +``` + +### GatewayClass controller selection + +The `GatewayClass.spec.controller` field determines the controller implementation +responsible for managing the `GatewayClass`. The format of the field is opaque +and specific to a particular controller. The GatewayClass selected by a given +controller field depends on how various controller(s) in the cluster interpret +this field. + +It is RECOMMENDED that controller authors/deployments make their selection +unique by using a domain / path combination under their administrative control +(e.g. controller managing of all `controller`s starting with `example.net` is the +owner of the `example.net` domain) to avoid conflicts. + +Controller versioning can be done by encoding the version of a controller into +the path portion. An example scheme could be (similar to container URIs): + +```text +example.net/gateway/v1 // Use version 1 +example.net/gateway/v2.1 // Use version 2.1 +example.net/gateway // Use the default version +``` + +[gatewayclass]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#gatewayclass +[ingress-class-api]: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class diff --git a/site/content/en/v1.8/api/gateway_api/grpcroute.md b/site/content/en/v1.8/api/gateway_api/grpcroute.md new file mode 100644 index 0000000000..23dfbb9869 --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/grpcroute.md @@ -0,0 +1,421 @@ ++++ +title = "GRPCRoute" ++++ + + + The `GRPCRoute` resource is GA and has been part of the Standard Channel since + `v1.1.0`. For more information on release channels, refer to our [versioning + guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + + If you know you're working with gRPC, prefer using a `GRPCRoute`. An `HTTPRoute` may be sufficient + for basic routing and load balancing, but `GRPCRoute` makes the intent clearer and can unlock + more gRPC-specific functionality. See [When to Use GRPCRoute](#when-to-use-grpcroute). + +[GRPCRoute][grpcroute] is a Gateway API type for specifying routing behavior +of gRPC requests from a Gateway listener to an API object, i.e. Service. + +## Background + +While it is possible to route gRPC with `HTTPRoutes` or via custom, out-of-tree +CRDs, in the long run, this leads to a fragmented ecosystem. + +gRPC is a [popular RPC framework adopted widely across the industry](https://grpc.io/about/#whos-using-grpc-and-why). +The protocol is used pervasively within the Kubernetes project itself as the basis for +many interfaces, including: + +- [the CSI](https://github.com/container-storage-interface/spec/blob/5b0d4540158a260cb3347ef1c87ede8600afb9bf/spec.md), +- [the CRI](https://github.com/kubernetes/cri-api/blob/49fe8b135f4556ea603b1b49470f8365b62f808e/README.md), +- [the device plugin framework](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/) + +Given gRPC's importance in the application-layer networking space and to +the Kubernetes project in particular, the determination was made not to allow +the ecosystem to fragment unnecessarily. + +### Encapsulated Network Protocols + +In general, when it is possible to route an encapsulated protocol at a lower +level, it is acceptable to introduce a route resource at the higher layer when +the following criteria are met: + +- Users of the encapsulated protocol would miss out on significant conventional features from their ecosystem if forced to route at a lower layer. +- Users of the encapsulated protocol would experience a degraded user experience if forced to route at a lower layer. +- The encapsulated protocol has a significant user base, particularly in the Kubernetes community. + +gRPC meets all of these criteria, so the decision was made to include `GRPCRoute`in Gateway API. + +### Cross Serving + +Implementations that support GRPCRoute must enforce uniqueness of +hostnames between `GRPCRoute`s and `HTTPRoute`s. If a route (A) of type `HTTPRoute` or +`GRPCRoute` is attached to a Listener and that listener already has another Route (B) of +the other type attached and the intersection of the hostnames of A and B is +non-empty, then the implementation must reject Route A. That is, the +implementation must raise an 'Accepted' condition with a status of 'False' in +the corresponding RouteParentStatus. + +In general, it is recommended that separate hostnames be used for gRPC and +non-gRPC HTTP traffic. This aligns with standard practice in the gRPC community. +If however, it is a necessity to serve HTTP and gRPC on the same hostname with +the only differentiator being URI, the user should use `HTTPRoute` resources for +both gRPC and HTTP. This will come at the cost of the improved UX of the +`GRPCRoute` resource. + +## When to Use GRPCRoute + +gRPC traffic can be routed with either `HTTPRoute` or `GRPCRoute`. For basic +gRPC load balancing, `GRPCRoute` is not technically required because `HTTPRoute` +can do it. The following guidance helps you choose the right resource for your +use case. + +### When HTTPRoute Is Sufficient + +`HTTPRoute` is sufficient when you only need basic routing and load balancing +for gRPC traffic without gRPC-specific features. Use `HTTPRoute` when: + +- You need simple hostname- or path-based routing and load balancing only. +- You do not need gRPC-aware retries or metrics (e.g. retries on gRPC status codes, gRPC-oriented metrics). +- You must serve HTTP and gRPC on the same hostname with URI as the only + differentiator; in that case you must use `HTTPRoute` for both (see [Cross + Serving](#cross-serving) above). + +With `HTTPRoute`, gRPC methods are matched by specifying the gRPC path as a +URI path (e.g. `/package.Service/Method`). With `GRPCRoute`, you match by +service and method fields (e.g. `service: com.example.User`, `method: Login`). + +### When to Prefer GRPCRoute + +Prefer `GRPCRoute` when you need gRPC-specific behavior or better ergonomics +for gRPC users. Use `GRPCRoute` when: + +- You want to match by gRPC service and method names directly (e.g. + `service: com.example.User`, `method: Login`) instead of URI paths. +- You need gRPC-aware policies such as retries conditioned on gRPC status + codes (e.g. `CANCELLED`, `RESOURCE_EXHAUSTED`). +- You need gRPC-oriented metrics or observability from the implementation. + +### Guidance for Controller Implementers + +Controllers that generate Routes on behalf of users (e.g. higher-level APIs +that create Gateway API routes) should consider the following: + +- If you generate `HTTPRoute` for basic gRPC load balancing, consider + offering a `GRPCRoute` option so that users who need gRPC-specific features + can use them without switching to manually managing routes. +- Do not add gRPC-specific policy (such as retries on gRPC status codes) to + `HTTPRoute`. Keep gRPC-aware configuration in `GRPCRoute` only. + +## Spec + +The specification of a GRPCRoute consists of: + +- [ParentRefs][parentRef]- Define which Gateways this Route wants to be attached + to. +- [Hostnames][hostname] (optional)- Define a list of hostnames to use for + matching the Host header of gRPC requests. +- [Rules][grpcrouterule]- Define a list of rules to perform actions against + matching gRPC requests. Each rule consists of [matches][matches], + [filters][filters] (optional), [backendRefs][backendRef] (optional), and + [name][name] (optional) fields. + + +The following illustrates a GRPCRoute that sends all traffic to one Service: +![grpcroute-basic-example](https://gateway-api.sigs.k8s.io/images/grpcroute-basic-example.png) + +### Attaching to Gateways + +Each Route includes a way to reference the parent resources it wants to attach +to. In most cases, that's going to be Gateways, but there is some flexibility +here for implementations to support other types of parent resources. + +The following example shows how a Route would attach to the `acme-lb` Gateway: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: grpcroute-example +spec: + parentRefs: + - name: acme-lb +``` + +Note that the target Gateway needs to allow GRPCRoutes from the route's +namespace to be attached for the attachment to be successful. + +### Hostnames + +Hostnames define a list of hostnames to match against the Host header of the +gRPC request. When a match occurs, the GRPCRoute is selected to perform request +routing based on rules and filters (optional). A hostname is the fully qualified +domain name of a network host, as defined by [RFC 3986][rfc-3986]. Note the +following deviations from the “host” part of the URI as defined in the RFC: + +- IPs are not allowed. +- The : delimiter is not respected because ports are not allowed. + +Incoming requests are matched against hostnames before the GRPCRoute rules are +evaluated. If no hostname is specified, traffic is routed based on GRPCRoute +rules and filters (optional). + +The following example defines hostname "my.example.com": + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: grpcroute-example +spec: + hostnames: + - my.example.com +``` + +### Rules + +Rules define semantics for matching an gRPC requests based on conditions, +optionally executing additional processing steps, and optionally forwarding +the request to an API object. + +#### Matches + +Matches define conditions used for matching an gRPC requests. Each match is +independent, i.e. this rule will be matched if any single match is satisfied. + +Take the following matches configuration as an example: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +... +matches: + - method: + service: com.example.User + method: Login + headers: + - name: version + value: "2" + - method: + service: com.example.v2.User + method: Login +``` + +For a request to match against this rule, it must satisfy EITHER of the +following conditions: + + - The `com.example.User.Login` method **AND** contains the header "version: 2" + - The `com.example.v2.User.Login` method. + +If no matches are specified, the default is to match every gRPC request. + +#### Filters (optional) + +Filters define processing steps that must be completed during the request or +response lifecycle. Filters act as an extension point to express additional +processing that may be performed in Gateway implementations. Some examples +include request or response modification, implementing authentication +strategies, rate-limiting, and traffic shaping. + +The following example adds header "my-header: foo" to gRPC requests with Host +header "my.filter.com". Note that GRPCRoute uses HTTPRoute filters for features +with functionality identical to HTTPRoute, such as this. + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: grpc-filter-1 +spec: + hostnames: + - my.filter.com + rules: + - filters: + - type: RequestHeaderModifier + requestHeaderModifier: + add: + - name: my-header + value: foo + backendRefs: + - name: my-filter-svc1 + weight: 1 + port: 50051 + +``` + +API conformance is defined based on the filter type. The effects of ordering +multiple behaviors are currently unspecified. This may change in the future +based on feedback during the alpha stage. + +Conformance levels are defined by the filter type: + + - All "core" filters MUST be supported by implementations supporting GRPCRoute. + - Implementers are encouraged to support "extended" filters. + - "Implementation-specific" filters have no API guarantees across implementations. + +Specifying a core filter multiple times has unspecified or custom conformance. + +If an implementation cannot support a combinations of filters, they must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +#### BackendRefs (optional) + +BackendRefs defines the API objects to which matching requests should be sent. If +unspecified, the rule performs no forwarding. If unspecified and no filters +are specified that would result in a response being sent, an `UNIMPLEMENTED` error code +is returned. + +The following example forwards gRPC requests for the method `User.Login` to service +"my-service1" on port `50051` and gRPC requests for the method `Things.DoThing` with +header `magic: foo` to service "my-service2" on port `50051`: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: example +spec: + controllerName: acme.io/gateway-controller + parametersRef: + name: example + group: acme.io + kind: Parameters +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: my-gateway +spec: + gatewayClassName: example + listeners: # Use GatewayClass defaults for listener definition. + - name: https + protocol: HTTPS + port: 50051 + tls: + certificateRefs: + - kind: Secret + group: "" + name: example-com-cert +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: grpc-app-1 +spec: + parentRefs: + - name: my-gateway + hostnames: + - "example.com" + rules: + - matches: + - method: + service: com.example.User + method: Login + backendRefs: + - name: my-service1 + port: 50051 + - matches: + - headers: + - type: Exact + name: magic + value: foo + method: + service: com.example.Things + method: DoThing + backendRefs: + - name: my-service2 + port: 50051 + +``` + +The following example uses the `weight` field to forward 90% of gRPC requests to +`foo.example.com` to the "foo-v1" Service and the other 10% to the "foo-v2" +Service: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: foo-route + labels: + gateway: prod-web-gw +spec: + hostnames: + - foo.example.com + rules: + - backendRefs: + - name: foo-v1 + port: 50051 + weight: 90 + - name: foo-v2 + port: 50051 + weight: 10 + +``` + +Reference the [backendRef][backendRef] API documentation for additional details +on `weight` and other fields. + +#### Name (optional) + + + This concept has been part of the Experimental Channel since `v1.2.0`. + For more information on release channels, refer to our + [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +GRPCRoute Rules include an optional `name` field. The applications for the name of a route rule are implementation-specific. It can be used to reference individual route rules by name from other resources, such as in the `sectionName` field of metaresources ([GEP-2648](https://gateway-api.sigs.k8s.io/geps/gep-2648/index#section-names)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from GRPCRoute Rule, etc. + +If specified, the value of the name field must comply with the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/v1.0.0/apis/v1/shared_types.go#L607-L624) type. + +## Status + +Status defines the observed state of the GRPCRoute. + +### RouteStatus + +RouteStatus defines the observed state that is required across all route types. + +#### Parents + +Parents define a list of the Gateways (or other parent resources) that are +associated with the GRPCRoute, and the status of the GRPCRoute with respect to +each of these Gateways. When a GRPCRoute adds a reference to a Gateway in +parentRefs, the controller that manages the Gateway should add an entry to this +list when the controller first sees the route and should update the entry as +appropriate when the route is modified. + +## Examples + +The following example indicates GRPCRoute "grpc-example" has been accepted by +Gateway "gw-example" in namespace "gw-example-ns": + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GRPCRoute +metadata: + name: grpc-example +... +status: + parents: + - parentRefs: + name: gw-example + namespace: gw-example-ns + conditions: + - type: Accepted + status: "True" +``` + +## Merging +Multiple GRPCRoutes can be attached to a single Gateway resource. Importantly, +only one Route rule may match each request. For more information on how conflict +resolution applies to merging, refer to the [API specification][grpcrouterule]. + +[grpcroute]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroute +[grpcrouterule]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcrouterule +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#hostname +[rfc-3986]: https://tools.ietf.org/html/rfc3986 +[matches]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroutematch +[filters]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcroutefilter +[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#grpcbackendref +[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#parentreference +[name]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#sectionname diff --git a/site/content/en/v1.8/api/gateway_api/httproute.md b/site/content/en/v1.8/api/gateway_api/httproute.md new file mode 100644 index 0000000000..7aee7265c8 --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/httproute.md @@ -0,0 +1,477 @@ ++++ +title = "HTTPRoute" ++++ + + + The `HTTPRoute` resource is GA and has been part of the Standard Channel since + `v0.5.0`. For more information on release channels, refer to our [versioning + guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +[HTTPRoute][httproute] is a Gateway API type for specifying routing behavior +of HTTP requests from a Gateway listener to an API object, i.e. Service. + +## Spec + +The specification of an HTTPRoute consists of: + +- [ParentRefs][parentRef]- Define which Gateways this Route wants to be attached + to. +- [Hostnames][hostname] (optional)- Define a list of hostnames to use for + matching the Host header of HTTP requests. +- [Rules][httprouterule]- Define a list of rules to perform actions against + matching HTTP requests. Each rule consists of [matches][matches], + [filters][filters] (optional), [backendRefs][backendRef] (optional), + [timeouts][timeouts] (optional), and [name][sectionName] (optional) fields. + +The following illustrates an HTTPRoute that sends all traffic to one Service: +![httproute-basic-example](https://gateway-api.sigs.k8s.io/images/httproute-basic-example.svg) + +### Attaching to Gateways + +Each Route includes a way to reference the parent resources it wants to attach +to. In most cases, that's going to be Gateways, but there is some flexibility +here for implementations to support other types of parent resources. + +The following example shows how a Route would attach to the `acme-lb` Gateway: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httproute-example +spec: + parentRefs: + - name: acme-lb +``` + +Note that the target Gateway needs to allow HTTPRoutes from the route's +namespace to be attached for the attachment to be successful. + +You can also attach routes to specific sections of the parent resource. +For example, let's say that the `acme-lb` Gateway includes the following +listeners: + +```yaml + listeners: + - name: foo + protocol: HTTP + port: 8080 + ... + - name: bar + protocol: HTTP + port: 8090 + ... + - name: baz + protocol: HTTP + port: 8090 + ... +``` + +You can bind a route to listener `foo` only, using the `sectionName` field +in `parentRefs`: + +```yaml +spec: + parentRefs: + - name: acme-lb + sectionName: foo +``` + +Alternatively, you can achieve the same effect by using the `port` field, +instead of `sectionName`, in the `parentRefs`: + +```yaml +spec: + parentRefs: + - name: acme-lb + port: 8080 +``` + +Binding to a port also allows you to attach to multiple listeners at once. +For example, binding to port `8090` of the `acme-lb` Gateway would be more +convenient than binding to the corresponding listeners by name: + +```yaml +spec: + parentRefs: + - name: acme-lb + sectionName: bar + - name: acme-lb + sectionName: baz +``` + +However, when binding Routes by port number, Gateway admins will no longer have +the flexibility to switch ports on the Gateway without also updating the Routes. +The approach should only be used when a Route should apply to a specific port +number as opposed to listeners whose ports may be changed. + +### Hostnames + +Hostnames define a list of hostnames to match against the Host header of the +HTTP request. When a match occurs, the HTTPRoute is selected to perform request +routing based on rules and filters (optional). A hostname is the fully qualified +domain name of a network host, as defined by [RFC 3986][rfc-3986]. Note the +following deviations from the “host” part of the URI as defined in the RFC: + +- IPs are not allowed. +- The : delimiter is not respected because ports are not allowed. + +Incoming requests are matched against hostnames before the HTTPRoute rules are +evaluated. If no hostname is specified, traffic is routed based on HTTPRoute +rules and filters (optional). + +The following example defines hostname "my.example.com": + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httproute-example +spec: + hostnames: + - my.example.com +``` + +### Rules + +Rules define semantics for matching an HTTP request based on conditions, +optionally executing additional processing steps, and optionally forwarding +the request to an API object. + +#### Matches + +Matches define conditions used for matching an HTTP request. Each match is +independent, i.e. this rule will be matched if any single match is satisfied. + +Take the following matches configuration as an example: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +... +spec: + rules: + - matches: + - path: + value: "/foo" + headers: + - name: "version" + value: "2" + - path: + value: "/v2/foo" +``` + +For a request to match against this rule, it must satisfy EITHER of the +following conditions: + + - A path prefixed with /foo **AND** contains the header "version: 2" + - A path prefix of /v2/foo + +If no matches are specified, the default is a prefix path match on “/”, +which has the effect of matching every HTTP request. + +#### Filters (optional) + +Filters define processing steps that must be completed during the request or +response lifecycle. Filters act as an extension point to express additional +processing that may be performed in Gateway implementations. Some examples +include request or response modification, implementing authentication +strategies, rate-limiting, and traffic shaping. + +The following example adds header "my-header: foo" to HTTP requests with Host +header "my.filter.com". +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: http-filter-1 +spec: + hostnames: + - my.filter.com + rules: + - filters: + - type: RequestHeaderModifier + requestHeaderModifier: + add: + - name: my-header + value: foo + backendRefs: + - name: my-filter-svc1 + weight: 1 + port: 80 + +``` + +API conformance is defined based on the filter type. The effects of ordering +multiple behaviors is currently unspecified. This may change in the future +based on feedback during the alpha stage. + +Conformance levels are defined by the filter type: + + - All "core" filters MUST be supported by implementations. + - Implementers are encouraged to support "extended" filters. + - "Implementation-specific" filters have no API guarantees across implementations. + +Specifying a core filter multiple times has unspecified or +implementation-specific conformance. + +All filters are expected to be compatible with each other except for the +URLRewrite and RequestRedirect filters, which may not be combined. If an +implementation cannot support other combinations of filters, they must clearly +document that limitation. In cases where incompatible or unsupported +filters are specified and cause the `Accepted` condition to be set to status +`False`, implementations may use the `IncompatibleFilters` reason to specify +this configuration error. + +#### BackendRefs (optional) + +BackendRefs defines API objects where matching requests should be sent. If +unspecified, the rule performs no forwarding. If unspecified and no filters +are specified that would result in a response being sent, a 500 error code +is returned. + +The following example forwards HTTP requests for path prefix `/bar` to service +"my-service1" on port `8080`, and HTTP requests fulfilling _all_ four of the +following criteria + +- header `magic: foo` +- query param `great: example` +- path prefix `/some/thing` +- method `GET` + +to service "my-service2" on port `8080`: +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: example +spec: + controllerName: acme.io/gateway-controller + parametersRef: + name: example + group: acme.io + kind: Parameters +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: my-gateway +spec: + gatewayClassName: example + listeners: # Use GatewayClass defaults for listener definition. + - name: http + protocol: HTTP + port: 80 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: http-app-1 +spec: + parentRefs: + - name: my-gateway + hostnames: + - "foo.com" + rules: + - matches: + - path: + type: PathPrefix + value: /bar + backendRefs: + - name: my-service1 + port: 8080 + - matches: + - headers: + - type: Exact + name: magic + value: foo + queryParams: + - type: Exact + name: great + value: example + path: + type: PathPrefix + value: /some/thing + method: GET + backendRefs: + - name: my-service2 + port: 8080 + +``` + +The following example uses the `weight` field to forward 90% of HTTP requests to +`foo.example.com` to the "foo-v1" Service and the other 10% to the "foo-v2" +Service: +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: foo-route + labels: + gateway: prod-web-gw +spec: + hostnames: + - foo.example.com + rules: + - backendRefs: + - name: foo-v1 + port: 8080 + weight: 90 + - name: foo-v2 + port: 8080 + weight: 10 + +``` + +Reference the [backendRef][backendRef] API documentation for additional details +on `weight` and other fields. + +#### Timeouts (optional) + + + HTTPRoute timeouts have been part of the Standard Channel since `v1.2.0`. + For more information on release channels, refer to our + [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +HTTPRoute Rules include a `Timeouts` field. If unspecified, timeout behavior is implementation-specific. + +There are 2 kinds of timeouts that can be configured in an HTTPRoute Rule: + +1. `request` is the timeout for the Gateway API implementation to send a response to a client HTTP request. This timeout is intended to cover as close to the whole request-response transaction as possible, although an implementation MAY choose to start the timeout after the entire request stream has been received instead of immediately after the transaction is initiated by the client. + +2. `backendRequest` is a timeout for a single request from the Gateway to a backend. This timeout covers the time from when the request first starts being sent from the gateway to when the full response has been received from the backend. This can be particularly helpful if the Gateway retries connections to a backend. + +Because the `request` timeout encompasses the `backendRequest` timeout, the value of `backendRequest` must not be greater than the value of `request` timeout. + +Timeouts are optional, and their fields are of type [Duration](https://gateway-api.sigs.k8s.io/geps/gep-2257/index). A zero-valued timeout ("0s") MUST be interpreted as disabling the timeout. A valid non-zero-valued timeout MUST be >= 1ms. + +The following example uses the `request` field which will cause a timeout if a client request is taking longer than 10 seconds to complete. The example also defines a 2s `backendRequest` which specifies a timeout for an individual request from the gateway to a backend service `timeout-svc`: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: timeout-example +spec: + parentRefs: + - name: example-gateway + rules: + - matches: + - path: + type: PathPrefix + value: /timeout + timeouts: + request: 10s + backendRequest: 2s + backendRefs: + - name: timeout-svc + port: 8080 + +``` + +Reference the [timeouts][timeouts] API documentation for additional details. + +#### Name (optional) + + + This concept has been part of the Experimental Channel since `v1.2.0`. + For more information on release channels, refer to our + [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +HTTPRoute Rules include an optional `name` field. The applications for the name of a route rule are implementation-specific. It can be used to reference individual route rules by name from other resources, such as in the `sectionName` field of metaresources ([GEP-2648](https://gateway-api.sigs.k8s.io/geps/gep-2648/index#section-names)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from HTTPRoute Rule, etc. + +If specified, the value of the name field must comply with the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/v1.0.0/apis/v1/shared_types.go#L607-L624) type. + +The following example specifies the `name` field to identify HTTPRoute Rules used to split traffic between a _read-only_ backend service and a _write-only_ one: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: example-route +spec: + parentRefs: + - name: example-gateway + rules: + - name: read-only + matches: + - method: GET + backendRefs: + - name: backend-mirror-svc + port: 8080 + - name: write-only + matches: + - method: POST + - method: PATCH + - method: DELETE + backendRefs: + - name: backend-svc + port: 8080 + +``` + +##### Backend Protocol + + + This concept has been part of the Experimental Channel since `v1.0.0`. + For more information on release channels, refer to our + [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + +Some implementations may require the [backendRef][backendRef] to be labeled +explicitly in order to route traffic using a certain protocol. For Kubernetes +Service backends this can be done by specifying the [`appProtocol`][appProtocol] +field. + + +## Status + +Status defines the observed state of HTTPRoute. + +### RouteStatus + +RouteStatus defines the observed state that is required across all route types. + +#### Parents + +Parents define a list of the Gateways (or other parent resources) that are +associated with the HTTPRoute, and the status of the HTTPRoute with respect to +each of these Gateways. When an HTTPRoute adds a reference to a Gateway in +parentRefs, the controller that manages the Gateway should add an entry to this +list when the controller first sees the route and should update the entry as +appropriate when the route is modified. + +The following example indicates HTTPRoute "http-example" has been accepted by +Gateway "gw-example" in namespace "gw-example-ns": +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: http-example +... +status: + parents: + - parentRef: + name: gw-example + namespace: gw-example-ns + conditions: + - type: Accepted + status: "True" +``` + +## Merging +Multiple HTTPRoutes can be attached to a single Gateway resource. Importantly, +only one Route rule may match each request. For more information on how conflict +resolution applies to merging, refer to the [API specification][httprouterule]. + + +[httproute]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproute +[httprouterule]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httprouterule +[hostname]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#hostname +[rfc-3986]: https://tools.ietf.org/html/rfc3986 +[matches]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutematch +[filters]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutefilter +[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httpbackendref +[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#parentreference +[timeouts]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#httproutetimeouts +[appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol +[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.5/spec/#sectionname diff --git a/site/content/en/v1.8/api/gateway_api/referencegrant.md b/site/content/en/v1.8/api/gateway_api/referencegrant.md new file mode 100644 index 0000000000..d90e22c9fc --- /dev/null +++ b/site/content/en/v1.8/api/gateway_api/referencegrant.md @@ -0,0 +1,166 @@ ++++ +title = "ReferenceGrant" ++++ + + + The `ReferenceGrant` resource is Beta and part of the + Standard Channel since `v0.6.0`. For more information on release + channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning). + + This resource was originally named "ReferencePolicy". It was renamed + to "ReferenceGrant" to avoid any confusion with policy attachment. + +A ReferenceGrant can be used to enable cross namespace references within +Gateway API. In particular, Routes may forward traffic to backends in other +namespaces, or Gateways may refer to Secrets in another namespace. + +![Reference Grant](https://gateway-api.sigs.k8s.io/images/referencegrant-simple.svg) + + +In the past, we've seen that forwarding traffic across namespace boundaries is a +desired feature, but without a safeguard like ReferenceGrant, +[vulnerabilities](https://github.com/kubernetes/kubernetes/issues/103675) can +emerge. + +If an object is referred to from outside its namespace, the object's owner must +create a ReferenceGrant resource to explicitly allow that reference. Without a +ReferenceGrant, a cross namespace reference is invalid. + +It is recommended that `ReferenceGrants` are used with caution, and that validations +and limits are applied by cluster admins to guarantee the proper usage of this resource. + +Please refer to [Security Considerations](https://gateway-api.sigs.k8s.io/concepts/security#limiting-cross-namespace-references) +for more details. + +## Structure +Fundamentally a ReferenceGrant is made up of two lists, a list of resources +references may come from, and a list of resources that may be referenced. + +The `from` list allows you to specify the group, kind, and namespace of +resources that may reference items described in the `to` list. + +The `to` list allows you to specify the group and kind of resources that may be +referenced by items described in the `from` list. The namespace is not necessary +in the `to` list because a ReferenceGrant can only be used to allow references +to resources in the same namespace as the ReferenceGrant. + +## Example +The following example shows how an HTTPRoute in namespace `foo` can reference a +Service in namespace `bar`. In this example a ReferenceGrant in the `bar` +namespace explicitly allows references to Services from HTTPRoutes in the `foo` +namespace. + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: foo + namespace: foo +spec: + rules: + - matches: + - path: /bar + backendRefs: + - name: bar + namespace: bar +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: ReferenceGrant +metadata: + name: bar + namespace: bar +spec: + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: foo + to: + - group: "" + kind: Service +``` + +## API design decisions +While the API is simplistic in nature, it comes with a few notable decisions: + +1. Each ReferenceGrant only supports a single From and To section. Additional + trust relationships must be modeled with additional ReferenceGrant + resources. +1. Resource names are intentionally excluded from the "From" section of + ReferenceGrant because they rarely provide any meaningful protection. A user + that is able to write to resources of a certain kind within a namespace can + always rename resources or change the structure of the resources to match a + given grant. +1. A single Namespace is allowed per "From" struct. Although a selector would be + more powerful, it encourages unnecessarily insecure configuration. +1. The effect of these resources is purely additive, they stack on top of each + other. This makes it impossible for them to conflict with each other. + +Please see the [API +Specification](https://gateway-api.sigs.k8s.io/reference/spec#referencegrant) +for more details on how specific ReferenceGrant fields are interpreted. + +## Implementation Guidelines +This API relies on runtime verification. Implementations MUST watch for changes +to these resources and recalculate the validity of cross-namespace references +after each change or deletion. + +When communicating the status of a cross-namespace reference, implementations +MUST NOT expose information about the existence of a resource in another +namespace unless a ReferenceGrant exists allowing the reference to occur. This +means that if a cross-namespace reference is made without a ReferenceGrant to a +resource that doesn't exist, any status conditions or warning messages need to +focus on the fact that a ReferenceGrant does not exist to allow this reference. +No hints should be provided about whether or not the referenced resource exists. + +## Exceptions +Cross namespace Route -> Gateway binding follows a slightly different pattern +where the handshake mechanism is built into the Gateway resource. For more +information on that approach, refer to the relevant [Security Model +documentation](https://gateway-api.sigs.k8s.io/concepts/security). Although conceptually similar to +ReferenceGrant, this configuration is built directly into Gateway Listeners, +and allows for fine-grained per Listener configuration that would not be +possible with ReferenceGrant. + +There are some situations where it MAY be acceptable to ignore ReferenceGrant +in favor of some other security mechanism. This MAY only be done if other +mechanisms like NetworkPolicy can effectively limit cross-namespace references +by the implementation. + +An implementation choosing to make this exception MUST clearly document that +ReferenceGrant is not honored by their implementations and detail which +alternative safeguards are available. Note that this is unlikely to apply to +ingress implementations of the API and will not apply to all mesh +implementations. + +For an example of the risks involved in cross-namespace references, refer to +[CVE-2021-25740](https://github.com/kubernetes/kubernetes/issues/103675). +Implementations of this API need to be very careful to avoid confused deputy +attacks. ReferenceGrant provides a safeguard for that. Exceptions MUST only be +made by implementations that are absolutely certain that other equally effective +safeguards are in place. + +## Conformance Level +ReferenceGrant support is a "CORE" conformance level requirement for +cross-namespace references that originate from the following objects: + +- Gateway +- GRPCRoute +- HTTPRoute +- TLSRoute +- TCPRoute +- UDPRoute + +That is, all implementations MUST use this flow for any cross namespace +references in the Gateway and any of the core xRoute types, except as noted +in the Exceptions section above. + +Other "ImplementationSpecific" objects and references MUST also use this flow +for cross-namespace references, except as noted in the Exceptions section above. + +## Potential Future API Group Change + +ReferenceGrant is starting to gain interest outside of Gateway API and SIG +Network use cases. It is possible that this resource may move to a more neutral +home. Users of the ReferenceGrant API may be required to transition to a +different API Group (instead of `gateway.networking.k8s.io`) at some point in +the future. diff --git a/site/content/en/v1.8/boilerplates/index.md b/site/content/en/v1.8/boilerplates/index.md new file mode 100644 index 0000000000..dda80adbcb --- /dev/null +++ b/site/content/en/v1.8/boilerplates/index.md @@ -0,0 +1,5 @@ +--- +headless: true +--- + +This file tells Hugo that the files in this directory tree shouldn't be rendered as normal pages on the site. diff --git a/site/content/en/v1.8/boilerplates/kind-cluster.md b/site/content/en/v1.8/boilerplates/kind-cluster.md new file mode 100644 index 0000000000..5eebc5eb4c --- /dev/null +++ b/site/content/en/v1.8/boilerplates/kind-cluster.md @@ -0,0 +1,6 @@ +Envoy Gateway is typically deployed in a Kubernetes cluster. +If you don’t have one yet, you can use `kind` to create a local cluster for testing purposes. + +{{% alert title="Developer Guide" color="primary" %}} +Refer to the [Developer Guide](/community/develop) to learn more. +{{% /alert %}} diff --git a/site/content/en/v1.8/boilerplates/o11y_prerequisites.md b/site/content/en/v1.8/boilerplates/o11y_prerequisites.md new file mode 100644 index 0000000000..5c2e1e3e09 --- /dev/null +++ b/site/content/en/v1.8/boilerplates/o11y_prerequisites.md @@ -0,0 +1,25 @@ +--- +--- + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +### Install Add-ons + +Envoy Gateway provides an add-ons Helm chart to simplify the installation of observability components. +The documentation for the add-ons chart can be found +[here](https://gateway.envoyproxy.io/docs/install/gateway-addons-helm-api/). + +Follow the instructions below to install the add-ons Helm chart. + +```shell +helm install eg-addons oci://docker.io/envoyproxy/gateway-addons-helm --version {{< helm-version >}} -n monitoring --create-namespace +``` + +By default, the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) is **disabled.** +To install add-ons with OpenTelemetry Collector enabled, use the following command. + +```shell +helm install eg-addons oci://docker.io/envoyproxy/gateway-addons-helm --version {{< helm-version >}} --set opentelemetry-collector.enabled=true -n monitoring --create-namespace +``` \ No newline at end of file diff --git a/site/content/en/v1.8/boilerplates/open-ports.md b/site/content/en/v1.8/boilerplates/open-ports.md new file mode 100644 index 0000000000..f193c2d2d2 --- /dev/null +++ b/site/content/en/v1.8/boilerplates/open-ports.md @@ -0,0 +1,22 @@ +## Open Ports + +These are the ports used by Envoy Gateway and the managed Envoy Proxy. + +### Envoy Gateway + +| Envoy Gateway | Address | Port | Configurable | +| :-------------------: | :-------: | :---: | :----------: | +| Xds EnvoyProxy Server | 0.0.0.0 | 18000 | No | +| Xds RateLimit Server | 0.0.0.0 | 18001 | No | +| Admin Server | 127.0.0.1 | 19000 | Yes | +| Metrics Server | 0.0.0.0 | 19001 | No | +| Health Check | 127.0.0.1 | 8081 | No | + +### EnvoyProxy + +| Envoy Proxy | Address | Port | +| :--------------: | :-------: | :---: | +| Admin Server | 127.0.0.1 | 19000 | +| Stats | 0.0.0.0 | 19001 | +| Shutdown Manager | 0.0.0.0 | 19002 | +| Readiness | 0.0.0.0 | 19003 | diff --git a/site/content/en/v1.8/boilerplates/prerequisites.md b/site/content/en/v1.8/boilerplates/prerequisites.md new file mode 100644 index 0000000000..3ce0681312 --- /dev/null +++ b/site/content/en/v1.8/boilerplates/prerequisites.md @@ -0,0 +1,24 @@ +--- +--- + +Follow the steps below to install Envoy Gateway and the example manifest. Before +proceeding, you should be able to query the example backend using HTTP. + +
+Expand for instructions + +1. Install the Gateway API CRDs and Envoy Gateway using Helm: + + ```shell + helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace + ``` + +2. Install the GatewayClass, Gateway, HTTPRoute and example app: + + ```shell + kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default + ``` + +3. Verify Connectivity: + {{< tabpane-include testing >}} +
diff --git a/site/content/en/v1.8/boilerplates/rollout-envoy-gateway.md b/site/content/en/v1.8/boilerplates/rollout-envoy-gateway.md new file mode 100644 index 0000000000..9072526868 --- /dev/null +++ b/site/content/en/v1.8/boilerplates/rollout-envoy-gateway.md @@ -0,0 +1,10 @@ +--- +--- + +> After updating the `ConfigMap`, you will need to wait the configuration kicks in.
+> You can **force** the configuration to be reloaded by restarting the `envoy-gateway` deployment. +> +> ```shell +> kubectl rollout restart deployment envoy-gateway -n envoy-gateway-system +> ``` +> \ No newline at end of file diff --git a/site/content/en/v1.8/boilerplates/testing.md b/site/content/en/v1.8/boilerplates/testing.md new file mode 100644 index 0000000000..e55f0270a1 --- /dev/null +++ b/site/content/en/v1.8/boilerplates/testing.md @@ -0,0 +1,52 @@ +--- + +--- + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Curl the example app through Envoy proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +The above command should succeed with status code 200. + + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Get the deployment of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 & +``` + +Curl the example app through Envoy proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://localhost:8888/get +``` + +The above command should succeed with status code 200. + +{{% /tab %}} +{{< /tabpane >}} diff --git a/site/content/en/v1.8/concepts/_index.md b/site/content/en/v1.8/concepts/_index.md new file mode 100644 index 0000000000..54a1711fa4 --- /dev/null +++ b/site/content/en/v1.8/concepts/_index.md @@ -0,0 +1,90 @@ +--- +title: "Concepts" +weight: 1 +description: Learn about key concepts when working with Envoy Gateway +--- + +## Overview + +**Envoy Gateway** is a Kubernetes-native [API Gateway](api-gateways.md) and reverse proxy control plane. It simplifies deploying and operating [Envoy Proxy](proxy.md) as a data plane by using the standard [Gateway API](gateway-api.md) and its own extensible APIs. + +By combining Envoy's performance and flexibility with Kubernetes-native configuration, Envoy Gateway helps platform teams expose and manage secure, observable, and scalable APIs with minimal operational overhead. + +## Why Use Envoy Gateway? + +Traditionally, configuring Envoy Proxy required deep networking expertise and writing complex configuration files. Envoy Gateway removes that barrier by: + +- Integrating tightly with Kubernetes through the Gateway API +- Providing custom CRDs for advanced traffic policies +- Automatically translating Kubernetes resources into Envoy config +- Managing the lifecycle of Envoy Proxy instances + +Envoy Gateway is designed to be **simple for app developers**, **powerful for platform engineers**, and **production-ready for large-scale deployments**. + +## Structure + +The different layers of Envoy Gateway are the following: + +| Layer | Description | +|----------------|-------------| +| **User Configuration** | Users define routing, security, and traffic policies using standard Kubernetes Gateway API resources, optionally extended with Envoy Gateway CRDs.| +| **Envoy Gateway Controller** | A control plane component that watches Gateway API and Envoy Gateway-specific resources, translates them, and produces configuration for Envoy Proxy.| +| **Envoy Proxy(Data Plane)** | A high-performance proxy that receives and handles live traffic according to the configuration generated by Envoy Gateway.| + +Together, these layers create a system that's: +- Easy to configure +- Powerful enough for complex needs +- Standardized and familiar +- Ready for the future + +## Resources + +![](/img/envoy-gateway-resources-overview.png) + +There are several resources that play a part in enabling you to meet your Kubernetes ingress traffic handling needs. This page provides a brief overview of the resources you’ll be working with. + +### Kubernetes Gateway API Resources +- **GatewayClass:** Defines a class of Gateways with common configuration. +- **Gateway:** Specifies how traffic can enter the cluster. +- **Routes:** **HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute:** Define routing rules for different types of traffic. + +### Envoy Gateway (EG) API Resources +- **EnvoyProxy:** Represents the deployment and configuration of the Envoy proxy within a Kubernetes cluster, managing its lifecycle and settings. +- **EnvoyPatchPolicy, ClientTrafficPolicy, SecurityPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, BackendTLSPolicy:** Additional policies and configurations specific to Envoy Gateway. +- **Backend:** A resource that makes routing to cluster-external backends easier and makes access to external processes via Unix Domain Sockets possible. + +| Resource | API | Required | Purpose | References | Description | +| ----------------------------------------------------------------------- | ----------- | -------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [GatewayClass][1] | Gateway API | Yes | Gateway Config | Core | Defines a class of Gateways with common configuration. | +| [Gateway][2] | Gateway API | Yes | Gateway Config | GatewayClass | Specifies how traffic can enter the cluster. | +| [HTTPRoute][3] [GRPCRoute][4] [TLSRoute][5] [TCPRoute][6] [UDPRoute][7] | Gateway API | Yes | Routing | Gateway | Define routing rules for different types of traffic. **Note:**_For simplicity these resources are referenced collectively as Route in the References column_ | +| [Backend][8] | EG API | No | Routing | N/A | Used for routing to cluster-external backends using FQDN or IP. Can also be used when you want to extend Envoy with external processes accessed via Unix Domain Sockets. | +| [ClientTrafficPolicy][9] | EG API | No | Traffic Handling | Gateway | Specifies policies for handling client traffic, including rate limiting, retries, and other client-specific configurations. | +| [BackendTrafficPolicy][10] | EG API | No | Traffic Handling | Gateway, Route | Specifies policies for traffic directed towards backend services, including load balancing, health checks, and failover strategies. **Note:**_Most specific configuration wins_ | +| [SecurityPolicy][11] | EG API | No | Security | Gateway, Route | Defines security-related policies such as authentication, authorization, and encryption settings for traffic handled by Envoy Gateway. **Note:**_Most specific configuration wins_ | +| [BackendTLSPolicy][12] | Gateway API | No | Security | Service | Defines TLS settings for backend connections, including certificate management, TLS version settings, and other security configurations. This policy is applied to Kubernetes Services. | +| [EnvoyProxy][13] | EG API | No | Customize & Extend | GatewayClass, Gateway | The EnvoyProxy resource represents the deployment and configuration of the Envoy proxy itself within a Kubernetes cluster, managing its lifecycle and settings. **Note:**_Most specific configuration wins_ | +| [EnvoyPatchPolicy][14] | EG API | No | Customize & Extend | GatewayClass, Gateway | This policy defines custom patches to be applied to Envoy Gateway resources, allowing users to tailor the configuration to their specific needs. **Note:**_Most specific configuration wins_ | +| [EnvoyExtensionPolicy][15] | EG API | No | Customize & Extend | Gateway, Route, Backend| Allows for the configuration of Envoy proxy extensions, enabling custom behavior and functionality. **Note:**_Most specific configuration wins_ | +| [HTTPRouteFilter][16] | EG API | No | Customize & Extend | HTTPRoute | Allows for the additional request/response processing. | + + +## Next Steps +For a deeper understanding of Envoy Gateway’s building blocks, you may also wish to explore these conceptual guides: + +[1]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[2]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[3]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[4]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[5]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#tlsroute +[6]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#tcproute +[7]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#udproute +[8]: ../tasks/traffic/backend +[9]: ../api/extension_types#clienttrafficpolicy +[10]: ../api/extension_types#backendtrafficpolicy +[11]: ../api/extension_types#securitypolicy +[12]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[13]: ../api/extension_types#envoyproxy +[14]: ../api/extension_types#envoypatchpolicy +[15]: ../api/extension_types#envoyextensionpolicy +[16]: ../api/extension_types#httproutefilter diff --git a/site/content/en/v1.8/concepts/api-gateways.md b/site/content/en/v1.8/concepts/api-gateways.md new file mode 100644 index 0000000000..35e240e20e --- /dev/null +++ b/site/content/en/v1.8/concepts/api-gateways.md @@ -0,0 +1,27 @@ +--- +title: "API Gateways" +weight: 3 +--- + +## Overview +An API gateway is a centralized entry point for managing, securing, and routing requests to backend services. It handles cross-cutting concerns, like authentication, rate limiting, and protocol translation, so individual services don’t have to. Decoupling clients from internal systems simplifies scaling, enforces consistency, and reduces redundancy. + +## Use Cases + +Use an API Gateway to: +- Avoid duplicating logic across microservices. +- Create a central point of control for access, monitoring, and traffic rules. +- Expose internal services to the public internet. +- Provide protocol support for HTTP, gRPC, or TLS. +- Enforce policies and see traffic metrics at the edge. + +## API Gateways in relation to Envoy Gateway + +Under the hood, Envoy Proxy is a powerful, production-grade proxy that supports many of the capabilities you'd expect from an API Gateway, like traffic routing, retries, TLS termination, observability, and more. However, configuring Envoy directly can be complex and verbose. + +Envoy Gateway makes configuring Envoy Proxy simple by implementing and extending the Kubernetes-native Gateway API. You define high-level traffic rules using resources like Gateway, HTTPRoute, or TLSRoute, and Envoy Gateway automatically translates them into detailed Envoy Proxy configurations. + +## Related Resources + +- [Getting Started with Envoy Gateway](../tasks/quickstart.md) +- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) diff --git a/site/content/en/v1.8/concepts/gateway-api.md b/site/content/en/v1.8/concepts/gateway-api.md new file mode 100644 index 0000000000..1ee514ff5f --- /dev/null +++ b/site/content/en/v1.8/concepts/gateway-api.md @@ -0,0 +1,35 @@ +--- +title: "The Gateway API" +weight: 1 +--- + +## Before You Begin +You may want to be familiar with: +- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) +- [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) + +## Overview +The Gateway API is a Kubernetes API designed to provide a consistent, expressive, and extensible method for managing network traffic into and within a Kubernetes cluster, compared to the legacy Ingress API. It introduces core resources such as `GatewayClass` and `Gateway` and various route types like `HTTPRoute` and `TLSRoute`, which allow you to define how traffic is routed, secured, and exposed. + +The Gateway API succeeds the Ingress API, which many Kubernetes users may already be familiar with. The Ingress API provided a mechanism for exposing HTTP(S) services to external traffic. The lack of advanced features like regex path matching led to custom annotations to compensate for these deficiencies. This non-standard approach led to fragmentation across Ingress Controllers, challenging portability. + +## Use Cases +Use The Gateway API to: +- Define how external traffic enters and is routed within your cluster +- Configure HTTP(S), TLS, and TCP traffic routing in a standardized, Kubernetes-native way +- Apply host-based, path-based, and header-based routing rules using HTTPRoute +- Terminate TLS at the edge using Gateway TLS configuration +- Separate responsibilities between infrastructure and application teams through role-oriented resource design +- Improve portability and consistency across different gateway implementations + +## The Gateway API in Envoy Gateway +In essence, the Gateway API provides a standard interface. Envoy Gateway adds production-grade capabilities to that interface, bridging the gap between simplicity and power while keeping everything Kubernetes-native. + +One of the Gateway API's key strengths is that implementers can extend it. While providing a foundation for standard routing and traffic control needs, it enables implementations to introduce custom resources that address specific use cases. + +Envoy Gateway leverages this model by introducing a suite of Gateway API extensions—implemented as Kubernetes Custom Resource Definitions (CRDs)—to expose powerful features from Envoy Proxy. These features include enhanced support for rate limiting, authentication, traffic shaping, and more. By utilizing these extensions, users can access production-grade functionality in a Kubernetes-native and declarative manner, without needing to write a low-level Envoy configuration. + +## Related Resources +- [Getting Started with Envoy Gateway](../tasks/quickstart.md) +- [Envoy Gateway API Reference](../api/extension_types) +- [Extensibility Tasks](../tasks/extensibility/_index.md) diff --git a/site/content/en/v1.8/concepts/gateway_api_extensions/_index.md b/site/content/en/v1.8/concepts/gateway_api_extensions/_index.md new file mode 100644 index 0000000000..dd17ded0a4 --- /dev/null +++ b/site/content/en/v1.8/concepts/gateway_api_extensions/_index.md @@ -0,0 +1,46 @@ +--- +title: "Gateway API Extensions" +weight: 2 +--- +## Before You Begin +- [The Gateway API](https://gateway-api.sigs.k8s.io/) + +## Overview +Gateway API Extensions let you configure extra features that aren't part of the standard Kubernetes Gateway API. These extensions are built by the teams that create and maintain Gateway API implementations. +The Gateway API was designed to be extensible, safe, and reliable. In the old Ingress API, people had to use custom annotations to add new features, but those weren't type-safe, making it hard to check if their configuration was correct. +With Gateway API Extensions, implementers provide type-safe Custom Resource Definitions (CRDs). This means every configuration you write has a clear structure and strict rules, making it easier to catch mistakes early and be confident your setup is valid. +## Use Cases + +Here are some examples of what kind of features extensions include: + +1. **Advanced Traffic Management:** + Implementing sophisticated load balancing algorithms, circuit breaking, or retries not defined in the core API +2. **Enhanced Security Controls:** + Adding implementation-specific TLS configurations, authentication mechanisms, or access control rules +3. **Observability Integration:** + Connecting Gateway resources to monitoring systems, logging pipelines, or tracing frameworks +4. **Custom Protocol Support:** + Extending beyond HTTP/TCP/UDP with specialized protocol handling +5. **Rate Limiting and Compression:** + Implementing traffic policing specific to the implementation's capabilities + +## Gateway API Extensions in Envoy Gateway + +The Envoy Gateway API introduces a set of Gateway API extensions that enable users to leverage the power of the Envoy proxy. Envoy Gateway uses a policy attachment model, where custom policies are applied to standard Gateway API resources (like HTTPRoute or Gateway) without modifying the core API. This approach provides separation of concerns and makes it easier to manage configurations across teams. + +{{% alert title="Current Extensions" color="info" %}} +Currently supported extensions include +[`Backend`](../../api/extension_types#backend), +[`BackendTrafficPolicy`](../../api/extension_types#backendtrafficpolicy), +[`ClientTrafficPolicy`](../../api/extension_types#clienttrafficpolicy), +[`EnvoyExtensionPolicy`](../../api/extension_types#envoyextensionpolicy), +[`EnvoyGateway`](../../api/extension_types#envoygateway), +[`EnvoyPatchPolicy`](../../api/extension_types#envoypatchpolicy), +[`EnvoyProxy`](../../api/extension_types#envoyproxy), +[`HTTPRouteFilter`](../../api/extension_types#httproutefilter), and +[`SecurityPolicy`](../../api/extension_types#securitypolicy), +{{% /alert %}} + +These extensions are processed through Envoy Gateway's control plane, translating them into xDS configurations applied to Envoy Proxy instances. This layered architecture allows for consistent, scalable, and production-grade traffic control without needing to manage raw Envoy configuration directly. + +## Related Resources diff --git a/site/content/en/v1.8/concepts/gateway_api_extensions/backend-traffic-policy.md b/site/content/en/v1.8/concepts/gateway_api_extensions/backend-traffic-policy.md new file mode 100644 index 0000000000..daa6fa1abf --- /dev/null +++ b/site/content/en/v1.8/concepts/gateway_api_extensions/backend-traffic-policy.md @@ -0,0 +1,233 @@ +--- +title: "BackendTrafficPolicy" +--- +## Before you Begin +- [Gateway API Extensions](_index.md) + +## Overview +`BackendTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway communicates with your backend services. It can configure connection behavior, resilience mechanisms, and performance optimizations without requiring changes to your applications. + +Think of it as a traffic controller between your gateway and backend services. It can detect problems, prevent failures from spreading, and optimize request handling to improve system stability. + +## Use Cases + +`BackendTrafficPolicy` is particularly useful in scenarios where you need to: + +1. **Protect your services:** + Limit connections and reject excess traffic when necessary + +2. **Build resilient systems:** + Detect failing services and redirect traffic + +3. **Improve performance:** + Optimize how requests are distributed and responses are handled + +4. **Test system behavior:** + Inject faults and validate your recovery mechanisms + +## BackendTrafficPolicy in Envoy Gateway + +`BackendTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages traffic to your backend services. + +### Targets + +BackendTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms: + +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) + +```yaml +# Direct reference targeting +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: direct-policy +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 50 + +--- +# Label-based targeting +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: selector-policy +spec: + targetSelectors: + - kind: HTTPRoute + matchLabels: + app: payment-service + rateLimit: + local: + requests: 10 + unit: Second +``` + +The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including +`Gateway`, `HTTPRoute`, `GRPCRoute`, `TCPRoute`, `UDPRoute`, `TLSRoute`. + +**Important**: A BackendTrafficPolicy can only target resources in the same namespace as the policy itself. + +### Precedence + +When multiple BackendTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type and section-level specificity: + +1. **Route rule-level policies** (HTTPRoute/GRPCRoute with `sectionName` targeting specific rules) - Highest precedence +2. **Route-level policies** (HTTPRoute, GRPCRoute without `sectionName`) - High precedence +3. **Listener-level policies** (Gateway with `sectionName` targeting specific listeners) - Medium precedence +4. **Gateway-level policies** (Gateway without `sectionName`) - Lowest precedence + +```yaml +# Gateway-level policy (lower precedence) - Applies to all routes in the gateway +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: gateway-policy +spec: + targetRefs: + - kind: Gateway + name: my-gateway + circuitBreaker: + maxConnections: 100 + +--- +# Route-level policy (higher precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: route-policy +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 50 +``` + +In this example, the HTTPRoute `my-route` would use `maxConnections: 50` from the route-level policy, overriding the gateway-level setting of 100. + +#### Multiple Policies at the Same Level + +When multiple BackendTrafficPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 30 + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 40 +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use `maxConnections: 30`. + +When the `mergeType` field is unset, no merging occurs and only the most specific configuration takes effect. However, policies can be configured to merge with parent policies using the `mergeType` field (see [Policy Merging](#policy-merging) section below). + +## Policy Merging + +BackendTrafficPolicy supports merging configurations using the `mergeType` field, which allows route-level or route rule-level policies to combine with gateway-level or listener-level policies rather than completely overriding them. This enables layered policy strategies where platform teams can set baseline configurations at the Gateway level, while application teams can add specific policies for their routes. + +When merging occurs, route-level policies will merge with either a gateway-level or listener-level policy, but not both. If both gateway and listener policies exist, the listener-level policy takes precedence. + +### Merge Types + +- **StrategicMerge**: Uses Kubernetes strategic merge patch semantics, providing intelligent merging for complex data structures including arrays +- **JSONMerge**: Uses RFC 7396 JSON Merge Patch semantics, with simple replacement strategy where arrays are completely replaced + +### Example Usage + +Here's an example demonstrating policy merging for rate limiting: + +```yaml +# Platform team: Gateway-level policy with global abuse prevention +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: global-backendtrafficpolicy +spec: + rateLimit: + global: + rules: + - clientSelectors: + - sourceCIDR: + type: Distinct + value: 0.0.0.0/0 + limit: + requests: 100 + unit: Second + shared: true + targetRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: eg + +--- +# Application team: Route-level policy with specific limits +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: route-backendtrafficpolicy +spec: + mergeType: StrategicMerge # Enables merging with gateway policy + rateLimit: + global: + rules: + - clientSelectors: + - sourceCIDR: + type: Distinct + value: 0.0.0.0/0 + limit: + requests: 5 + unit: Minute + shared: false + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: signup-service-httproute +``` + +In this example, the route-level policy merges with the gateway-level policy, resulting in both rate limits being enforced: the global 100 requests/second abuse limit and the route-specific 5 requests/minute limit. + +### Key Constraints + +- The `mergeType` field can only be set on policies targeting child resources (like HTTPRoute), not parent resources (like Gateway) +- When `mergeType` is unset, no merging occurs - only the most specific policy takes effect +- The merged configuration combines both policies, enabling layered protection strategies + +## Related Resources + +- [Circuit Breakers](../../tasks/traffic/circuit-breaker.md) +- [Failover](../../tasks/traffic/failover) +- [Fault Injection](../../tasks/traffic/fault-injection) +- [Global Rate Limit](../../tasks/traffic/global-rate-limit) +- [Local Rate Limit](../../tasks/traffic/local-rate-limit) +- [Load Balancing](../../tasks/traffic/load-balancing) +- [Response Compression](../../tasks/traffic/response-compression) +- [Response Override](../../tasks/traffic/response-override) +- [BackendTrafficPolicy API Reference](../../api/extension_types#backendtrafficpolicy) diff --git a/site/content/en/v1.8/concepts/gateway_api_extensions/client-traffic-policy.md b/site/content/en/v1.8/concepts/gateway_api_extensions/client-traffic-policy.md new file mode 100644 index 0000000000..563e1e68c0 --- /dev/null +++ b/site/content/en/v1.8/concepts/gateway_api_extensions/client-traffic-policy.md @@ -0,0 +1,144 @@ +--- +title: "ClientTrafficPolicy" +--- +## Before you Begin + +- [Gateway API Extensions](_index.md) + +## Overview + +`ClientTrafficPolicy` is an extension to the Kubernetes Gateway API that allows system administrators to configure how the Envoy Proxy server behaves with downstream clients. It is a policy attachment resource that can be applied to Gateway resources and holds settings for configuring the behavior of the connection between the downstream client and Envoy Proxy listener. + +Think of `ClientTrafficPolicy` as a set of rules for your Gateway's entry points, it lets you configure specific behaviors for each listener in your Gateway, with more specific rules taking precedence over general ones. + +## Use Cases + +`ClientTrafficPolicy` is particularly useful in scenarios where you need to: + +1. **Enforce TLS Security** + Configure TLS termination, mutual TLS (mTLS), and certificate validation at the edge. + +2. **Manage Client Connections** + Control TCP keepalive behavior and connection timeouts for optimal resource usage. + +3. **Handle Client Identity** + Configure trusted proxy chains to correctly resolve client IPs for logging and access control. + +4. **Normalize Request Paths** + Sanitize incoming request paths to ensure compatibility with backend routing rules. + +5. **Tune HTTP Protocols** + Configure HTTP/1, HTTP/2, and HTTP/3 settings for compatibility and performance. + +6. **Monitor Listener Health** + Set up health checks for integration with load balancers and failover mechanisms. + +## ClientTrafficPolicy in Envoy Gateway + +`ClientTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages incoming client traffic. + +### Targets + +ClientTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms: + +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific Gateway resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match Gateway resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) + +The policy applies to all Gateway resources that match either targeting method. + +**Important**: A ClientTrafficPolicy can only target Gateway resources in the same namespace as the policy itself. + +### Precedence + +When multiple ClientTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using section-level specificity and creation-time priority: + +1. **Section-specific policies** (targeting specific listeners via `sectionName`) - Highest precedence +2. **Gateway-wide policies** (targeting entire Gateway) - Lower precedence + +#### Multiple Policies at the Same Level + +When multiple ClientTrafficPolicies target the same resource at the same specificity level (e.g., multiple policies targeting the same Gateway listener section), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https-listener + timeout: + http: + idleTimeout: 30s + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https-listener + timeout: + http: + idleTimeout: 40s +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the listener would use `idleTimeout: 30s`. + +For example, consider these policies with different specificity levels targeting the same Gateway: + +```yaml +# Policy A: Targets a specific listener in the gateway +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: listener-specific-policy +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https-listener # Targets specific listener + timeout: + http: + idleTimeout: 30s + +--- +# Policy B: Targets the entire gateway +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: gateway-wide-policy +spec: + targetRefs: + - kind: Gateway + name: my-gateway # Targets all listeners + timeout: + http: + idleTimeout: 60s +``` + +In this case: + +- Policy A will be applied/attached to the specific Listener defined in the `targetRef.SectionName` +- Policy B will be applied to the remaining Listeners within the Gateway. Policy B will have an additional status condition Overridden=True. + +## Related Resources + +- [Connection Limit](../../tasks/traffic/connection-limit.md) +- [HTTP Request Headers](../../tasks/traffic/http-request-headers) +- [HTTP Response Headers](../../tasks/traffic/http-response-headers) +- [HTTP/3](../../tasks/traffic/http3) +- [Mutual TLS: External Clients to the Gateway](../../tasks/security/mutual-tls/) +- [ClientTrafficPolicy API Reference](../../api/extension_types#clienttrafficpolicy) diff --git a/site/content/en/v1.8/concepts/gateway_api_extensions/security-policy.md b/site/content/en/v1.8/concepts/gateway_api_extensions/security-policy.md new file mode 100644 index 0000000000..d1454f2f03 --- /dev/null +++ b/site/content/en/v1.8/concepts/gateway_api_extensions/security-policy.md @@ -0,0 +1,283 @@ +--- +title: "SecurityPolicy" +--- + +## Before you Begin +- [Gateway API Extensions](_index.md) + +## Overview + +`SecurityPolicy` is an Envoy Gateway extension to the Kubernetes Gateway API that allows you to define authentication and authorization requirements for traffic entering your gateway. It acts as a security layer that only properly authenticated and authorized requests are allowed through your backend services. + +`SecurityPolicy` is designed for you to enforce access controls through configuration at the edge of your infrastructure in a declarative, Kubernetes-native way, without needing to configure complex proxy rules manually. + +## Use Cases + +1. **Authentication Methods:** + - Authenticate client apps using mTLS, JWTs, API keys, or Basic Auth + - Authenticate users with OIDC Provider integration + +2. **Authorization Controls:** + - Define and enforce authorization rules based on user roles and permissions + - Integrate with external authorization services for real-time policy decisions + - JWT Token Authorization Checks + +3. **Cross-Origin Security:** + - Configure CORS to allow or restrict cross-origin requests for APIs + +## SecurityPolicy in Envoy Gateway + +`SecurityPolicy` is implemented as a Kubernetes Custom Resource Definition (CRD) and follows the policy attachment model. + +### Targets + +SecurityPolicy can be attached to Gateway API resources using two targeting mechanisms: + +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) + +The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including `Gateway`, `HTTPRoute`, `GRPCRoute`, and `TCPRoute`. + +Note: TCPRoute support is limited to authorization using client IP allow/deny lists (IP-based authorization). Other SecurityPolicy features such as JWT, API Key, Basic Auth, or OIDC are not applicable to TCPRoute targets. + +**Important**: A SecurityPolicy can only target resources in the same namespace as the policy itself. + +### Precedence + +When multiple SecurityPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type and section-level specificity: + +1. **Route rule-level policies** (HTTPRoute, GRPCRoute, or TCPRoute with `sectionName` targeting specific rules) - Highest precedence +2. **Route-level policies** (HTTPRoute, GRPCRoute, or TCPRoute without `sectionName`) - High precedence +3. **Listener-level policies** (Gateway with `sectionName` targeting specific listeners) - Medium precedence +4. **Gateway-level policies** (Gateway without `sectionName`) - Lowest precedence + +#### Multiple Policies at the Same Level + +When multiple SecurityPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + cors: + allowOrigins: + - exact: https://example.com + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + cors: + allowOrigins: + - exact: https://different.com +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use the CORS setting from `alpha-policy`. + +```yaml +# HTTPRoute with named rules +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: my-route +spec: + rules: + - name: rule-1 # Named rule for sectionName targeting + matches: + - path: + value: "/api" + backendRefs: + - name: api-service + port: 80 + +--- +# Route rule-level policy (highest precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: rule-policy +spec: + targetRef: + kind: HTTPRoute + name: my-route + sectionName: rule-1 # Targets specific named rule + cors: + allowOrigins: + - exact: https://rule.example.com + +--- +# Route-level policy (high precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: route-policy +spec: + targetRef: + kind: HTTPRoute + name: my-route # No sectionName = entire route + cors: + allowOrigins: + - exact: https://route.example.com + +--- +# Listener-level policy (medium precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: listener-policy +spec: + targetRef: + kind: Gateway + name: my-gateway + sectionName: https-listener # Targets specific listener + cors: + allowOrigins: + - exact: https://listener.example.com + +--- +# Gateway-level policy (lowest precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: gateway-policy +spec: + targetRef: + kind: Gateway + name: my-gateway # No sectionName = entire gateway + cors: + allowOrigins: + - exact: https://gateway.example.com +``` + +In this example, the specific rule `rule-1` within HTTPRoute `my-route` would use the CORS settings from the route rule-level policy (`https://rule.example.com`), overriding the route-level, listener-level, and gateway-level settings. + +For section-specific targeting, consider these policies with different hierarchy levels targeting the same Gateway: + +```yaml +# Policy A: Applies to a specific listener +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: listener-policy + namespace: default +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https # Applies only to "https" listener + cors: + allowOrigins: + - exact: https://example.com +--- +# Policy B: Applies to the entire gateway +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: gateway-policy + namespace: default +spec: + targetRefs: + - kind: Gateway + name: my-gateway # Applies to all listeners + cors: + allowOrigins: + - exact: https://default.com +``` + +In the example, policy A affects only the HTTPS listener, while policy B applies to the rest of the listeners in the gateway. Since Policy A is more specific, the system will show Overridden=True for Policy B on the https listener. + +When the `mergeType` field is unset, no merging occurs and only the most specific configuration takes effect. However, policies can be configured to merge with parent policies using the `mergeType` field (see [Policy Merging](#policy-merging) section below). + +## Policy Merging + +SecurityPolicy supports merging configurations using the `mergeType` field, which allows route-level or route rule-level policies to combine with gateway-level or listener-level policies rather than completely overriding them. This enables layered security strategies where platform teams can set baseline security configurations at the Gateway level, while application teams can add specific security policies for their routes. + +When merging occurs, route-level policies will merge with either a gateway-level or listener-level policy, but not both. If both gateway and listener policies exist, the listener-level policy takes precedence. + +### Merge Types + +- **StrategicMerge**: Uses Kubernetes strategic merge patch semantics, providing intelligent merging for complex data structures including arrays +- **JSONMerge**: Uses RFC 7396 JSON Merge Patch semantics, with simple replacement strategy where arrays are completely replaced + +### Example Usage + +Here's an example demonstrating policy merging for combining authentication and CORS policies: + +```yaml +# Platform team: Gateway-level policy with baseline authentication +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: gateway-security + namespace: default +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: my-gateway + sectionName: https-listener + basicAuth: + users: + name: basic-auth-secret + +--- +# Application team: Route-level policy with CORS configuration +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: route-security + namespace: default +spec: + mergeType: StrategicMerge # Enables merging with gateway policy + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: my-route + cors: + allowOrigins: + - exact: https://example.com + allowMethods: + - GET + - POST + allowHeaders: + - x-header-1 +``` + +In this example, the route-level policy merges with the gateway-level policy, resulting in both security controls being enforced: the baseline BasicAuth (from Gateway) and the route-specific CORS policy (from Route). This allows platform teams to enforce organization-wide authentication requirements while enabling application teams to configure route-specific cross-origin policies. + +### Key Constraints + +- The `mergeType` field can only be set on policies targeting child resources (like HTTPRoute), not parent resources (like Gateway) +- When `mergeType` is unset, no merging occurs - only the most specific policy takes effect +- The merged configuration combines both policies, enabling layered security strategies +- When the same security feature is configured in both parent and child policies (e.g., both define CORS), the child policy's configuration takes precedence for that specific feature +- Secret references and backend references are resolved against the namespace of the **policy that originally configured the field** (either route or parent). For example, if a Gateway policy defines BasicAuth, its secret is looked up in the Gateway policy's namespace even after merging. + +## Related Resources +- [API Key Authentication](../../tasks/security/apikey-auth.md) +- [Basic Authentication](../../tasks/security/basic-auth.md) +- [CORS](../../tasks/security/cors.md) +- [External Authorization](../../tasks/security/ext-auth.md) +- [GeoIP Authorization](../../tasks/security/geoip-authorization.md) +- [IP Allowlist/Denylist](../../tasks/security/restrict-ip-access.md) +- [JWT Authentication](../../tasks/security/jwt-authentication.md) +- [JWT Claim Based Authorization](../../tasks/security/jwt-claim-authorization.md) +- [OIDC Authorization](../../tasks/security/oidc.md) +- [SecurityPolicy API Reference](../../api/extension_types#securitypolicy) diff --git a/site/content/en/v1.8/concepts/load-balancing.md b/site/content/en/v1.8/concepts/load-balancing.md new file mode 100644 index 0000000000..c02b1290cb --- /dev/null +++ b/site/content/en/v1.8/concepts/load-balancing.md @@ -0,0 +1,118 @@ +--- +title: "Load Balancing" +--- + +## Overview + +Load balancing distributes incoming requests across multiple backend services to improve availability, responsiveness, and scalability. Instead of directing all traffic to a single backend, which can cause slowdowns or outages, load balancing spreads the load across multiple instances, helping your applications stay fast and reliable under pressure. + +## Use Cases + +Use load balancing to: + +- Handle high traffic by distributing it across multiple service instances +- Keep services available even if one or more backends go down +- Improve response time by routing to less busy or closer backends + +## Load Balancing in Envoy Gateway + +Envoy Gateway supports several load balancing strategies that determine how traffic is distributed across backend services. These strategies are configured using the `BackendTrafficPolicy` resource and can be applied to `Gateway`, `HTTPRoute`, or `GRPCRoute` resources either by directly referencing them using the targetRefs field or by dynamically selecting them using the targetSelectors field, which matches resources based on Kubernetes labels. + +**Supported load balancing types:** +- **Round Robin** – Sends requests sequentially to all available backends +- **Random** – Chooses a backend at random to balance load +- **Least Request** – Sends the request to the backend with the fewest active requests (this is the default) +- **Consistent Hash** – Routes requests based on a hash (e.g., client IP or header), which helps keep repeat requests going to the same backend (useful for session affinity) +- **Backend Utilization** – Uses client-observed load reports (e.g., Open Resource Cost Aggregation (ORCA) metrics) to dynamically weight endpoints; if no metrics are available, it behaves similar to even-weight round-robin. + +If no load balancing strategy is specified, Envoy Gateway uses **Least Request** by default. + +## Example: Round Robin Load Balancing + +This example shows how to apply the Round Robin strategy using a `BackendTrafficPolicy` that targets a specific `HTTPRoute`: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: round-robin-policy + namespace: default +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: round-robin-route + loadBalancer: + type: RoundRobin +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: round-robin-route + namespace: default +spec: + parentRefs: + - name: eg + hostnames: + - "www.example.com" + rules: + - matches: + - path: + type: PathPrefix + value: /round + backendRefs: + - name: backend + port: 3000 +``` +In this setup, traffic matching /round is distributed evenly across all available backend service instances. For example, if there are four replicas of the backend service, each one should receive roughly 25% of the requests. + +## Backend Utilization (ORCA) + +Backend Utilization load balancing uses Open Resource Cost Application (ORCA) metrics to make load balancing decisions. These metrics are reported by the backend service in response headers or trailers. + +### ORCA Load Metrics + +The backend service (or its sidecar) reports load metrics in response headers or trailers (for streaming requests). ORCA supports multiple formats for these metrics: + +- **JSON**: Use the `endpoint-load-metrics` header with a JSON object. + ```http + endpoint-load-metrics: JSON {"cpu_utilization": 0.3, "mem_utilization": 0.8} + ``` +- **TEXT**: Use the `endpoint-load-metrics` header with comma-separated key-value pairs. + ```http + endpoint-load-metrics: TEXT cpu=0.3,mem=0.8,foo_bytes=123 + ``` +- **Binary Proto**: Use the `endpoint-load-metrics-bin` header with a base64-encoded serialized `OrcaLoadReport` proto. + ```http + endpoint-load-metrics-bin: Cg4KCHNvbWUta2V5Eg0AAAAAAADwPw== + ``` + +For more details, see: +- [ORCA Load Report Proto](https://www.envoyproxy.io/docs/envoy/latest/xds/data/orca/v3/orca_load_report.proto) +- [ORCA Design Document](https://docs.google.com/document/d/1NSnK3346BkBo1JUU3I9I5NYYnaJZQPt8_Z_XCBCI3uA) + +### Automatic Header Removal + +By default, Envoy forwards the ORCA response headers/trailers from the upstream cluster to the downstream client. This means that if the downstream client is also configured to use client-side weighted round-robin, it will load balance against Envoy based on upstream weights. + +To prevent this, Envoy Gateway automatically removes these headers by default when `BackendUtilization` is enabled. You can change this behavior using the `keepResponseHeaders` field in `backendUtilization`. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: backend-utilization-policy +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: backend-utilization-route + loadBalancer: + type: BackendUtilization + backendUtilization: + keepResponseHeaders: true # Keep headers and forward them to the client +``` + +## Related Resources +- [BackendTrafficPolicy](gateway_api_extensions/backend-traffic-policy.md) +- [Task: Load Balancing](../tasks/traffic/load-balancing.md) diff --git a/site/content/en/v1.8/concepts/proxy.md b/site/content/en/v1.8/concepts/proxy.md new file mode 100644 index 0000000000..5e4dcb5b92 --- /dev/null +++ b/site/content/en/v1.8/concepts/proxy.md @@ -0,0 +1,33 @@ +--- +title: "Proxy" +weight: 4 +--- + +## Overview +**A proxy server is an intermediary between a client (like a web browser) and another server (like an API server).** When the client makes a request, the proxy forwards it to the destination server, receives the response, and then sends it back to the client. + +Proxies are used to enhance security, manage traffic, anonymize user activity, or optimize performance through caching and load balancing features. In cloud environments, they often handle critical tasks such as request routing, TLS termination, authentication, and traffic shaping. + +## Use Cases + +**Use Envoy Proxy to:** +- Manage internal or external traffic with a powerful L3/L4/L7 proxy +- Control HTTP, gRPC, or TLS routing with fine-grained match and rewrite rules +- Gain full observability via built-in metrics, tracing, and logging +- Implement intelligent load balancing and resilient failover strategies +- Integrate seamlessly with service meshes, API gateways, and other control planes + +## Proxy in Envoy Gateway +Envoy Gateway is a system made up of two main parts: +- A _data plane_, which handles the actual network traffic +- A _control plane_, which manages and configures the _data plane_ + +Envoy Gateway uses the Envoy Proxy, which was originally developed at Lyft. This proxy is the foundation of the Envoy project, of which Envoy Gateway is a part, and is now a graduated project within the Cloud Native Computing Foundation (CNCF). + +Envoy Proxy is a high-performance, open-source proxy designed for cloud-native applications. Envoy supports use cases for edge and service proxies, routing traffic at the system’s boundary or between internal services. + +The control plane uses the Kubernetes Gateway API to understand your settings and then translates them into the format Envoy Proxy needs (called _xDS configuration_). It also runs and updates the Envoy Proxy instances inside your Kubernetes cluster. + +## Related Resources +- [Getting Started with Envoy Gateway](../tasks/quickstart.md) +- [Envoy Proxy](https://www.envoyproxy.io/) diff --git a/site/content/en/v1.8/concepts/rate-limiting.md b/site/content/en/v1.8/concepts/rate-limiting.md new file mode 100644 index 0000000000..2b308f9815 --- /dev/null +++ b/site/content/en/v1.8/concepts/rate-limiting.md @@ -0,0 +1,156 @@ +--- +title: "Rate Limiting" +--- + +## Overview + +Rate limiting is a technique for controlling the number of incoming requests over a defined period. It can be used to control usage for business purposes, like agreed usage quotas, or to ensure the stability of a system, preventing overload and protecting the system from, e.g., Denial of Service attacks. + +## Use Cases + +Rate limiting is commonly used to: + +- **Prevent Overload:** Protect internal systems like databases from excessive traffic. +- **Enhance Security:** Block or limit abusive behavior such as brute-force attempts or DDoS attacks. +- **Ensure Fair Usage:** Enforce quotas and prevent resource hogging by individual clients. +- **Implement Entitlements:** Define API usage limits based on user identity or role. + +## Rate Limiting in Envoy Gateway + +Envoy Gateway supports two types of rate limiting: + +- **Global Rate Limiting:** Shared limits across all Envoy instances. +- **Local Rate Limiting:** Independent limits per Envoy instance. + +Envoy Gateway supports rate limiting through the `BackendTrafficPolicy` custom resource. You can define rate-limiting rules and apply them to `HTTPRoute`, `GRPCRoute`, or `Gateway` resources either by directly referencing them with the targetRefs field or by dynamically selecting them using the targetSelectors field, which matches resources based on Kubernetes labels. + +{{% alert title="Note" color="primary" %}} +Rate limits are applied per route, even if the `BackendTrafficPolicy` targets a `Gateway`. For example, if the limit is 100r/s and a Gateway has 3 routes, each route has its own 100r/s bucket. +{{% /alert %}} + +--- + +## Global Rate Limiting + +Global rate limiting ensures a consistent request limit across the entire Envoy fleet. This is ideal for shared resources or distributed environments where coordinated enforcement is critical. + +Global limits are enforced via Envoy’s external Rate Limit Service, which is automatically deployed and managed by the Envoy Gateway system. The Rate Limit Service requires a datastore component (commonly Redis). When a request is received, Envoy sends a descriptor to this external service to determine if the request should be allowed. + +**Benefits of global limits:** + +- Centralized control across instances +- Fair sharing of backend capacity +- Burst resistance during autoscaling + +### Example + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: global-ratelimit +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: my-api + rateLimit: + global: + rules: + - limit: + requests: 100 + unit: Minute + +``` +This configuration limits all requests across all Envoy instances for the my-api route to 100 requests per minute total. If there are multiple replicas of Envoy, the limit is shared across all of them. + +--- + +## Local Rate Limiting + + +Local rate limiting applies limits independently within each Envoy Proxy instance. It does not rely on external services, making it lightweight and efficient—especially for blocking abusive traffic early. + +**Benefits of local limits:** + +- Lightweight and does not require an external rate limit service +- Fast enforcement with rate limiting at the edge +- Effective as a first line of defense against traffic bursts + +### Example + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: local-ratelimit +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: my-api + rateLimit: + local: + rules: + - limit: + requests: 50 + unit: Minute + +``` +This configuration limits traffic to 50 requests per minute per Envoy instance for the my-api route. If there are two Envoy replicas, up to 100 total requests per minute may be allowed (50 per replica). + +--- + +## Combining Global and Local Rate Limiting + +Envoy Gateway supports configuring both Global and Local rate limits simultaneously on the same route. This layered approach provides comprehensive protection by combining the benefits of both strategies. + +**How it works:** + +When both rate limits are configured: +1. **Local rate limits** is evaluated first at each Envoy instance +2. **Global rate limits** is then evaluated using the shared rate limit service +3. A request must pass both checks to be allowed through + +**Benefits of combined rate limiting:** + +- Local limits provide immediate protection against sudden traffic spikes at each instance without external service calls +- Reduces load on the global rate limit service + +### Example + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: combined-ratelimit +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: my-api + rateLimit: + local: + rules: + - limit: + requests: 50 + unit: Minute + global: + rules: + - limit: + requests: 100 + unit: Minute +``` + +This configuration applies both rate limiting strategies to the my-api route: +- **Local limiting**: Each Envoy instance independently allows up to 50 requests per second. If you have 3 Envoy replicas, the theoretical maximum would be 150 requests per second (50 per replica) assuming perfect load distribution. +- **Global limiting**: All requests across all Envoy instances are limited to 100 requests per minute total. This is enforced by the shared rate limit service, ensuring the combined traffic from all replicas never exceeds this limit. + +In practice, a request will be rejected if it exceeds either limit. For example: +- If one Envoy instance receives 51 requests in a second, the 51st request is rejected locally (local limit exceeded) +- If the system has already processed 100 requests in the current minute across all instances, the 101st request is rejected globally (global limit exceeded) + +## Related Resources +- [BackendTrafficPolicy](gateway_api_extensions/backend-traffic-policy.md) +- [Task: Global Rate Limit](../tasks/traffic/global-rate-limit.md) +- [Task: Local Rate Limit](../tasks/traffic/local-rate-limit.md) diff --git a/site/content/en/v1.8/install/_index.md b/site/content/en/v1.8/install/_index.md new file mode 100644 index 0000000000..b4c6f79c6f --- /dev/null +++ b/site/content/en/v1.8/install/_index.md @@ -0,0 +1,5 @@ +--- +title: "Installation" +description: This section includes installation related contents of Envoy Gateway. +weight: 70 +--- diff --git a/site/content/en/v1.8/install/custom-cert.md b/site/content/en/v1.8/install/custom-cert.md new file mode 100644 index 0000000000..4aa0d9687c --- /dev/null +++ b/site/content/en/v1.8/install/custom-cert.md @@ -0,0 +1,146 @@ +--- +title: Control Plane Authentication using custom certs +weight: -70 +--- + +Envoy Gateway establishes a secure TLS connection for control plane communication between Envoy Gateway pods and the Envoy Proxy fleet. The TLS Certificates used here are self signed and generated using a job that runs before envoy gateway is created, and these certs and mounted on to the envoy gateway and envoy proxy pods. + +This task will walk you through configuring custom certs for control plane auth. + +## Before you begin + +We use Cert-Manager to manage the certificates. You can install it by following the [official guide](https://cert-manager.io/docs/installation/kubernetes/). + +## Configure custom certs for control plane + +1. First you need to set up the CA issuer, in this task, we use the `selfsigned-issuer` as an example. + + *You should not use the self-signed issuer in production, you should use a real CA issuer.* + + ```shell + cat < + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| envoy-gateway-steering-committee | | | +| envoy-gateway-maintainers | | | + +## Source Code + +* + +## Requirements + +| Repository | Name | Version | +|------------|------|---------| +| https://fluent.github.io/helm-charts | fluent-bit | 0.56.0 | +| https://grafana.github.io/helm-charts | alloy | 1.8.0 | +| https://grafana.github.io/helm-charts | grafana | 10.5.15 | +| https://grafana.github.io/helm-charts | loki | 7.0.0 | +| https://grafana.github.io/helm-charts | tempo | 1.3.1 | +| https://open-telemetry.github.io/opentelemetry-helm-charts | opentelemetry-collector | 0.153.0 | +| https://prometheus-community.github.io/helm-charts | prometheus | 29.6.0 | + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| alloy.alloy.configMap.content | string | `"// Write your Alloy config here:\nlogging {\n level = \"info\"\n format = \"logfmt\"\n}\nloki.write \"alloy\" {\n endpoint {\n url = \"http://loki.monitoring.svc:3100/loki/api/v1/push\"\n }\n}\n// discovery.kubernetes allows you to find scrape targets from Kubernetes resources.\n// It watches cluster state and ensures targets are continually synced with what is currently running in your cluster.\ndiscovery.kubernetes \"pod\" {\n role = \"pod\"\n}\n\n// discovery.relabel rewrites the label set of the input targets by applying one or more relabeling rules.\n// If no rules are defined, then the input targets are exported as-is.\ndiscovery.relabel \"pod_logs\" {\n targets = discovery.kubernetes.pod.targets\n\n // Label creation - \"namespace\" field from \"__meta_kubernetes_namespace\"\n rule {\n source_labels = [\"__meta_kubernetes_namespace\"]\n action = \"replace\"\n target_label = \"namespace\"\n }\n\n // Label creation - \"pod\" field from \"__meta_kubernetes_pod_name\"\n rule {\n source_labels = [\"__meta_kubernetes_pod_name\"]\n action = \"replace\"\n target_label = \"pod\"\n }\n\n // Label creation - \"container\" field from \"__meta_kubernetes_pod_container_name\"\n rule {\n source_labels = [\"__meta_kubernetes_pod_container_name\"]\n action = \"replace\"\n target_label = \"container\"\n }\n\n // Label creation - \"app\" field from \"__meta_kubernetes_pod_label_app_kubernetes_io_name\"\n rule {\n source_labels = [\"__meta_kubernetes_pod_label_app_kubernetes_io_name\"]\n action = \"replace\"\n target_label = \"app\"\n }\n\n // Label creation - \"job\" field from \"__meta_kubernetes_namespace\" and \"__meta_kubernetes_pod_container_name\"\n // Concatenate values __meta_kubernetes_namespace/__meta_kubernetes_pod_container_name\n rule {\n source_labels = [\"__meta_kubernetes_namespace\", \"__meta_kubernetes_pod_container_name\"]\n action = \"replace\"\n target_label = \"job\"\n separator = \"/\"\n replacement = \"$1\"\n }\n\n // Label creation - \"container\" field from \"__meta_kubernetes_pod_uid\" and \"__meta_kubernetes_pod_container_name\"\n // Concatenate values __meta_kubernetes_pod_uid/__meta_kubernetes_pod_container_name.log\n rule {\n source_labels = [\"__meta_kubernetes_pod_uid\", \"__meta_kubernetes_pod_container_name\"]\n action = \"replace\"\n target_label = \"__path__\"\n separator = \"/\"\n replacement = \"/var/log/pods/*$1/*.log\"\n }\n\n // Label creation - \"container_runtime\" field from \"__meta_kubernetes_pod_container_id\"\n rule {\n source_labels = [\"__meta_kubernetes_pod_container_id\"]\n action = \"replace\"\n target_label = \"container_runtime\"\n regex = \"^(\\\\S+):\\\\/\\\\/.+$\"\n replacement = \"$1\"\n }\n}\n\n// loki.source.kubernetes tails logs from Kubernetes containers using the Kubernetes API.\nloki.source.kubernetes \"pod_logs\" {\n targets = discovery.relabel.pod_logs.output\n forward_to = [loki.process.pod_logs.receiver]\n}\n// loki.process receives log entries from other Loki components, applies one or more processing stages,\n// and forwards the results to the list of receivers in the component’s arguments.\nloki.process \"pod_logs\" {\n stage.static_labels {\n values = {\n cluster = \"envoy-gateway\",\n }\n }\n\n forward_to = [loki.write.alloy.receiver]\n}"` | | +| alloy.enabled | bool | `false` | | +| alloy.fullnameOverride | string | `"alloy"` | | +| dashboard.annotations | object | `{}` | | +| dashboard.labels | object | `{}` | | +| fluent-bit.config.filters | string | `"[FILTER]\n Name kubernetes\n Match kube.*\n Merge_Log On\n Keep_Log Off\n K8S-Logging.Parser On\n K8S-Logging.Exclude On\n\n[FILTER]\n Name grep\n Match kube.*\n Regex $kubernetes['container_name'] ^envoy$\n\n[FILTER]\n Name parser\n Match kube.*\n Key_Name log\n Parser envoy\n Reserve_Data True\n"` | | +| fluent-bit.config.inputs | string | `"[INPUT]\n Name tail\n Path /var/log/containers/*.log\n multiline.parser docker, cri\n Tag kube.*\n Mem_Buf_Limit 5MB\n Skip_Long_Lines On\n"` | | +| fluent-bit.config.outputs | string | `"[OUTPUT]\n Name loki\n Match kube.*\n Host loki.monitoring.svc.cluster.local\n Port 3100\n Labels job=fluentbit, app=$kubernetes['labels']['app'], k8s_namespace_name=$kubernetes['namespace_name'], k8s_pod_name=$kubernetes['pod_name'], k8s_container_name=$kubernetes['container_name']\n"` | | +| fluent-bit.config.service | string | `"[SERVICE]\n Daemon Off\n Flush {{ .Values.flush }}\n Log_Level {{ .Values.logLevel }}\n Parsers_File parsers.conf\n Parsers_File custom_parsers.conf\n HTTP_Server On\n HTTP_Listen 0.0.0.0\n HTTP_Port {{ .Values.metricsPort }}\n Health_Check On\n"` | | +| fluent-bit.enabled | bool | `true` | | +| fluent-bit.fullnameOverride | string | `"fluent-bit"` | | +| fluent-bit.image.repository | string | `"fluent/fluent-bit"` | | +| fluent-bit.podAnnotations."fluentbit.io/exclude" | string | `"true"` | | +| fluent-bit.podAnnotations."prometheus.io/path" | string | `"/api/v1/metrics/prometheus"` | | +| fluent-bit.podAnnotations."prometheus.io/port" | string | `"2020"` | | +| fluent-bit.podAnnotations."prometheus.io/scrape" | string | `"true"` | | +| fluent-bit.testFramework.enabled | bool | `false` | | +| grafana.adminPassword | string | `"admin"` | | +| grafana.dashboardProviders."dashboardproviders.yaml".apiVersion | int | `1` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].disableDeletion | bool | `false` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].editable | bool | `true` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].folder | string | `"envoy-gateway"` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].name | string | `"envoy-gateway"` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].options.path | string | `"/var/lib/grafana/dashboards/envoy-gateway"` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].orgId | int | `1` | | +| grafana.dashboardProviders."dashboardproviders.yaml".providers[0].type | string | `"file"` | | +| grafana.dashboardsConfigMaps.envoy-gateway | string | `"grafana-dashboards"` | | +| grafana.datasources."datasources.yaml".apiVersion | int | `1` | | +| grafana.datasources."datasources.yaml".datasources[0].editable | bool | `true` | | +| grafana.datasources."datasources.yaml".datasources[0].name | string | `"Prometheus"` | | +| grafana.datasources."datasources.yaml".datasources[0].type | string | `"prometheus"` | | +| grafana.datasources."datasources.yaml".datasources[0].url | string | `"http://prometheus"` | | +| grafana.datasources."datasources.yaml".datasources[1].editable | bool | `true` | | +| grafana.datasources."datasources.yaml".datasources[1].name | string | `"Tempo"` | | +| grafana.datasources."datasources.yaml".datasources[1].type | string | `"tempo"` | | +| grafana.datasources."datasources.yaml".datasources[1].url | string | `"http://tempo:3100"` | | +| grafana.datasources."datasources.yaml".datasources[2].editable | bool | `true` | | +| grafana.datasources."datasources.yaml".datasources[2].name | string | `"Loki"` | | +| grafana.datasources."datasources.yaml".datasources[2].type | string | `"loki"` | | +| grafana.datasources."datasources.yaml".datasources[2].url | string | `"http://loki:3100"` | | +| grafana.enabled | bool | `true` | | +| grafana.env.GF_AUTH_ANONYMOUS_ENABLED | string | `"true"` | | +| grafana.env.GF_AUTH_ANONYMOUS_ORG_ROLE | string | `"Admin"` | | +| grafana.env.GF_AUTH_BASIC_ENABLED | string | `"false"` | | +| grafana.env.GF_SECURITY_ADMIN_PASSWORD | string | `"admin"` | | +| grafana.env.GF_SECURITY_ADMIN_USER | string | `"admin"` | | +| grafana.fullnameOverride | string | `"grafana"` | | +| grafana.service.type | string | `"LoadBalancer"` | | +| grafana.testFramework.enabled | bool | `false` | | +| loki.backend.replicas | int | `0` | | +| loki.chunksCache.enabled | bool | `false` | | +| loki.deploymentMode | string | `"SingleBinary"` | | +| loki.enabled | bool | `true` | | +| loki.fullnameOverride | string | `"loki"` | | +| loki.gateway.enabled | bool | `false` | | +| loki.loki.auth_enabled | bool | `false` | | +| loki.loki.commonConfig.instance_addr | string | `"${INSTANCE_ADDR}"` | | +| loki.loki.commonConfig.replication_factor | int | `1` | | +| loki.loki.commonConfig.ring.kvstore.store | string | `"memberlist"` | | +| loki.loki.compactorAddress | string | `"loki"` | | +| loki.loki.limits_config.otlp_config.resource_attributes.attributes_config[0].action | string | `"index_label"` | | +| loki.loki.limits_config.otlp_config.resource_attributes.attributes_config[0].attributes[0] | string | `"exporter"` | | +| loki.loki.memberlist | string | `"loki-memberlist"` | | +| loki.loki.rulerConfig.storage.type | string | `"local"` | | +| loki.loki.storage.type | string | `"filesystem"` | | +| loki.loki.useTestSchema | bool | `true` | | +| loki.lokiCanary.enabled | bool | `false` | | +| loki.monitoring.selfMonitoring.enabled | bool | `false` | | +| loki.monitoring.selfMonitoring.grafanaAgent.installOperator | bool | `false` | | +| loki.read.replicas | int | `0` | | +| loki.resultsCache.enabled | bool | `false` | | +| loki.singleBinary.extraArgs[0] | string | `"-config.expand-env=true"` | | +| loki.singleBinary.extraEnv[0].name | string | `"INSTANCE_ADDR"` | | +| loki.singleBinary.extraEnv[0].valueFrom.fieldRef.fieldPath | string | `"status.podIP"` | | +| loki.singleBinary.replicas | int | `1` | | +| loki.test.enabled | bool | `false` | | +| loki.write.replicas | int | `0` | | +| opentelemetry-collector.config.exporters.debug.verbosity | string | `"detailed"` | | +| opentelemetry-collector.config.exporters.otlp.endpoint | string | `"tempo.monitoring.svc:4317"` | | +| opentelemetry-collector.config.exporters.otlp.tls.insecure | bool | `true` | | +| opentelemetry-collector.config.exporters.otlphttp/loki.endpoint | string | `"http://loki.monitoring.svc:3100/otlp"` | | +| opentelemetry-collector.config.exporters.prometheus.endpoint | string | `":19001"` | | +| opentelemetry-collector.config.extensions.health_check.endpoint | string | `"[${env:MY_POD_IP}]:13133"` | | +| opentelemetry-collector.config.processors.transform/loki.log_statements[0].context | string | `"log"` | | +| opentelemetry-collector.config.processors.transform/loki.log_statements[0].statements[0] | string | `"set(resource.attributes[\"exporter\"], \"OTLP\")"` | | +| opentelemetry-collector.config.processors.transform/loki.log_statements[0].statements[1] | string | `"set(resource.attributes[\"k8s.namespace.name\"], log.attributes[\"k8s.namespace.name\"])"` | | +| opentelemetry-collector.config.processors.transform/loki.log_statements[0].statements[2] | string | `"delete_key(log.attributes, \"k8s.namespace.name\")"` | | +| opentelemetry-collector.config.receivers.datadog.endpoint | string | `"[${env:MY_POD_IP}]:8126"` | | +| opentelemetry-collector.config.receivers.envoyals.endpoint | string | `"[${env:MY_POD_IP}]:9000"` | | +| opentelemetry-collector.config.receivers.jaeger.protocols.grpc.endpoint | string | `"[${env:MY_POD_IP}]:14250"` | | +| opentelemetry-collector.config.receivers.jaeger.protocols.thrift_compact.endpoint | string | `"[${env:MY_POD_IP}]:6831"` | | +| opentelemetry-collector.config.receivers.jaeger.protocols.thrift_http.endpoint | string | `"[${env:MY_POD_IP}]:14268"` | | +| opentelemetry-collector.config.receivers.otlp.protocols.grpc.endpoint | string | `"[${env:MY_POD_IP}]:4317"` | | +| opentelemetry-collector.config.receivers.otlp.protocols.http.endpoint | string | `"[${env:MY_POD_IP}]:4318"` | | +| opentelemetry-collector.config.receivers.prometheus.config.scrape_configs[0].job_name | string | `"opentelemetry-collector"` | | +| opentelemetry-collector.config.receivers.prometheus.config.scrape_configs[0].scrape_interval | string | `"10s"` | | +| opentelemetry-collector.config.receivers.prometheus.config.scrape_configs[0].static_configs[0].targets[0] | string | `"[${env:MY_POD_IP}]:8888"` | | +| opentelemetry-collector.config.receivers.zipkin.endpoint | string | `"[${env:MY_POD_IP}]:9411"` | | +| opentelemetry-collector.config.service.extensions[0] | string | `"health_check"` | | +| opentelemetry-collector.config.service.pipelines.logs.exporters[0] | string | `"otlphttp/loki"` | | +| opentelemetry-collector.config.service.pipelines.logs.processors[0] | string | `"transform/loki"` | | +| opentelemetry-collector.config.service.pipelines.logs.receivers[0] | string | `"otlp"` | | +| opentelemetry-collector.config.service.pipelines.logs.receivers[1] | string | `"envoyals"` | | +| opentelemetry-collector.config.service.pipelines.metrics.exporters[0] | string | `"prometheus"` | | +| opentelemetry-collector.config.service.pipelines.metrics.receivers[0] | string | `"datadog"` | | +| opentelemetry-collector.config.service.pipelines.metrics.receivers[1] | string | `"otlp"` | | +| opentelemetry-collector.config.service.pipelines.traces.exporters[0] | string | `"otlp"` | | +| opentelemetry-collector.config.service.pipelines.traces.receivers[0] | string | `"datadog"` | | +| opentelemetry-collector.config.service.pipelines.traces.receivers[1] | string | `"otlp"` | | +| opentelemetry-collector.config.service.pipelines.traces.receivers[2] | string | `"zipkin"` | | +| opentelemetry-collector.config.service.telemetry.metrics.level | string | `"none"` | | +| opentelemetry-collector.config.service.telemetry.metrics.readers[0].pull.exporter.prometheus.host | string | `"localhost"` | | +| opentelemetry-collector.config.service.telemetry.metrics.readers[0].pull.exporter.prometheus.port | int | `8888` | | +| opentelemetry-collector.enabled | bool | `false` | | +| opentelemetry-collector.fullnameOverride | string | `"otel-collector"` | | +| opentelemetry-collector.image.repository | string | `"otel/opentelemetry-collector-contrib"` | | +| opentelemetry-collector.image.tag | string | `"0.151.0"` | | +| opentelemetry-collector.mode | string | `"deployment"` | | +| opentelemetry-collector.ports.datadog.containerPort | int | `8126` | | +| opentelemetry-collector.ports.datadog.enabled | bool | `true` | | +| opentelemetry-collector.ports.datadog.hostPort | int | `8126` | | +| opentelemetry-collector.ports.datadog.protocol | string | `"TCP"` | | +| opentelemetry-collector.ports.datadog.servicePort | int | `8126` | | +| opentelemetry-collector.ports.envoy-als.appProtocol | string | `"grpc"` | | +| opentelemetry-collector.ports.envoy-als.containerPort | int | `9000` | | +| opentelemetry-collector.ports.envoy-als.enabled | bool | `true` | | +| opentelemetry-collector.ports.envoy-als.hostPort | int | `9000` | | +| opentelemetry-collector.ports.envoy-als.protocol | string | `"TCP"` | | +| opentelemetry-collector.ports.envoy-als.servicePort | int | `9000` | | +| opentelemetry-collector.presets.kubernetesAttributes.enabled | bool | `true` | | +| prometheus.alertmanager.enabled | bool | `false` | | +| prometheus.enabled | bool | `true` | | +| prometheus.kube-state-metrics.customResourceState.config.kind | string | `"CustomResourceStateMetrics"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].groupVersionKind.kind | string | `"Gateway"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].groupVersionKind.version | string | `"v1"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metricNamePrefix | string | `"gatewayapi_gateway"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[0].each.info.labelsFromPath.gatewayclass_name[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[0].each.info.labelsFromPath.gatewayclass_name[1] | string | `"gatewayClassName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[0].help | string | `"Gateway information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[0].name | string | `"info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[1].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[1].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[1].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[1].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[1].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[2].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[2].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[2].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[3].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[3].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[3].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[3].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[3].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.allowed_routes_namespaces_from[0] | string | `"allowedRoutes"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.allowed_routes_namespaces_from[1] | string | `"namespaces"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.allowed_routes_namespaces_from[2] | string | `"from"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.hostname[0] | string | `"hostname"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.listener_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.protocol[0] | string | `"protocol"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.tls_mode[0] | string | `"tls"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.labelsFromPath.tls_mode[1] | string | `"mode"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.info.path[1] | string | `"listeners"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].help | string | `"Gateway listener information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[4].name | string | `"listener_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].each.gauge.labelsFromPath.type[0] | string | `"type"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].each.gauge.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].each.gauge.path[1] | string | `"conditions"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].each.gauge.valueFrom[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].help | string | `"status condition"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[5].name | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].each.gauge.labelsFromPath.listener_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].each.gauge.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].each.gauge.path[1] | string | `"listeners"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].each.gauge.valueFrom[0] | string | `"attachedRoutes"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].help | string | `"Number of attached routes for a listener"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[6].name | string | `"status_listener_attached_routes"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].each.info.labelsFromPath.type[0] | string | `"type"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].each.info.labelsFromPath.value[0] | string | `"value"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].each.info.path[1] | string | `"addresses"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].help | string | `"Gateway address types and values"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[0].metrics[7].name | string | `"status_address_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].groupVersionKind.kind | string | `"GatewayClass"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].groupVersionKind.version | string | `"v1"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metricNamePrefix | string | `"gatewayapi_gatewayclass"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[0].each.info.labelsFromPath.controller_name[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[0].each.info.labelsFromPath.controller_name[1] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[0].help | string | `"GatewayClass information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[0].name | string | `"info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[1].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[1].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[1].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[1].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[1].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[2].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[2].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[2].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[3].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[3].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[3].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[3].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[3].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].each.gauge.labelsFromPath.type[0] | string | `"type"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].each.gauge.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].each.gauge.path[1] | string | `"conditions"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].each.gauge.valueFrom[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].help | string | `"status condition"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[4].name | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].each.info.labelsFromPath.features | list | `[]` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].each.info.path[1] | string | `"supportedFeatures"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].help | string | `"List of supported features for the GatewayClass"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[1].metrics[5].name | string | `"status_supported_features"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].groupVersionKind.kind | string | `"HTTPRoute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].groupVersionKind.version | string | `"v1"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metricNamePrefix | string | `"gatewayapi_httproute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].each.info.labelsFromPath.hostname | list | `[]` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].each.info.path[1] | string | `"hostnames"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].help | string | `"Hostname information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[3].name | string | `"hostname_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.labelsFromPath.parent_section_name[0] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.info.path[1] | string | `"parentRefs"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].help | string | `"Parent references that the httproute wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[4].name | string | `"parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.controller_name[0] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_group[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_group[1] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_kind[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_kind[1] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_namespace[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_port[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_port[1] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_section_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.labelsFromPath.parent_section_name[1] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.info.path[1] | string | `"parents"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].help | string | `"Parent references that the httproute is attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[2].metrics[5].name | string | `"status_parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].groupVersionKind.kind | string | `"GRPCRoute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].groupVersionKind.version | string | `"v1"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metricNamePrefix | string | `"gatewayapi_grpcroute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].each.info.labelsFromPath.hostname | list | `[]` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].each.info.path[1] | string | `"hostnames"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].help | string | `"Hostname information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[3].name | string | `"hostname_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.labelsFromPath.parent_section_name[0] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.info.path[1] | string | `"parentRefs"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].help | string | `"Parent references that the grpcroute wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[4].name | string | `"parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.controller_name[0] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_group[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_group[1] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_kind[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_kind[1] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_namespace[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_port[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_port[1] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_section_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.labelsFromPath.parent_section_name[1] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.info.path[1] | string | `"parents"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].help | string | `"Parent references that the grpcroute is attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[3].metrics[5].name | string | `"status_parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].groupVersionKind.kind | string | `"TCPRoute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].groupVersionKind.version | string | `"v1alpha2"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metricNamePrefix | string | `"gatewayapi_tcproute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.labelsFromPath.parent_section_name[0] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.info.path[1] | string | `"parentRefs"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].help | string | `"Parent references that the tcproute wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[3].name | string | `"parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.controller_name[0] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_group[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_group[1] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_kind[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_kind[1] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_namespace[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_port[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_port[1] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_section_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.labelsFromPath.parent_section_name[1] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.info.path[1] | string | `"parents"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].help | string | `"Parent references that the tcproute is attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[4].metrics[4].name | string | `"status_parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].groupVersionKind.kind | string | `"TLSRoute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].groupVersionKind.version | string | `"v1alpha2"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metricNamePrefix | string | `"gatewayapi_tlsroute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].each.info.labelsFromPath.hostname | list | `[]` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].each.info.path[1] | string | `"hostnames"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].help | string | `"Hostname information"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[3].name | string | `"hostname_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.labelsFromPath.parent_section_name[0] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.info.path[1] | string | `"parentRefs"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].help | string | `"Parent references that the tlsroute wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[4].name | string | `"parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.controller_name[0] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_group[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_group[1] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_kind[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_kind[1] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_namespace[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_port[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_port[1] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_section_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.labelsFromPath.parent_section_name[1] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.info.path[1] | string | `"parents"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].help | string | `"Parent references that the tlsroute is attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[5].metrics[5].name | string | `"status_parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].groupVersionKind.kind | string | `"UDPRoute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].groupVersionKind.version | string | `"v1alpha2"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metricNamePrefix | string | `"gatewayapi_udproute"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_port[0] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.labelsFromPath.parent_section_name[0] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.info.path[1] | string | `"parentRefs"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].help | string | `"Parent references that the udproute wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[3].name | string | `"parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.controller_name[0] | string | `"controllerName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_group[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_group[1] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_kind[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_kind[1] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_namespace[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_port[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_port[1] | string | `"port"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_section_name[0] | string | `"parentRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.labelsFromPath.parent_section_name[1] | string | `"sectionName"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.path[0] | string | `"status"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.info.path[1] | string | `"parents"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].help | string | `"Parent references that the udproute is attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[6].metrics[4].name | string | `"status_parent_info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].groupVersionKind.group | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].groupVersionKind.kind | string | `"BackendTLSPolicy"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].groupVersionKind.version | string | `"v1alpha3"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].labelsFromPath.name[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].labelsFromPath.name[1] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].labelsFromPath.namespace[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].labelsFromPath.namespace[1] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metricNamePrefix | string | `"gatewayapi_backendtlspolicy"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[0].each.info.labelsFromPath.*[0] | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[0].each.info.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[0].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[0].help | string | `"Kubernetes labels converted to Prometheus labels."` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[0].name | string | `"labels"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[1].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[1].each.gauge.path[1] | string | `"creationTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[1].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[1].help | string | `"created timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[1].name | string | `"created"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[2].each.gauge.path[0] | string | `"metadata"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[2].each.gauge.path[1] | string | `"deletionTimestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[2].each.type | string | `"Gauge"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[2].help | string | `"deletion timestamp"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[2].name | string | `"deleted"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.labelsFromPath.target_group[0] | string | `"group"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.labelsFromPath.target_kind[0] | string | `"kind"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.labelsFromPath.target_name[0] | string | `"name"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.labelsFromPath.target_namespace[0] | string | `"namespace"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.path[0] | string | `"spec"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.info.path[1] | string | `"targetRef"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].each.type | string | `"Info"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].help | string | `"Target references that the backendtlspolicy wants to be attached to"` | | +| prometheus.kube-state-metrics.customResourceState.config.spec.resources[7].metrics[3].name | string | `"target_info"` | | +| prometheus.kube-state-metrics.customResourceState.enabled | bool | `true` | | +| prometheus.kube-state-metrics.enabled | bool | `false` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].apiGroups[0] | string | `"gateway.networking.k8s.io"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[0] | string | `"gateways"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[1] | string | `"gatewayclasses"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[2] | string | `"httproutes"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[3] | string | `"grpcroutes"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[4] | string | `"tcproutes"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[5] | string | `"tlsroutes"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[6] | string | `"udproutes"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].resources[7] | string | `"backendtlspolicies"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].verbs[0] | string | `"list"` | | +| prometheus.kube-state-metrics.rbac.extraRules[0].verbs[1] | string | `"watch"` | | +| prometheus.prometheus-node-exporter.enabled | bool | `false` | | +| prometheus.prometheus-pushgateway.enabled | bool | `false` | | +| prometheus.server.fullnameOverride | string | `"prometheus"` | | +| prometheus.server.global.scrape_interval | string | `"15s"` | | +| prometheus.server.image.repository | string | `"prom/prometheus"` | | +| prometheus.server.persistentVolume.enabled | bool | `false` | | +| prometheus.server.readinessProbeInitialDelay | int | `0` | | +| prometheus.server.securityContext | object | `{}` | | +| prometheus.server.service.type | string | `"LoadBalancer"` | | +| tempo.enabled | bool | `true` | | +| tempo.fullnameOverride | string | `"tempo"` | | +| tempo.service.type | string | `"LoadBalancer"` | | + diff --git a/site/content/en/v1.8/install/gateway-crds-helm-api.md b/site/content/en/v1.8/install/gateway-crds-helm-api.md new file mode 100644 index 0000000000..b331653392 --- /dev/null +++ b/site/content/en/v1.8/install/gateway-crds-helm-api.md @@ -0,0 +1,29 @@ ++++ +title = "Gateway Crds Helm Chart" ++++ + +![Version: v0.0.0-latest](https://img.shields.io/badge/Version-v0.0.0--latest-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square) + +A Helm chart for Envoy Gateway CRDs + +**Homepage:** + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| envoy-gateway-steering-committee | | | +| envoy-gateway-maintainers | | | + +## Source Code + +* + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| crds.envoyGateway.enabled | bool | `false` | | +| crds.gatewayAPI.channel | string | `"experimental"` | | +| crds.gatewayAPI.enabled | bool | `false` | | + diff --git a/site/content/en/v1.8/install/gateway-helm-api.md b/site/content/en/v1.8/install/gateway-helm-api.md new file mode 100644 index 0000000000..415d76595b --- /dev/null +++ b/site/content/en/v1.8/install/gateway-helm-api.md @@ -0,0 +1,99 @@ ++++ +title = "Gateway Helm Chart" ++++ + +![Version: v0.0.0-latest](https://img.shields.io/badge/Version-v0.0.0--latest-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square) + +The Helm chart for Envoy Gateway + +**Homepage:** + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| envoy-gateway-steering-committee | | | +| envoy-gateway-maintainers | | | + +## Source Code + +* + +## Requirements + +| Repository | Name | Version | +|------------|------|---------| +| | crds | 0.0.0 | + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| certgen | object | `{"job":{"affinity":{},"annotations":{},"args":[],"nodeSelector":{},"pod":{"annotations":{},"labels":{}},"resources":{},"securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"privileged":false,"readOnlyRootFilesystem":true,"runAsGroup":65532,"runAsNonRoot":true,"runAsUser":65532,"seccompProfile":{"type":"RuntimeDefault"}},"tolerations":[],"ttlSecondsAfterFinished":30},"rbac":{"annotations":{},"labels":{}}}` | Certgen is used to generate the certificates required by EnvoyGateway. If you want to construct a custom certificate, you can generate a custom certificate through Cert-Manager before installing EnvoyGateway. Certgen will not overwrite the custom certificate. Please do not manually modify `values.yaml` to disable certgen, it may cause EnvoyGateway OIDC,OAuth2,etc. to not work as expected. | +| commonLabels | object | `{}` | Labels to apply to all resources | +| config.envoyGateway | object | `{"extensionApis":{},"gateway":{"controllerName":"gateway.envoyproxy.io/gatewayclass-controller"},"logging":{"level":{"default":"info"}},"provider":{"type":"Kubernetes"}}` | EnvoyGateway configuration. Visit https://gateway.envoyproxy.io/docs/api/extension_types/#envoygateway to view all options. | +| createNamespace | bool | `false` | | +| deployment.annotations | object | `{}` | | +| deployment.envoyGateway.extraEnv | list | `[]` | Additional environment variables for the envoy-gateway container. | +| deployment.envoyGateway.image.repository | string | `""` | | +| deployment.envoyGateway.image.tag | string | `""` | | +| deployment.envoyGateway.imagePullPolicy | string | `""` | | +| deployment.envoyGateway.imagePullSecrets | list | `[]` | | +| deployment.envoyGateway.resources.limits.memory | string | `"1024Mi"` | | +| deployment.envoyGateway.resources.requests.cpu | string | `"100m"` | | +| deployment.envoyGateway.resources.requests.memory | string | `"256Mi"` | | +| deployment.envoyGateway.securityContext.allowPrivilegeEscalation | bool | `false` | | +| deployment.envoyGateway.securityContext.capabilities.drop[0] | string | `"ALL"` | | +| deployment.envoyGateway.securityContext.privileged | bool | `false` | | +| deployment.envoyGateway.securityContext.runAsGroup | int | `65532` | | +| deployment.envoyGateway.securityContext.runAsNonRoot | bool | `true` | | +| deployment.envoyGateway.securityContext.runAsUser | int | `65532` | | +| deployment.envoyGateway.securityContext.seccompProfile.type | string | `"RuntimeDefault"` | | +| deployment.pod.affinity | object | `{}` | | +| deployment.pod.annotations."prometheus.io/port" | string | `"19001"` | | +| deployment.pod.annotations."prometheus.io/scrape" | string | `"true"` | | +| deployment.pod.extraVolumeMounts | list | `[]` | | +| deployment.pod.extraVolumes | list | `[]` | | +| deployment.pod.labels | object | `{}` | | +| deployment.pod.nodeSelector | object | `{}` | | +| deployment.pod.tolerations | list | `[]` | | +| deployment.pod.topologySpreadConstraints | list | `[]` | | +| deployment.ports[0].name | string | `"grpc"` | | +| deployment.ports[0].port | int | `18000` | | +| deployment.ports[0].targetPort | int | `18000` | | +| deployment.ports[1].name | string | `"ratelimit"` | | +| deployment.ports[1].port | int | `18001` | | +| deployment.ports[1].targetPort | int | `18001` | | +| deployment.ports[2].name | string | `"wasm"` | | +| deployment.ports[2].port | int | `18002` | | +| deployment.ports[2].targetPort | int | `18002` | | +| deployment.ports[3].name | string | `"metrics"` | | +| deployment.ports[3].port | int | `19001` | | +| deployment.ports[3].targetPort | int | `19001` | | +| deployment.priorityClassName | string | `nil` | | +| deployment.replicas | int | `1` | | +| global.imagePullSecrets | list | `[]` | Global override for image pull secrets | +| global.imageRegistry | string | `""` | Global override for image registry | +| global.images.envoyGateway.image | string | `nil` | | +| global.images.envoyGateway.pullPolicy | string | `nil` | | +| global.images.envoyGateway.pullSecrets | list | `[]` | | +| global.images.envoyProxy.image | string | `""` | | +| global.images.envoyProxy.pullPolicy | string | `""` | | +| global.images.envoyProxy.pullSecrets | list | `[]` | | +| global.images.ratelimit.image | string | `"docker.io/envoyproxy/ratelimit:master"` | | +| global.images.ratelimit.pullPolicy | string | `"IfNotPresent"` | | +| global.images.ratelimit.pullSecrets | list | `[]` | | +| hpa.behavior | object | `{}` | | +| hpa.enabled | bool | `false` | | +| hpa.maxReplicas | int | `1` | | +| hpa.metrics | list | `[]` | | +| hpa.minReplicas | int | `1` | | +| kubernetesClusterDomain | string | `"cluster.local"` | | +| namespaceOverride | string | `""` | Override the namespace for resources deployed by the chart. Defaults to the release namespace. | +| podDisruptionBudget.minAvailable | int | `0` | | +| service.annotations | object | `{}` | | +| service.trafficDistribution | string | `""` | | +| service.type | string | `"ClusterIP"` | Service type. Can be set to LoadBalancer with specific IP, e.g.: type: LoadBalancer loadBalancerIP: 10.236.90.20 | +| topologyInjector.annotations | object | `{}` | | +| topologyInjector.enabled | bool | `true` | | + diff --git a/site/content/en/v1.8/install/install-argocd.md b/site/content/en/v1.8/install/install-argocd.md new file mode 100644 index 0000000000..b04ec51262 --- /dev/null +++ b/site/content/en/v1.8/install/install-argocd.md @@ -0,0 +1,128 @@ ++++ +title = "Install with Argo CD" +weight = -99 ++++ + +[Argo CD](https://argo-cd.readthedocs.io) is a declarative, GitOps continuous delivery tool for Kubernetes. +Argo CD can be used to manage the deployment of Envoy Gateway on Kubernetes clusters. + +## Before you begin + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more. +{{% /alert %}} + +{{< boilerplate kind-cluster >}} + +Argo CD must be installed in your Kubernetes cluster, and the argocd CLI must be available on your local machine. +If you haven’t set it up yet, you can follow the [official installation guide](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/) to install Argo CD. + +## Install with Argo CD + +Create a new Argo CD Application that pulls the Envoy Gateway Helm chart as its source. + +```shell +cat <}} + destination: + namespace: envoy-gateway-system + server: https://kubernetes.default.svc + syncPolicy: + syncOptions: + - CreateNamespace=true + - ServerSideApply=true + automated: + prune: true + selfHeal: true +EOF +``` + +**Note**: + +* Set `ServerSideApply` to `true` to enable Kubernetes [server-side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/). This helps avoid the 262,144-byte annotation size limit. +* For simplicity, we apply the Application resource directly to the cluster. +In a production environment, it’s recommended to store this configuration in a Git repository and manage it using another Argo CD Application that uses Git as its source — following a GitOps workflow. + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available +``` + +Install the GatewayClass, Gateway, HTTPRoute and example app: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default +``` + +**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for +traffic on port 80 on its globally-routable IP address, to make it easy to use +browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is +using a privileged port (<1024), it will map this internally to an +unprivileged port, so that Envoy Gateway doesn't need additional privileges. +It's important to be aware of this mapping, since you may need to take it into +consideration when debugging. + +[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml + + +## Helm chart customizations + +You can customize the Envoy Gateway installation by using the Helm chart values. + +{{% alert title="Helm Chart Values" color="primary" %}} +If you want to know all the available fields inside the values.yaml file, please see the [Helm Chart Values](./gateway-helm-api). +{{% /alert %}} + +Below is an example of how to customize the Envoy Gateway installation by using the `valuesObject` field in the Argo CD Application. + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: envoy-gateway + namespace: argocd +spec: + project: default + source: + helm: + valuesObject: + deployment: + envoyGateway: + resources: + limits: + cpu: 700m + memory: 256Mi + chart: gateway-helm + path: gateway-helm + repoURL: docker.io/envoyproxy + targetRevision: {{< helm-version >}} + destination: + namespace: envoy-gateway-system + server: https://kubernetes.default.svc + syncPolicy: + syncOptions: + - CreateNamespace=true + - ServerSideApply=true + automated: + prune: true + selfHeal: true +``` + +Argo CD supports multiple ways of specifying Helm chart values, you can find more details in the [Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/#helm). + +{{< boilerplate open-ports >}} + +{{% alert title="Next Steps" color="warning" %}} +Envoy Gateway should now be successfully installed and running. To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks). +{{% /alert %}} diff --git a/site/content/en/v1.8/install/install-egctl.md b/site/content/en/v1.8/install/install-egctl.md new file mode 100644 index 0000000000..4698cde420 --- /dev/null +++ b/site/content/en/v1.8/install/install-egctl.md @@ -0,0 +1,69 @@ +--- +title: "Install egctl" +weight: -80 +--- + +{{% alert title="What is egctl?" color="primary" %}} + +`egctl` is a command line tool to provide additional functionality for Envoy Gateway users. + +{{% /alert %}} + + +This task shows how to install the egctl CLI. egctl can be installed either from source, or from pre-built binary releases. + +## From The Envoy Gateway Project + +The Envoy Gateway project provides two ways to fetch and install egctl. These are the official methods to get egctl releases. Installation through those methods can be found below the official methods. + +{{< tabpane text=true >}} +{{% tab header="From the Binary Releases" %}} + +Every [release](https://github.com/envoyproxy/gateway/releases) of egctl provides binary releases for a variety of OSes. These binary versions can be manually downloaded and installed. + +1. Download your [desired version](https://github.com/envoyproxy/gateway/releases) +2. Unpack it (tar -zxvf egctl_{{< yaml-version >}}_linux_amd64.tar.gz) +3. Find the egctl binary in the unpacked directory, and move it to its desired destination (mv bin/linux/amd64/egctl /usr/local/bin/egctl) + +From there, you should be able to run: `egctl help`. + +{{% /tab %}} +{{% tab header="From Script" %}} + +`egctl` now has an installer script that will automatically grab the latest release version of egctl and install it locally. + +You can fetch that script, and then execute it locally. It's well documented so that you can read through it and understand what it is doing before you run it. + +```shell +curl -fsSL -o get-egctl.sh https://gateway.envoyproxy.io/get-egctl.sh + +chmod +x get-egctl.sh + +# get help info of the +bash get-egctl.sh --help +``` + +Yes, you can just use the below command if you want to live on the edge. + +```shell +curl -fsSL https://gateway.envoyproxy.io/get-egctl.sh | VERSION={{< yaml-version >}} bash +``` + +{{% /tab %}} + +{{% tab header="From Homebrew" %}} + +You can also install egctl using homebrew: + +```shell +brew install egctl +``` + +{{% /tab %}} +{{< /tabpane >}} + +{{% alert title="Next Steps" color="warning" %}} + +You can refer to the [Use egctl task](../tasks/operations/egctl) for more details about egctl. + +{{% /alert %}} diff --git a/site/content/en/v1.8/install/install-flux.md b/site/content/en/v1.8/install/install-flux.md new file mode 100644 index 0000000000..4cff2b98fa --- /dev/null +++ b/site/content/en/v1.8/install/install-flux.md @@ -0,0 +1,132 @@ ++++ +title = "Install with Flux CD" +weight = -98 ++++ + +[Flux](https://fluxcd.io) is a CNCF-graduated, GitOps-based continuous delivery tool for Kubernetes that reconciles cluster state from a Git repository or OCI registry. +Flux can be used to manage the deployment of Envoy Gateway on Kubernetes clusters. + +## Before you begin + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more. +{{% /alert %}} + +{{< boilerplate kind-cluster >}} + +Flux must be installed in your Kubernetes cluster. +If you haven't set it up yet, follow the [Flux installation guide](https://fluxcd.io/flux/installation/). +You can use the `flux` CLI, the [Flux Operator](https://fluxoperator.dev/), or any other supported method. + +## Install with Flux + +The Envoy Gateway Helm chart is published as an OCI artifact at `oci://docker.io/envoyproxy/gateway-helm`. +Create an `OCIRepository` source and a `HelmRelease` that installs the chart into the `envoy-gateway-system` namespace. + +```shell +cat <}} +--- +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: envoy-gateway + namespace: envoy-gateway-system +spec: + interval: 5m + releaseName: eg + chartRef: + kind: OCIRepository + name: gateway-helm + upgrade: + strategy: + name: RetryOnFailure + retryInterval: 5m +EOF +``` + +**Note**: For simplicity, we apply these manifests directly to the cluster. +In a production environment, it's recommended to store this configuration in a Git or OCI source that Flux reconciles, following a GitOps workflow. + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available +``` + +Install the GatewayClass, Gateway, HTTPRoute and example app: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default +``` + +**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for +traffic on port 80 on its globally-routable IP address, to make it easy to use +browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is +using a privileged port (<1024), it will map this internally to an +unprivileged port, so that Envoy Gateway doesn't need additional privileges. +It's important to be aware of this mapping, since you may need to take it into +consideration when debugging. + +[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml + + +## Helm chart customizations + +You can customize the Envoy Gateway installation by setting Helm chart values on the `HelmRelease`. + +{{% alert title="Helm Chart Values" color="primary" %}} +If you want to know all the available fields inside the values.yaml file, please see the [Helm Chart Values](./gateway-helm-api). +{{% /alert %}} + +Below is an example of how to customize the Envoy Gateway installation by using the `values` field on the `HelmRelease`. + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: envoy-gateway + namespace: envoy-gateway-system +spec: + interval: 5m + releaseName: eg + chartRef: + kind: OCIRepository + name: gateway-helm + upgrade: + strategy: + name: RetryOnFailure + retryInterval: 5m + values: + deployment: + envoyGateway: + resources: + limits: + cpu: 700m + memory: 256Mi +``` + +For values stored in a `ConfigMap` or `Secret`, or for advanced merge strategies, see the [Flux HelmRelease values reference](https://fluxcd.io/flux/components/helm/helmreleases/#values). + +{{< boilerplate open-ports >}} + +{{% alert title="Next Steps" color="warning" %}} +Envoy Gateway should now be successfully installed and running. To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks). +{{% /alert %}} diff --git a/site/content/en/v1.8/install/install-helm.md b/site/content/en/v1.8/install/install-helm.md new file mode 100644 index 0000000000..18da890f8f --- /dev/null +++ b/site/content/en/v1.8/install/install-helm.md @@ -0,0 +1,189 @@ ++++ +title = "Install with Helm" +weight = -100 ++++ + +[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. + +Envoy Gateway can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Envoy Gateway from an existing installation, or migrating from Envoy Gateway. + +## Before you begin + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more. +{{% /alert %}} + +{{< boilerplate kind-cluster >}} + +The Envoy Gateway Helm chart is hosted by DockerHub. + +It is published at `oci://docker.io/envoyproxy/gateway-helm`. + +{{% alert title="Note" color="primary" %}} +We use `v0.0.0-latest` as the latest development version. + +You can visit [Envoy Gateway Helm Chart](https://hub.docker.com/r/envoyproxy/gateway-helm/tags) for more releases. +{{% /alert %}} + +## Install with Helm + +Install the Gateway API CRDs and Envoy Gateway: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace +``` + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available +``` + +Install the GatewayClass, Gateway, HTTPRoute and example app: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default +``` + +**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for +traffic on port 80 on its globally-routable IP address, to make it easy to use +browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is +using a privileged port (<1024), it will map this internally to an +unprivileged port, so that Envoy Gateway doesn't need additional privileges. +It's important to be aware of this mapping, since you may need to take it into +consideration when debugging. + +[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml + +## Installing CRDs separately + +The [Envoy Gateway Helm Chart](https://hub.docker.com/r/envoyproxy/gateway-helm/tags) includes two types of CRDs under its crds/ directory: +* [Gateway API CRDs](../concepts/#gateway-api) (from the *experimental* channel): This channel includes additional `alpha` resources +such as `TCPRoute` and `BackendTLSPolicy`, which are commonly used by Envoy Gateway users. +* [Envoy Gateway CRDs](../concepts/gateway_api_extensions/): These are custom CRDs that extend the Gateway API to support additional +Envoy Gateway-specific features. + +If you prefer to manage CRDs separately, the [Envoy Gateway CRDs Helm Chart](https://hub.docker.com/r/envoyproxy/gateway-crds-helm/tags) allows you +to install just the CRDs, with fine-grained control over: +* Which Gateway API channel to use (`standard` or `experimental`) +* Whether to include Envoy Gateway-specific CRDs + +Use the following command to install the CRDs using `helm template` and `kubectl` + +```shell +helm template eg oci://docker.io/envoyproxy/gateway-crds-helm \ + --version {{< helm-version >}} \ + --set crds.gatewayAPI.enabled=true \ + --set crds.gatewayAPI.channel=standard \ + --set crds.envoyGateway.enabled=true \ + | kubectl apply --server-side -f - +``` + +**Note**: We're using `helm template` piped into `kubectl apply` instead of `helm install` due to a [known Helm limitation](https://github.com/helm/helm/pull/12277) +related to large CRDs in the `templates/` directory. + +Once the CRDs are installed, you can install the main Envoy Gateway Helm chart without re-applying CRDs by using the `--skip-crds` flag: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm \ + --version {{< helm-version >}} \ + -n envoy-gateway-system \ + --create-namespace \ + --skip-crds +``` + +## Upgrading from the previous version + +[Helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations) does not update CRDs +that live in the `/crds` folder in the Helm Chart. So you will manually need to update the CRDs. +Follow the steps outlined in [this](./install-yaml/#upgrading-from-the-previous-version) section if you're upgrading from a previous version. + +Note: make sure to upgrade the CRDs first, then upgrade Envoy Gateway. Otherwise, Envoy Gateway may not find the new CRD versions and could fail to reconcile existing resources. + +## Helm chart customizations + +Some of the quick ways of using the helm install command for envoy gateway installation are below. + +{{% alert title="Helm Chart Values" color="primary" %}} +If you want to know all the available fields inside the values.yaml file, please see the [Helm Chart Values](./gateway-helm-api). +{{% /alert %}} + +### Enable Backend API + +The Backend API is not enabled by default. Enable it via Helm values: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace --set config.envoyGateway.extensionApis.enableBackend=true +``` + +Or with a `values.yaml` file: + +```yaml +config: + envoyGateway: + extensionApis: + enableBackend: true +``` + +Then install using the file: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace -f values.yaml +``` + +### Increase the replicas + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace --set deployment.replicas=2 +``` + +### Change the kubernetesClusterDomain name + +If you have installed your cluster with different domain name you can use below command. + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace --set kubernetesClusterDomain= +``` + +**Note**: Above are some of the ways we can directly use for customization of our installation. But if you are looking for more complex changes [values.yaml](https://helm.sh/docs/chart_template_guide/values_files/) comes to rescue. + +### Using values.yaml file for complex installation + +```yaml +deployment: + envoyGateway: + resources: + limits: + cpu: 700m + memory: 128Mi + requests: + cpu: 10m + memory: 64Mi + ports: + - name: grpc + port: 18005 + targetPort: 18000 + - name: ratelimit + port: 18006 + targetPort: 18001 + +config: + envoyGateway: + logging: + level: + default: debug +``` + +Here we have made three changes to our values.yaml file. Increase the resources limit for cpu to `700m`, changed the port for grpc to `18005` and for ratelimit to `18006` and also updated the logging level to `debug`. + +You can use the below command to install the envoy gateway using values.yaml file. + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace -f values.yaml +``` + +{{< boilerplate open-ports >}} + +{{% alert title="Next Steps" color="warning" %}} +Envoy Gateway should now be successfully installed and running. To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks). +{{% /alert %}} diff --git a/site/content/en/v1.8/install/install-yaml.md b/site/content/en/v1.8/install/install-yaml.md new file mode 100644 index 0000000000..71bbab53fd --- /dev/null +++ b/site/content/en/v1.8/install/install-yaml.md @@ -0,0 +1,56 @@ ++++ +title = "Install with Kubernetes YAML" +weight = -98 ++++ + +This task walks you through installing Envoy Gateway in your Kubernetes cluster. + +The manual installation process does not allow for as much configuration control (e.g. when you are using a custom domain Kubernetes cluster) +as the [Helm install method](./install-helm), so if you need more control over your Envoy Gateway +installation, it is recommended that you use helm. + +## Before you begin + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more. +{{% /alert %}} + +{{< boilerplate kind-cluster >}} + +## Install with YAML + +1. In your terminal, run the following command: + + ```shell + kubectl apply --server-side -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/install.yaml + ``` + +2. Next Steps + + Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [Tasks](/latest/tasks). + +## Upgrading from the previous version + +Some manual migration steps are required to upgrade Envoy Gateway. + +1. Update Gateway-API and Envoy Gateway CRDs: + +```shell +helm template eg-crds oci://docker.io/envoyproxy/gateway-crds-helm \ + --version {{< yaml-version >}} \ + --set crds.gatewayAPI.enabled=true \ + --set crds.envoyGateway.enabled=true \ + | kubectl apply --force-conflicts --server-side -f - +``` + +2. Install Envoy Gateway {{< yaml-version >}}: + +```shell +helm upgrade eg oci://docker.io/envoyproxy/gateway-helm --version {{< yaml-version >}} -n envoy-gateway-system +``` + +{{< boilerplate open-ports >}} + +{{% alert title="Next Steps" color="warning" %}} +Envoy Gateway should now be successfully installed and running. To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks). +{{% /alert %}} diff --git a/site/content/en/v1.8/install/migrating-to-envoy.md b/site/content/en/v1.8/install/migrating-to-envoy.md new file mode 100644 index 0000000000..af5011ebc4 --- /dev/null +++ b/site/content/en/v1.8/install/migrating-to-envoy.md @@ -0,0 +1,295 @@ +--- +title: Migrating from Ingress Resources +--- + +## Introduction + +Migrating from Ingress to Envoy Gateway involves converting existing Ingress resources into resources compatible with Envoy Gateway. Two tools are available to help with this migration: + +### ingress2gateway + +The official `ingress2gateway` tool (maintained by Kubernetes SIG-Network) transforms Ingress resources into Gateway API resources. + +### ingress2eg + +The `ingress2eg` tool is an **unofficial proof-of-concept** forked from ingress2gateway with additional capabilities: + +- **NGINX Annotation Support**: Converts NGINX-specific annotations (16+ feature categories including session affinity, authentication, rate limiting, CORS, canary deployments, etc.) +- **Envoy Gateway CRD Output**: Generates not only Gateway API resources (Gateway, HTTPRoute) but also Envoy Gateway specific CRDs (BackendTrafficPolicy, SecurityPolicy, etc.) + +We aim to get this feature merged upstream in `ingress2gateway` as well. + +This guide will walk you through the prerequisites, installation of both tools, and provide example migration processes. + +## Prerequisites + +Before you start the migration, ensure you have the following: + +1. **Envoy Gateway Installed**: You need Envoy Gateway set up in your Kubernetes cluster. Follow the [Envoy Gateway installation guide](../install) for details. +2. **Kubernetes Cluster Access**: Ensure you have access to your Kubernetes cluster and necessary permissions to manage resources. +3. **Installation of `ingress2gateway` Tool**: You need to install the `ingress2gateway` tool in your Kubernetes cluster and configure it accordingly. Follow the [ingress2gateway tool installation guide](https://github.com/kubernetes-sigs/ingress2gateway/blob/main/README.md#installation) for details. +4. **Installation of `ingress2eg` Tool**: You need to install the `ingress2eg` tool in your Kubernetes cluster and configure it accordingly. Follow the [ingress2eg tool installation guide](https://github.com/kkk777-7/ingress2eg?tab=readme-ov-file#installation) for details. + +## Example Migration + +Here’s a step-by-step example of migrating from Ingress to Envoy Gateway using `ingress2gateway`: + +### 1. Install and Configure Envoy Gateway + +Ensure that Envoy Gateway is installed and running in your cluster. Follow the [official Envoy Gateway installation guide](../install) for setup instructions. + +### 2. Create a GatewayClass + +To ensure the generated HTTPRoutes are programmed correctly in the Envoy Gateway data plane, create a GatewayClass that links to the Envoy Gateway controller. + +Create a `GatewayClass` resource: + +```yaml +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: GatewayClass +metadata: + name: envoy-gateway-class +spec: + controllerName: gateway.envoyproxy.io/controller +``` + +Apply this resource: + +```sh +kubectl apply -f gatewayclass.yaml +``` + +### 3. Install Ingress2gateway + +Ensure you have the Ingress2gateway package installed. If not, follow the package’s installation instructions. + +### 4. Run Ingress2gateway + +Use Ingress2gateway to read your existing Ingress resources and translate them into Gateway API resources. + +```sh +./ingress2gateway print +``` + +This command will: +1. Read your Kube config file to extract the cluster credentials and the current active namespace. +2. Search for Ingress and provider-specific resources in that namespace. +3. Convert them to Gateway API resources (Gateways and HTTPRoutes). + +#### Example Ingress Configuration + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: example-ingress + namespace: default + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / +spec: + rules: + - host: example.com + http: + paths: + - path: /foo + pathType: Prefix + backend: + service: + name: foo-service + port: + number: 80 +``` + +### 5. Save the Output + +The command will output the equivalent Gateway API resources in YAML/JSON format to stdout. Save this output to a file for further use. + +```sh +./ingress2gateway print > gateway-resources.yaml +``` + +### 6. Apply the Translated Resources + +Apply the translated Gateway API resources to your cluster. + +```sh +kubectl apply -f gateway-resources.yaml +``` + +### 7. Create a Gateway Resource + +Create a `Gateway` resource specifying the `GatewayClass` created earlier and including the necessary listeners. + +```yaml +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: example-gateway + namespace: default +spec: + gatewayClassName: envoy-gateway-class + listeners: + - name: http + protocol: HTTP + port: 80 + hostname: example.com +``` + +Apply this resource: + +```sh +kubectl apply -f gateway.yaml +``` + +### 8. Validate the Migration + +Ensure the HTTPRoutes and Gateways are correctly set up and that traffic is being routed as expected. Validate the new configuration by checking the status of the Gateway and HTTPRoute resources. + +```sh +kubectl get gateways +kubectl get httproutes +``` + +### 9. Monitor and Troubleshoot + +Monitor the Envoy Gateway logs and metrics to ensure everything is functioning correctly. Troubleshoot any issues by reviewing the Gateway and HTTPRoute statuses and Envoy Gateway controller logs. + +## Example Migration using ingress2eg + +The `ingress2eg` tool provides extended support for NGINX-specific annotations and generates Envoy Gateway CRD resources in addition to Gateway API resources. Follow steps 1-2 from the ingress2gateway example above for Envoy Gateway installation and GatewayClass creation. + +### 1. Install ingress2eg + +Ensure you have the ingress2eg tool installed. Follow the [installation guide](https://github.com/kkk777-7/ingress2eg?tab=readme-ov-file#installation) for details. + +### 2. Prepare Ingress with NGINX Annotations + +Here's an example Ingress resource using NGINX annotations for rate limiting and CORS: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: example-ingress-nginx + namespace: default + annotations: + nginx.ingress.kubernetes.io/limit-rps: "10" + nginx.ingress.kubernetes.io/enable-cors: "true" + nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, OPTIONS" + nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com" +spec: + rules: + - host: example.com + http: + paths: + - path: /api + pathType: Prefix + backend: + service: + name: api-service + port: + number: 80 +``` + +### 3. Run ingress2eg + +Use ingress2eg to convert the Ingress resources. The tool supports various options: + +```sh +# Convert from cluster resources in a specific namespace +ingress2eg print --namespace default + +# Convert from a file +ingress2eg print --input-file ingress.yaml +``` + +### 4. Review Generated Resources + +For the above Ingress example, ingress2eg generates the following resources: + +**Gateway API Resources:** +- Gateway +- HTTPRoute + +**Envoy Gateway CRD Resources:** +- **BackendTrafficPolicy**: Generated from rate limiting annotation (`limit-rps`) +- **SecurityPolicy**: Generated from CORS annotations (`enable-cors`, `cors-allow-methods`, `cors-allow-origin`) + +Generated BackendTrafficPolicy (from the `limit-rps` annotation): + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: rate-limit-policy + namespace: default +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: example-httproute + rateLimit: + type: Local + local: + rules: + - clientSelectors: + - sourceCIDR: + type: Distinct + value: 0.0.0.0/0 + limit: + requests: 10 + unit: Second +``` + +Generated SecurityPolicy (from the CORS annotations): + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: cors-policy + namespace: default +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: example-httproute + cors: + allowOrigins: + - "https://example.com" + allowMethods: + - GET + - POST + - OPTIONS +``` + +### 5. Apply the Generated Resources + +Save the output and apply all resources to your cluster: + +```sh +ingress2eg print --namespace default > gateway-resources.yaml +kubectl apply -f gateway-resources.yaml +``` + +### 6. Validate the Migration + +Verify that all resources are created correctly: + +```sh +kubectl get gateways +kubectl get httproutes +kubectl get backendtrafficpolicies +kubectl get securitypolicies +``` + +Check the status of the policies to ensure they are accepted: + +```sh +kubectl describe backendtrafficpolicy rate-limit-policy +kubectl describe securitypolicy cors-policy +``` + +## Summary + +By following this guide, users can effectively migrate their existing Ingress resources to Envoy Gateway using the Ingress2gateway, Ingress2eg package. Creating a GatewayClass and linking it to the Envoy Gateway controller ensures that the translated resources are properly programmed in the data plane, providing a seamless transition to the Envoy Gateway environment. \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/_index.md b/site/content/en/v1.8/tasks/_index.md new file mode 100644 index 0000000000..49e8595328 --- /dev/null +++ b/site/content/en/v1.8/tasks/_index.md @@ -0,0 +1,5 @@ +--- +title: "Tasks" +weight: 2 +description: Learn Envoy Gateway hands-on through tasks +--- diff --git a/site/content/en/v1.8/tasks/extensibility/_index.md b/site/content/en/v1.8/tasks/extensibility/_index.md new file mode 100644 index 0000000000..9254243470 --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/_index.md @@ -0,0 +1,19 @@ +--- +title: "Extensibility" +weight: 4 +description: This section includes Extensibility tasks. +--- + +Envoy Gateway provides several ways to extend its functionality beyond the built-in features. + +## Extension Options + +**Need access to Envoy Proxy features not available through the API ?** +- [Envoy Patch Policy](envoy-patch-policy) - Directly modify Envoy xDS configuration +- [Extension Server](extension-server) - Build external services to transform xDS configuration + +**Want to add custom processing logic?** +- [WASM Extensions](wasm) - Run WebAssembly modules for high-performance custom logic +- [External Processing](ext-proc) - Call external gRPC services during request processing +- [Lua Extensions](lua) - Write lightweight scripting extensions +- [Dynamic Modules](dynamic-modules) - Load custom C++ modules at runtime for advanced extensibility diff --git a/site/content/en/v1.8/tasks/extensibility/build-wasm-image.md b/site/content/en/v1.8/tasks/extensibility/build-wasm-image.md new file mode 100644 index 0000000000..e12a9f361d --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/build-wasm-image.md @@ -0,0 +1,71 @@ +--- +title: "Build a Wasm image" +--- + +Envoy Gateway supports two types of Wasm extensions within the [EnvoyExtensionPolicy][] API: HTTP Wasm Extensions and Image Wasm Extensions. +Packaging a Wasm extension as an OCI image is beneficial because it simplifies versioning and distribution for users. +Additionally, users can leverage existing image toolchain to build and manage Wasm images. + +This document describes how to build OCI images which are consumable by Envoy Gateway. + +## Wasm Image Formats + +There are two types of images that are supported by Envoy Gateway. One is in the Docker format, and another is the standard +OCI specification compliant format. Please note that both of them are supported by any OCI registries. You can choose +either format depending on your preference, and both types of images are consumable by Envoy Gateway [EnvoyExtensionPolicy][] API. + +## Build Wasm Docker image + +We assume that you have a valid Wasm binary named `plugin.wasm`. Then you can build a Wasm Docker image with the Docker CLI. + +1. First, we prepare the following Dockerfile: + +``` +$ cat Dockerfile +FROM scratch + +COPY plugin.wasm ./ +``` + +**Note: you must have exactly one `COPY` instruction in the Dockerfile in order to end up having only one layer in produced images.** + +2. Then, build your image via `docker build` command + +``` +$ docker build . -t my-registry/mywasm:0.1.0 +``` + +3. Finally, push the image to your registry via `docker push` command + +``` +$ docker push my-registry/mywasm:0.1.0 +``` + +## Build Wasm OCI image + +We assume that you have a valid Wasm binary named `plugin.wasm`, and you have [buildah](https://buildah.io/) installed on your machine. +Then you can build a Wasm OCI image with the `buildah` CLI. + +1. First, we create a working container from `scratch` base image with `buildah from` command. + +``` +$ buildah --name mywasm from scratch +mywasm +``` + +2. Then copy the Wasm binary into that base image by `buildah copy` command to create the layer. + +``` +$ buildah copy mywasm plugin.wasm ./ +af82a227630327c24026d7c6d3057c3d5478b14426b74c547df011ca5f23d271 +``` + +**Note: you must execute `buildah copy` exactly once in order to end up having only one layer in produced images** + +4. Now, you can build an OCI image and push it to your registry via `buildah commit` command + +``` +$ buildah commit mywasm docker://my-remote-registry/mywasm:0.1.0 +``` + +[EnvoyExtensionPolicy]: ../../../api/extension_types#envoyextensionpolicy diff --git a/site/content/en/v1.8/tasks/extensibility/dynamic-modules.md b/site/content/en/v1.8/tasks/extensibility/dynamic-modules.md new file mode 100644 index 0000000000..dd02b428a1 --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/dynamic-modules.md @@ -0,0 +1,256 @@ +--- +title: "Dynamic Modules" +--- + +This task provides instructions for configuring [Dynamic Modules](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/dynamic_modules). + +Dynamic Modules are a critical extension mechanism that allows functionality to be loaded directly into the Envoy proxy process at runtime, typically as shared object files (`.so`). This approach enables customized filtering and request processing without requiring a full recompile of the core Envoy binary, streamlining deployments and upgrades. + +Envoy Gateway is able to load dynamic modules from the local filesystem using [EnvoyExtensionPolicy][]. This example demonstrates it's working by loading the [Coraza](https://www.coraza.io/) Web Application Firewall (WAF) using [Built On Envoy](https://builtonenvoy.io/) development toolkit. The module's full documentation can be found on the [Coraza WAF extension page](https://builtonenvoy.io/extensions/coraza-waf/). + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Coraza WAF Extension + +### Installation + +Add the dynamic module to the Envoy proxy container's filesystem and configure the [DynamicModules][] spec to load it into Envoy. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +**Note: verify version compatibility of the extension because of dynamic module forward compatibility.** + +[Image Volumes](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/) are relatively new and only supported from Kubernetes `1.35` onwards. +Alternative ways of loading the dynamic module are: +- Building a custom docker image +- Copying from `InitContainer` to a shared volume + + +Verify the [EnvoyProxy][] status: + +```shell +kubectl get envoyproxy/my-proxy -o yaml +``` + +Attach to Gateway via a GatewayClass with `spec.parametersRef` + +```shell +kubectl patch gatewayclass eg --type=merge -p '{ + "spec": { + "parametersRef": { + "group": "gateway.envoyproxy.io", + "kind": "EnvoyProxy", + "name": "my-proxy", + "namespace": "envoy-gateway-system" + } + } +}' +``` + +The entire configuration can also be specified directly on the Gateway instead by using `spec.envoyProxy`. + +### Configuration + +Create a new EnvoyExtensionPolicy resource to configure the dynamic module for an entire Gateway or per HTTPRoute. + +This EnvoyExtensionPolicy targets the Gateway "eg" created with the quickstart. It loads the Coraza WAF extension with its configuration. + + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the Envoy Extension Policy configuration: + +```shell +kubectl get envoyextensionpolicy/waf-extension -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a normal request to the backend service: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/" +``` + +You should get a `200 OK` response from the backend. + +Now send a request with a SQL injection payload to trigger the WAF: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/?id=1'+OR+'1'%3D'1" +``` + +The Coraza WAF should block the request and return a `403 Forbidden` response: + +``` +> GET /?id=1'+OR+'1'='1 HTTP/1.1 +> Host: www.example.com +[...] +< HTTP/1.1 403 Forbidden +< date: Sat, 03 May 2026 12:00:00 GMT +< content-length: 0 +< +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the [EnvoyProxy][] and [EnvoyExtensionPolicy][]: + +```shell +kubectl delete envoyproxy/my-proxy +kubectl delete envoyextensionpolicy/waf-extension +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[EnvoyProxy]: ../../../api/extension_types#envoyproxy +[EnvoyExtensionPolicy]: ../../../api/extension_types#envoyextensionpolicy +[DynamicModules]: ../../../api/extension_types#dynamicmoduleentry diff --git a/site/content/en/v1.8/tasks/extensibility/envoy-patch-policy.md b/site/content/en/v1.8/tasks/extensibility/envoy-patch-policy.md new file mode 100644 index 0000000000..ae08eb26ac --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/envoy-patch-policy.md @@ -0,0 +1,536 @@ +--- +title: "Envoy Patch Policy" +--- + +This task explains the usage of the [EnvoyPatchPolicy][] API. +__Note:__ This API is meant for users extremely familiar with Envoy [xDS][] semantics. +Also before considering this API for production use cases, please be aware that this API +is unstable and the outcome may change across versions. Use at your own risk. + +## Introduction + +The [EnvoyPatchPolicy][] API allows user to modify the output [xDS][] +configuration generated by Envoy Gateway intended for EnvoyProxy, +using [JSON Patch][] semantics. + +## Motivation + +This API was introduced to allow advanced users to be able to leverage Envoy Proxy functionality +not exposed by Envoy Gateway APIs today. + +## Security Warning + +{{% alert title="Security Warning" color="warning" %}} +Enabling `EnvoyPatchPolicy` may lead to complete security compromise of your system. +Users with `EnvoyPatchPolicy` permissions can inject arbitrary configuration to proxies, +leading to high Confidentiality, Integrity and Availability risks. + +Injected configuration may include arbitrary code executed by the proxy without any isolation. Such code may be used +to launch SSRF attacks, as well as allow users to gain access to proxy credentials as described in [CVE-2026-22771][]. +With such access, users can fetch the complete proxy configuration, including secrets and cluster network topology. + +When enabling `EnvoyPatchPolicy`, additional security measures should be taken by admins to reduce security risks, including: +* Using K8s [RBAC][] to restrict access to `EnvoyPatchPolicy`. +* Disabling envoy extensions which are not needed with envoy [command line options][]. +* Implementing Kubernetes [network policies][] that restrict traffic from the proxy pod only to relevant targets. +* Use [admission control][] tools to validate `EnvoyPatchPolicy` resources, ensuring that only approved patches admitted. +* Audit `EnvoyPatchPolciy` resources periodically, and [audit log][] `EnvoyPatchPolicy` API server operations. +{{% /alert %}} + +## Quickstart + +### Prerequisites + +{{< boilerplate prerequisites >}} + +### Enable EnvoyPatchPolicy + +* By default [EnvoyPatchPolicy][] is disabled. Lets enable it in the [EnvoyGateway][] startup configuration + +* The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and attaches it +using a `ConfigMap`. In the next step, we will update this resource to enable EnvoyPatchPolicy. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +## XDS Name Scheme V2 + +Starting from v1.5, Envoy Gateway uses version 2 of the xDS name scheme when generating xDS resources. +Because [EnvoyPatchPolicy][] relies on specific xDS resource names, it’s important to use the correct naming format when authoring a patch policy. + +| Component | Scheme Version | Format Description | Example | +|----------------------|----------------|------------------------------------------------------------------------------|----------------------------------| +| **Listener name** | Old | `//` | `default/eg/http` | +| | V2 | `-` | `tcp-80` | +| **RouteConfig name** | Old | `//` | `default/eg/http` | +| | V2 (HTTP) | `http-` | `http-80` | +| | V2 (HTTPS) | `//` | `default/eg/https` | +| **FilterChain name** | Old | `//` | `default/eg/http` | +| | V2 (HTTP) | `http-` | `http-80` | +| | V2 (HTTPS) | `//` | `default/eg/https` | +| **VirtualHost name** | Old | `///` | `default/eg/http/www_example_com` | +| | V2 | `` | `www_example_com` | +| **HCM StatPrefix** | Old | `/` | `http-10080`, `https-10443` | +| | V2 (HTTP) | `http-` | `http-80` | +| | V2 (HTTPS) | `https-` | `https-443` | + + +This change is gated by the XDSNameSchemeV2 runtime flag. The flag is disabled by default in v1.5 and will be enabled by default starting in v1.10. + +We recommend users begin migrating their [EnvoyPatchPolicy][] resources to use the version 2 naming scheme before upgrading to v1.10. + +To opt in to the new naming scheme early, add the`XDSNameSchemeV2` runtime flag to the `runtimeFlags.enabled` field in your [EnvoyGateway][] configuration. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing + +### Customize Response + +* Use EnvoyProxy's [Local Reply Modification][] feature to return a custom response back to the client when +the status code is `404` + +* Apply the configuration + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <// + name: default/eg/http + operation: + op: add + path: "/default_filter_chain/filters/0/typed_config/local_reply_config" + value: + mappers: + - filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + runtime_key: key_b + status_code: 406 + body: + inline_string: "could not find what you are looking for" +EOF +``` + +{{% /tab %}} +{{% tab header="Apply from file" %}} +Save and apply the following resource to your cluster: + +```yaml +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyPatchPolicy +metadata: + name: custom-response-patch-policy + namespace: default +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg + type: JSONPatch + jsonPatches: + - type: "type.googleapis.com/envoy.config.listener.v3.Listener" + # The listener name is of the form // + name: default/eg/http + operation: + op: add + path: "/default_filter_chain/filters/0/typed_config/local_reply_config" + value: + mappers: + - filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + runtime_key: key_b + status_code: 406 + body: + inline_string: "could not find what you are looking for" +``` + +{{% /tab %}} +{{< /tabpane >}} + +When mergeGateways is enabled, there will be one Envoy deployment for all Gateways in the cluster. +Then the EnvoyPatchPolicy should target a specific GatewayClass. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <// + name: default/eg/http + operation: + op: add + path: "/default_filter_chain/filters/0/typed_config/local_reply_config" + value: + mappers: + - filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + runtime_key: key_b + status_code: 406 + body: + inline_string: "could not find what you are looking for" +EOF +``` + +{{% /tab %}} +{{% tab header="Apply from file" %}} +Save and apply the following resource to your cluster: + +```yaml +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyPatchPolicy +metadata: + name: custom-response-patch-policy + namespace: default +spec: + targetRef: + group: gateway.networking.k8s.io + kind: GatewayClass + name: eg + type: JSONPatch + jsonPatches: + - type: "type.googleapis.com/envoy.config.listener.v3.Listener" + # The listener name is of the form // + name: default/eg/http + operation: + op: add + path: "/default_filter_chain/filters/0/typed_config/local_reply_config" + value: + mappers: + - filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + runtime_key: key_b + status_code: 406 + body: + inline_string: "could not find what you are looking for" +``` + +{{% /tab %}} +{{< /tabpane >}} + +* Edit the HTTPRoute resource from the Quickstart to only match on paths with value `/get` + +```shell +kubectl patch httproute backend --type=json --patch ' + - op: add + path: /spec/rules/0/matches/0/path/value + value: /get + ' +``` + +* Test it out by specifying a path apart from `/get` + +```shell +$ curl --header "Host: www.example.com" http://$GATEWAY_HOST/find +Handling connection for 8888 +could not find what you are looking for +``` + +### Customize VirtualHost by name + +* Use EnvoyProxy's `include_attempt_count_in_response` feature to include the attempt count as header in the downstream response. +* Apply the configuration + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <// + name: default/eg/http + operation: + op: add + # Every virtual_host that ends with 'www_example_com' (using RegEx Filter) + jsonPath: "..virtual_hosts[?match(@.name, '.*www_example_com')]" + # If the property does not exists, it can not be selected with jsonPath + # Therefore the new property must be set in path + path: "include_attempt_count_in_response" + value: true +EOF +``` + +{{% /tab %}} +{{% tab header="Apply from file" %}} +Save and apply the following resource to your cluster: + +```yaml +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyPatchPolicy +metadata: + name: include-attempts + namespace: default +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg + type: JSONPatch + jsonPatches: + - type: "type.googleapis.com/envoy.config.route.v3.RouteConfiguration" + # The RouteConfiguration name is of the form // + name: default/eg/http + operation: + op: add + # Every virtual_host that ends with 'www_example_com' (using RegEx Filter) + jsonPath: "..virtual_hosts[?match(@.name, '.*www_example_com')]" + # If the property does not exists, it can not be selected with jsonPath + # Therefore the new property must be set in path + path: "include_attempt_count_in_response" + value: true +``` + +{{% /tab %}} +{{< /tabpane >}} + +* Test it out by looking at the response headers + +``` +$ curl -v --header "Host: www.example.com" http://localhost:8888/ +... +< x-envoy-attempt-count: 1 +... +``` + +## Debugging + +### Runtime + +* The `Status` subresource should have information about the status of the resource. Make sure +`Accepted=True` and `Programmed=True` conditions are set to ensure that the policy has been +applied to Envoy Proxy. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyPatchPolicy +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"gateway.envoyproxy.io/v1alpha1","kind":"EnvoyPatchPolicy","metadata":{"annotations":{},"name":"custom-response-patch-policy","namespace":"default"},"spec":{"jsonPatches":[{"name":"default/eg/http","operation":{"op":"add","path":"/default_filter_chain/filters/0/typed_config/local_reply_config","value":{"mappers":[{"body":{"inline_string":"could not find what you are looking for"},"filter":{"status_code_filter":{"comparison":{"op":"EQ","value":{"default_value":404}}}}}]}},"type":"type.googleapis.com/envoy.config.listener.v3.Listener"}],"priority":0,"targetRef":{"group":"gateway.networking.k8s.io","kind":"Gateway","name":"eg","namespace":"default"},"type":"JSONPatch"}} + creationTimestamp: "2023-07-31T21:47:53Z" + generation: 1 + name: custom-response-patch-policy + namespace: default + resourceVersion: "10265" + uid: a35bda6e-a0cc-46d7-a63a-cee765174bc3 +spec: + jsonPatches: + - name: default/eg/http + operation: + op: add + path: /default_filter_chain/filters/0/typed_config/local_reply_config + value: + mappers: + - body: + inline_string: could not find what you are looking for + filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + type: type.googleapis.com/envoy.config.listener.v3.Listener + priority: 0 + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg + type: JSONPatch +status: + conditions: + - lastTransitionTime: "2023-07-31T21:48:19Z" + message: EnvoyPatchPolicy has been accepted. + observedGeneration: 1 + reason: Accepted + status: "True" + type: Accepted + - lastTransitionTime: "2023-07-31T21:48:19Z" + message: successfully applied patches. + reason: Programmed + status: "True" + type: Programmed +``` + +### Offline + +* You can use [egctl x translate][] to validate the translated xds output. + +## Caveats + +This API will always be an unstable API and the same outcome cannot be guaranteed +across versions for these reasons +* The Envoy Proxy API might deprecate and remove API fields +* Envoy Gateway might alter the xDS translation creating a different xDS output +such as changing the `name` field of resources. + +[EnvoyPatchPolicy]: ../../../api/extension_types#envoypatchpolicy +[CVE-2026-22771]: https://github.com/envoyproxy/gateway/security/advisories/GHSA-xrwg-mqj6-6m22 +[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ +[command line options]: ../operations/customize-envoyproxy/#customize-envoyproxy-command-line-options +[network policies]: https://kubernetes.io/docs/concepts/services-networking/network-policies/ +[admission control]: https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/ +[audit log]: https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/ +[EnvoyGateway]: ../../../api/extension_types#envoygateway +[JSON Patch]: https://datatracker.ietf.org/doc/html/rfc6902 +[xDS]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/dynamic_configuration +[Local Reply Modification]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/local_reply +[egctl x translate]: ../operations/egctl#egctl-experimental-translate diff --git a/site/content/en/v1.8/tasks/extensibility/ext-proc.md b/site/content/en/v1.8/tasks/extensibility/ext-proc.md new file mode 100644 index 0000000000..65ebfbc81e --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/ext-proc.md @@ -0,0 +1,281 @@ +--- +title: "External Processing" +--- + +This task provides instructions for configuring external processing. + +External processing calls an external gRPC service to process HTTP requests and responses. +The external processing service can inspect and mutate requests and responses. + +Envoy Gateway introduces a new CRD called [EnvoyExtensionPolicy][] that allows the user to configure external processing. +This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute][HTTPRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## GRPC External Processing Service + +### Installation + +Install a demo GRPC service that will be used as the external processing service: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-proc-grpc-service.yaml +``` + +Create a new HTTPRoute resource to route traffic on the path `/myapp` to the backend service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute status: + +```shell +kubectl get httproute/myapp -o yaml +``` + +### Configuration + +Create a new EnvoyExtensionPolicy resource to configure the external processing service. This EnvoyExtensionPolicy targets the HTTPRoute +"myApp" created in the previous step. It calls the GRPC external processing service "grpc-ext-proc" on port 9002 for +processing. + +By default, requests and responses are not sent to the external processor. The `processingMode` struct is used to define what should be sent to the external processor. +In this example, we configure the following processing modes: +* The empty `request` field configures envoy to send request headers to the external processor. +* The `response` field includes configuration for body processing. As a result, response headers are sent to the external processor. Additionally, the response body is streamed to the external processor. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the Envoy Extension Policy configuration: + +```shell +kubectl get envoyextensionpolicy/ext-proc-example -o yaml +``` + + +Because the gRPC external processing service is enabled with TLS, a [BackendTLSPolicy][] needs to be created to configure +the communication between the Envoy proxy and the gRPC auth service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the BackendTLSPolicy configuration: + +```shell +kubectl get backendtlspolicy/grpc-ext-proc-btls -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `Authentication` header: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/myapp" +``` + +You should see that the external processor added headers: +- `x-request-ext-processed` - this header was added before the request was forwarded to the backend +- `x-response-ext-processed`- this header was added before the response was returned to the client + + +``` +curl -v -H "Host: www.example.com" http://localhost:10080/myapp +[...] +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Fri, 14 Jun 2024 19:30:40 GMT +< content-length: 502 +< x-response-ext-processed: true +< +{ + "path": "/myapp", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { +[...] + "X-Request-Ext-Processed": [ + "true" + ], +[...] + } +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the demo auth services, HTTPRoute, EnvoyExtensionPolicy and BackendTLSPolicy: + +```shell +kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-proc-grpc-service.yaml +kubectl delete httproute/myapp +kubectl delete envoyextensionpolicy/ext-proc-example +kubectl delete backendtlspolicy/grpc-ext-proc-btls +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[EnvoyExtensionPolicy]: ../../../api/extension_types#envoyextensionpolicy +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute diff --git a/site/content/en/v1.8/tasks/extensibility/extension-server.md b/site/content/en/v1.8/tasks/extensibility/extension-server.md new file mode 100644 index 0000000000..aa28fb82ce --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/extension-server.md @@ -0,0 +1,397 @@ +--- +title: "Envoy Gateway Extension Server" +linkTitle: "Extension Server" +--- + +This task explains how to extend Envoy Gateway using an Extension Server. Envoy Gateway +can be configured to call an external server over gRPC with the xDS configuration _before_ +it is sent to Envoy Proxy. The external server can modify the provided configuration +programmatically using any semantics supported by the [xDS][] API. + +Using an extension server allows vendors to add xDS configuration that Envoy Gateway itself +doesn't support with a very high level of control over the generated xDS configuration. + +**Note:** Modifying the xDS configuration generated by Envoy Gateway may break functionality +configured by native Envoy Gateway means. Like other cases where the xDS configuration +is modified outside of Envoy Gateway's control, this is risky and should be tested thoroughly, +especially when using the same extension server across different Envoy Gateway versions. + +## Introduction + +One of the Envoy Gateway project goals is to "provide a common foundation for vendors to +build value-added products without having to re-engineer fundamental interactions". The +Envoy Gateway Extension Server provides a mechanism where Envoy Gateway tracks all provider +resources and then calls a set of hooks that allow the generated xDS configuration to be +modified before it is sent to Envoy Proxy. See the [design documentation][] for full details. + +## Security Warning + +{{% alert title="Security Warning" color="warning" %}} +Enabling an Extension Server may lead to complete security compromise of your system. +Users that control the Extension Server can inject arbitrary configuration to proxies, +leading to high Confidentiality, Integrity and Availability risks. + +Injected configuration may include arbitrary code executed by the proxy without any isolation. Such code may be used +to launch SSRF attacks, as well as allow users to gain access to proxy credentials as described in [CVE-2026-22771][]. +With such access, users can fetch the complete proxy configuration, including secrets and cluster network topology. + +When enabling Extension Server, additional security measures should be taken by admins to reduce security risks, including: +* Using K8s [RBAC][] to restrict access to the Envoy Gateway Configuration as well as the Extension Server deployment. +* Disabling envoy extensions which are not needed with envoy [command line options][]. +* Implementing Kubernetes [network policies][] that restrict traffic from the proxy pod only to relevant targets. + {{% /alert %}} + +## Extension Hooks Overview + +Envoy Gateway provides several extension hooks that are called at different stages of the xDS translation process. These hooks allow extensions to modify various aspects of the generated xDS configuration: + +### Available Hooks + +| Hook Type | Hook Method Name | Purpose | Resources Modified | Execution Context | +|-----------|------------------|---------|-------------------|-------------------| +| `Route` | `PostRouteModifyHook` | Modify individual routes | Single `envoy.config.route.v3.Route` | Per-route, only for routes with extension filters | +| `Cluster` | `PostClusterModifyHook` | Modify clusters for custom backends | Single `envoy.config.cluster.v3.Cluster` | Per-cluster, only for custom backend clusters | +| `VirtualHost` | `PostVirtualHostModifyHook` | Modify virtual hosts and add custom routes | Single `envoy.config.route.v3.VirtualHost` | Per-virtual-host | +| `HTTPListener` | `PostHTTPListenerModifyHook` | Modify HTTP listeners | Single `envoy.config.listener.v3.Listener` | Per-listener | +| `Translation` | `PostTranslateModifyHook` | Global modification of all xDS resources | All clusters, secrets, listeners, and routes | Once per translation cycle | + +### Hook Execution Order + +The hooks are executed in the following order during xDS translation: + +1. **Route Processing Phase** + - `Route` hook (`PostRouteModifyHook`): Called for each route that has extension filters attached + - `Cluster` hook (`PostClusterModifyHook`): Called for each cluster generated from custom backend references + +2. **Virtual Host Processing Phase** + - `VirtualHost` hook (`PostVirtualHostModifyHook`): Called for each virtual host after all routes are processed + +3. **Listener Processing Phase** + - `HTTPListener` hook (`PostHTTPListenerModifyHook`): Called for each HTTP listener after virtual hosts are configured + +4. **Final Translation Phase** + - `Translation` hook (`PostTranslateModifyHook`): Called once with all generated clusters, secrets, listeners, and routes + +### Hook Details + +#### Route Hook (`PostRouteModifyHook`) + +- **When called**: After each individual route is generated from an HTTPRoute with extension filters +- **Input**: Single route, hostnames, and extension resources from the HTTPRoute +- **Output**: Modified route +- **Use cases**: Add route-specific filters, modify route configuration, add typed per-filter config + +#### Cluster Hook (`PostClusterModifyHook`) + +- **When called**: During cluster generation for custom backend references only +- **Input**: Single cluster and extension resources from the backend reference +- **Output**: Modified cluster +- **Use cases**: Configure custom backend clusters, add health checks, modify load balancing + +#### VirtualHost Hook (`PostVirtualHostModifyHook`) + +- **When called**: After all routes for a virtual host are processed +- **Input**: Complete virtual host with all its routes +- **Output**: Modified virtual host (can add/remove/modify routes) +- **Use cases**: Add virtual host-level configuration, inject additional routes + +#### HTTPListener Hook (`PostHTTPListenerModifyHook`) + +- **When called**: After listener is fully configured with all virtual hosts +- **Input**: Complete HTTP listener and associated extension policies +- **Output**: Modified listener +- **Use cases**: Add listener filters, modify listener configuration, add authentication + +#### Translation Hook (`PostTranslateModifyHook`) + +- **When called**: After all individual resources are generated and processed +- **Input**: All clusters, secrets, listeners, and routes, plus extension policies +- **Output**: Complete set of modified resources +- **Use cases**: Global resource injection, cross-resource modifications, cleanup operations + +### Configuration + +Extensions must specify which hooks they want to use in the `extensionManager.hooks` configuration: + +```yaml +extensionManager: + hooks: + xdsTranslator: + post: + - Route # Enable route modification hook + - VirtualHost # Enable virtual host modification hook + - HTTPListener # Enable HTTP listener modification hook + - Cluster # Enable cluster modification hook + - Translation # Enable global translation hook + # Configure which resources to include in PostTranslateModifyHook + # Default: true for clusters and secrets (for backward compatibility) + # Default: false for listeners and routes (for backward compatibility) + translation: + listener: + includeAll: true + route: + includeAll: true +``` + +This task sets up an example extension server that adds the Envoy Proxy Basic Authentication +HTTP filter to all the listeners generated by Envoy Gateway. The example extension server +includes its own CRD which allows defining username/password pairs that will be accepted by +the Envoy Proxy. + +**Note:** Envoy Gateway supports adding Basic Authentication to routes using a [SecurityPolicy][]. +See [this task](../security/basic-auth) for the preferred way to configure Basic +Authentication. + +## Quickstart + +### Prerequisites + +{{< boilerplate prerequisites >}} + +### Build and run the example Extension Server + +Build and deploy the example extension server in the `examples/extension-server` folder into the cluster +running Envoy Gateway. + +* Build the extension server image + + **Note:** The provided `Makefile` builds an image with the name `extension-server:latest`. You may need to create +a different tag for it in order to allow Kubernetes to pull it correctly. + + ```shell + make image + ``` + +* Publish the extension server image in your docker repository + + {{< tabpane text=true >}} + {{% tab header="local kind server" %}} + + ```shell + kind load docker-image --name envoy-gateway extension-server:latest + ``` + + {{% /tab %}} + {{% tab header="other Kubernetes server" %}} + + ```shell + docker tag extension-server:latest $YOUR_DOCKER_REPO + docker push $YOUR_DOCKER_REPO + ``` + + {{% /tab %}} + {{< /tabpane >}} + +* Deploy the extension server in your cluster + + If you are using your own docker image repository, make sure to update the `values.yaml` with the correct +image name and tag. + + ```shell + helm install -n envoy-gateway-system extension-server ./examples/extension-server/charts/extension-server + ``` + +### Configure Envoy Gateway + +* Grant Envoy Gateway's `ServiceAccount` permission to access the extension server's CRD + + ```shell + kubectl create clusterrole listener-context-example-status-update \ + --verb=update \ + --resource=ListenerContextExample/status + + kubectl create clusterrole listener-context-example-viewer \ + --verb=get,list,watch \ + --resource=ListenerContextExample + + kubectl create clusterrolebinding envoy-gateway-listener-context \ + --clusterrole=listener-context-example-viewer \ + --serviceaccount=envoy-gateway-system:envoy-gateway + + kubectl create clusterrolebinding envoy-gateway-listener-context-status \ + --clusterrole=listener-context-example-status-update \ + --serviceaccount=envoy-gateway-system:envoy-gateway + ``` + +* Configure Envoy Gateway to use the Extension Server + + Add the following fragment to Envoy Gateway's configmap: + + ```shell + cat <": `. +* **Mutually exclusive with the singular form.** `extensionManager` and + `extensionManagers` cannot both be set. + +## Testing + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +The extension server adds the Basic Authentication HTTP filter to all listeners configured by +Envoy Gateway. Initially there are no valid user/password combinations available. Accessing the +example backend should fail with a 401 status: + +```console +$ curl -v --header "Host: www.example.com" "http://${GATEWAY_HOST}/example" +... +> GET /example HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/7.81.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 401 Unauthorized +< www-authenticate: Basic realm="http://www.example.com/example" +< content-length: 58 +< content-type: text/plain +< date: Mon, 08 Jul 2024 10:53:11 GMT +< +... +User authentication failed. Missing username and password. +... +``` + +Add a new Username/Password combination using the example extension server's CRD: + +```shell +kubectl apply -f - << EOF +apiVersion: example.extensions.io/v1alpha1 +kind: ListenerContextExample +metadata: + name: listeneruser +spec: + targetRefs: + - kind: Gateway + name: eg + group: gateway.networking.k8s.io + username: user + password: p@ssw0rd +EOF +``` + +Authenticating with this user/password combination will now work. + +```console +$ curl -v http://${GATEWAY_HOST}/example -H "Host: www.example.com" --user 'user:p@ssw0rd' +... +> GET /example HTTP/1.1 +> Host: www.example.com +> Authorization: Basic dXNlcm5hbWU6cEBzc3cwcmQ= +> User-Agent: curl/7.81.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Mon, 08 Jul 2024 10:56:17 GMT +< content-length: 559 +< +... + "headers": { + "Authorization": [ + "Basic dXNlcm5hbWU6cEBzc3cwcmQ=" + ], + "X-Example-Ext": [ + "user" + ], +... +``` + + +[xDS]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/dynamic_configuration +[design documentation]: /community/design/extending-envoy-gateway +[CVE-2026-22771]: https://github.com/envoyproxy/gateway/security/advisories/GHSA-xrwg-mqj6-6m22 +[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ +[command line options]: ../operations/customize-envoyproxy/#customize-envoyproxy-command-line-options +[network policies]: https://kubernetes.io/docs/concepts/services-networking/network-policies/ +[SecurityPolicy]: /latest/api/extension_types/#securitypolicy diff --git a/site/content/en/v1.8/tasks/extensibility/lua.md b/site/content/en/v1.8/tasks/extensibility/lua.md new file mode 100644 index 0000000000..4393802cfd --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/lua.md @@ -0,0 +1,203 @@ +--- +title: "Lua Extensions" +--- + +This task provides instructions for extending Envoy Gateway with Lua extensions. + +Lua extensions allow you to extend the functionality of Envoy Gateway by running custom code against HTTP requests and responses, +without modifying the Envoy Gateway binary. These comparatively light-weight extensions are written in the Lua scripting language using APIs defined [here](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter#stream-handle-api). + +Envoy Gateway allows the user to configure Lua extensions using the [EnvoyExtensionPolicy][] CRD. +This instantiated resource can be linked to a [Gateway][Gateway] or [HTTPRoute][HTTPRoute] resource. If linked to both, the resource linked to the route takes precedence over those linked to Gateway. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +Envoy Gateway supports Lua in [EnvoyExtensionPolicy][] in two modes: +* Inline Lua: The extension defines the Lua script as an inline string. +* ValueRef Lua: The extension points to an in-cluster ConfigMap resource that contains the Lua script in it's data. + +The following example demonstrates how to configure an [EnvoyExtensionPolicy][] to attach a Lua extension to a [HTTPRoute][HTTPRoute]. +This Lua extension adds a custom header `x-lua-custom: FOO` to the response. + +### Lua Extension - Inline + +This [EnvoyExtensionPolicy][] configuration defines the Lua script as an inline string. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the EnvoyExtensionPolicy status: + +```shell +kubectl get envoyextensionpolicy/lua-inline-test -o yaml +``` + +### Lua Extension - ValueRef + +This [EnvoyExtensionPolicy][] configuration defines the Lua extension in a ConfigMap resource. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the EnvoyExtensionPolicy status: + +```shell +kubectl get envoyextensionpolicy/lua-valueref-test -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service: + +```shell +curl -i -H "Host: www.example.com" "http://${GATEWAY_HOST}" +``` + +You should see that the lua extension has added this header to the response: + +``` +x-lua-custom: FOO +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the EnvoyExtensionPolicy: + +```shell +kubectl delete envoyextensionpolicy/lua-inline-test +kubectl delete envoyextensionpolicy/lua-valueref-test +kubectl delete configmap/cm-lua-valueref +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[EnvoyExtensionPolicy]: ../../../api/extension_types#envoyextensionpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute diff --git a/site/content/en/v1.8/tasks/extensibility/opa-sidecar-unix-domain-socket.md b/site/content/en/v1.8/tasks/extensibility/opa-sidecar-unix-domain-socket.md new file mode 100644 index 0000000000..2d469d4a75 --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/opa-sidecar-unix-domain-socket.md @@ -0,0 +1,413 @@ +--- +title: "OPA Sidecar with Unix Domain Socket" +--- + +This task demonstrates how to deploy an Open Policy Agent (OPA) sidecar inside Envoy Proxy pods created by Envoy Gateway, with Envoy Proxy communicating with OPA over a Unix Domain Socket. + +The setup provides these advantages over running OPA as its own Kubernetes service: + +- Using a sidecar ensures that the OPA is always on the same worker node as Envoy Proxy. This reduces latency and simplifies access control. +- Using a Unix Domain Socket avoids TCP/TLS overhead while improving security by avoiding network exposure and reduces latency. + +This production-ready approach uses Envoy Gateway's extension APIs to configure Envoy Proxy's external authorization and standard Kubernetes API objects to configure OPA's Envoy External Authorization gRPC plugin. + +```mermaid +graph TB + subgraph K8sPod ["⎈ Envoy Proxy Pod"] + subgraph EnvoyContainer ["Envoy Proxy Container"] + ExtAuthz("🔐 ext_authz Filter") + end + + UnixSocket[("Unix Domain Socket
/shared/opa/opa.sock")] + + subgraph OPAContainer ["OPA Container"] + RegoPolicy("⚙️ Rego Policy") + end + end + + %% Flow Definitions + ExtAuthz <-->|"Authz check"| UnixSocket + UnixSocket <-->|"Authz check"| RegoPolicy + + style UnixSocket fill:#D0D0D0 + style EnvoyContainer fill:#2962FF,color:#FFFFFF + style OPAContainer fill:#2962FF,color:#FFFFFF +``` + +Note: In this diagram, the Unix Domain Socket is shown outside of the Proxy and OPA containers, but it is actually mounted to both containers. + +The example flow on this page will use Envoy to authenticate JWTs and OPA to validate the ISS claim on the JWT. If the ISS matches a configured env var value then requests will be allowed. + +Note that the OPA sidecar with Unix Domain Sockets pattern does _not_ require that JWTs be used. Also, simple ISS claim validation could be done more easily using the "authentication" property of the `SecurityPolicy` spec, but using OPA allows for more complex logic to be applied. See [JWT Claim-Based Authorization](../security/jwt-claim-authorization.md) to see how to use the `SecurityPolicy` "authentication" property. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Steps overview + +1. Enable the `Backend` extension API so Envoy can reference a Unix Domain Socket. +2. Create an OPA policy in a `ConfigMap` and mount it into an OPA sidecar in the Envoy pods. +3. Configure the Envoy Proxy pods to have an OPA sidecar +4. Configure a `SecurityPolicy` that delegates authorization to OPA via the Unix Domain Socket `Backend`. For demonstration purposes we'll also configure JWT authentication. +5. Create an HTTPRoute that requires protection +6. Test the configuration + +## Step 1: Enable the Backend extension API + +Enable the `Backend` API in your Envoy Gateway `ConfigMap` to allow Envoy to reference Unix Domain Sockets by setting the "enableBackend" property to "true" in the "envoy-gateway-config" `ConfigMap`: + +```yaml +data: + envoy-gateway.yaml: | + ... + extensionApis: + enableBackend: true +``` + +Run these commands to update the `ConfigMap`: + +```shell +OLD_CONFIG=$(kubectl get cm envoy-gateway-config -n envoy-gateway-system -o jsonpath='{.data.envoy-gateway\.yaml}') +NEW_CONFIG=$(echo "$OLD_CONFIG" | sed "s/extensionApis: {}/extensionApis:\n enableBackend: true/") +kubectl create configmap envoy-gateway-config -n envoy-gateway-system \ + --from-literal=envoy-gateway.yaml="$NEW_CONFIG" \ + --dry-run=client -o yaml | kubectl apply -f - +``` + +Ignore the kubectl warning. It happens because `kubectl apply` expects a "receipt" (the `last-applied-configuration` annotation) to be present on the resource so it can track changes over time. If the ConfigMap was originally created using `kubectl create` (without `--save-config`) or by a Helm chart, that receipt is missing. `kubectl` is simply telling you that it's adding that receipt now. + +Restart the Envoy Gateway deployment to apply the updated configuration: + +```shell +kubectl -n envoy-gateway-system rollout restart deploy/envoy-gateway +``` + +The Envoy Proxy pod will be restarted later in this guide. + +## Step 2: Create the OPA policy + +Create a `ConfigMap` with a [Rego](https://www.openpolicyagent.org/docs/policy-language) policy that OPA will load. This example reads the "ALLOWED_ISS" environment variable and compares it to the JWT ISS claim, allowing the request only if they match. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: opa-policy + namespace: envoy-gateway-system +data: + policy.rego: | + package envoy.authz + + import rego.v1 + + default allow := false + + opa_env := opa.runtime().env + allowed_iss := opa_env.ALLOWED_ISS + jwt_iss := input.attributes.request.http.headers["x-jwt-iss"] + + allow if { + jwt_iss == allowed_iss + } +``` + +On MacOS you can apply that by copying it and running `pbpaste | kubectl apply -f -`. + +In this policy we extract a `x-jwt-iss` header from the request. That header is not automatically available on `ext_authz` filter requests. We will configure Envoy to add that header from the decoded JWT. That configuration happens in the SecurityPolicy in step 4. + +## Step 3: Configure the Envoy Proxy pods to have an OPA sidecar + +Create an `EnvoyProxy` resource that mounts the OPA policy `ConfigMap`, shares a Unix Domain Socket between Envoy and OPA, and configures the "ext_authz" filter order so OPA receives JWT headers from the JWT authentication filter. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: eg + namespace: envoy-gateway-system +spec: + # Ensure ext_authz runs after jwt_authn so that OPA sees the JWT-derived headers + # configured in the SecurityPolicy in step 4 + filterOrder: + - name: envoy.filters.http.ext_authz + after: envoy.filters.http.jwt_authn + provider: + type: Kubernetes + kubernetes: + envoyDeployment: + patch: + type: StrategicMerge + value: + spec: + template: + spec: + volumes: + # Shared Unix Domain Socket volume for communication between Envoy + # and OPA. This will be mounted in both containers. + - name: opa-unix-socket + emptyDir: {} + # OPA Rego policy file from ConfigMap. This will be mounted + # in the OPA container. + - name: opa-policy + configMap: + name: opa-policy + containers: + # Add the Unix Domain Socket volume to the existing envoy + # proxy container named "envoy". + - name: envoy + volumeMounts: + # Mount the Unix Domain Socket volume in the Envoy container + - name: opa-unix-socket + mountPath: /shared/opa + # Create the OPA sidecar container + - name: opa + # OPA image tag format: + # - "x.y.z": OPA version + # - "envoy": includes OPA's Envoy External Authorization gRPC plugin + # - "5": plugin version + # - "static": static build (no glibc dependency, smaller image) + image: openpolicyagent/opa:1.10.1-envoy-5-static + args: + - "run" + - "--server" + # In addition to listening on the Unix Domain Socket, we'll listen + # on port 8181 for k8s probes + - "--addr=0.0.0.0:8181" + # Configure OPA's Envoy external authorization plugin to listen on a Unix Domain Socket + - "--set=plugins.envoy_ext_authz_grpc.addr=unix:///shared/opa/opa.sock" + # In the OPA policy we defined the policy as being in a + # "envoy.authz" package and set the "allow" variable + # based on the policy decision. Here we tell the plugin + # to check that value. + - "--set=plugins.envoy_ext_authz_grpc.query=data.envoy.authz.allow" + - "--ignore=.*" + # You can set log-level to "debug" for detailed request logging + - "--log-level=error" + # Tell OPA where to find the policy file + - "/policy/policy.rego" + env: + # Environment variable used by the OPA policy to validate the JWT issuer + - name: ALLOWED_ISS + value: "https://example.com" + ports: + # Port for health checks only; gRPC server listens on the Unix Domain Socket + - name: http + containerPort: 8181 + protocol: TCP + volumeMounts: + # Mount the Unix Domain Socket volume in the OPA container + - name: opa-unix-socket + mountPath: /shared/opa + # Mount the OPA Rego policy from ConfigMap + - name: opa-policy + mountPath: /policy + readOnly: true + livenessProbe: + httpGet: + path: /health + port: 8181 + initialDelaySeconds: 5 + periodSeconds: 10 + timeoutSeconds: 3 + failureThreshold: 3 + readinessProbe: + httpGet: + path: /health?bundle=true + port: 8181 + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + securityContext: + # Use the same user ID as the Envoy container (65532) so both containers can access the socket + # The user ID was found by running "docker pull docker.io/envoyproxy/gateway:v && docker inspect docker.io/envoyproxy/gateway:v" + runAsUser: 65532 + allowPrivilegeEscalation: false + resources: + # Adjust as necessary + requests: + cpu: 100m + memory: 128Mi + limits: + memory: 512Mi +``` + +This patch adds an OPA sidecar container to the Envoy pods, creates a shared Unix Domain Socket at `/shared/opa/opa.sock`, and configures OPA to listen only on this socket instead of TCP. It sets an `ALLOWED_ISS` property that OPA will use to validate the request. We purposefully set the wrong value here so we can see the response when the wrong ISS is used. We'll set it to the correct value later. + +Tell Envoy Gateway to use this `EnvoyProxy` spec by patching the `GatewayClass`. + +```shell +kubectl patch gatewayclass eg --type merge -p ' +{ + "spec": { + "parametersRef": { + "group": "gateway.envoyproxy.io", + "kind": "EnvoyProxy", + "name": "eg", + "namespace": "envoy-gateway-system" + } + } +}' +``` + +This will cause the Envoy Proxy pod to be replaced with the new config. + +## Step 4: Connect Envoy to OPA with a SecurityPolicy and Backend + +Create a Unix Domain Socket `SecurityPolicy` and a `Backend` that authenticates JWTs, maps the ISS claims to the `x-jwt-iss` header, and delegates authorization to OPA. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: opa-jwt-authz + # The SecurityPolicy must be in the same namespace as the HTTPRoutes that it + # will apply to + namespace: default +spec: + targetSelectors: + - group: gateway.networking.k8s.io + kind: HTTPRoute + matchLabels: + auth: opa-jwt + jwt: + providers: + - name: my-jwt-validator + # Verify that the JWT is signed with the correct key + remoteJWKS: + uri: https://raw.githubusercontent.com/envoyproxy/gateway/refs/heads/main/examples/kubernetes/jwt/jwks.json + # Add the JWT ISS claim to request to the headers sent to OPA. Note: this only works + # for string claims, not arrays. For example, the "aud" claim cannot be passed + # this way because the JWT spec defines it as an array. + claimToHeaders: + - header: x-jwt-iss + claim: iss + # Delegate authorization to an external program after JWT verification + extAuth: + grpc: + backendRefs: + # Reference the OPA Unix Domain Socket backend, which is the next API object in this code block + - group: gateway.envoyproxy.io + kind: Backend + name: opa-unix-socket + # Headers to send to OPA for authorization decisions. This should match the + # "claimToHeaders" values above. + headersToExtAuth: + - x-jwt-iss +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: Backend +metadata: + name: opa-unix-socket + # The Backend must be in the same namespace as the SecurityPolicy + namespace: default +spec: + endpoints: + # This configures Envoy proxy to send external auth requests to the Unix Domain Socket + - unix: + path: /shared/opa/opa.sock +``` + +## Step 5: Configure route to use the OPA authorization + +Attach the policy by labeling routes that require authorization. This `HTTPRoute` uses the `backend` service installed in the Quick Start: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: test-opa + namespace: default + labels: + auth: opa-jwt +spec: + hostnames: + - foo.bar.com + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: eg + rules: + - matches: + - path: + type: PathPrefix + value: /test-opa + backendRefs: + - name: backend + port: 3000 +``` + +## Step 6: Test the configuration + +Prepare some env vars: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +export VALID_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImI1MjBiM2MyYzRiZDc1YTEwZTljZWJjOTU3NjkzM2RjIn0.eyJpc3MiOiJodHRwczovL2Zvby5iYXIuY29tIiwic3ViIjoiMTIzNDU2Nzg5MCIsInVzZXIiOnsibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsInJvbGVzIjpbImFkbWluIiwiZWRpdG9yIl19LCJwcmVtaXVtX3VzZXIiOnRydWUsImlhdCI6MTUxNjIzOTAyMiwic2NvcGUiOiJyZWFkIGFkZCBkZWxldGUgbW9kaWZ5In0.P36iAlmiRCC79OiB3vstF5Q_9OqUYAMGF3a3H492GlojbV6DcuOz8YIEYGsRSWc-BNJaBKlyvUKsKsGVPtYbbF8ajwZTs64wyO-zhd2R8riPkg_HsW7iwGswV12f5iVRpfQ4AG2owmdOToIaoch0aym89He1ZzEjcShr9olgqlAbbmhnk-namd1rP-xpzPnWhhIVI3mCz5hYYgDTMcM7qbokM5FzFttTRXAn5_Luor23U1062Ct_K53QArwxBvwJ-QYiqcBycHf-hh6sMx_941cUswrZucCpa-EwA3piATf9PKAyeeWHfHV9X-y8ipGOFg3mYMMVBuUZ1lBkJCik9f9kboRY6QzpOISARQj9PKMXfxZdIPNuGmA7msSNAXQgqkvbx04jMwb9U7eCEdGZztH4C8LhlRjgj0ZdD7eNbRjeH2F6zrWyMUpGWaWyq6rMuP98W2DWM5ZflK6qvT1c7FuFsWPvWLkgxQwTWQKrHdKwdbsu32Sj8VtUBJ0-ddEb" +``` + +If Envoy is not running behind a load balancer, then you'll have to start port forwarding whenever the Envoy Proxy pod is reconfigured and the proxy pods are replaced: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 & +``` + +### Test without a JWT + +Requests without a valid JWT are denied: + +```shell +curl -v -H "Host: foo.bar.com" "http://${GATEWAY_HOST}/test-opa/get" +``` + +Expected result: HTTP 401 Unauthorized + +### Test with a valid JWT that has the wrong ISS claim + +Earlier, we configured the "ALLOWED_ISS" env var on the proxy pods to be "https://example.com", but the JWT in the "VALID_TOKEN" env var has an ISS claim of "https://foo.bar.com". + +Requests with an incorrect ISS are denied: + +```shell +curl -v -H "Host: foo.bar.com" -H "Authorization: Bearer $VALID_TOKEN" "http://${GATEWAY_HOST}/test-opa/get" +``` + +Expected result: HTTP 403 Forbidden + +### Test with a valid JWT and ISS claim + +We must update the `EnvoyProxy` spec to use "https://foo.bar.com" for the "ALLOWED_ISS" so that it matches the ISS in "$VALID_TOKEN". + +```yaml +... + containers: + - name: opa + env: + - name: ALLOWED_ISS + value: "https://foo.bar.com" # Change to this +... +``` + +The quickest way to do that for this tutorial is via `kubectl -n envoy-gateway-system edit envoyproxy eg`. + +Wait for the Envoy Proxy pod to be replaced. + +When the JWT issuer matches your configured provider and the OPA policy allows it, the request is forwarded to the backend: + +```shell +curl -v -H "Host: foo.bar.com" -H "Authorization: Bearer $VALID_TOKEN" "http://${GATEWAY_HOST}/test-opa/get" +``` + +Expected result: HTTP 200 and a response from the backend service. + +## Clean up + +Delete all resources created by this task: + +```shell +kubectl delete httproute/test-opa securitypolicy/opa-jwt-authz backend/opa-unix-socket +kubectl delete envoyproxy/eg configmap/opa-policy -n envoy-gateway-system +kubectl delete deploy/$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') -n envoy-gateway-system +``` \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/extensibility/wasm.md b/site/content/en/v1.8/tasks/extensibility/wasm.md new file mode 100644 index 0000000000..e33640787d --- /dev/null +++ b/site/content/en/v1.8/tasks/extensibility/wasm.md @@ -0,0 +1,187 @@ +--- +title: "Wasm Extensions" +--- + +This task provides instructions for extending Envoy Gateway with WebAssembly (Wasm) extensions. + +Wasm extensions allow you to extend the functionality of Envoy Gateway by running custom code against HTTP requests and responses, +without modifying the Envoy Gateway binary. These extensions can be written in any language that compiles to Wasm, such as C++, Rust, AssemblyScript, or TinyGo. + +Envoy Gateway introduces a new CRD called [EnvoyExtensionPolicy][] that allows the user to configure Wasm extensions. +This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute][HTTPRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +Envoy Gateway supports two types of Wasm extensions: +* HTTP Wasm Extension: The Wasm extension is fetched from a remote URL. +* Image Wasm Extension: The Wasm extension is packaged as an OCI image and fetched from an image registry. + +The following example demonstrates how to configure an [EnvoyExtensionPolicy][] to attach a Wasm extension to an [EnvoyExtensionPolicy][] . +This Wasm extension adds a custom header `x-wasm-custom: FOO` to the response. + +### HTTP Wasm Extension + +This [EnvoyExtensionPolicy][] configuration fetches the Wasm extension from an HTTP URL. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the EnvoyExtensionPolicy status: + +```shell +kubectl get envoyextensionpolicy/wasm-test -o yaml +``` + +### Image Wasm Extension + +This [EnvoyExtensionPolicy][] configuration fetches the Wasm extension from an OCI image. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the EnvoyExtensionPolicy status: + +```shell +kubectl get envoyextensionpolicy/wasm-test -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service: + +```shell +curl -i -H "Host: www.example.com" "http://${GATEWAY_HOST}" +``` + +You should see that the wasm extension has added this header to the response: + +``` +x-wasm-custom: FOO +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the EnvoyExtensionPolicy: + +```shell +kubectl delete envoyextensionpolicy/wasm-test +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[EnvoyExtensionPolicy]: ../../../api/extension_types#envoyextensionpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute diff --git a/site/content/en/v1.8/tasks/observability/_index.md b/site/content/en/v1.8/tasks/observability/_index.md new file mode 100644 index 0000000000..9ca4896ee8 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/_index.md @@ -0,0 +1,5 @@ +--- +title: "Observability" +weight: 4 +description: This section includes Observability tasks. +--- diff --git a/site/content/en/v1.8/tasks/observability/gateway-api-metadata.md b/site/content/en/v1.8/tasks/observability/gateway-api-metadata.md new file mode 100644 index 0000000000..eca2bec93b --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/gateway-api-metadata.md @@ -0,0 +1,89 @@ +--- +title: "Gateway API Metadata" +--- + +## Background +Envoy Gateway translates Gateway API resources to Envoy XDS resources. In this translation process, Envoy Gateway annotates XDS resources with additional metadata from their origin Gateway API resources. + +Gateway API Metadata includes: +- K8s Resource Kinds, Names and Namespaces. +- K8s Resource Annotations with the `gateway.envoyproxy.io/` prefix. +- K8s Resource SectionNames (when applicable, e.g. for Route rules and Listeners). + +Gateway API Metadata is added to XDS resources using envoy's [Static Metadata][] under `metadata.filter_metadata.envoy-gateway.resources`. Currently, `resources` only contains the primary origin resource. +However, in the future, additional relevant resources (e.g. policies, filters attached to the primary origin resources) may be added. + +## Supported Resources +Currently, the following mapping of Gateway API metadata to XDS metadata are supported: + +| XDS Resource | Primary Gateway API Resource | XDS Metadata | Comments +|------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| [Virtual Host][] | `Gateway` | Kind, Namespace, Name, Annotations, SectionName (`spec.listeners..name`) | | +| [Route][] | `HTTPRoute`, `GRPCRoute` | Kind, Namespace, Name, Annotations, SectionName (`spec.listener.rules..name`) | | +| [Cluster][] | `xRoute` | Kind, Namespace, Name, Annotations, SectionName (`spec.listener.rules..name`) | | +| [Cluster][] | `EnvoyProxy`, `EnvoyExtensionPolicy`, `SecurityPolicy` | Kind, Namespace, Name, Annotations, SectionName (`spec.listener.rules..name`) | When a non-xRoute BackendRef is used (e.g. ext_auth, observabiltiy sink, ... ) | +| [LBEndpoints][] | `Service`, `ServiceImport`, `Backend` | Kind, Namespace, Name, Annotations, SectionName (`backendRef.port`) | | + +For example, consider the following Gateway API HTTPRoute: + +```yaml +kind: HTTPRoute +apiVersion: gateway.networking.k8s.io/v1 +metadata: + annotations: + gateway.envoyproxy.io/foo: bar + name: myroute + namespace: myns +spec: + rules: + - name: myrule + matches: + - path: + type: PathPrefix + value: /mypath +``` + +The translated XDS [Route][] contains Gateway API metadata under : + +```yaml +name: httproute/myns/myroute/rule/0/match/0/* +match: + path_separated_prefix: "/mypath" +route: + cluster: httproute/myns/myroute/rule/0 +metadata: + filter_metadata: + envoy-gateway: + resources: + - namespace: myns + kind: HTTPRoute + annotations: + foo: bar + name: myroute + sectionName: myrule +``` + +## Use Cases +XDS Metadata serves multiple purposes: +- Observability: Envoy proxy access logs can be [enriched with Gateway-API resource](./proxy-accesslog.md) context and custom annotations, creating an association with relevant Application Developers personas. +- Troubleshooting: users and tools that analyze the envoy proxy XDS config can identify the Gateway API resources that lead to the XDS configuration's creation. +- Extensibility: + - Envoy Gateway [Extension Servers][] can leverage Gateway API metadata as additional context annotating XDS resources sent for mutation. + - Envoy Proxy extensions can leverage XDS metadata as additional context when processing traffic: + - [lua][] extensions can access metadata using the [Metadata Stream handle API][] . + - [ext_proc][] extensions can access metadata using the `xds.*_metadata` [ext_proc attribute][]. + + +[Static Metadata]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-metadata +[Virtual Host]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-virtualhost +[Route]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-route +[Cluster]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html +[LBEndpoints]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/endpoint/v3/endpoint_components.proto#envoy-v3-api-msg-config-endpoint-v3-lbendpoint +[Metadata Stream handle API]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter#metadata +[lua]: ../../api/extension_types#lua +[ext_proc]: ../../api/extension_types#extproc +[ext_proc attribute]: ../../api/extension_types#processingmodeoptions +[Extension Servers]: ../extensibility/extension-server.md + + + diff --git a/site/content/en/v1.8/tasks/observability/gateway-api-metrics.md b/site/content/en/v1.8/tasks/observability/gateway-api-metrics.md new file mode 100644 index 0000000000..08f8bc8758 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/gateway-api-metrics.md @@ -0,0 +1,127 @@ +--- +title: "Gateway API Metrics" +--- +## Prerequisites + +{{< boilerplate o11y_prerequisites >}} + +### Enable kube-state-metrics + +The `kube-state-metrics` service is required to collect metrics from the Kubernetes API server. Use the following command to enable it: + +```shell +helm upgrade eg-addons oci://docker.io/envoyproxy/gateway-addons-helm \ +--version {{< helm-version >}} \ +--reuse-values \ +--set prometheus.kube-state-metrics.enabled=true \ +-n monitoring +``` + +## Metrics + +To query metrics using Prometheus API, follow the steps below. Make sure to wait for the statefulset to be ready before port-forwarding. + +```shell +export PROMETHEUS_PORT=$(kubectl get service prometheus -n monitoring -o jsonpath='{.spec.ports[0].port}') +kubectl port-forward service/prometheus -n monitoring 9090:$PROMETHEUS_PORT +``` + +The example query below fetches the `gatewayapi_gateway_created` metric. +Alternatively, access the Prometheus UI at `http://localhost:9090`. + +```shell +curl -s 'http://localhost:9090/api/v1/query?query=gatewayapi_gateway_created' | jq . +``` + + +## Alerts + +A set of example alert rules are available in +[config/examples/rules](https://github.com/Kuadrant/gateway-api-state-metrics/tree/main/config/examples/rules). To create alert use the following command: + +```shell +cat < **New** > **Import**. + +Alternatively, use the following command to import dashboards using the Grafana API: + + +```shell +export GRAFANA_API_KEY="your-api-key" + +urls=( + "https://grafana.com/api/dashboards/19433/revisions/1/download" + "https://grafana.com/api/dashboards/19432/revisions/1/download" + "https://grafana.com/api/dashboards/19434/revisions/1/download" + "https://grafana.com/api/dashboards/19570/revisions/1/download" +) + +for url in "${urls[@]}"; do + dashboard_data=$(curl -s "$url") + curl -X POST \ + -H "Authorization: Bearer $GRAFANA_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{\"dashboard\": $dashboard_data, \"overwrite\": true}" \ + "http://localhost:3000/api/dashboards/db" +done +``` + +## Next Steps + +Check out the [Gateway Exported Metrics](./gateway-exported-metrics.md) section to learn more about the metrics exported by the Envoy Gateway. diff --git a/site/content/en/v1.8/tasks/observability/gateway-exported-metrics.md b/site/content/en/v1.8/tasks/observability/gateway-exported-metrics.md new file mode 100644 index 0000000000..73f720a412 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/gateway-exported-metrics.md @@ -0,0 +1,108 @@ +--- +title: "Gateway Exported Metrics" +--- + +The Envoy Gateway provides a collection of self-monitoring metrics in [Prometheus format][prom-format]. + +These metrics allow monitoring of the behavior of Envoy Gateway itself (as distinct from that of the EnvoyProxy it managed). + +{{% alert title="EnvoyProxy Metrics" color="warning" %}} +For EnvoyProxy Metrics, please refer to the [EnvoyProxy Metrics](./proxy-metric) to learn more. +{{% /alert %}} + +## Watching Components + +The Resource Provider, xDS Translator and Infra Manager etc. are key components that made up of Envoy Gateway, +they all follow the design of [Watching Components](/community/design/watching). + +Envoy Gateway collects the following metrics in Watching Components: + +| Name | Description | +|----------------------------------------|--------------------------------------------------------------| +| `watchable_depth` | Current depth of watchable map. | +| `watchable_subscribe_duration_seconds` | How long in seconds a subscribed watchable queue is handled. | +| `watchable_subscribe_total` | Total number of subscribed watchable queue. | +| `watchable_panics_recovered_total` | Total recovered panics in the watchable infrastructure. | +| `watchable_publish_total` | Total number of published event to watchable queue. | + +Each metric includes the `runner` label to identify the corresponding components, +the relationship between label values and components is as follows: + +| Value | Components | +|--------------------|---------------------------------| +| `gateway-api` | Gateway API Translator | +| `infrastructure` | Infrastructure Manager | +| `xds-server` | xDS Server | +| `xds-translator` | xDS Translator | +| `global-ratelimit` | Global RateLimit xDS Translator | + +Metrics may include one or more additional labels, such as `message`, `status` and `reason` etc. + +## Status Updater + +Envoy Gateway monitors the status updates of various resources (like `GatewayClass`, `Gateway` and `HTTPRoute` etc.) through Status Updater. + +Envoy Gateway collects the following metrics in Status Updater: + +| Name | Description | +|----------------------------------|------------------------------------------------| +| `status_update_total` | Total number of status update by object kind. | +| `status_update_duration_seconds` | How long a status update takes to finish. | + +Each metric includes `kind` label to identify the corresponding resources. + +## xDS Server + +Envoy Gateway monitors the cache and xDS connection status in xDS Server. + +Envoy Gateway collects the following metrics in xDS Server: + +| Name | Description | +|-------------------------------|--------------------------------------------------------| +| `xds_snapshot_create_total` | Total number of xds snapshot cache creates. | +| `xds_snapshot_update_total` | Total number of xds snapshot cache updates by node id. | +| `xds_stream_duration_seconds` | How long a xds stream takes to finish. | + +- For xDS snapshot cache update and xDS stream connection status, each metric includes `nodeID` label to identify the connection peer. +- For xDS stream connection status, each metric also includes `streamID` label to identify the connection stream, and `isDeltaStream` label to identify the delta connection stream. + +## Infrastructure Manager + +Envoy Gateway monitors the `apply` (`create` or `update`) and `delete` operations in Infrastructure Manager. + +Envoy Gateway collects the following metrics in Infrastructure Manager: + +| Name | Description | +|------------------------------------|---------------------------------------------------------| +| `resource_apply_total` | Total number of applied resources. | +| `resource_apply_duration_seconds` | How long in seconds a resource be applied successfully. | +| `resource_delete_total` | Total number of deleted resources. | +| `resource_delete_duration_seconds` | How long in seconds a resource be deleted successfully. | + +Each metric includes the `kind` label to identify the corresponding resources being applied or deleted by Infrastructure Manager. + +Metrics may also include `name` and `namespace` label to identify the name and namespace of corresponding Infrastructure Manager. + +## Wasm + +Envoy Gateway monitors the status of Wasm remote fetch cache. + +| Name | Description | +|---------------------------|--------------------------------------------------| +| `wasm_cache_entries` | Number of Wasm remote fetch cache entries. | +| `wasm_cache_lookup_total` | Total number of Wasm remote fetch cache lookups. | +| `wasm_remote_fetch_total` | Total number of Wasm remote fetches and results. | + +For metric `wasm_cache_lookup_total`, we are using `hit` label (boolean) to indicate whether the Wasm cache has been hit. + +## Topology Injector MutatingWebhookConfiguration + +Envoy Gateway monitors the status of the TopologyInjector webhook which injects node topology information to EnvoyProxy pods. + +| Name | Description | +|------------------------------------------|---------------------------------------------------| +| `topology_injector_webhook_events_total` | Total number of topology injector webhook events. | + +This metrics provides information on whether a webhook request was successful, failed, or a no-op. + +[prom-format]: https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format diff --git a/site/content/en/v1.8/tasks/observability/gateway-observability.md b/site/content/en/v1.8/tasks/observability/gateway-observability.md new file mode 100644 index 0000000000..f23eb9097c --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/gateway-observability.md @@ -0,0 +1,168 @@ +--- +title: "Gateway Observability" +--- + +Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances. +This task show you how to config gateway control-plane observability, includes metrics. + +## Prerequisites + +{{< boilerplate o11y_prerequisites >}} + +## Metrics + +The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and attaches it +using a `ConfigMap`. In this section, we will update this resource to enable various ways to retrieve metrics +from Envoy Gateway. + +{{% alert title="Exported Metrics" color="warning" %}} +Refer to the [Gateway Exported Metrics List](./gateway-exported-metrics) to learn more about Envoy Gateway's Metrics. +{{% /alert %}} + +### Retrieve Prometheus Metrics from Envoy Gateway + +By default, prometheus metric is enabled. You can directly retrieve metrics from Envoy Gateway: + +```shell +export ENVOY_POD_NAME=$(kubectl get pod -n envoy-gateway-system --selector=control-plane=envoy-gateway,app.kubernetes.io/instance=eg -o jsonpath='{.items[0].metadata.name}') +kubectl port-forward pod/$ENVOY_POD_NAME -n envoy-gateway-system 19001:19001 + +# check metrics +curl localhost:19001/metrics +``` + +The following is an example to disable prometheus metric for Envoy Gateway. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +### Enable Open Telemetry sink in Envoy Gateway + +The following is an example to send metric via Open Telemetry sink to OTEL gRPC Collector. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +Verify OTel-Collector metrics: + +```shell +export OTEL_POD_NAME=$(kubectl get pod -n monitoring --selector=app.kubernetes.io/name=opentelemetry-collector -o jsonpath='{.items[0].metadata.name}') +kubectl port-forward pod/$OTEL_POD_NAME -n monitoring 19001:19001 + +# check metrics +curl localhost:19001/metrics +``` + +[EnvoyGateway]: ../../api/extension_types#envoygateway diff --git a/site/content/en/v1.8/tasks/observability/grafana-integration.md b/site/content/en/v1.8/tasks/observability/grafana-integration.md new file mode 100644 index 0000000000..7d54b31151 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/grafana-integration.md @@ -0,0 +1,87 @@ +--- +title: "Visualising metrics using Grafana" +--- + +Envoy Gateway provides support for exposing Envoy Gateway and Envoy Proxy metrics to a Prometheus instance. +This task shows you how to visualise the metrics exposed to Prometheus using Grafana. + +## Prerequisites + +{{< boilerplate o11y_prerequisites >}} + +Follow the steps from the [Gateway Observability](./gateway-observability) and [Proxy Metrics](./proxy-metric) to enable Prometheus metrics +for both Envoy Gateway (Control Plane) and Envoy Proxy (Data Plane). + +Expose endpoints: + +```shell +GRAFANA_IP=$(kubectl get svc grafana -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +## Connecting Grafana with Prometheus datasource + +To visualise metrics from Prometheus, we have to connect Grafana with Prometheus. If you installed Grafana follow the command +from prerequisites sections, the Prometheus datasource should be already configured. + +You can also add the datasource manually by following the instructions from [Grafana Docs](https://grafana.com/docs/grafana/latest/datasources/prometheus/configure/). + +## Accessing Grafana + +You can access the Grafana instance by visiting `http://{GRAFANA_IP}`, derived in prerequisites. + +To log in to Grafana, use the credentials `admin:admin`. + +Envoy Gateway has examples of dashboard for you to get started, you can check them out under `Dashboards/envoy-gateway`. + +If you'd like import Grafana dashboards on your own, please refer to Grafana docs for [importing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard). + +### Envoy Proxy Global + +This dashboard example shows the overall downstream and upstream stats for each Envoy Proxy instance. + +![Envoy Proxy Global](/img/envoy-proxy-global-dashboard.png) + +### Envoy Clusters + +This dashboard example shows the overall stats for each cluster from Envoy Proxy fleet. + +![Envoy Clusters](/img/envoy-clusters-dashboard.png) + +### Envoy Gateway Global + +This dashboard example shows the overall stats exported by Envoy Gateway fleet. + +![Envoy Gateway Global: Watching Components](/img/envoy-gateway-global-watching-components.png) + +![Envoy Gateway Global: Status Updater](/img/envoy-gateway-global-status-updater.png) + +![Envoy Gateway Global: xDS Server](/img/envoy-gateway-global-xds-server.png) + +![Envoy Gateway Global: Infrastructure Manager](/img/envoy-gateway-global-infra-manager.png) + +### Resources Monitor + +This dashboard example shows the overall resources stats for both Envoy Gateway and Envoy Proxy fleet. + +![Envoy Gateway Resources](/img/resources-monitor-dashboard.png) + +## Update Dashboards + +All dashboards of Envoy Gateway are maintained under `charts/gateway-addons-helm/dashboards`, +feel free to make [contributions](/community/CONTRIBUTING). + +### Grafonnet + +Newer dashboards are generated with [Jsonnet](https://jsonnet.org/) with the [Grafonnet](https://grafana.github.io/grafonnet/index.html). +This is the preferred method for any new dashboards. + +You can run `make helm-generate.gateway-addons-helm` to generate new version of dashboards. +All the generated dashboards have a `.gen.json` suffix. + +### Legacy Dashboards + +Many of our older dashboards are manually created in the UI and exported as JSON and checked in. + +These example dashboards cannot be updated in-place by default, if you are trying to +make some changes to the older dashboards, you can save them directly as a JSON file +and then re-import. diff --git a/site/content/en/v1.8/tasks/observability/proxy-accesslog.md b/site/content/en/v1.8/tasks/observability/proxy-accesslog.md new file mode 100644 index 0000000000..1d93ab2c02 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/proxy-accesslog.md @@ -0,0 +1,309 @@ +--- +title: "Proxy Access Logs" +--- + +Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances. +This task show you how to config proxy access logs. + +## Prerequisites + +{{< boilerplate o11y_prerequisites >}} + +By default, the Service type of `loki` is ClusterIP, you can change it to LoadBalancer type for further usage: + +```shell +kubectl patch service loki -n monitoring -p '{"spec": {"type": "LoadBalancer"}}' +``` + +Expose endpoints: + +```shell +LOKI_IP=$(kubectl get svc loki -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +## Default Access Log + +If custom format string is not specified, Envoy Gateway uses the following default format: + +```json +{ + "start_time": "%START_TIME%", + "method": "%REQ(:METHOD)%", + "x-envoy-origin-path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", + "protocol": "%PROTOCOL%", + "response_code": "%RESPONSE_CODE%", + "response_flags": "%RESPONSE_FLAGS%", + "response_code_details": "%RESPONSE_CODE_DETAILS%", + "connection_termination_details": "%CONNECTION_TERMINATION_DETAILS%", + "upstream_transport_failure_reason": "%UPSTREAM_TRANSPORT_FAILURE_REASON%", + "bytes_received": "%BYTES_RECEIVED%", + "bytes_sent": "%BYTES_SENT%", + "duration": "%DURATION%", + "x-envoy-upstream-service-time": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%", + "x-forwarded-for": "%REQ(X-FORWARDED-FOR)%", + "user-agent": "%REQ(USER-AGENT)%", + "x-request-id": "%REQ(X-REQUEST-ID)%", + ":authority": "%REQ(:AUTHORITY)%", + "upstream_host": "%UPSTREAM_HOST%", + "upstream_cluster": "%UPSTREAM_CLUSTER%", + "upstream_local_address": "%UPSTREAM_LOCAL_ADDRESS%", + "downstream_local_address": "%DOWNSTREAM_LOCAL_ADDRESS%", + "downstream_remote_address": "%DOWNSTREAM_REMOTE_ADDRESS%", + "requested_server_name": "%REQUESTED_SERVER_NAME%", + "route_name": "%ROUTE_NAME%" +} +``` + +> Note: Envoy Gateway disable envoy headers by default, you can enable it by setting `EnableEnvoyHeaders` to `true` in the [ClientTrafficPolicy](../../api/extension_types#backendtrafficpolicy) CRD. + + +Verify logs from loki: + +```shell +curl -s "http://$LOKI_IP:3100/loki/api/v1/query_range" --data-urlencode "query={job=\"fluentbit\"}" | jq '.data.result[0].values' +``` + +## Disable Access Log + +If you want to disable it, set the `telemetry.accesslog.disable` to `true` in the `EnvoyProxy` CRD. + +```shell +kubectl apply -f - <}} + +## Metrics + +### Prometheus Metrics + +To query metrics using Prometheus API, follow the steps below. + +```shell +export PROMETHEUS_PORT=$(kubectl get service prometheus -n monitoring -o jsonpath='{.spec.ports[0].port}') +kubectl port-forward service/prometheus -n monitoring 19001:$PROMETHEUS_PORT +``` + +Query metrics using Prometheus API: + +```shell +curl -s 'http://localhost:19001/api/v1/query?query=topk(1,envoy_cluster_upstream_cx_connect_ms_sum)' | jq . +``` + +To directly view the metrics in Prometheus format from the Envoy's `/stats/prometheus` +[admin endpoint](https://www.envoyproxy.io/docs/envoy/latest/operations/admin), follow the steps below. + +```shell +export ENVOY_POD_NAME=$(kubectl get pod -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +kubectl port-forward pod/$ENVOY_POD_NAME -n envoy-gateway-system 19001:19001 +``` + +View the metrics: + +```shell +curl localhost:19001/stats/prometheus | grep "default/backend/rule/0" +``` + +If you are only using the OpenTelemetry sink, you might want to set the `telemetry.metrics.prometheus.disable` to `true` +in the _EnvoyProxy CRD_ as shown in the following command. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +To completely remove Prometheus resources from the cluster, set the `prometheus.enabled` Helm value to `false`. + +```shell +helm upgrade eg-addons oci://docker.io/envoyproxy/gateway-addons-helm --version {{< helm-version >}} -n monitoring --reuse-values --set prometheus.enabled=false +``` + +### OpenTelemetry Metrics + +Envoy Gateway can export metrics to an OpenTelemetry sink. Use the following command to send metrics to the +OpenTelemetry Collector. Ensure that the OpenTelemetry components are enabled, +as mentioned in the [Prerequisites](#prerequisites). + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +Temporarily enable the `debug` exporter in the OpenTelemetry Collector +to view metrics in the pod logs using the following command. Debug exporter is enabled for demonstration purposes and +should not be used in production. + +```shell +helm upgrade eg-addons oci://docker.io/envoyproxy/gateway-addons-helm --version {{< helm-version >}} -n monitoring --reuse-values --set opentelemetry-collector.config.service.pipelines.metrics.exporters='{debug,prometheus}' + +``` + +To view the logs of the OpenTelemetry Collector, use the following command: + +```shell +export OTEL_POD_NAME=$(kubectl get pod -n monitoring --selector=app.kubernetes.io/name=opentelemetry-collector -o jsonpath='{.items[0].metadata.name}') +kubectl logs -n monitoring -f $OTEL_POD_NAME --tail=100 + +``` + +## Next Steps + +Check out the [Visualising metrics using Grafana](./grafana-integration.md) section to learn more about how you can observe all the metrics in one place. \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/observability/proxy-trace.md b/site/content/en/v1.8/tasks/observability/proxy-trace.md new file mode 100644 index 0000000000..363abdc598 --- /dev/null +++ b/site/content/en/v1.8/tasks/observability/proxy-trace.md @@ -0,0 +1,424 @@ +--- +title: "Proxy Tracing" +--- + +Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances. +This task show you how to config proxy tracing. + +## Prerequisites + +{{< boilerplate o11y_prerequisites >}} + +Expose Tempo endpoints: + +```shell +TEMPO_IP=$(kubectl get svc tempo -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +## Traces + +By default, Envoy Gateway doesn't send traces to any sink. +You can enable traces by setting the `telemetry.tracing` in the [EnvoyProxy][envoy-proxy-crd] CRD. +Currently, Envoy Gateway support OpenTelemetry, [Zipkin](../../api/extension_types#zipkintracingprovider) and Datadog tracer. + +### Tracing Provider + +The following configurations show how to apply proxy with different providers: + +{{< tabpane text=true >}} +{{% tab header="OpenTelemetry" %}} + +```shell +kubectl apply -f - <}} + +Query trace by trace id: + +```shell +curl -s "http://$TEMPO_IP:3100/api/traces/" | jq +``` + + +### Sampling Rate + +Envoy Gateway use 100% sample rate, which means all requests will be traced. +This may cause performance issues when traffic is very high, you can adjust +the sample rate by setting the `telemetry.tracing.samplingRate` in the [EnvoyProxy][envoy-proxy-crd] CRD. + +The following configurations show how to apply proxy with 1% sample rates: + +```shell +kubectl apply -f - <}} + +Follow the steps from the [Global Rate Limit](../traffic/global-rate-limit) to install RateLimit. + +## Metrics + +Envoy Gateway’s RateLimit service exposes Prometheus metrics that help you answer: + +- Are requests being rate-limited? +- Which *domain*/*descriptor keys* are hottest? +- Are you getting close to limits (before you start denying traffic)? + +### Retrieve Prometheus metrics + +1) Find the RateLimit Pod (names can vary by installation): + +```bash +kubectl get pods -n envoy-gateway-system | grep -i ratelimit +``` + +2) Port-forward the metrics port (default is **19001**): + +```bash +export RATELIMIT_POD="" +kubectl -n envoy-gateway-system port-forward pod/${RATELIMIT_POD} 19001:19001 +``` + +3) Verify the metrics exist and check the exact metric names: + +```bash +curl -s localhost:19001/metrics | grep -E '^ratelimit_service_rate_limit_' | head +``` + +> Tip: keep `/metrics` open while you write PromQL. It’s the fastest way to confirm whether a metric is exported as a **counter** (single series) or a **histogram family** (`_bucket`, `_sum`, `_count`). + +### Metric names and meanings + +These metrics are exported per RateLimit *domain* and (by default) up to two descriptor-key labels: + +- `ratelimit_service_rate_limit_total_hits` + Total number of requests evaluated by RateLimit (allowed + denied). + +- `ratelimit_service_rate_limit_over_limit` + Number of requests that were **denied** (rate-limited). + +- `ratelimit_service_rate_limit_near_limit` + Number of requests that were **allowed**, but close enough to the configured limit to be considered “near limit”. + (Useful as an early warning signal.) + +- `ratelimit_service_rate_limit_within_limit` + Number of requests that were **allowed** and not considered “near limit”. + (Good for dashboards tracking allowed request QPS.) + +- `ratelimit_service_rate_limit_shadow_mode` + Number of requests evaluated under **shadow mode** (dry-run / not enforced), when shadow mode is enabled in the rate limit service config. + +### Labels + +Typical labels you’ll see: + +- `domain`: the RateLimit domain (a namespace for rate limit configs) +- `key1`: first descriptor key (when present) +- `key2`: second descriptor key (when present) + +> Note: The exported label depth is controlled by the StatsD → Prometheus mapping configuration. By default you should expect **only `domain`, `key1`, and `key2`** to be labeled. Deeper descriptor segments typically won’t appear as additional labels unless the mapping is extended. +> +> **Warning: High Cardinality Risk** +> +> Descriptor keys can include unbounded values (e.g., client IPs, user IDs, unique headers). Grouping or filtering on those labels can create a time series per unique value and cause cardinality explosion in Prometheus. Avoid grouping by high-cardinality labels unless the value set is known and bounded. + +--- + +## PromQL examples + +### Histogram vs counter metric names + +By default, Envoy Gateway’s StatsD → Prometheus mapping emits **histogram-family metrics**. If you customize the mapping, you may instead see **counter-style metrics**. + +- **Histogram-family metrics** (multiple series, default): + - `ratelimit_service_rate_limit_total_hits_bucket` + - `ratelimit_service_rate_limit_total_hits_sum` + - `ratelimit_service_rate_limit_total_hits_count` +- **Counter-style metrics** (single series, custom mapping): + - `ratelimit_service_rate_limit_total_hits` + +If you see `*_count` in `/metrics`, treat that as the primary “counter-like” series and use it with `rate()`. Use the counter-style examples only if the histogram family is not present. + +### RateLimit request rate (QPS) + +**Histogram-style (preferred when `_count` exists):** +```promql +sum(rate(ratelimit_service_rate_limit_total_hits_count[5m])) by (domain, key1, key2) +``` + +**Counter-style (fallback):** +```promql +sum(rate(ratelimit_service_rate_limit_total_hits[5m])) by (domain, key1, key2) +``` + +### Denied request rate (QPS, over-limit) + +**Histogram-style:** +```promql +sum(rate(ratelimit_service_rate_limit_over_limit_count[5m])) by (domain, key1, key2) +``` + +**Counter-style:** +```promql +sum(rate(ratelimit_service_rate_limit_over_limit[5m])) by (domain, key1, key2) +``` + +### Allowed request rate (QPS, within-limit) + +**Histogram-style:** +```promql +sum(rate(ratelimit_service_rate_limit_within_limit_count[5m])) by (domain, key1, key2) +``` + +**Counter-style:** +```promql +sum(rate(ratelimit_service_rate_limit_within_limit[5m])) by (domain, key1, key2) +``` + +### Near-limit request rate (QPS, early warning) + +**Histogram-style:** +```promql +sum(rate(ratelimit_service_rate_limit_near_limit_count[5m])) by (domain, key1, key2) +``` + +**Counter-style:** +```promql +sum(rate(ratelimit_service_rate_limit_near_limit[5m])) by (domain, key1, key2) +``` + +### Over-limit ratio (denied/total) + +This shows the fraction of requests denied by RateLimit. + +**Histogram-style:** +```promql +sum(rate(ratelimit_service_rate_limit_over_limit_count[5m])) by (domain, key1, key2) +/ +sum(rate(ratelimit_service_rate_limit_total_hits_count[5m])) by (domain, key1, key2) +``` + +**Counter-style:** +```promql +sum(rate(ratelimit_service_rate_limit_over_limit[5m])) by (domain, key1, key2) +/ +sum(rate(ratelimit_service_rate_limit_total_hits[5m])) by (domain, key1, key2) +``` + +## Quick self-check while reviewing + +After you apply RateLimit and send traffic, you should be able to see series for at least `total_hits` (and usually `within_limit`/`over_limit`) in `/metrics`. + +If your PromQL query returns nothing: +- Confirm the metric name in `/metrics` (do you have `_count`?). +- Confirm label names in `/metrics` (do you have `key1`/`key2`?). +- Confirm traffic is actually hitting RateLimit (look for `total_hits` moving). + +## Traces + +By default, the Envoy Gateway does not configure RateLimit to send traces to the OpenTelemetry Sink. +You can configure the collector in the `rateLimit.telemetry.tracing` of the `EnvoyGateway`CRD. + +RateLimit uses the OpenTelemetry Exporter to export traces to the collector. +You can configure a collector that supports the OTLP protocol, which includes but is not limited to: OpenTelemetry Collector, Jaeger, Zipkin, and so on. + +***Note:*** + +* By default, the Envoy Gateway configures a `100%` sampling rate for RateLimit, which may lead to performance issues. + +Assuming the OpenTelemetry Collector is running in the `observability` namespace, and it has a service named `otel-svc`, +we only want to sample `50%` of the trace data. We would configure it as follows: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} diff --git a/site/content/en/v1.8/tasks/operations/_index.md b/site/content/en/v1.8/tasks/operations/_index.md new file mode 100644 index 0000000000..d87097c7d1 --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/_index.md @@ -0,0 +1,5 @@ +--- +title: "Operations" +weight: 4 +description: This section includes Operations tasks. +--- diff --git a/site/content/en/v1.8/tasks/operations/airgap-deployment.md b/site/content/en/v1.8/tasks/operations/airgap-deployment.md new file mode 100644 index 0000000000..86579e2d55 --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/airgap-deployment.md @@ -0,0 +1,99 @@ +--- +title: 'Deploy Envoy Gateway in Air-Gapped Environments' +--- + +Deploying the Envoy Gateway in an air-gapped environment using a Helm chart +requires careful configuration of the `values.yaml` file as well as adjustments +when deploying a Gateway resource. + +You will need to specify custom image repositories for the following components +in the Helm chart. This can be done on a global level or image level. + +- Gateway +- Ratelimit + +## Gateway – `values.yaml` Configuration + +Example done in image level: + +```yaml +deployment: + envoyGateway: + image: + repository: custom-cr.internal.io/envoyproxy/gateway + tag: v1.4.1 +``` + +It's also possible to define the registry on a global level: + +```yaml +# Global settings +global: + # If set, these take highest precedence and change both envoyGateway and ratelimit's container registry and pull secrets. + # -- Global override for image registry + imageRegistry: 'custom-cr.internal.io' +``` + +## Ratelimit - `values.yaml` Configuration + +Example done on global level: + +```yaml +global: + images: + ratelimit: + image: custom-cr.internal.io/envoyproxy/ratelimit:master +``` + +Furthermore for private registries you might need to define imagePullSecrets. + +On global level: + +```yaml +global: + imagePullSecrets: + - my-private-registry-secret +``` + +or per image + +```yaml +global: + images: + ratelimit: + pullSecrets: + - name: my-private-registry-secret +``` + +## Gateway Requires a Custom EnvoyProxy Reference + +Either the Gateway or GatewayClass must reference a custom EnvoyProxy resource +that explicitly specifies the location of the distroless Envoy container image. +Without this, the image will be pulled implicitly from Docker Hub. + +For air-gapped deployments, you must configure the EnvoyProxy to use your internal container registry: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: custom-envoy-proxy + namespace: default +spec: + provider: + type: Kubernetes + kubernetes: + envoyDeployment: + container: + image: custom-cr.internal.io/envoyproxy/envoy:distroless-v1.34.1 +``` + +For comprehensive EnvoyProxy configuration options including deployment settings, resource limits, annotations, and other customizations, see [Customize EnvoyProxy](customize-envoyproxy). + +## Default LoadBalancer Service Type + +By default, Envoy uses a Service of type `LoadBalancer`. In air-gapped environments, +you may need to configure service annotations or change the service type depending +on your Kubernetes environment and network restrictions. + +For detailed service configuration options including annotations, service types, and other networking customizations, see [Customize EnvoyProxy](customize-envoyproxy). diff --git a/site/content/en/v1.8/tasks/operations/customize-envoyproxy.md b/site/content/en/v1.8/tasks/operations/customize-envoyproxy.md new file mode 100644 index 0000000000..c09f9ce3ca --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/customize-envoyproxy.md @@ -0,0 +1,1203 @@ +--- +title: "Customize EnvoyProxy" +--- + +Envoy Gateway provides an [EnvoyProxy][] CRD that can be linked to the ParametersRef +in a Gateway and GatewayClass, allowing cluster admins to customize the managed EnvoyProxy Deployment and +Service. To learn more about GatewayClass and ParametersRef, please refer to [Gateway API documentation][]. + +**Note**: We recommend creating a [EnvoyProxy][] resource before creating a Gateway or GatewayClass that references it to avoid temporary disruption. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +Before you start, you need to add `Infrastructure.ParametersRef` in Gateway, and refer to EnvoyProxy Config: +**Note**: `MergeGateways` cannot be set to `true` in your EnvoyProxy config if attaching to the Gateway. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +You can also attach the EnvoyProxy resource to the GatewayClass using the `parametersRef` field. +This configuration is discouraged if you plan on creating multiple Gateways linking to the same +GatewayClass and would like different infrastructure configurations for each of them. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Customize EnvoyProxy Deployment Replicas + +You can customize the EnvoyProxy Deployment Replicas via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After you apply the config, you should see the replicas of envoyproxy changes to 2. +And also you can dynamically change the value. + +``` shell +kubectl get deployment -l gateway.envoyproxy.io/owning-gateway-name=eg -n envoy-gateway-system +``` + +## Customize EnvoyProxy Image + +You can customize the EnvoyProxy Image via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, you can get the deployment image, and see it has changed. + +## Customize EnvoyProxy Pod Annotations + +You can customize the EnvoyProxy Pod Annotations via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, you can get the envoyproxy pods, and see new annotations has been added. + +## Customize EnvoyProxy Deployment Resources + +You can customize the EnvoyProxy Deployment Resources via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Customize EnvoyProxy Deployment Env + +You can customize the EnvoyProxy Deployment Env via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +> Envoy Gateway has provided two initial `env` `ENVOY_POD_NAMESPACE` and `ENVOY_POD_NAME` for envoyproxy container. + +After applying the config, you can get the envoyproxy deployment, and see resources has been changed. + +## Customize EnvoyProxy Deployment Volumes or VolumeMounts + +You can customize the EnvoyProxy Deployment Volumes or VolumeMounts via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, you can get the envoyproxy deployment, and see resources has been changed. + +## Customize EnvoyProxy Priority Class + +You can configure the [PriorityClassName](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/) for the Envoy Proxy pods via EnvoyProxy Config. + +**Note:** The PriorityClass must exist in your cluster before creating the EnvoyProxy resource. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, you can get the envoyproxy deployment and see the priorityClassName has been set. + +## Customize EnvoyProxy Service Annotations + +You can customize the EnvoyProxy Service Annotations via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, you can get the envoyproxy service, and see annotations has been added. + +## Customize EnvoyProxy Bootstrap Config + +You can customize the EnvoyProxy bootstrap config via EnvoyProxy Config. +There are three ways to customize it: + +* Replace: the whole bootstrap config will be replaced by the config you provided. +* Merge: the config you provided will be merged into the default bootstrap config. +* JSONPatch: the list of JSON Patches you provided will be applied to the bootstrap config. JSON Patch is a standard format specified in [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/). + +{{< tabpane text=true >}} +{{% tab header="Replace: apply from stdin" %}} + +```shell +cat <}} + +You can use [egctl x translate][] +to get the default xDS Bootstrap configuration used by Envoy Gateway. + +After applying the config, the bootstrap config will be overridden by the new config you provided. +Any errors in the configuration will be surfaced as status within the `GatewayClass` resource. +You can also validate this configuration using [egctl x translate][]. + +## Customize EnvoyProxy Horizontal Pod Autoscaler + +You can enable [Horizontal Pod Autoscaler](https://github.com/envoyproxy/gateway/issues/703) for EnvoyProxy Deployment. However, before enabling the HPA for EnvoyProxy, please ensure that the [metrics-server](https://github.com/kubernetes-sigs/metrics-server) component is installed in the cluster. + +Once confirmed, you can apply it via EnvoyProxy Config as shown below: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, the EnvoyProxy HPA (Horizontal Pod Autoscaler) is generated. However, upon activating the EnvoyProxy's HPA, the Envoy Gateway will no longer reference the `replicas` field specified in the `envoyDeployment`, as outlined [here](#customize-envoyproxy-deployment-replicas). + +## Customize EnvoyProxy Command line options + +You can customize the EnvoyProxy Command line options via `spec.extraArgs` in EnvoyProxy Config. +For example, the following configuration will add `--disable-extensions` arg in order to disable `envoy.access_loggers/envoy.access_loggers.wasm` extension: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Customize EnvoyProxy with Patches + +You can customize the EnvoyProxy using patches. + +### Patching Deployment for EnvoyProxy + +For example, the following configuration will add resource limits to the `envoy` and the `shutdown-manager` containers in the `envoyproxy` deployment: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the configuration, you will see the change in both containers in the `envoyproxy` deployment. + +### Patching Service for EnvoyProxy + +For example, the following configuration will add an annotation for the `envoyproxy` service: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the configuration, you will see the `custom-annotation: foobar` has been added to the `envoyproxy` service. + +## Customize Filter Order + +Under the hood, Envoy Gateway uses a series of [Envoy HTTP filters](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/http_filters) +to process HTTP requests and responses, and to apply various policies. + +By default, Envoy Gateway applies the following filters in the order shown: +* envoy.filters.http.health_check +* envoy.filters.http.fault +* envoy.filters.http.cors +* envoy.filters.http.ext_authz +* envoy.filters.http.api_key_auth +* envoy.filters.http.basic_auth +* envoy.filters.http.oauth2 +* envoy.filters.http.jwt_authn +* envoy.filters.http.stateful_session +* envoy.filters.http.buffer +* envoy.filters.http.lua +* envoy.filters.http.ext_proc +* envoy.filters.http.wasm +* envoy.filters.http.rbac +* envoy.filters.http.local_ratelimit +* envoy.filters.http.ratelimit +* envoy.filters.http.grpc_web +* envoy.filters.http.grpc_stats +* envoy.filters.http.custom_response +* envoy.filters.http.credential_injector +* envoy.filters.http.compressor +* envoy.filters.http.router + +The default order in which these filters are applied is opinionated and may not suit all use cases. +To address this, Envoy Gateway allows you to adjust the execution order of these filters with the `filterOrder` field in the [EnvoyProxy][] resource. + +`filterOrder` is a list of customized filter order configurations. Each configuration can specify a filter +name and a filter to place it before or after. These configurations are applied in the order they are listed. +If a filter occurs in multiple configurations, the final order is the result of applying all these configurations in order. +To avoid conflicts, it is recommended to only specify one configuration per filter. + +For example, the following configuration moves the `envoy.filters.http.wasm` filter before the `envoy.filters.http.jwt_authn` +filter and the `envoy.filters.http.cors` filter after the `envoy.filters.http.basic_auth` filter: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Customize EnvoyProxy IP Family + +You can customize the IP family configuration for EnvoyProxy via the EnvoyProxy Config. +This allows the Envoy Proxy fleet to serve external clients over IPv4 as well as IPv6. + +The below configuration sets the `ipFamily` to `DualStack` to allow ingressing IPv4 as well as IPv6 traffic. + +**Note**: Envoy Gateway relies on the [Service](https://kubernetes.io/docs/concepts/services-networking/dual-stack/#services) spec of the BackendRef resource (linked to xRoutes) to decide which type of IP addresses to use to route to them. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +After applying the config, the EnvoyProxy deployment will be configured to use the specified IP family. When set to `DualStack`, both IPv4 and IPv6 networking will be enabled. + +**Note**: Your cluster must support the selected IP family configuration. For DualStack support, ensure your Kubernetes cluster is properly configured for dual-stack networking. + +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[EnvoyProxy]: ../../../api/extension_types#envoyproxy +[egctl x translate]: ../operations/egctl#egctl-experimental-translate diff --git a/site/content/en/v1.8/tasks/operations/deployment-mode.md b/site/content/en/v1.8/tasks/operations/deployment-mode.md new file mode 100644 index 0000000000..f0b3f922ab --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/deployment-mode.md @@ -0,0 +1,1084 @@ +--- +title: "Deployment Mode" +--- +## Deployment modes + +### One GatewayClass per Envoy Gateway Controller + +* An Envoy Gateway is associated with a single [GatewayClass][] resource under one controller. +This is the simplest deployment mode and is suitable for scenarios where each Gateway needs to have its own dedicated set of resources and configurations. + +### Multiple GatewayClasses per Envoy Gateway Controller + +* An Envoy Gateway is associated with multiple [GatewayClass][] resources under one controller. +* Support for accepting multiple GatewayClasses was added [here][issue1231]. + +### Separate Envoy Gateway Controllers + +If you've instantiated multiple GatewayClasses, you can also run separate Envoy Gateway controllers in different namespaces, linking a GatewayClass to each of them for multi-tenancy. +Please follow the example [Multi-tenancy](#multi-tenancy). + +### Merged Gateways onto a single EnvoyProxy fleet + +By default, each Gateway has its own dedicated set of Envoy Proxy and its configurations. +However, for some deployments, it may be more convenient to merge listeners across multiple Gateways and deploy a single Envoy Proxy fleet. + +This can help to efficiently utilize the infra resources in the cluster and manage them in a centralized manner, or have a single IP address for all of the listeners. +Setting the `mergeGateways` field in the EnvoyProxy resource linked to GatewayClass will result in merging all Gateway listeners under one GatewayClass resource. + +* The tuple of port, protocol, and hostname must be unique across all Listeners. + +Please follow the example [Merged gateways deployment](#merged-gateways-deployment). + +### Gateway Namespace Mode + +Gateway Namespace Mode is a deployment model for Envoy Gateway that creates Envoy Proxy infrastructure resources like Deployments, Services and ServiceAccounts in the namespace where each Gateway resource is defined, rather than in the Envoy Gateway controller namespace. + +* Support for this deployment mode was added [here][issue2629]. + +Please follow the example [Gateway Namespace Mode][]. + +### Supported Modes + +#### Kubernetes + +* The default deployment model is - Envoy Gateway **watches** for resources such a `Service` & `HTTPRoute` in **all** namespaces +and **creates** managed data plane resources such as EnvoyProxy `Deployment` in the **namespace where Envoy Gateway is running**. +* Envoy Gateway also supports [Namespaced deployment mode][], you can watch resources in the specific namespaces by assigning +`EnvoyGateway.provider.kubernetes.watch.namespaces` or `EnvoyGateway.provider.kubernetes.watch.namespaceSelector` and **creates** managed data plane resources in the **namespace where Envoy Gateway is running**. + +### Multi-tenancy + +#### Kubernetes + +* A `tenant` is a group within an organization (e.g. a team or department) who shares organizational resources. We recommend +each `tenant` deploy their own Envoy Gateway controller in their respective `namespace`. Below is an example of deploying Envoy Gateway +by the `marketing` and `product` teams in separate namespaces. + +* Lets deploy Envoy Gateway in the `marketing` namespace and also watch resources only in this namespace. We are also setting the controller name to a unique string here `gateway.envoyproxy.io/marketing-gatewayclass-controller`. + +```shell +helm install \ +--set config.envoyGateway.gateway.controllerName=gateway.envoyproxy.io/marketing-gatewayclass-controller \ +--set config.envoyGateway.provider.kubernetes.watch.type=Namespaces \ +--set config.envoyGateway.provider.kubernetes.watch.namespaces={marketing} \ +eg-marketing oci://docker.io/envoyproxy/gateway-helm \ +--version {{< helm-version >}} -n marketing --create-namespace +``` + +Lets create a `GatewayClass` linked to the marketing team's Envoy Gateway controller, and as well other resources linked to it, so the `backend` application operated by this team can be exposed to external clients. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Lets port forward to the generated envoy proxy service in the `marketing` namespace and send a request to it. + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n marketing --selector=gateway.envoyproxy.io/owning-gateway-namespace=marketing,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +kubectl -n marketing port-forward service/${ENVOY_SERVICE} 8888:8080 & +``` + +```shell +curl --verbose --header "Host: www.marketing.example.com" http://localhost:8888/get +``` + +```console +* Trying 127.0.0.1:8888... +* Connected to localhost (127.0.0.1) port 8888 (#0) +> GET /get HTTP/1.1 +> Host: www.marketing.example.com +> User-Agent: curl/7.86.0 +> Accept: */* +> +Handling connection for 8888 +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Thu, 20 Apr 2023 19:19:42 GMT +< content-length: 521 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "www.marketing.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.86.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "10.1.0.157" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "c637977c-458a-48ae-92b3-f8c429849322" + ] + }, + "namespace": "marketing", + "ingress": "", + "service": "", + "pod": "backend-74888f465f-bcs8f" +* Connection #0 to host localhost left intact +``` + +* Lets deploy Envoy Gateway in the `product` namespace and also watch resources only in this namespace. + +```shell +helm install \ +--set config.envoyGateway.gateway.controllerName=gateway.envoyproxy.io/product-gatewayclass-controller \ +--set config.envoyGateway.provider.kubernetes.watch.type=Namespaces \ +--set config.envoyGateway.provider.kubernetes.watch.namespaces={product} \ +eg-product oci://docker.io/envoyproxy/gateway-helm \ +--version {{< helm-version >}} -n product --create-namespace +``` + +Lets create a `GatewayClass` linked to the product team's Envoy Gateway controller, and as well other resources linked to it, so the `backend` application operated by this team can be exposed to external clients. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Lets port forward to the generated envoy proxy service in the `product` namespace and send a request to it. + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n product --selector=gateway.envoyproxy.io/owning-gateway-namespace=product,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +kubectl -n product port-forward service/${ENVOY_SERVICE} 8889:8080 & +``` + +```shell +curl --verbose --header "Host: www.product.example.com" http://localhost:8889/get +``` + +```shell +* Trying 127.0.0.1:8889... +* Connected to localhost (127.0.0.1) port 8889 (#0) +> GET /get HTTP/1.1 +> Host: www.product.example.com +> User-Agent: curl/7.86.0 +> Accept: */* +> +Handling connection for 8889 +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Thu, 20 Apr 2023 19:20:17 GMT +< content-length: 517 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "www.product.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.86.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "10.1.0.156" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "39196453-2250-4331-b756-54003b2853c2" + ] + }, + "namespace": "product", + "ingress": "", + "service": "", + "pod": "backend-74888f465f-64fjs" +* Connection #0 to host localhost left intact +``` + +With the below command you can ensure that you are no able to access the marketing team's backend exposed using the `www.marketing.example.com` hostname +and the product team's data plane. + +```shell +curl --verbose --header "Host: www.marketing.example.com" http://localhost:8889/get +``` + +```console +* Trying 127.0.0.1:8889... +* Connected to localhost (127.0.0.1) port 8889 (#0) +> GET /get HTTP/1.1 +> Host: www.marketing.example.com +> User-Agent: curl/7.86.0 +> Accept: */* +> +Handling connection for 8889 +* Mark bundle as not supporting multiuse +< HTTP/1.1 404 Not Found +< date: Thu, 20 Apr 2023 19:22:13 GMT +< server: envoy +< content-length: 0 +< +* Connection #0 to host localhost left intact +``` + +### Merged gateways deployment + +In this example, we will deploy GatewayClass + +```shell +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: merged-eg +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller + parametersRef: + group: gateway.envoyproxy.io + kind: EnvoyProxy + name: custom-proxy-config + namespace: envoy-gateway-system +``` + +with a referenced [EnvoyProxy][] resource configured to enable merged Gateways deployment mode. + +```shell +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: custom-proxy-config + namespace: envoy-gateway-system +spec: + mergeGateways: true +``` + +#### Deploy merged-gateways example + +Deploy resources on your cluster from the example. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/merged-gateways.yaml +``` + +Verify that Gateways are deployed and programmed + +```shell +kubectl get gateways -n default + +NAMESPACE NAME CLASS ADDRESS PROGRAMMED AGE +default merged-eg-1 merged-eg 172.18.255.202 True 2m4s +default merged-eg-2 merged-eg 172.18.255.202 True 2m4s +default merged-eg-3 merged-eg 172.18.255.202 True 2m4s +``` + +Verify that HTTPRoutes are deployed + +```shell +kubectl get httproute -n default +NAMESPACE NAME HOSTNAMES AGE +default hostname1-route ["www.merged1.com"] 2m4s +default hostname2-route ["www.merged2.com"] 2m4s +default hostname3-route ["www.merged3.com"] 2m4s +``` + +If you take a look at the deployed Envoy Proxy service you would notice that all of the Gateway listeners ports are added to that service. + +```shell +kubectl get service -n envoy-gateway-system +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy-gateway ClusterIP 10.96.141.4 18000/TCP,18001/TCP 6m43s +envoy-gateway-metrics-service ClusterIP 10.96.113.191 19001/TCP 6m43s +envoy-merged-eg-668ac7ae LoadBalancer 10.96.48.255 172.18.255.202 8081:30467/TCP,8082:31793/TCP,8080:31153/TCP 3m17s +``` + +There should be also one deployment (envoy-merged-eg-668ac7ae-775f9865d-55zhs) for every Gateway and its name should reference the name of the GatewayClass. + +```shell +kubectl get pods -n envoy-gateway-system +NAME READY STATUS RESTARTS AGE +envoy-gateway-5d998778f6-wr6m9 1/1 Running 0 6m43s +envoy-merged-eg-668ac7ae-775f9865d-55zhs 2/2 Running 0 3m17s +``` + +#### Testing the Configuration + +Get the name of the merged gateways Envoy service: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gatewayclass=merged-eg -o jsonpath='{.items[0].metadata.name}') +``` + +Fetch external IP of the service: + +```shell +export GATEWAY_HOST=$(kubectl get svc/${ENVOY_SERVICE} -n envoy-gateway-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +In certain environments, the load balancer may be exposed using a hostname, instead of an IP address. If so, replace +`ip` in the above command with `hostname`. + +Curl the route hostname-route2 through Envoy proxy: + +```shell +curl --header "Host: www.merged2.com" http://$GATEWAY_HOST:8081/example2 +``` + +```shell +{ + "path": "/example2", + "host": "www.merged2.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.4.0" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "deed2767-a483-4291-9429-0e256ab3a65f" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "merged-backend-64ddb65fd7-ttv5z" +} +``` + +Curl the route hostname-route1 through Envoy proxy: + +```shell +curl --header "Host: www.merged1.com" http://$GATEWAY_HOST:8080/example +``` + +```shell +{ + "path": "/example", + "host": "www.merged1.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.4.0" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "20a53440-6327-4c3c-bc8b-8e79e7311043" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "merged-backend-64ddb65fd7-ttv5z" +} +``` + +#### Verify deployment of multiple GatewayClass + +Install the GatewayClass, Gateway, HTTPRoute and example app from [Quickstart][] example: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default +``` + +Lets create also and additional `Gateway` linked to the GatewayClass and `backend` application from Quickstart example. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify that Gateways are deployed and programmed + +```shell +kubectl get gateways -n default +``` + +```shell +NAME CLASS ADDRESS PROGRAMMED AGE +eg eg 172.18.255.203 True 114s +eg-2 eg 172.18.255.204 True 89s +merged-eg-1 merged-eg 172.18.255.202 True 8m33s +merged-eg-2 merged-eg 172.18.255.202 True 8m33s +merged-eg-3 merged-eg 172.18.255.202 True 8m33s +``` + +Verify that HTTPRoutes are deployed + +```shell +kubectl get httproute -n default +``` + +```shell +NAMESPACE NAME HOSTNAMES AGE +default backend ["www.example.com"] 2m29s +default eg-2 ["www.quickstart.example.com"] 87s +default hostname1-route ["www.merged1.com"] 10m4s +default hostname2-route ["www.merged2.com"] 10m4s +default hostname3-route ["www.merged3.com"] 10m4s +``` + +Verify that services are now deployed separately. + +```shell +kubectl get service -n envoy-gateway-system +``` + +```shell +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy-default-eg-2-7e515b2f LoadBalancer 10.96.121.46 172.18.255.204 8080:32705/TCP 3m27s +envoy-default-eg-e41e7b31 LoadBalancer 10.96.11.244 172.18.255.203 80:31930/TCP 2m26s +envoy-gateway ClusterIP 10.96.141.4 18000/TCP,18001/TCP 14m25s +envoy-gateway-metrics-service ClusterIP 10.96.113.191 19001/TCP 14m25s +envoy-merged-eg-668ac7ae LoadBalancer 10.96.243.32 172.18.255.202 8082:31622/TCP,8080:32262/TCP,8081:32305/TCP 10m59s +``` + +There should be two deployments for each of newly deployed Gateway and its name should reference the name of the namespace and the Gateway. + +```shell +kubectl get pods -n envoy-gateway-system +``` + +```shell +NAME READY STATUS RESTARTS AGE +envoy-default-eg-2-7e515b2f-8c98fdf88-p6jhg 2/2 Running 0 3m27s +envoy-default-eg-e41e7b31-6f998d85d7-jpvmj 2/2 Running 0 2m26s +envoy-gateway-5d998778f6-wr6m9 1/1 Running 0 14m25s +envoy-merged-eg-668ac7ae-5958f7b7f6-9h9v2 2/2 Running 0 10m59s +``` + +#### Testing the Configuration + +Get the name of the merged gateways Envoy service: + +```shell +export DEFAULT_ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Fetch external IP of the service: + +```shell +export DEFAULT_GATEWAY_HOST=$(kubectl get svc/${DEFAULT_ENVOY_SERVICE} -n envoy-gateway-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +Curl the route Quickstart backend route through Envoy proxy: + +```shell +curl --header "Host: www.example.com" http://$DEFAULT_GATEWAY_HOST +``` + +```shell +{ + "path": "/", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.4.0" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "70a40595-67a1-4776-955b-2dee361baed7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-96f75bbf-6w67z" +} +``` + +Curl the route hostname-route3 through Envoy proxy: + +```shell +curl --header "Host: www.merged3.com" http://$GATEWAY_HOST:8082/example3 +``` + +```shell +{ + "path": "/example3", + "host": "www.merged3.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.4.0" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "47aeaef3-abb5-481a-ab92-c2ae3d0862d6" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "merged-backend-64ddb65fd7-k84gv" +} +``` + +[Quickstart]: ../quickstart.md +[EnvoyProxy]: ../../api/extension_types#envoyproxy +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Namespaced deployment mode]: ../../api/extension_types#kuberneteswatchmode +[Gateway Namespace Mode]: ./gateway-namespace-mode +[issue1231]: https://github.com/envoyproxy/gateway/issues/1231 +[issue2629]: https://github.com/envoyproxy/gateway/issues/2629 diff --git a/site/content/en/v1.8/tasks/operations/egctl.md b/site/content/en/v1.8/tasks/operations/egctl.md new file mode 100644 index 0000000000..a6cca6968e --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/egctl.md @@ -0,0 +1,1078 @@ +--- +title: "Use egctl" +--- + +`egctl` is a command line tool to provide additional functionality for Envoy Gateway users. + +Follow the instructions [here](./../../install/install-egctl.md) to install `egctl`. + +## egctl config + +The `egctl config` subcommand provides tools for viewing and validating the Envoy Proxy and Envoy RateLimit configuration configured in Envoy Proxy. + +Here's an example of retrieving the [xDS Route Configuration](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route.proto#envoy-v3-api-msg-config-route-v3-routeconfiguration) from all the proxies. + +```console +~ egctl config envoy-proxy route +{ + "envoy-gateway-system": { + "envoy-default-eg-e41e7b31-6d749cdb85-hcfrk": { + "@type": "type.googleapis.com/envoy.admin.v3.RoutesConfigDump", + "dynamicRouteConfigs": [ + { + "lastUpdated": "2025-05-22T17:51:06.237Z", + "routeConfig": { + "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", + "ignorePortInHostMatching": true, + "name": "default/eg/http", + "virtualHosts": [ + { + "domains": [ + "www.example.com" + ], + "metadata": { + "filterMetadata": { + "envoy-gateway": { + "resources": [ + { + "kind": "Gateway", + "name": "eg", + "namespace": "default", + "sectionName": "http" + } + ] + } + } + }, + "name": "default/eg/http/www_example_com", + "routes": [ + { + "match": { + "prefix": "/" + }, + "metadata": { + "filterMetadata": { + "envoy-gateway": { + "resources": [ + { + "kind": "HTTPRoute", + "name": "backend", + "namespace": "default" + } + ] + } + } + }, + "name": "httproute/default/backend/rule/0/match/0/www_example_com", + "route": { + "cluster": "httproute/default/backend/rule/0", + "upgradeConfigs": [ + { + "upgradeType": "websocket" + } + ] + } + } + ] + } + ] + }, + "versionInfo": "bc44981323d08bcb24abad6867942912675bb35bb674f2ee9ae866efbe1375dd" + } + ], + "staticRouteConfigs": [ + { + "lastUpdated": "2025-05-22T17:51:06.198Z", + "routeConfig": { + "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", + "name": "local_route", + "virtualHosts": [ + { + "domains": [ + "*" + ], + "name": "prometheus_stats", + "routes": [ + { + "match": { + "headers": [ + { + "name": ":method", + "stringMatch": { + "exact": "GET" + } + } + ], + "path": "/stats/prometheus" + }, + "route": { + "cluster": "prometheus_stats" + } + } + ] + } + ] + } + }, + { + "lastUpdated": "2025-05-22T17:51:06.219Z", + "routeConfig": { + "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", + "name": "ready_route", + "virtualHosts": [ + { + "domains": [ + "*" + ], + "name": "ready_route", + "routes": [ + { + "directResponse": { + "status": 500 + }, + "match": { + "prefix": "/" + } + } + ] + } + ] + } + } + ] + } + } +} +``` + +`egctl config` also supports reading Envoy Gateway in-memory resources through the Envoy Gateway admin API config dump endpoint. + +```console +~ egctl config envoy-gateway all -n envoy-gateway-system +{ + "envoy-gateway-system": { + "envoy-gateway-6d8f9d7d9f-abcde": [ + { + "gatewayClass": { + "metadata": { + "name": "eg" + } + }, + "gateways": [ + { + "metadata": { + "name": "eg", + "namespace": "default" + } + } + ] + } + ] + } +} +``` + +You can also retrieve a specific resource type from Envoy Gateway memory. For example: + +```console +~ egctl config envoy-gateway gateway -n envoy-gateway-system +``` + +## egctl experimental status + +This subcommand allows users to show the summary of the status of specific or all resource types, in order to quickly find +out the status of any resources. + +By default, `egctl x status` display all the conditions for one resource type. You can either add `--quiet` to only +display the latest condition, or add `--verbose` to display more details about current status. + +{{% alert title="Note" color="primary" %}} + +The resource types that this subcommand currently supports: + +- `xRoute`, `HTTPRoute`, `GRPCRoute`, `TLSRoute`, `TCPRoute`, `UDPRoute` +- `xPolicy`, `BackendTLSPolicy`, `BackendTrafficPolicy`, `ClientTrafficPolicy`, `EnvoyPatchPolicy`, `SecurityPolicy` +- `all`, `GatewayClass`, `Gateway` + +{{% /alert %}} + +Some examples of this command after installing [Multi-tenancy][] example manifest: + +- Show the summary of GatewayClass. + +```console +~ egctl x status gatewayclass + +NAME TYPE STATUS REASON +eg-marketing Accepted True Accepted +eg-product Accepted True Accepted +``` + +- Show the summary of all resource types under all namespaces, the resource type with empty status will be ignored. + +```console +~ egctl x status all -A + +NAME TYPE STATUS REASON +gatewayclass/eg-marketing Accepted True Accepted +gatewayclass/eg-product Accepted True Accepted + +NAMESPACE NAME TYPE STATUS REASON +marketing gateway/eg Programmed True Programmed + Accepted True Accepted +product gateway/eg Programmed True Programmed + Accepted True Accepted + +NAMESPACE NAME PARENT TYPE STATUS REASON +marketing httproute/backend gateway/eg ResolvedRefs True ResolvedRefs + Accepted True Accepted +product httproute/backend gateway/eg ResolvedRefs True ResolvedRefs + Accepted True Accepted +``` + +- Show the summary of all the Gateways with details under all namespaces. + +```console +~ egctl x status gateway --verbose --all-namespaces + +NAMESPACE NAME TYPE STATUS REASON MESSAGE OBSERVED GENERATION LAST TRANSITION TIME +marketing eg Programmed True Programmed Address assigned to the Gateway, 1/1 envoy Deployment replicas available 1 2024-02-02 18:17:14 +0800 CST + Accepted True Accepted The Gateway has been scheduled by Envoy Gateway 1 2024-02-01 17:50:39 +0800 CST +product eg Programmed True Programmed Address assigned to the Gateway, 1/1 envoy Deployment replicas available 1 2024-02-02 18:17:14 +0800 CST + Accepted True Accepted The Gateway has been scheduled by Envoy Gateway 1 2024-02-01 17:52:42 +0800 CST +``` + +- Show the summary of the latest Gateways condition under `product` namespace. + +```console +~ egctl x status gateway --quiet -n product + +NAME TYPE STATUS REASON +eg Programmed True Programmed +``` + +- Show the summary of latest HTTPRoutes condition under all namespaces. + +```console +~ egctl x status httproute --quiet --all-namespaces + +NAMESPACE NAME PARENT TYPE STATUS REASON +marketing backend gateway/eg ResolvedRefs True ResolvedRefs +product backend gateway/eg ResolvedRefs True ResolvedRefs +``` + +[Multi-tenancy]: ../deployment-mode#multi-tenancy +[EnvoyProxy]: ../../../api/extension_types#envoyproxy + +## egctl experimental dashboard + +This subcommand streamlines the process for users to access the Envoy admin dashboard. By executing the following command: + +```bash +egctl x dashboard envoy-proxy -n envoy-gateway-system envoy-engw-eg-a9c23fbb-558f94486c-82wh4 +``` + +You will see the following output: + +```bash +egctl x dashboard envoy-proxy -n envoy-gateway-system envoy-engw-eg-a9c23fbb-558f94486c-82wh4 +http://localhost:19000 +``` + +the Envoy admin dashboard will automatically open in your default web browser. This eliminates the need to manually locate and expose the admin port. + + +## egctl experimental install + +This subcommand can be used to install envoy-gateway. + +```bash +egctl x install +``` + +By default, this will install both the envoy-gateway workload resource and the required gateway-api and envoy-gatewayCRDs. + +We can specify to install only workload resources via `--skip-crds` + +```bash +egctl x install --skip-crds +``` + +We can specify to install only CRDs resources via `--only-crds` + +```bash +egctl x install --only-crds +``` + +We can specify `--name` and `--namespace` to install envoy-gateway in different places to support multi-tenant mode. +> Note: If CRDs are already installed, then we need to specify `--skip-crds` to avoid repeated installation of CRDs resources. + +```bash +egctl x install --name shop-backend --namespace shop +``` + +## egctl experimental uninstall + +This subcommand can be used to uninstall envoy-gateway. + +```bash +egctl x uninstall +``` + +By default, this will only uninstall the envoy-gateway workload resource, if we want to also uninstall CRDs, we need to specify `--with-crds` + +```bash +egctl x uninstall --with-crds +``` + +## egctl experimental translate + +This subcommand allows users to translate from an input configuration type to an output configuration type. + +The `translate` subcommand can translate Kubernetes resources to: +* Gateway API resources + This is useful in order to see how validation would occur if these resources were applied to Kubernetes. + + Use the `--to gateway-api` parameter to translate to Gateway API resources. + +* Envoy Gateway intermediate representation (IR) + This represents Envoy Gateway's translation of the Gateway API resources. + + Use the `--to ir` parameter to translate to Envoy Gateway intermediate representation. + +* Envoy Proxy xDS + This is the xDS configuration provided to Envoy Proxy. + + Use the `--to xds` parameter to translate to Envoy Proxy xDS. + + +In the below example, we will translate the Kubernetes resources (including the Gateway API resources) into xDS +resources. + +```shell +cat <}} -n envoy-gateway-system --create-namespace +``` + +### RBAC configuration + +When using Gateway Namespace Mode, Envoy Gateway needs additional RBAC permissions to create and manage resources across different namespaces. The following RBAC resources are automatically created when installing Envoy Gateway Helm Chart with Gateway Namespace Mode enabled. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: gateway-helm-cluster-infra-manager +rules: +- apiGroups: [""] + resources: ["serviceaccounts", "services", "configmaps"] + verbs: ["create", "get", "delete", "deletecollection", "patch"] +- apiGroups: ["apps"] + resources: ["deployments", "daemonsets"] + verbs: ["create", "get", "delete", "deletecollection", "patch"] +- apiGroups: ["autoscaling", "policy"] + resources: ["horizontalpodautoscalers", "poddisruptionbudgets"] + verbs: ["create", "get", "delete", "deletecollection", "patch"] +- apiGroups: ["authentication.k8s.io"] + resources: ["tokenreviews"] + verbs: ["create"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: gateway-helm-cluster-infra-manager +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: 'gateway-helm-cluster-infra-manager' +subjects: +- kind: ServiceAccount + name: 'envoy-gateway' + namespace: 'envoy-gateway-system' +``` + +### Watch Mode Configuration + +Envoy Gateway also supports configuration to watch resources only in specific namespaces by using: +- `EnvoyGateway.provider.kubernetes.watch.namespaces` - An explicit list of namespace names +- `EnvoyGateway.provider.kubernetes.watch.namespaceSelector` - A label selector for dynamic namespace selection + +#### Using Explicit Namespace List + +When you specify an explicit namespace list with Gateway Namespace Mode, Envoy Gateway will: +- Only watch for Gateway API resources in the specified namespaces +- Create namespace-scoped Roles for infrastructure management in each specified namespace + +Example configuration: +```yaml +envoyGateway: + provider: + type: Kubernetes + kubernetes: + deploy: + type: GatewayNamespace + watch: + type: Namespaces + namespaces: + - team-a + - team-b +``` + +#### Using Namespace Selector + +When you use a namespace selector with Gateway Namespace Mode, Envoy Gateway will: +- Watch for Gateway API resources in all namespaces matching the label selector +- Use a ClusterRole for infrastructure management (since target namespaces are determined dynamically at runtime) + +Example configuration: +```yaml +envoyGateway: + provider: + type: Kubernetes + kubernetes: + deploy: + type: GatewayNamespace + watch: + type: NamespaceSelector + namespaceSelector: + matchLabels: + gateway: enabled +``` + +**Note:** When using `NamespaceSelector`, the ClusterRole for infrastructure management is automatically created by the Helm chart, providing permissions across all namespaces that match the selector. + +## Testing + +The following example demonstrates deploying two Gateways in different namespaces `team-a` and `team-b`. + +### Create test namespaces + +```shell +kubectl create namespace team-a +kubectl create namespace team-b +``` + +### Deploy Gateway Namespace Mode Example + +Deploy resources on your cluster from the example, it will create two sets of backend deployments, Gateways and their respective HTTPRoutes in the previously created namespaces `team-a` and `team-b`. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/{{< yaml-version >}}/examples/kubernetes/gateway-namespace-mode.yaml +``` + +Verify that Gateways are deployed and programmed + +```shell +kubectl get gateways -n team-a + +NAME CLASS ADDRESS PROGRAMMED AGE +gateway-a eg 172.18.0.200 True 67s +``` + +```shell +kubectl get gateways -n team-b + +NAME CLASS ADDRESS PROGRAMMED AGE +gateway-b eg 172.18.0.201 True 67s +``` + +Verify that HTTPRoutes are deployed + +```shell +kubectl get httproute -n team-a + +NAME HOSTNAMES AGE +team-a-route ["www.team-a.com"] 67s +``` + +```shell +kubectl get httproute -n team-b + +NAME HOSTNAMES AGE +team-b-route ["www.team-b.com"] 67s +``` + +Envoy Proxy resources should be created now in the namespace of every Gateway. + +```shell +kubectl get pods -n team-a + +NAME READY STATUS RESTARTS AGE +envoy-team-a-gateway-a-b65c6264-d56f5d989-6dv5s 2/2 Running 0 65s +team-a-backend-6f786fb76f-nx26p 1/1 Running 0 65s +``` + +```shell +kubectl get pods -n team-b + +NAME READY STATUS RESTARTS AGE +envoy-team-b-gateway-b-0ac91f5a-74f445884f-95pl8 2/2 Running 0 87s +team-b-backend-966b5f47c-zxngl 1/1 Running 0 87s +``` + +```shell +kubectl get services -n team-a + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy-team-a-gateway-a-b65c6264 LoadBalancer 10.96.191.198 172.18.0.200 8080:30999/TCP 3m2s +team-a-backend ClusterIP 10.96.92.226 3000/TCP 3m2s +``` + +```shell +kubectl get services -n team-b + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy-team-b-gateway-b-0ac91f5a LoadBalancer 10.96.144.13 172.18.0.201 8081:31683/TCP 3m43s +team-b-backend ClusterIP 10.96.26.162 3000/TCP 3m43s +``` + +### Testing the Configuration + +Fetch external IPs of the services: + +```shell +export GATEWAY_HOST_A=$(kubectl get gateway/gateway-a -n team-a -o jsonpath='{.status.addresses[0].value}') +``` + +```shell +export GATEWAY_HOST_B=$(kubectl get gateway/gateway-b -n team-b -o jsonpath='{.status.addresses[0].value}') +``` + +Curl the route team-a-route through Envoy proxy: + +```shell +curl --header "Host: www.team-a.com" http://$GATEWAY_HOST_A:8080/example +``` + +```shell +{ + "path": "/example", + "host": "www.team-a.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "172.18.0.3" + ], + "X-Forwarded-For": [ + "172.18.0.3" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "52f08a5c-7e07-43b7-bd23-44693c60fc0c" + ] + }, + "namespace": "team-a", + "ingress": "", + "service": "", + "pod": "team-a-backend-6f786fb76f-nx26p" +``` + +Curl the route team-b-route through Envoy proxy: + +```shell +curl --header "Host: www.team-b.com" http://$GATEWAY_HOST_B:8081/example +``` + +```shell +{ + "path": "/example", + "host": "www.team-b.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "172.18.0.3" + ], + "X-Forwarded-For": [ + "172.18.0.3" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "62a06bd7-4754-475b-854a-dca3fc159e93" + ] + }, + "namespace": "team-b", + "ingress": "", + "service": "", + "pod": "team-b-backend-966b5f47c-d6jwj" +``` diff --git a/site/content/en/v1.8/tasks/operations/graceful-shutdown.md b/site/content/en/v1.8/tasks/operations/graceful-shutdown.md new file mode 100644 index 0000000000..3f6bc08f20 --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/graceful-shutdown.md @@ -0,0 +1,91 @@ +--- +title: "Graceful Shutdown and Hitless Upgrades" +--- + +Envoy Gateway enables zero-downtime deployments through graceful connection draining during pod termination. + +## Overview + +The shutdown manager sidecar coordinates graceful connection draining during pod termination, providing: + +- Zero-downtime rolling updates +- Configurable drain timeouts +- Automatic health check failure to remove pods from load balancer rotation + +### Shutdown Process + +1. Kubernetes sends SIGTERM to the pod +2. Shutdown manager fails health checks via `/healthcheck/fail` + - This causes Kubernetes readiness probes to fail + - External load balancers and services stop routing new traffic to the pod + - Existing connections continue to be served while draining +3. Connection monitoring begins, polling `server.total_connections` +4. Process exits when connections reach zero or drain timeout is exceeded + +## Configuration + +Graceful shutdown behavior includes default values that can be overridden using the EnvoyProxy resource. The EnvoyProxy resource can be referenced in two ways: +1. **Gateway-level**: Referenced from a Gateway via `infrastructure.parametersRef` +2. **GatewayClass-level**: Referenced from a GatewayClass via `parametersRef` + +**Default Values:** +- `drainTimeout`: 60 seconds - Maximum time for connection draining +- `minDrainDuration`: 10 seconds - Minimum wait before allowing exit + +{{< tabpane text=true >}} +{{% tab header="Gateway-Level Configuration" %}} + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: eg +spec: + gatewayClassName: eg + infrastructure: + parametersRef: + group: gateway.envoyproxy.io + kind: EnvoyProxy + name: graceful-shutdown-config + listeners: + - name: http + port: 80 + protocol: HTTP +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: graceful-shutdown-config +spec: + shutdown: + drainTimeout: "90s" # Override default 60s + minDrainDuration: "15s" # Override default 10s +``` + +{{% /tab %}} +{{% tab header="GatewayClass-Level Configuration" %}} + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: eg +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller + parametersRef: + group: gateway.envoyproxy.io + kind: EnvoyProxy + name: graceful-shutdown-config +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyProxy +metadata: + name: graceful-shutdown-config +spec: + shutdown: + drainTimeout: "90s" # Override default 60s + minDrainDuration: "15s" # Override default 10s +``` + +{{% /tab %}} +{{< /tabpane >}} diff --git a/site/content/en/v1.8/tasks/operations/standalone-deployment-mode.md b/site/content/en/v1.8/tasks/operations/standalone-deployment-mode.md new file mode 100644 index 0000000000..c8527a9433 --- /dev/null +++ b/site/content/en/v1.8/tasks/operations/standalone-deployment-mode.md @@ -0,0 +1,278 @@ +--- +title: "Standalone Deployment Mode" +--- + +{{% alert title="Notice" color="warning" %}} + +Standalone mode is an experimental feature, please **DO NOT** use it in production. + +{{% /alert %}} + +Envoy Gateway also supports running in standalone mode. In this mode, Envoy Gateway +does not need to rely on Kubernetes and can be deployed directly on bare metal or virtual machines. + +Currently, Envoy Gateway only supports the file provider and the host infrastructure provider combinations. + +- The file provider will configure the Envoy Gateway to get all gateway-api resources from file system. +- The host infrastructure provider will configure the Envoy Gateway to deploy one Envoy Proxy as a host process. + +# Quick Start + +## Running locally on the host machine + +In this quick-start, we will run Envoy Gateway in standalone mode with the file provider +and the host infrastructure provider. + +### Prerequisites + +Create a local directory just for testing: + +```shell +mkdir -p /tmp/envoy-gateway-test +``` + +You can download the Envoy Gateway binary from [Github release](https://github.com/envoyproxy/gateway/releases/tag/{{< yaml-version >}}), +or compile the binary on your own from project by using command: + +```shell +make build +``` + +The compiled binary lies in `{project-home}/bin/{os}/{arch}/envoy-gateway`. + +### Create Certificates + +All runners in Envoy Gateway are using TLS connection, so create these TLS certificates locally to +ensure the Envoy Gateway works properly. + +```shell +envoy-gateway certgen --local +``` + +By default, certificates are stored in `~/.config/envoy-gateway/certs/`. You can customize this +location using the `--config-home` flag (certs will be in a `certs/` subdirectory): + +```shell +envoy-gateway certgen --local --config-home /custom/config/path +``` + +### Start Envoy Gateway + +Start Envoy Gateway by the following command: + +```shell +envoy-gateway server --config-path standalone.yaml +``` + +with `standalone.yaml` configuration: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyGateway +gateway: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +provider: + type: Custom + custom: + resource: + type: File + file: + paths: ["/tmp/envoy-gateway-test"] + infrastructure: + type: Host + host: + # Optional: Configure XDG-compliant directory paths + # If not specified, uses XDG Base Directory defaults: + # - configHome: ~/.config/envoy-gateway + # - dataHome: ~/.local/share/envoy-gateway + # - stateHome: ~/.local/state/envoy-gateway + # - runtimeDir: /tmp/envoy-gateway-${UID} + # Example custom configuration: + # dataHome: /custom/data/path +logging: + level: + default: info +extensionApis: + enableBackend: true +``` + +As you can see, we have enabled the [Backend][] API, this API will be used to represent our local endpoints. + +### Trigger an Update + +Any changes under watched `paths` will be considered as an update by the file provider. + +For instance, copying example file into `/tmp/envoy-gateway-test/` will trigger an update of gateway-api resources: + +```shell +cp examples/standalone/quickstart.yaml /tmp/envoy-gateway-test/quickstart.yaml +``` + +From the Envoy Gateway log, you should be able to observe that the Envoy Proxy has been started, and its admin address has been returned. + +### Test Connection + +Starts a simple local server as an endpoint: + +```shell +python3 -m http.server 3000 +``` + +Curl the example server through Envoy Proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://0.0.0.0:8888/ +``` + +```console +* Trying 0.0.0.0:8888... +* Connected to 0.0.0.0 (127.0.0.1) port 8888 (#0) +> GET / HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/7.81.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< server: SimpleHTTP/0.6 Python/3.10.12 +< date: Sat, 26 Oct 2024 13:20:34 GMT +< content-type: text/html; charset=utf-8 +< content-length: 1870 +< +... +* Connection #0 to host 0.0.0.0 left intact +``` + +## Running in a Container + +In this quick-start, we will run Envoy Gateway in standalone mode with the file provider +and the host infrastructure provider. + +### Prerequisites + +Create a local directory just for testing: + +```shell +mkdir -p /tmp/envoy-gateway-test/config +chmod -R 777 /tmp/envoy-gateway-test +``` + +Create a container network to run Envoy Gateway and a local server: + +```shell +docker network create envoy-gateway-test +``` + +It's important to widen permissions of a created directory to avoid `Permission denied` error + +### Create Certificates + +All runners in Envoy Gateway are using TLS connection, so create these TLS certificates locally to +ensure the Envoy Gateway works properly. + +```shell +docker run --rm --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway envoyproxy/gateway:{{< helm-version >}} certgen --local --config-home /tmp/envoy-gateway +``` + +### Start Envoy Gateway + +The following configuration should be placed into `/tmp/envoy-gateway-test/standalone.yaml` on the host: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyGateway +gateway: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +provider: + type: Custom + custom: + resource: + type: File + file: + paths: ["/tmp/envoy-gateway/config"] + infrastructure: + type: Host + host: + # Configure configHome and dataHome to use the mounted volume + # configHome: for certificates + # dataHome: for Envoy binaries + configHome: /tmp/envoy-gateway + dataHome: /tmp/envoy-gateway +logging: + level: + default: info +extensionApis: + enableBackend: true +``` + +Start Envoy Gateway by the following command: + +```shell +$ docker run \ + --name envoy-gateway \ + --network envoy-gateway-test \ + --publish 8888:8888 \ + --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway \ + --detach \ + envoyproxy/gateway:{{< helm-version >}} \ + server --config-path /tmp/envoy-gateway/standalone.yaml +``` + +As you can see, we have enabled the [Backend][] API, this API will be used to represent our local endpoints. + +### Trigger an Update + +Any changes under watched `paths` will be considered as an update by the file provider. + +For instance, copying example file into `/tmp/envoy-gateway/config` will trigger an update of gateway-api resources: + +```shell +cp examples/standalone/quickstart-containers.yaml /tmp/envoy-gateway-test/config/ +``` + +From the Envoy Gateway log, you should be able to observe that the Envoy Proxy has been started, and its admin address has been returned. + +### Test Connection + +Starts a simple local server in a same container network: + +```shell +$ docker run \ + --name local-server \ + --hostname local-server.local \ + --network envoy-gateway-test \ + --detach \ + python:3 \ + python3 -m http.server 3000 +``` + +The `--hostname` field values is used in `Backend` object of Envoy Gateway as FQDN. +This way there is no need to update `Backend` object if IP address of container changed. + +Curl the example server through Envoy Proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://0.0.0.0:8888/ +``` + +```console +* Trying 0.0.0.0:8888... +* Connected to 0.0.0.0 (0.0.0.0) port 8888 +* using HTTP/1.x +> GET / HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.11.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 200 OK +< server: SimpleHTTP/0.6 Python/3.13.1 +< date: Wed, 29 Jan 2025 17:04:11 GMT +< content-type: text/html; charset=utf-8 +< content-length: 877 +< +... +* Connection #0 to host 0.0.0.0 left intact +``` + +[Backend]: ../../../api/extension_types#backend diff --git a/site/content/en/v1.8/tasks/quickstart.md b/site/content/en/v1.8/tasks/quickstart.md new file mode 100644 index 0000000000..5605e0aeb4 --- /dev/null +++ b/site/content/en/v1.8/tasks/quickstart.md @@ -0,0 +1,128 @@ +--- +title: "Quickstart" +weight: 1 +description: Get started with Envoy Gateway in a few simple steps. +--- + +This "quick start" will help you get started with Envoy Gateway in a few simple steps. + +## Prerequisites + +A Kubernetes cluster. + +__Note:__ Refer to the [Compatibility Matrix](/news/releases/matrix) for supported Kubernetes versions. + +__Note:__ In case your Kubernetes cluster does not have a LoadBalancer implementation, we recommend installing one +so the `Gateway` resource has an Address associated with it. We recommend using [MetalLB](https://metallb.universe.tf/installation/). + +## Installation + +Install the Gateway API CRDs and Envoy Gateway: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace +``` + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available +``` + +Install the [GatewayClass][], [Gateway][], [HTTPRoute][] and example app: + +```shell +kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default +``` + +**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for +traffic on port 80 on its globally-routable IP address, to make it easy to use +browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is +using a privileged port (<1024), it will map this internally to an +unprivileged port, so that Envoy Gateway doesn't need additional privileges. +It's important to be aware of this mapping, since you may need to take it into +consideration when debugging. + +[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml + +## Testing the Configuration + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +You can also test the same functionality by sending traffic to the External IP. To get the external IP of the +Envoy service, run: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +In certain environments, the load balancer may be exposed using a hostname, instead of an IP address. If so, replace +`ip` in the above command with `hostname`. + +Curl the example app through Envoy proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 & +``` + +Curl the example app through Envoy proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://localhost:8888/get +``` + +{{% /tab %}} +{{< /tabpane >}} + +## What to explore next? + +In this quickstart, you have: +- Installed Envoy Gateway +- Deployed a backend service, and a gateway +- Configured the gateway using Kubernetes Gateway API resources [Gateway][] and [HTTPRoute][] to direct incoming requests over HTTP to the backend service. + +Here is a suggested list of follow-on tasks to guide you in your exploration of Envoy Gateway: + +- [HTTP Routing](traffic/http-routing) +- [Traffic Splitting](traffic/http-traffic-splitting) +- [Secure Gateways](security/secure-gateways/) +- [Global Rate Limit](traffic/global-rate-limit/) +- [gRPC Routing](traffic/grpc-routing/) + +Review the [Tasks](_index.md) section for the scenario matching your use case. The Envoy Gateway tasks are organized by category: traffic management, security, extensibility, observability, and operations. + +## Clean-Up + +Use the steps in this section to uninstall everything from the quickstart. + +Delete the [GatewayClass][], [Gateway][], [HTTPRoute][] and Example App: + +```shell +kubectl delete -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml --ignore-not-found=true +``` + +Delete the Gateway API CRDs and Envoy Gateway: + +```shell +helm uninstall eg -n envoy-gateway-system +``` + +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ diff --git a/site/content/en/v1.8/tasks/security/_index.md b/site/content/en/v1.8/tasks/security/_index.md new file mode 100644 index 0000000000..4269d2c5a4 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/_index.md @@ -0,0 +1,8 @@ +--- +title: "Security" +weight: 2 +description: This section includes Security tasks. +--- + +- [GeoIP Authorization](geoip-authorization/) +- [HTTP Header and Method Based Authentication](http-header-method-auth/) diff --git a/site/content/en/v1.8/tasks/security/apikey-auth.md b/site/content/en/v1.8/tasks/security/apikey-auth.md new file mode 100644 index 0000000000..4fa2a082ad --- /dev/null +++ b/site/content/en/v1.8/tasks/security/apikey-auth.md @@ -0,0 +1,213 @@ +--- +title: "API Key Authentication" +--- + +This task provides instructions for configuring API Key Authentication. +API Key Authentication verifies whether an incoming request includes a valid API key in the header, parameter, or cookie before routing the request to +a backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure Api Key +authentication. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +API Key must be stored in a kubernetes secret and referenced in the [SecurityPolicy][] configuration. +The secret is an Opaque secret, with each API key stored under a key corresponding to the client ID. + +> **Important** +> +> When API keys are extracted from the `Authorization` header, the value stored in the Kubernetes +> Secret **must not include the `Bearer` prefix**. +> +> Envoy Gateway compares the extracted header value directly against the stored secret value. +> Authentication scheme prefixes (such as `Bearer`) are not stripped automatically. +> +> For example: +> +> **Non-working configuration** +> ```yaml +> stringData: +> client1: "Bearer my-api-key" +> ``` +> +> **Working configuration** +> ```yaml +> stringData: +> client1: "my-api-key" +> ``` +> +> Clients may still send requests using: +> ```http +> Authorization: Bearer my-api-key +> ``` + + + +### Create an API Key Secret + +Create an Opaque Secret containing the client ID and its corresponding API key + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Create a SecurityPolicy + +The below example defines a SecurityPolicy that authenticates requests against the client list in the kubernetes +secret created in the previous step. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/apikey-auth-example -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `x-api-key` header: + +```shell +curl -kv -H "Host: www.example.com" "http://${GATEWAY_HOST}/" +``` + +You should see `401 Unauthorized` in the response, indicating that the request is not allowed without providing valid API Key in `x-api-key` header. + +```shell +* Connected to 127.0.0.1 (127.0.0.1) port 80 +... +> GET / HTTP/2 +> Host: www.example.com +> User-Agent: curl/8.7.1 +> Accept: */* +... +< HTTP/2 401 +< content-length: 58 +< content-type: text/plain +< date: Sun, 19 Jan 2025 12:55:39 GMT +< + +* Connection #0 to host 127.0.0.1 left intact +Client authentication failed. +``` + +Send a request to the backend service with `x-api-key` header: + +```shell +curl -v -H "Host: www.example.com" -H 'x-api-key: supersecret' "http://${GATEWAY_HOST}/" +``` + +The request should be allowed and you should see the response from the backend service. + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the secret + +```shell +kubectl delete securitypolicy/apikey-auth-example +kubectl delete secret/apikey-secret +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute diff --git a/site/content/en/v1.8/tasks/security/backend-mtls.md b/site/content/en/v1.8/tasks/security/backend-mtls.md new file mode 100644 index 0000000000..4f59027529 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/backend-mtls.md @@ -0,0 +1,353 @@ +--- +title: "Backend Mutual TLS: Gateway to Backend" +--- + +This task demonstrates how mTLS can be achieved between the Gateway and a backend. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][] to establish TLS. For mTLS, the Gateway must authenticate by presenting a client certificate to the backend. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +Follow the steps from the [Backend TLS][] to install Envoy Gateway and configure TLS to the backend server. + +## TLS Certificates + +Generate the client certificate and key used by the Gateway for authentication against the backend. + +Create a root certificate and private key to sign the client certificate: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout clientca.key -out clientca.crt +``` + +Create the client certificate and a private key for `www.example.com`: + +```shell +openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr -subj "/CN=example-client/O=example organization" +openssl x509 -req -days 365 -CA clientca.crt -CAkey clientca.key -set_serial 0 -in client.csr -out client.crt +``` + +Store the the client cert/key in a Secret: + +```shell +kubectl -n envoy-gateway-system create secret tls example-client-cert --key=client.key --cert=client.crt +``` + +Store the CA Cert in another Secret: + +```shell +kubectl create configmap example-client-ca --from-file=clientca.crt +``` + +## Enforce Client Certificate Authentication on the backend + +Patch the existing quickstart backend to enforce Client Certificate Authentication. The patch will mount the server certificate and key required for TLS, and the CA certificate into the backend as volumes. + +```shell +kubectl patch deployment backend --type=json --patch ' + - op: add + path: /spec/template/spec/containers/0/volumeMounts + value: + - name: client-certs-volume + mountPath: /etc/client-certs + - name: secret-volume + mountPath: /etc/secret-volume + - op: add + path: /spec/template/spec/volumes + value: + - name: client-certs-volume + configMap: + name: example-client-ca + items: + - key: clientca.crt + path: crt + - name: secret-volume + secret: + secretName: example-cert + items: + - key: tls.crt + path: crt + - key: tls.key + path: key + - op: add + path: /spec/template/spec/containers/0/env/- + value: + name: TLS_CLIENT_CACERTS + value: /etc/client-certs/crt + ' +``` + +## Configure Envoy Proxy to use a client certificate + +Envoy Gateway supports two ways to configure client certificates for backend mTLS. +* Configure the [EnvoyProxy][] resource to specify a client certificate globally. +* Configure a [Backend][] resource to specify a client certificate per backend. + +### Configure EnvoyProxy + +The [EnvoyProxy][] resource can be used to specify a client certificate globally for a GatewayClass or Gateway. + +The following example shows how to configure a GatewayClass to reference an EnvoyProxy resource with a client certificate. + +First, add a parametersRef field in the GatewayClass to reference the EnvoyProxy configuration: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Configure a Backend Resource + +When multiple backends require distinct client certificates, configure each one using a dedicated [Backend][] resource that includes its own client certificate reference. +TLS settings defined in the Backend resource take precedence over the defaults set in EnvoyProxy.backendTLS. + +Before creating Backend resources, make sure the Backend API is enabled in the Envoy Gateway configuration (see [Backend Routing](../traffic/backend#enable-backend) for full details). If it is not already enabled, update the `envoy-gateway-config` ConfigMap as shown below: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +Roll out the updated Envoy Gateway deployment: + +```shell +kubectl -n envoy-gateway-system rollout restart deployment envoy-gateway +``` + +Create the client certificate secret in the backend namespace (reusing the same certificate and key generated earlier): + +```shell +kubectl -n default create secret tls example-client-cert --key=client.key --cert=client.crt +``` + +Define the backend and include both the trust anchor and the client credentials: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Update the HTTPRoute to reference the backend instead of the Kubernetes Service: + +```shell +kubectl patch HTTPRoute backend --type=json --patch ' + - op: replace + path: /spec/rules/0/backendRefs/0/group + value: gateway.envoyproxy.io + - op: replace + path: /spec/rules/0/backendRefs/0/kind + value: Backend + - op: replace + path: /spec/rules/0/backendRefs/0/name + value: tls-backend-client-cert + - op: remove + path: /spec/rules/0/backendRefs/0/port + ' +``` + +## Testing mTLS + +Query the TLS-enabled backend through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \ +http://www.example.com:80/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend. +The response now contains a "peerCertificates" attribute that reflects the client certificate used by the Gateway to establish mTLS with the backend. + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.2", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + "peerCertificates": ["-----BEGIN CERTIFICATE-----\n[...]-----END CERTIFICATE-----\n"] + } +``` + +[Backend TLS]: ./backend-tls +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[EnvoyProxy]: ../../api/extension_types#envoyproxy +[Backend]: ../../api/extension_types#backend diff --git a/site/content/en/v1.8/tasks/security/backend-skip-tls-verification.md b/site/content/en/v1.8/tasks/security/backend-skip-tls-verification.md new file mode 100644 index 0000000000..4d862b0b18 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/backend-skip-tls-verification.md @@ -0,0 +1,341 @@ +--- +title: "Backend TLS: Skip TLS Verification" +--- + +This task demonstrates how to skip TLS verification for a backend service in Envoy Gateway. + +By default, you must configure a [BackendTLSPolicy][] to validate the TLS certificate of a backend service when it uses TLS. + +However, in certain scenarios—such as development or testing—you might want to skip TLS verification for a backend service. +To do this, you can use the [Backend][] API and set the `tls.insecureSkipVerify` field to true in the [Backend][] resource. + +Warning: Skipping TLS verification disables certificate validation, which can expose your connection to man-in-the-middle +attacks. This setting is typically used only for development or testing and is not recommended in production environments. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## Enable Backend + +The [Backend][] API is disabled by default in Envoy Gateway. To enable it, follow the steps outlined in [Backend Routing][] to configure the [EnvoyGateway][] startup settings accordingly. + +## TLS Certificates + +Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout ca.key -out ca.crt +``` + +Create a certificate and a private key for `www.example.com`. + +First, create an openssl configuration file: + +```shell +cat > openssl.conf <}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Skip TLS Verification + +In the following example, we will create a [Backend][] resource that routes to the `tls-backend` service, and an [HTTPRoute][] +that references the [Backend][] resource. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Send a request to the backend service: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:${GATEWAY_HOST}" \ +http://www.example.com:80/get +``` + +Because the backend service is using TLS, and no [BackendTLSPolicy][] is configured to validate the TLS certificate, +the request will fail with a `400 Bad Request` error: + +```bash +* Connected to www.example.com (172.18.0.200) port 80 +* using HTTP/1.x +> GET /get HTTP/1.1 +> Host:www.example.com +> User-Agent: curl/8.14.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 400 Bad Request +< date: Thu, 31 Jul 2025 06:09:51 GMT +< transfer-encoding: chunked +``` + +Disabling TLS verification by setting the `InsecureSkipVerify` field to `true` allows the request to succeed: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Send the request again: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:${GATEWAY_HOST}" \ +http://www.example.com:80/get +``` + +You should now see a successful response from the backend service. Since TLS verification has been skipped, the request +proceeds without validating the backend’s TLS certificate. The response will include TLS details such as the protocol +version and cipher suite used for the connection. + + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.2", + "serverName": "", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + } +``` + +[Backend Routing]: ../traffic/backend/#enable-backend +[Backend]: ../../../api/extension_types#backend +[EnvoyGateway]: ../../../api/extension_types#envoygateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ diff --git a/site/content/en/v1.8/tasks/security/backend-tls.md b/site/content/en/v1.8/tasks/security/backend-tls.md new file mode 100644 index 0000000000..cb851fbf09 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/backend-tls.md @@ -0,0 +1,436 @@ +--- +title: "Backend TLS: Gateway to Backend" +--- + +This task demonstrates how TLS can be achieved between the Gateway and a backend. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][]. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## TLS Certificates + +Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout ca.key -out ca.crt +``` + +Create a certificate and a private key for `www.example.com`. + +First, create an openssl configuration file: + +```shell +cat > openssl.conf <}} +{{% tab header="ConfigMap" %}} + +```shell +kubectl create configmap example-ca --from-file=ca.crt +``` + +{{% /tab %}} + +{{% tab header="ClusterTrustBundle" %}} + +Save and apply the following resource to your cluster: + +```shell +apiVersion: certificates.k8s.io/v1beta1 +kind: ClusterTrustBundle +metadata: + name: example-ca +spec: + trustBundle: | + [content from ca.crt] +``` + +{{% /tab %}} + +{{< /tabpane >}} + +## Setup TLS on the backend + +Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume. + +```shell +kubectl patch deployment backend --type=json --patch ' + - op: add + path: /spec/template/spec/containers/0/volumeMounts + value: + - name: secret-volume + mountPath: /etc/secret-volume + - op: add + path: /spec/template/spec/volumes + value: + - name: secret-volume + secret: + secretName: example-cert + items: + - key: tls.crt + path: crt + - key: tls.key + path: key + - op: add + path: /spec/template/spec/containers/0/env/- + value: + name: TLS_SERVER_CERT + value: /etc/secret-volume/crt + - op: add + path: /spec/template/spec/containers/0/env/- + value: + name: TLS_SERVER_PRIVKEY + value: /etc/secret-volume/key + ' +``` + +Create a service that exposes port 443 on the backend service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Create a [BackendTLSPolicy][] instructing Envoy Gateway to establish a TLS connection with the backend and validate the backend certificate is issued by a trusted CA and contains an appropriate DNS SAN. + +Note: SectionName is an optional field that specifies the name of the port in the target backend. This example uses a Kubernetes Service as the backend target, so the sectionName is set to `https` to match the port name in the Service. +If the target is a [Backend] resource, the `sectionName` field should be set to the port number of the backend. + +{{< tabpane text=true >}} +{{% tab header="ConfigMap" %}} + +```shell +cat <}} + +Patch the HTTPRoute's backend reference, so that it refers to the new TLS-enabled service: + +```shell +kubectl patch HTTPRoute backend --type=json --patch ' + - op: replace + path: /spec/rules/0/backendRefs/0/port + value: 443 + - op: replace + path: /spec/rules/0/backendRefs/0/name + value: tls-backend + ' +``` + +Verify the HTTPRoute status: + +```shell +kubectl get HTTPRoute backend -o yaml +``` + +## Testing backend TLS + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through the Gateway: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:${GATEWAY_HOST}" \ +http://www.example.com:80/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend: + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.2", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + } +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8080:80 & +``` + +Query the TLS-enabled backend through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8080:127.0.0.1" \ +http://www.example.com:8080/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend: + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.2", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + } +``` + +{{% /tab %}} +{{< /tabpane >}} + +## Customize backend TLS Parameters + +In addition to enablement of backend TLS with the Gateway-API BackendTLSPolicy, Envoy Gateway supports customizing TLS parameters. +To achieve this, the [EnvoyProxy][] resource can be used to specify TLS parameters. We will customize the TLS version in this example. + +First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +You can customize the EnvoyProxy Backend TLS Parameters via EnvoyProxy Config like: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing TLS Parameters + +Query the TLS-enabled backend through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \ +http://www.example.com:80/get +``` + +Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend. +The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS cipher is also changed, since TLS1.3 supports different ciphers from TLS1.2. + +```shell +< HTTP/1.1 200 OK +[...] + "tls": { + "version": "TLSv1.3", + "serverName": "www.example.com", + "negotiatedProtocol": "http/1.1", + "cipherSuite": "TLS_AES_128_GCM_SHA256" + } +``` + +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[EnvoyProxy]: ../../api/extension_types#envoyproxy +[Backend]: ../../api/extension_types#backend diff --git a/site/content/en/v1.8/tasks/security/basic-auth.md b/site/content/en/v1.8/tasks/security/basic-auth.md new file mode 100644 index 0000000000..4a2e02c7ad --- /dev/null +++ b/site/content/en/v1.8/tasks/security/basic-auth.md @@ -0,0 +1,219 @@ +--- +title: "Basic Authentication" +--- + +This task provides instructions for configuring [HTTP Basic authentication][http Basic authentication]. +HTTP Basic authentication checks if an incoming request has a valid username and password before routing the request to +a backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure HTTP Basic +authentication. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +Envoy Gateway uses [.htpasswd][.htpasswd] format to store the username-password pairs for authentication. +The file must be stored in a kubernetes secret and referenced in the [SecurityPolicy][] configuration. +The secret is an Opaque secret, and the username-password pairs must be stored in the key ".htpasswd". + +### Create a root certificate + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +### Create a certificate secret + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +### Create certificate + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt +``` + +### Enable HTTPS +Update the Gateway from the Quickstart to include an HTTPS listener that listens on port `443` and references the +`example-cert` Secret: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - kind: Secret + group: "" + name: example-cert + ' +``` + +### Create a .htpasswd file +First, create a [.htpasswd][] file with the username and password you want to use for authentication. + +Note: Please always use HTTPS with Basic Authentication. This prevents credentials from being transmitted in plain text. + +The input password won't be saved, instead, a hash will be generated and saved in the output file. When a request +tries to access protected resources, the password in the "Authorization" HTTP header will be hashed and compared with the +saved hash. + +Note: only SHA hash algorithm is supported for now. + +```shell +htpasswd -cbs .htpasswd foo bar +``` + +You can also add more users to the file: + +```shell +htpasswd -bs .htpasswd foo1 bar1 +``` + +### Create a basic-auth secret + + +Next, create a kubernetes secret with the generated .htpasswd file in the previous step. + +```shell +kubectl create secret generic basic-auth --from-file=.htpasswd +``` + +### Create a SecurityPolicy + +The below example defines a SecurityPolicy that authenticates requests against the user list in the kubernetes +secret generated in the previous step. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/basic-auth-example -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `Authentication` header: + +```shell +curl -kv -H "Host: www.example.com" "https://${GATEWAY_HOST}/" +``` + +You should see `401 Unauthorized` in the response, indicating that the request is not allowed without authentication. + +```shell +* Connected to 127.0.0.1 (127.0.0.1) port 443 +... +* Server certificate: +* subject: CN=www.example.com; O=example organization +* issuer: O=example Inc.; CN=example.com +> GET / HTTP/2 +> Host: www.example.com +> User-Agent: curl/8.6.0 +> Accept: */* +... +< HTTP/2 401 +< content-length: 58 +< content-type: text/plain +< date: Wed, 06 Mar 2024 15:59:36 GMT +< + +* Connection #0 to host 127.0.0.1 left intact +User authentication failed. Missing username and password. +``` + +Send a request to the backend service with `Authentication` header: + +```shell +curl -kv -H "Host: www.example.com" -u 'foo:bar' "https://${GATEWAY_HOST}/" +``` + +The request should be allowed and you should see the response from the backend service. + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the secret + +```shell +kubectl delete securitypolicy/basic-auth-example +kubectl delete secret/basic-auth +kubectl delete secret/example-cert +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[http Basic authentication]: https://tools.ietf.org/html/rfc2617 +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute +[.htpasswd]: https://httpd.apache.org/docs/current/programs/htpasswd.html diff --git a/site/content/en/v1.8/tasks/security/cors.md b/site/content/en/v1.8/tasks/security/cors.md new file mode 100644 index 0000000000..4c28497ece --- /dev/null +++ b/site/content/en/v1.8/tasks/security/cors.md @@ -0,0 +1,280 @@ +--- +title: "CORS" +--- + +This task provides instructions for configuring [Cross-Origin Resource Sharing (CORS)][cors] on Envoy Gateway. +CORS defines a way for client web applications that are loaded in one domain to interact with resources in a different +domain. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure CORS. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +You can also configure CORS using the Gateway API's [HTTPCORSFilter][], which offers a simpler option but +is only supported on the [HTTPRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +When configuring CORS either an origin with a precise hostname can be configured or an hostname containing a wildcard prefix, +allowing all subdomains of the specified hostname. +In addition to that the entire origin (with or without specifying a scheme) can be a wildcard to allow all origins. + +### Configuring CORS with SecurityPolicy + +The below example defines a SecurityPolicy that allows CORS for requests originating from `http://*.foo.com`. +It also enables credentialed requests with `allowCredentials: true`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/cors-example -o yaml +``` + +### Configuring CORS with HTTPCORSFilter + +Alternatively, you can configure CORS using the Gateway API's `HTTPCORSFilter`. This filter can be directly configured +within an `HTTPRoute` resource, which is simpler if you only need to apply CORS to a specific route. + +The below example applies CORS to the `backend` HTTPRoute, allowing requests from `http://*.foo.com`. +It also enables credentialed requests with `allowCredentials: true`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute configuration: + +```shell +kubectl get httproute/backend -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Verify that the CORS headers are present in the response of the OPTIONS request from `http://www.foo.com`: + +```shell +curl -H "Origin: http://www.foo.com" \ + -H "Host: www.example.com" \ + -H "Access-Control-Request-Method: GET" \ + -X OPTIONS -v -s \ + http://$GATEWAY_HOST \ + 1> /dev/null +``` + +You should see the below response, indicating that the request from `http://www.foo.com` is allowed: + +```shell +< access-control-allow-origin: http://www.foo.com +< access-control-allow-credentials: true +< access-control-allow-methods: GET, POST +< access-control-allow-headers: x-header-1, x-header-2 +< access-control-max-age: 86400 +< access-control-expose-headers: x-header-3, x-header-4 +``` + +If you try to send a request from `http://www.bar.com`, you should see the below response: + +```shell +curl -H "Origin: http://www.bar.com" \ + -H "Host: www.example.com" \ + -H "Access-Control-Request-Method: GET" \ + -X OPTIONS -v -s \ + http://$GATEWAY_HOST \ + 1> /dev/null +``` + +You won't see any CORS headers in the response, indicating that the request from `http://www.bar.com` was not allowed. + +If you try to send a request from `http://www.foo.com:8080`, you should also see similar response because the port number +`8080` is not included in the allowed origins. + +```shell +curl -H "Origin: http://www.foo.com:8080" \ + -H "Host: www.example.com" \ + -H "Access-Control-Request-Method: GET" \ + -X OPTIONS -v -s \ + http://$GATEWAY_HOST \ + 1> /dev/null +``` + +Note: +* CORS specification requires that the browsers to send a preflight request to the server to ask if it's allowed +to access the limited resource in another domains. The browsers are supposed to follow the response from the server to +determine whether to send the actual request or not. The CORS filter only response to the preflight requests according to +its configuration. It won't deny any requests. The browsers are responsible for enforcing the CORS policy. +* The targeted HTTPRoute or the HTTPRoutes that the targeted Gateway routes to must allow the OPTIONS method for the CORS +filter to work. Otherwise, the OPTIONS request won't match the routes and the CORS filter won't be invoked. + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy: + +```shell +kubectl delete securitypolicy/cors-example +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute +[HTTPCORSFilter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpcorsfilter diff --git a/site/content/en/v1.8/tasks/security/credential-injection.md b/site/content/en/v1.8/tasks/security/credential-injection.md new file mode 100644 index 0000000000..53a33df13d --- /dev/null +++ b/site/content/en/v1.8/tasks/security/credential-injection.md @@ -0,0 +1,261 @@ +--- +title: "Credential Injection" +--- + +This task shows how to use [HTTPRouteFilter][HTTPRouteFilter] to inject credentials into requests. It can be used to add +credentials such as Basic Authentication, JWTs, or API keys before the requests are sent to the backend service. + +This is useful in scenarios where the backend service requires authentication or other credentials that are not provided +by the client. For example, you can use this feature to inject an access token into an API call to AWS. + +Credentials can be injected at the HTTPRoute level or at the BackendRef level, allowing for fine-grained control over +which requests receive injected credentials. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +To inject credentials into requests, you need to create a [HTTPRouteFilter][HTTPRouteFilter] resource that defines the +credentials to be injected. The filter can be applied to an [HTTPRoute][HTTPRoute] or a [BackendRef][BackendRef] resource. + +### Create a Secret with the Credential that you want to inject into requests + +Create a secret with the credential you want to inject into requests. The secret should contain the credential in a field +named `credential`. + +You can use any type of credential, such as a JWT token, Basic Authentication credentials, an API key, +or a custom credential. In this example, we will use a JWT token as the credential to be injected into requests. + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) +kubectl create secret generic jwt-credential --from-literal=credential=" Bearer $TOKEN" +``` + +### Create a HTTPRouteFilter + +Create a `HTTPRouteFilter` resource that injects the JWT token into requests. + +By default, the credentials will be injected into the `Authorization` header. You can also inject credentials into other +headers by specifying the `header` field in the `credentialInjection` section of the `HTTPRouteFilter`. + +If the `Authorization` header or the specified header already exists in the request, the credentials won't be injected +unless you set `overwrite` to `true`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Injecting Credentials into HTTPRoute + +To inject the credentials at the [HTTPRoute][HTTPRoute] level, you need to reference the `HTTPRouteFilter` in the `filters` +section of the `HTTPRoute` resource. The credentials will be injected into all requests that match the route. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Injecting Credentials into BackendRef +To inject the credentials at the [BackendRef][BackendRef] level, you need to reference the `HTTPRouteFilter` in the +`filters` section of the `BackendRef` resource. The credentials will be injected into all requests that are sent to that +backend. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing + +Send a request to the backend service without `Authentication` header: + +```shell +curl -kv -H "Host: www.example.com" "http://${GATEWAY_HOST}/" +``` + +You should see the Authorization header with the JWT token in the echoed request headers in the response, indicating +that the token was successfully injected into the request. + +```shell + +"Authorization": [ + "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.NHVaYe26MbtOYhSKkoKYdFVomg4i8ZJd8_-RU8VNbftc4TSMb4bXP3l3YlNWACwyXPGffz5aXHc6lty1Y2t4SWRqGteragsVdZufDn5BlnJl9pdR_kdVFUsra2rWKEofkZeIC4yWytE58sMIihvo9H1ScmmVwBcQP6XETqYd0aSHp1gOa9RdUPDvoXQ5oqygTqVtxaDr6wUFKrKItgBMzWIdNZ6y7O9E0DhEPTbE9rfBo6KTFsHAZnMg4k68CDp2woYIaXbmYTWcvbzIuHO7_37GT79XdIwkm95QJ7hYC9RiwrV7mesbY4PAahERJawntho0my942XheVLmGwLMBkQ" + ], + +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the secret + +```shell +kubectl delete httproutefilter/credential-injection +kubectl delete secret/jwt-credential +``` + +## Next Steps + +Check out the [Developer Guide](/community/develop) to get involved in the project. + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[BackendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpbackendref +[HTTPRouteFilter]: ../../../api/extension_types#httproutefilter diff --git a/site/content/en/v1.8/tasks/security/ext-auth.md b/site/content/en/v1.8/tasks/security/ext-auth.md new file mode 100644 index 0000000000..a53ff58e98 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/ext-auth.md @@ -0,0 +1,451 @@ +--- +title: "External Authorization" +--- + +This task provides instructions for configuring external authorization. + +External authorization calls an external HTTP or gRPC service to check whether an incoming HTTP request is authorized +or not. If the request is deemed unauthorized, then the request will be denied with a 403 (Forbidden) response. If the +request is authorized, then the request will be allowed to proceed to the backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure external authorization. +This instantiated resource can be linked to a [Gateway][] and [HTTPRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## HTTP External Authorization Service + +### Installation + +Install a demo HTTP service that will be used as the external authorization service: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-auth-http-service.yaml +``` + +Create a new HTTPRoute resource to route traffic on the path `/myapp` to the backend service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute status: + +```shell +kubectl get httproute/myapp -o yaml +``` + +### Configuration + +Create a new SecurityPolicy resource to configure the external authorization. This SecurityPolicy targets the HTTPRoute +"myApp" created in the previous step. It calls the HTTP external authorization service "http-ext-auth" on port 9002 for +authorization. The `headersToBackend` field specifies the headers that will be sent to the backend service if the request +is successfully authorized. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/ext-auth-example -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `Authorization` header: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/myapp" +``` + +You should see `403 Forbidden` in the response, indicating that the request is not allowed without authorization. + +```shell +* Connected to 172.18.255.200 (172.18.255.200) port 80 (#0) +> GET /myapp HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +... +< HTTP/1.1 403 Forbidden +< date: Mon, 11 Mar 2024 03:41:15 GMT +< x-envoy-upstream-service-time: 0 +< content-length: 0 +< +* Connection #0 to host 172.18.255.200 left intact +``` + +Send a request to the backend service with `Authorization` header: + +```shell +curl -v -H "Host: www.example.com" -H "Authorization: Bearer token1" "http://${GATEWAY_HOST}/myapp" +``` + +The request should be allowed and you should see the response from the backend service. +Because the `x-current-user` header from the auth response has been sent to the backend service, +you should see the `x-current-user` header in the response. + +``` +"X-Current-User": [ + "user1" + ], +``` + +## GRPC External Authorization Service + +### Installation + +Install a demo gRPC service that will be used as the external authorization service. The demo gRPC service is enabled +with TLS and a BackendTLSConfig is created to configure the communication between the Envoy proxy and the gRPC service. + +Note: TLS is optional for HTTP or gRPC external authorization services. However, enabling TLS is recommended for enhanced +security in production environments. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-auth-grpc-service.yaml +``` + +The HTTPRoute created in the previous section is still valid and can be used with the gRPC auth service, but if you have +not created the HTTPRoute, you can create it now. + +Create a new HTTPRoute resource to route traffic on the path `/myapp` to the backend service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute status: + +```shell +kubectl get httproute/myapp -o yaml +``` + +### Configuration + +Update the SecurityPolicy that was created in the previous section to use the gRPC external authorization service. +It calls the gRPC external authorization service "grpc-ext-auth" on port 9002 for authorization. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/ext-auth-example -o yaml +``` + +Because the gRPC external authorization service is enabled with TLS, a BackendTLSConfig needs to be created to configure +the communication between the Envoy proxy and the gRPC auth service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the BackendTLSPolicy configuration: + +```shell +kubectl get backendtlspolicy/grpc-ext-auth-btls -o yaml +``` + +### Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without `Authorization` header: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/myapp" +``` + +You should see `403 Forbidden` in the response, indicating that the request is not allowed without authorization. + +```shell +* Connected to 172.18.255.200 (172.18.255.200) port 80 (#0) +> GET /myapp HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +... +< HTTP/1.1 403 Forbidden +< date: Mon, 11 Mar 2024 03:41:15 GMT +< x-envoy-upstream-service-time: 0 +< content-length: 0 +< +* Connection #0 to host 172.18.255.200 left intact +``` + +Send a request to the backend service with `Authorization` header: + +```shell +curl -v -H "Host: www.example.com" -H "Authorization: Bearer token1" "http://${GATEWAY_HOST}/myapp" +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the demo auth services, HTTPRoute, SecurityPolicy and BackendTLSPolicy: + +```shell +kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-auth-http-service.yaml +kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/ext-auth-grpc-service.yaml +kubectl delete httproute/myapp +kubectl delete securitypolicy/ext-auth-example +kubectl delete backendtlspolicy/grpc-ext-auth-btls +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute diff --git a/site/content/en/v1.8/tasks/security/geoip-authorization.md b/site/content/en/v1.8/tasks/security/geoip-authorization.md new file mode 100644 index 0000000000..f8976ac7c7 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/geoip-authorization.md @@ -0,0 +1,365 @@ +--- +title: "GeoIP Authorization" +--- + +This task provides instructions for configuring GeoIP-based authorization with Envoy Gateway. + +GeoIP authorization uses geolocation data derived from the client IP address to determine whether a request should be +allowed or denied before it is forwarded to the backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure GeoIP-based authorization. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][], or [GRPCRoute][] resource. + +GeoIP authorization is configured through `SecurityPolicy.spec.authorization.rules[].principal.clientIPGeoLocations`. + +GeoIP authorization requires: + +- GeoIP provider configuration on [EnvoyProxy][] +- client IP detection on [ClientTrafficPolicy][] +- a [SecurityPolicy][] attached to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +### Prepare the GeoIP database + +Envoy reads GeoIP data from a local MaxMind `.mmdb` database file mounted into the proxy container. + +This task uses a public MaxMind anonymous-IP test database. Apply the example manifest before continuing: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/{{< yaml-version >}}/examples/kubernetes/geoip-anonymous-ip-db.yaml +``` + +To keep this guide readable, the full base64-encoded `ConfigMap` is not repeated here. + +For production deployments, mount your own supported MaxMind database and update the file path in the `EnvoyProxy` resource accordingly. + +### Configure the Gateway and EnvoyProxy + +The following resources create a dedicated `Gateway`, mount the anonymous-IP database into the Envoy proxy, and configure `EnvoyProxy.spec.geoIP.provider.maxMind.anonymousIpDbSource` to read it. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Create the route and SecurityPolicy + +The following resources create an `HTTPRoute` for `/geo-anonymous` and attach a `SecurityPolicy` that denies requests identified as anonymous networks while allowing other traffic. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the `SecurityPolicy` configuration: + +```shell +kubectl get securitypolicy/authorization-geoip-anonymous -o yaml +``` + +### Enable client IP detection + +GeoIP authorization depends on Envoy Gateway correctly detecting the client IP address. Without `ClientTrafficPolicy.spec.clientIPDetection`, the `clientIPGeoLocations` match will not work as intended. + +The following `ClientTrafficPolicy` tells Envoy Gateway to use the `X-Forwarded-For` header and trust one upstream hop: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the `ClientTrafficPolicy` configuration: + +```shell +kubectl get clienttrafficpolicy/enable-client-ip-detection-geoip -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request with a regular client IP that is not flagged as anonymous by the test database: + +```shell +curl -v -H "Host: www.example.com" -H "X-Forwarded-For: 8.8.8.8" "http://${GATEWAY_HOST}/geo-anonymous" +``` + +The request should be allowed and return `200 OK`. + +Send a request with an IP that the anonymous-IP test database marks as anonymous: + +```shell +curl -v -H "Host: www.example.com" -H "X-Forwarded-For: 6.1.0.3" "http://${GATEWAY_HOST}/geo-anonymous" +``` + +The request should be denied and return `403 Forbidden`. + +## Clean-Up + +Remove the resources created in this task: + +```shell +kubectl delete clienttrafficpolicy/enable-client-ip-detection-geoip +kubectl delete securitypolicy/authorization-geoip-anonymous +kubectl delete httproute/http-with-authorization-geoip-anonymous +kubectl delete gateway/geoip-authz-gateway +kubectl delete envoyproxy/geoip-authz-proxy +``` + +If you applied the test GeoIP database `ConfigMap`, remove it as well: + +```shell +kubectl delete configmap/geoip-anonymous-ip-db +``` + +## Next Steps + +Checkout the following related guides: + +- [IP Allowlist/Denylist](restrict-ip-access/) +- [SecurityPolicy API Reference](../../api/extension_types#securitypolicy) +- [ClientTrafficPolicy API Reference](../../api/extension_types#clienttrafficpolicy) + +[SecurityPolicy]: ../../api/extension_types#securitypolicy +[EnvoyProxy]: ../../api/extension_types#envoyproxy +[ClientTrafficPolicy]: ../../api/extension_types#clienttrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute diff --git a/site/content/en/v1.8/tasks/security/http-header-method-auth.md b/site/content/en/v1.8/tasks/security/http-header-method-auth.md new file mode 100644 index 0000000000..609bf2d1f5 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/http-header-method-auth.md @@ -0,0 +1,122 @@ +--- +title: HTTP Header and Method Based Authorization +description: + Configure request authorization using HTTP headers and HTTP methods with + SecurityPolicy. +--- + +## Overview + +Envoy Gateway allows controlling access to requests based on HTTP headers and HTTP methods using `SecurityPolicy` **authorization rules**. + +This enables restricting access to routes based on specific header values, allowed HTTP methods, or a combination of both. + +> **Note:** Header and method based access control is implemented using `SecurityPolicy` authorization rules, not request authentication. + +--- + +## Header-Based Authorization + +Header-based authorization allows controlling access based on values present in HTTP request headers. + +This can be used to allow requests only from specific users or identities represented via request headers. + +### Example +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: header-auth +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: gateway-1 + authorization: + defaultAction: Deny + rules: + - name: allow-specific-users + action: Allow + principal: + headers: + - name: x-user-id + values: + - example-user +``` + +In this example, requests are allowed only if the `x-user-id` request header matches one of the configured allowed values. + +--- + +## Method-Based Authorization + +Method-based authorization restricts access based on the HTTP method of incoming requests. + +This can be used to allow or deny specific operations such as `GET`, `POST`, or `DELETE`. + +### Example +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: method-auth +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: gateway-1 + authorization: + defaultAction: Deny + rules: + - name: allow-read-methods + action: Allow + operation: + methods: + - GET + - POST +``` + +In this configuration, only `GET` and `POST` requests are permitted. Any other HTTP methods (such as `PUT` or `DELETE`) will be denied by default. + +--- + +## Combined Header and Method Authorization + +Header-based and method-based authorization can be combined within a single authorization rule for more granular access control. + +### Example +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: combined-auth +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: gateway-1 + authorization: + defaultAction: Deny + rules: + - name: allow-user-get + action: Allow + operation: + methods: + - GET + principal: + headers: + - name: x-user-id + values: + - example-user +``` + +In this scenario, a request is authorized only if it uses an allowed HTTP method and matches the configured header-based principal conditions. + +--- + +## Behavior Notes + +- **Authorization semantics:** Rules define authorization behavior, not request authentication. +- **Logical AND:** Conditions within a rule use logical AND semantics. Requests must satisfy all configured header and method requirements. +- **Rule Evaluation:** Rules are evaluated in the order they are defined. +- **Default Action:** Requests that do not match any rule are handled according to the configured `defaultAction`. \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/security/jwt-authentication.md b/site/content/en/v1.8/tasks/security/jwt-authentication.md new file mode 100644 index 0000000000..a0ed0377a5 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/jwt-authentication.md @@ -0,0 +1,426 @@ +--- +title: "JWT Authentication" +--- + +This task provides instructions for configuring [JSON Web Token (JWT)][jwt] authentication. JWT authentication checks +if an incoming request has a valid JWT before routing the request to a backend service. Currently, Envoy Gateway only +supports validating a JWT from an HTTP header, e.g. `Authorization: Bearer `. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure JWT authentication. +This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HTTPRoute] or [GRPCRoute][GRPCRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +For GRPC - follow the steps from the [GRPC Routing](../traffic/grpc-routing) example. + +## Configuration + +Allow requests with a valid JWT by creating an [SecurityPolicy][SecurityPolicy] and attaching it to the example +HTTPRoute or GRPCRoute. + +### HTTPRoute + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/jwt/jwt.yaml +``` + +Two HTTPRoute has been created, one for `/foo` and another for `/bar`. A SecurityPolicy has been created and targeted +HTTPRoute foo to authenticate requests for `/foo`. The HTTPRoute bar is not targeted by the SecurityPolicy and will allow +unauthenticated requests to `/bar`. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/foo -o yaml +kubectl get httproute/bar -o yaml +``` + +The SecurityPolicy is configured for JWT authentication and uses a single [JSON Web Key Set (JWKS)][jwks] +provider for authenticating the JWT. + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/jwt-example -o yaml +``` + +### GRPCRoute + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/jwt/grpc-jwt.yaml +``` + +A SecurityPolicy has been created and targeted GRPCRoute yages to authenticate all requests for `yages` service.. + +Verify the GRPCRoute configuration and status: + +```shell +kubectl get grpcroute/yages -o yaml +``` + +The SecurityPolicy is configured for JWT authentication and uses a single [JSON Web Key Set (JWKS)][jwks] +provider for authenticating the JWT. + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/jwt-example -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +Verify that requests to `/foo` are denied without a JWT: + +```shell +curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/foo +``` + +A `401` HTTP response code should be returned. + +Get the JWT used for testing request authentication: + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode +``` + +__Note:__ The above command decodes and returns the token's payload. You can replace `f2` with `f1` to view the token's +header. + +Verify that a request to `/foo` with a valid JWT is allowed: + +```shell +curl -sS -o /dev/null -H "Host: www.example.com" -H "Authorization: Bearer $TOKEN" -w "%{http_code}\n" http://$GATEWAY_HOST/foo +``` + +A `200` HTTP response code should be returned. + +Verify that requests to `/bar` are allowed __without__ a JWT: + +```shell +curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/bar +``` + +### GRPCRoute + +Verify that requests to `yages`service are denied without a JWT: + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +You should see the below response + +```shell +Error invoking method "yages.Echo/Ping": rpc error: code = Unauthenticated desc = failed to query for service descriptor "yages.Echo": Jwt is missing +``` + +Get the JWT used for testing request authentication: + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode +``` + +__Note:__ The above command decodes and returns the token's payload. You can replace `f2` with `f1` to view the token's +header. + +Verify that a request to `yages` service with a valid JWT is allowed: + +```shell +grpcurl -plaintext -H "authorization: Bearer $TOKEN" -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +You should see the below response + +```shell +{ + "text": "pong" +} +``` + +## Connect to a remote JWKS with Self-Signed Certificate + +To connect to a remote JWKS with a self-signed certificate, you need to configure it using the [BackendTLSPolicy] to specify the CA certificate required to authenticate the JWKS host. Additionally, if the JWKS is outside of the cluster, you need to configure the [Backend] resource to specify the JWKS host. + +The following example demonstrates how to configure the remote JWKS with a self-signed certificate. + +Please note that the `Backend` resource is not required if the JWKS is hosted on the same cluster as the Envoy Gateway, since +it can be accessed directly via the Kubernetes Service DNS name. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +As shown in the example above, the [SecurityPolicy] resource is configured with a remote JWKS within its JWT settings. The `backendRefs` field references the [Backend] resource that defines the JWKS host. The [BackendTLSPolicy] resource specifies the CA certificate required to authenticate the JWKS host. + +Additional connection settings for the remote JWKS host can be configured in the [backendSettings]. Currently, only the retry policy is supported. + +For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks. + +## Use a local JWKS to authenticate requests + +Envoy Gateway also supports using a local JWKS stored in a Kubernetes ConfigMap to authenticate requests. + +The following example demonstrates how to configure a local JWKS within the [SecurityPolicy] resource. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +With the above configuration, the [SecurityPolicy] resource will use the JWKS stored in the `jwt-local-jwks` ConfigMap to authenticate requests for the `foo` HTTPRoute. + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy: + +```shell +kubectl delete securitypolicy/jwt-example +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: /community/design/security-policy +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute +[Backend]: ../../../api/extension_types#backend +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[backend-routing]: ../traffic/backend +[backend-tls]: ../backend-tls +[BackendSettings]: ../../../api/extension_types/#clustersettings diff --git a/site/content/en/v1.8/tasks/security/jwt-claim-authorization.md b/site/content/en/v1.8/tasks/security/jwt-claim-authorization.md new file mode 100644 index 0000000000..86a32c384b --- /dev/null +++ b/site/content/en/v1.8/tasks/security/jwt-claim-authorization.md @@ -0,0 +1,226 @@ +--- +title: "JWT Claim-Based Authorization" +--- + +This task provides instructions for configuring JWT claim-based authorization. JWT claim-based authorization checks if an incoming request has the required JWT claims before routing the request to a backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][] that allows the user to configure JWT claim-based authorization. + +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +### Create a SecurityPolicy + +Please note that the JWT claim-based authorization requires the JWT token to be present in the request. A JWT authentication must be configured in the same SecurityPolicy to validate the JWT token and extract the claims. + +The below SecurityPolicy configuration allows requests with a valid JWT token that has the following claims: +- `user.name` claim with the value `John Doe` +- `user.roles` claim with the value `admin` +- `scope` claim with the values `read`, `add`, and `modify` + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/authorization-jwt-claim -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Define a JWT token with the required claims. + +```shell +export VALID_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImI1MjBiM2MyYzRiZDc1YTEwZTljZWJjOTU3NjkzM2RjIn0.eyJpc3MiOiJodHRwczovL2Zvby5iYXIuY29tIiwic3ViIjoiMTIzNDU2Nzg5MCIsInVzZXIiOnsibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsInJvbGVzIjpbImFkbWluIiwiZWRpdG9yIl19LCJwcmVtaXVtX3VzZXIiOnRydWUsImlhdCI6MTUxNjIzOTAyMiwic2NvcGUiOiJyZWFkIGFkZCBkZWxldGUgbW9kaWZ5In0.P36iAlmiRCC79OiB3vstF5Q_9OqUYAMGF3a3H492GlojbV6DcuOz8YIEYGsRSWc-BNJaBKlyvUKsKsGVPtYbbF8ajwZTs64wyO-zhd2R8riPkg_HsW7iwGswV12f5iVRpfQ4AG2owmdOToIaoch0aym89He1ZzEjcShr9olgqlAbbmhnk-namd1rP-xpzPnWhhIVI3mCz5hYYgDTMcM7qbokM5FzFttTRXAn5_Luor23U1062Ct_K53QArwxBvwJ-QYiqcBycHf-hh6sMx_941cUswrZucCpa-EwA3piATf9PKAyeeWHfHV9X-y8ipGOFg3mYMMVBuUZ1lBkJCik9f9kboRY6QzpOISARQj9PKMXfxZdIPNuGmA7msSNAXQgqkvbx04jMwb9U7eCEdGZztH4C8LhlRjgj0ZdD7eNbRjeH2F6zrWyMUpGWaWyq6rMuP98W2DWM5ZflK6qvT1c7FuFsWPvWLkgxQwTWQKrHdKwdbsu32Sj8VtUBJ0-ddEb" +``` + +Decode the JWT token to verify that it has the required claims. + +```shell +jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< $(echo ${VALID_TOKEN}) +``` + +The decoded JWT token should look like the following: + +```json +{ + "typ": "JWT", + "alg": "RS256", + "kid": "b520b3c2c4bd75a10e9cebc9576933dc" +} +{ + "iss": "https://foo.bar.com", + "sub": "1234567890", + "user": { + "name": "John Doe", + "email": "john.doe@example.com", + "roles": [ + "admin", + "editor" + ] + }, + "premium_user": true, + "iat": 1516239022, + "scope": "read add delete modify" +} +``` + +Send a request to the backend service with the valid JWT token: + +```shell +curl -H "Host: www.example.com" -H "Authorization: Bearer ${VALID_TOKEN}" "http://${GATEWAY_HOST}/" +``` + +The request should be allowed and you should see the response from the backend service. + +Define a JWT token without the required claims. + +```shell +export INVALID_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImI1MjBiM2MyYzRiZDc1YTEwZTljZWJjOTU3NjkzM2RjIn0.eyJpc3MiOiJodHRwczovL2Zvby5iYXIuY29tIiwic3ViIjoiMTIzNDU2Nzg5MCIsInVzZXIiOnsibmFtZSI6IkFsaWNlIFNtaXRoIiwiZW1haWwiOiJhbGljZS5zbWl0aEBleGFtcGxlLmNvbSIsInJvbGVzIjpbImRldmVsb3BlciJdfSwicHJlbWl1bV91c2VyIjpmYWxzZSwiaWF0IjoxNTE2MjM5MDIyLCJzY29wZSI6InJlYWQgYWRkIGRlbGV0ZSJ9.Da547nNXzuQXm5E7LuLAiyFswXsW4RDhuitD_rpadtR7PTwzzOsJoqrVWJ_u1jJDaOTWIpLF4gwxDoY-Aoz_couzXzlAbECLs45ZFoc_UdffpfIbGKqTZx8VtwKuDLFsAeDDDqqx1flxFhvXHftJJdZYr1FgFz9u-absMmRU90DLmEZX3Hnyc8k8eBgeiu6vsWUD0-aNy8cWkFRbwRggkGmucFyUTG8Z1MY3iyH5E66W-ISoX8G9bzE9PTxVAAPDTvefD5iLJPSDJ8qV69OuMCJ8Dczq0L9Dd_w0sF-D1s9MTvexmGg4zBWluJ3r-pU9NHEdhqBypehp_yH8xF5Rt9AE7stZ4oPFZNyfrtkE-4IOnSEkMmzcC65g_rscn0ycerv4N5ZNpkr0x2IYYM4iGuo-ULv5Htnli3rffST45kx1XA8cdsrT1D0K3aPxdIxDIk8sTJf5-WVqRyo-bwxXXltwQLB9jCM_7QbTWQBYAJwUpi-0RW4jCl44-42gZnXf" +``` + +Decode the JWT token to verify that it does not have the required claims. + +```shell +jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< $(echo ${INVALID_TOKEN}) +``` + +The decoded JWT token should look like the following: + +```json +{ + "typ": "JWT", + "alg": "RS256", + "kid": "b520b3c2c4bd75a10e9cebc9576933dc" +} +{ + "iss": "https://foo.bar.com", + "sub": "1234567890", + "user": { + "name": "Alice Smith", + "email": "alice.smith@example.com", + "roles": [ + "developer" + ] + }, + "premium_user": false, + "iat": 1516239022, + "scope": "read add delete" +} +``` + +Send a request to the backend service with the invalid JWT token: + +```shell +curl -v -H "Host: www.example.com" -H "Authorization: Bearer ${INVALID_TOKEN}" "http://${GATEWAY_HOST}/" +``` + +The request should be denied and you should see a `403 Forbidden` response. + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the ClientTrafficPolicy + +```shell +kubectl delete securitypolicy/authorization-jwt-claim +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute diff --git a/site/content/en/v1.8/tasks/security/mutual-tls.md b/site/content/en/v1.8/tasks/security/mutual-tls.md new file mode 100644 index 0000000000..9ecc607000 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/mutual-tls.md @@ -0,0 +1,207 @@ +--- +title: "Mutual TLS: External Clients to the Gateway" +--- + +This task demonstrates how mutual TLS can be achieved between external clients and the Gateway. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## TLS Certificates + +Generate the certificates and keys used by the Gateway to terminate client TLS connections. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt --certificate-authority=example.com.crt +``` + +Store the CA Cert in another Secret: + +```shell +kubectl create secret generic example-ca-cert --from-file=ca.crt=example.com.crt +``` + +Create a certificate and a private key for the client `client.example.com`: + +```shell +openssl req -out client.example.com.csr -newkey rsa:2048 -nodes -keyout client.example.com.key -subj "/CN=client.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in client.example.com.csr -out client.example.com.crt +``` + +Update the Gateway from the Quickstart to include an HTTPS listener that listens on port `443` and references the +`example-cert` Secret: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - kind: Secret + group: "" + name: example-cert + ' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +Create a [ClientTrafficPolicy][] to enforce client validation using the CA Certificate as a trusted anchor. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through the Gateway: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cert client.example.com.crt --key client.example.com.key \ +--cacert example.com.crt https://www.example.com/get +``` + +Don't specify the client key and certificate in the above command, and ensure that the connection fails: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 & +``` + +Query the example app through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cert client.example.com.crt --key client.example.com.key \ +--cacert example.com.crt https://www.example.com:8443/get +``` + +{{% /tab %}} +{{< /tabpane >}} + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the ClientTrafficPolicy and the secrets: + +```shell +kubectl delete clienttrafficpolicy/enable-mtls +kubectl delete secret/example-cert +kubectl delete secret/example-ca-cert +``` + +Delete the certificates and keys: + +```shell +rm example.com.crt example.com.key +rm www.example.com.crt www.example.com.key www.example.com.csr +rm client.example.com.crt client.example.com.key client.example.com.csr +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy diff --git a/site/content/en/v1.8/tasks/security/oidc.md b/site/content/en/v1.8/tasks/security/oidc.md new file mode 100644 index 0000000000..7a5624dde8 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/oidc.md @@ -0,0 +1,629 @@ +--- +title: "OIDC Authentication" +--- + +This task provides instructions for configuring [OpenID Connect (OIDC)][oidc] authentication. +OpenID Connect (OIDC) is an authentication standard built on top of OAuth 2.0. +It enables EG to rely on authentication that is performed by an OpenID Connect Provider (OP) +to verify the identity of a user. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure OIDC +authentication. +This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute][HTTPRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +EG OIDC authentication requires the redirect URL to be HTTPS. Follow the [Secure Gateways](../secure-gateways) guide +to generate the TLS certificates and update the Gateway configuration to add an HTTPS listener. + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +Let's create an HTTPRoute that represents an application protected by OIDC. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute status: + +```shell +kubectl get httproute/myapp -o yaml +``` + +## OIDC Authentication for a HTTPRoute + +OIDC can be configured at the Gateway level to authenticate all the HTTPRoutes that are associated with the Gateway with +the same OIDC configuration, or at the HTTPRoute level to authenticate each HTTPRoute with different OIDC configurations. + +This section demonstrates how to configure OIDC authentication for a specific HTTPRoute. + +### Register an OIDC application + +This task uses Google as the OIDC provider to demonstrate the configuration of OIDC. However, EG works with any OIDC +providers, including Auth0, Azure AD, Keycloak, Okta, OneLogin, Salesforce, UAA, etc. + +Follow the steps in the [Google OIDC documentation][google-oidc] to register an OIDC application. Please make sure the +redirect URL is set to the one you configured in the SecurityPolicy that you will create in the step below. In this example, +the redirect URL is `https://www.example.com:8443/myapp/oauth2/callback`. + +After registering the application, you should have the following information: +* Client ID: The client ID of the OIDC application. +* Client Secret: The client secret of the OIDC application. + +### Create a kubernetes secret + +Next, create a kubernetes secret with the Client Secret created in the previous step. The secret is an Opaque secret, +and the Client Secret must be stored in the key "client-secret". + +Note: please replace the ${CLIENT_SECRET} with the actual Client Secret that you got from the previous step. + +```shell +kubectl create secret generic my-app-client-secret --from-literal=client-secret=${CLIENT_SECRET} +``` + +### Create a SecurityPolicy + +**Please notice that the `redirectURL` and `logoutPath` must match the target HTTPRoute.** In this example, the target +HTTPRoute is configured to match the host `www.example.com` and the path `/myapp`, so the `redirectURL` must be prefixed +with `https://www.example.com:8443/myapp`, and `logoutPath` must be prefixed with`/myapp`, otherwise the OIDC authentication +will fail because the redirect and logout requests will not match the target HTTPRoute and therefore can't be processed +by the OAuth2 filter on that HTTPRoute. + +Note: please replace the ${CLIENT_ID} in the below yaml snippet with the actual Client ID that you got from the OIDC provider. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/oidc-example -o yaml +``` + +### Testing + +Port forward gateway port to localhost: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') + +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 +``` + +Put www.example.com in the /etc/hosts file in your test machine, so we can use this host name to access the gateway from a browser: + +```shell +... +127.0.0.1 www.example.com +``` + +Open a browser and navigate to the `https://www.example.com:8443/myapp` address. You should be redirected to the Google +login page. After you successfully login, you should see the response from the backend service. + +Clean the cookies in the browser and try to access `https://www.example.com:8443/foo` address. You should be able to see +this page since the path `/foo` is not protected by the OIDC policy. + +## OIDC Authentication for a Gateway + +OIDC can be configured at the Gateway level to authenticate all the HTTPRoutes that are associated with the Gateway with +the same OIDC configuration, or at the HTTPRoute level to authenticate each HTTPRoute with different OIDC configurations. + +This section demonstrates how to configure OIDC authentication for a Gateway. + +### Register an OIDC application + +If you haven't registered an OIDC application, follow the steps in the previous section to register an OIDC application. + +### Create a kubernetes secret + +If you haven't created a kubernetes secret, follow the steps in the previous section to create a kubernetes secret. + +### Create an HTTPRoute with a different subdomain + +Let's create another HTTPRoute in the same Gateway, but with a different subdomain. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the HTTPRoute status: + +```shell +kubectl get httproute/foo -o yaml +``` + +### Create a SecurityPolicy + +Create or update the SecurityPolicy to target the Gateway instead of the HTTPRoute. **Please notice that the `redirectURL` +and `logoutPath` must match one of the HTTPRoutes associated with the Gateway.** In this example, the target Gateway has +three HTTPRoutes associated with it, one with the host `www.example.com` and the path `/myapp`, one with the host +`www.example.com` and the path `/`, and one with the host `foo.example.com` and the path `/`. Any of these HTTPRoutes +can be used to match the `redirectURL` and `logoutPath`. + +By default, the access token and ID token cookies are set to the host of the request, excluding subdomains. To allow the +token cookies to be shared across subdomains and prevent users from having to log in again when switching between subdomains, +the `cookieDomain` field needs to be set to the root domain. In this example, the root domain is `example.com`. + +Note: if a `cookieDomain` is added to an existing SecurityPolicy, the cookies in the browser must be cleared before sending a new request to the Gateway, otherwise the cookies with the old subdomain will take precedence and be sent to the Gateway, causing the OIDC authentication to fail. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/oidc-example -o yaml +``` + +### Update the Listener TLS certificate to support multiple subdomains + +Create a multi-domain wildcard certificate for `*.example.com`. + +```shell +openssl req -out wildcard.csr -newkey rsa:2048 -nodes -keyout wildcard.key -subj "/CN=*.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in wildcard.csr -out wildcard.crt +``` + +Replace the TLS certificate of the Gateway with the wildcard certificate. + +```shell +kubectl delete secret example-cert +kubectl create secret tls example-cert --key=wildcard.key --cert=wildcard.crt +``` + +### Testing + +If you haven't done so, follow the steps in the previous section to port forward gateway port to localhost and put +www.example.com in the /etc/hosts file in your test machine. + +Also, put foo.example.com in the /etc/hosts file in your test machine. + +```shell +... +127.0.0.1 foo.example.com +``` + +Open a browser and navigate to the `https://www.example.com:8443/myapp` address. You should be redirected to the Google +login page. After you successfully login, you should see the response from the backend service. + +You can also try to access `https://foo.example.com:8443` and `https://www.example.com:8443/bar` addresses. You should +be able to see the response from the backend service since these HTTPRoutes are also protected by the same OIDC config, +and the cookies are shared across subdomains. + +## Connect to an OIDC Provider with Self-Signed Certificate + +In some scenarios, the OIDC provider may use a self-signed certificate. To connect to an OIDC provider with a self-signed certificate, you need to configure it using the [Backend] resource within the [SecurityPolicy]. Additionally, use the [BackendTLSPolicy] to specify the CA certificate required to authenticate the OIDC provider. + +The following example demonstrates how to configure the OIDC provider with a self-signed certificate. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +As shown in the example above, the [SecurityPolicy] resource is configured with an OIDC provider in its OIDC settings. The `backendRefs` field references the [Backend] resource that defines the OIDC provider. The [BackendTLSPolicy] resource specifies the CA certificate required to authenticate the OIDC provider. + +Additional connection settings for the OIDC provider can be configured in the [backendSettings]. Currently, only the retry policy is supported. + +For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks. + + +## Providers + +Guides to integrate with specific OIDC providers. + +### Azure Entra + +This guide demonstrates how to configure Envoy Gateway to use [Azure Entra](https://learn.microsoft.com/en-us/entra) as the OIDC provider with additional JWT authorization. To get OAuth 2.0 compatible tokens you must register a Scope for your application as described in the [Microsoft Documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent). In this example the resulting scope is `api://custom/EnvoyGateway.OIDC`. + +```yaml +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: entra-example +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: eg + oidc: + clientID: "${CLIENT_ID}" + clientSecret: + name: "my-app-client-secret" + redirectURL: "https://www.example.com:8443/myapp/oauth2/callback" + logoutPath: "/myapp/logout" + + cookieDomain: "example.com" + cookieNames: + accessToken: "azure-access-token" + + provider: + issuer: "https://login.microsoftonline.com//v2.0" + scopes: + - api://custom/EnvoyGateway.OIDC + authorization: + defaultAction: Deny + rules: + - name: "allow-jwt-claim" + action: Allow + principal: + jwt: + provider: entra + claims: + - name: roles + valueType: "StringArray" + values: + - "administrators" + jwt: + providers: + - name: entra + issuer: "https://login.microsoftonline.com//v2.0" + remoteJWKS: + uri: https://login.microsoftonline.com//discovery/v2.0/keys + extractFrom: + cookies: + - "azure-access-token" +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy, the secret and the HTTPRoute: + +```shell +kubectl delete securitypolicy/oidc-example +kubectl delete secret/my-app-client-secret +kubectl delete httproute/myapp +kubectl delete httproute/foo +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[oidc]: https://openid.net/connect/ +[google-oidc]: https://developers.google.com/identity/protocols/oauth2/openid-connect +[SecurityPolicy]: ../../../api/extension_types#securitypolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[Backend]: ../../../api/extension_types#backend +[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[backend-routing]: ../traffic/backend +[backend-tls]: ../backend-tls +[BackendSettings]: ../../../api/extension_types/#clustersettings diff --git a/site/content/en/v1.8/tasks/security/private-key-provider.md b/site/content/en/v1.8/tasks/security/private-key-provider.md new file mode 100644 index 0000000000..24544f6797 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/private-key-provider.md @@ -0,0 +1,653 @@ +--- +title: "Accelerating TLS Handshakes using Private Key Provider in Envoy" +--- + +TLS operations can be accelerated or the private key can be protected using specialized hardware. This can be leveraged in Envoy using [Envoy Private Key Provider](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-privatekeyprovider) is added to Envoy. + +Today, there are two private key providers implemented in Envoy as contrib extensions: +- [QAT in Envoy 1.24 release](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/private_key_providers/qat/v3alpha/qat.proto#extensions-private-key-providers-qat-v3alpha-qatprivatekeymethodconfig) +- [CryptoMB in Envoy 1.20 release](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/private_key_providers/cryptomb/v3alpha/cryptomb.proto ) + +Both of them are used to accelerate the TLS handshake through the hardware capabilities. + +This task will walk you through the steps required to configure TLS Termination mode for TCP traffic while also using the Envoy Private Key Provider to accelerate the TLS handshake by leveraging QAT and the HW accelerator available on Intel SPR/EMR Xeon server platforms. + +## Prerequisites + +{{< tabpane text=true >}} + +{{% tab header="QAT (Intel QuickAssist Technology)" %}} + +- Install Linux kernel 5.17 or similar +- Ensure the node has QAT devices by checking the QAT physical function devices presented. [Supported Devices](https://intel.github.io/quickassist/qatlib/requirements.html#qat2-0-qatlib-supported-devices) + + ```shell + echo `(lspci -d 8086:4940 && lspci -d 8086:4941 && lspci -d 8086:4942 && lspci -d 8086:4943 && lspci -d 8086:4946 && lspci -d 8086:4947) | wc -l` supported devices found. + ``` + +- Enable IOMMU from BIOS +- Enable IOMMU for Linux kernel + + Figure out the QAT VF device id + + ```shell + lspci -d 8086:4941 && lspci -d 8086:4943 && lspci -d 8086:4947 + ``` + + Attach the QAT device to vfio-pci through kernel parameter by the device id gotten from previous command. + + ```shell + cat /etc/default/grub: + GRUB_CMDLINE_LINUX="intel_iommu=on vfio-pci.ids=[QAT device id]" + update-grub + reboot + ```` + + Once the system is rebooted, check if the IOMMU has been enabled via the following command: + + ```shell + dmesg| grep IOMMU + [ 1.528237] DMAR: IOMMU enabled + ``` + +- Enable virtual function devices for QAT device + + ```shell + modprobe vfio_pci + rmmod qat_4xxx + modprobe qat_4xxx + qat_device=$(lspci -D -d :[QAT device id] | awk '{print $1}') + for i in $qat_device; do echo 16|sudo tee /sys/bus/pci/devices/$i/sriov_numvfs; done + chmod a+rw /dev/vfio/* + ``` + +- Increase the container runtime memory lock limit (using the containerd as example here) + + ```shell + mkdir /etc/systemd/system/containerd.service.d + cat <>/etc/systemd/system/containerd.service.d/memlock.conf + [Service] + LimitMEMLOCK=134217728 + EOF + ``` + + Restart the container runtime (for containerd, CRIO has similar concept) + + ```shell + systemctl daemon-reload + systemctl restart containerd + ``` + +- Install [Intel® QAT Device Plugin for Kubernetes](https://github.com/intel/intel-device-plugins-for-kubernetes) + + ```shell + kubectl apply -k 'https://github.com/intel/intel-device-plugins-for-kubernetes/deployments/qat_plugin?ref=main' + ``` + + Verification of the plugin deployment and detection of QAT hardware can be confirmed by examining the resource allocations on the nodes: + + ```shell + kubectl get node -o yaml| grep qat.intel.com + ``` + +{{% /tab %}} + +{{% tab header="CryptoMB" %}} + +It required the node with 3rd generation Intel Xeon Scalable processor server processors, or later. +- For kubernetes Cluster, if not all nodes that support Intel® AVX-512 in Kubernetes cluster, you need to add some labels to divide these two kinds of nodes manually or using [NFD](https://github.com/kubernetes-sigs/node-feature-discovery). + + ```shell + kubectl apply -k https://github.com/kubernetes-sigs/node-feature-discovery/deployment/overlays/default?ref=v0.15.1 + ``` + +- Checking the available nodes with required cpu instructions: + - Check the node labels if using [NFD](https://github.com/kubernetes-sigs/node-feature-discovery): + + ```shell + kubectl get nodes -l feature.node.kubernetes.io/cpu-cpuid.AVX512F,feature.node.kubernetes.io/cpu-cpuid.AVX512DQ,feature.node.kubernetes.io/cpu-cpuid.AVX512BW,feature.node.kubernetes.io/cpu-cpuid.AVX512VBMI2,feature.node.kubernetes.io/cpu-cpuid.AVX512IFMA + ``` + + - Check CPUIDS manually on the node if without using NFD: + + ```shell + cat /proc/cpuinfo |grep avx512f|grep avx512dq|grep avx512bw|grep avx512_vbmi2|grep avx512ifma + ``` + +{{% /tab %}} + +{{< /tabpane >}} + +## Installation + +* Follow the steps from the [Quickstart](../quickstart) to install Envoy Gateway. + +* Enable the EnvoyPatchPolicy feature, which will allow us to directly configure the Private Key Provider Envoy Filter, since Envoy Gateway does not directly expose this functionality. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +## Create gateway for TLS termination + +* Follow the instructions in [TLS Termination for TCP](./tls-termination) to setup a TCP gateway to terminate the TLS connection. + +* Update GatewayClass for using the envoyproxy image with contrib extensions and requests required resources. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Change EnvoyProxy configuration + +Using the envoyproxy image with contrib extensions and add qat resources requesting, ensure the k8s scheduler find out a machine with required resource. + +{{< tabpane text=true >}} + +{{% tab header="QAT (Intel QuickAssist Technology)" %}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{% /tab %}} + +{{% tab header="CryptoMB" %}} + +Using the envoyproxy image with contrib extensions and add the node affinity to scheduling the Envoy Gateway pod on the machine with required CPU instructions. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Or using `preferredDuringSchedulingIgnoredDuringExecution` for best effort scheduling, or not doing any node affinity, just doing the random scheduling. The CryptoMB private key provider supports software fallback if the required CPU instructions aren't here. + +{{% /tab %}} + +{{< /tabpane >}} + +## Benchmark before enabling private key provider + +First follow the instructions in [TLS Termination for TCP](./tls-termination) to do the functionality test. + +Ensure the cpu frequency governor set as `performance`. + +```shell +export NUM_CPUS=`lscpu | grep "^CPU(s):"|awk '{print $2}'` +for i in `seq 0 1 $NUM_CPUS`; do sudo cpufreq-set -c $i -g performance; done +``` + +Using the nodeport as the example, fetch the node port from envoy gateway service. + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +export NODE_PORT=$(kubectl -n envoy-gateway-system get svc/$ENVOY_SERVICE -o jsonpath='{.spec.ports[0].nodePort}') +``` + +```shell +echo "127.0.0.1 www.example.com" >> /etc/hosts +``` + +Benchmark the gateway with fortio. + +```shell +fortio load -c 10 -k -qps 0 -t 30s -keepalive=false https://www.example.com:${NODE_PORT} +``` + +## Apply EnvoyPatchPolicy to enable private key provider + +{{< tabpane text=true >}} + +{{% tab header="QAT (Intel QuickAssist Technology)" %}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{% /tab %}} + +{{% tab header="CryptoMB" %}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{% /tab %}} + +{{< /tabpane >}} + +## Benchmark after enabling private key provider + +First follow the instructions in [TLS Termination for TCP](./tls-termination) to do the functionality test again. + +Benchmark the gateway with fortio. + +```shell +fortio load -c 64 -k -qps 0 -t 30s -keepalive=false https://www.example.com:${NODE_PORT} +``` + +## Benchmark Result + +You will see a performance boost after private key provider enabled. For example, you will get results as below. + +Without private key provider: + +```shell +All done 43069 calls (plus 10 warmup) 6.966 ms avg, 1435.4 qps +``` + +{{< tabpane text=true >}} + +{{% tab header="QAT (Intel QuickAssist Technology)" %}} + +With QAT private key provider, the QPS is over 3 times than without private key provider + +```shell +All done 134746 calls (plus 128 warmup) 28.505 ms avg, 4489.6 qps +``` + +{{% /tab %}} + +{{% tab header="CryptoMB" %}} + +With CryptoMB private key provider, the QPS is over 2 times than without private key provider. + +```shell +All done 93983 calls (plus 128 warmup) 40.880 ms avg, 3130.5 qps +``` + +{{% /tab %}} + +{{< /tabpane >}} diff --git a/site/content/en/v1.8/tasks/security/restrict-ip-access.md b/site/content/en/v1.8/tasks/security/restrict-ip-access.md new file mode 100644 index 0000000000..f03a8eb259 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/restrict-ip-access.md @@ -0,0 +1,197 @@ +--- +title: "IP Allowlist/Denylist" +--- + +This task provides instructions for configuring IP allowlist/denylist on Envoy Gateway. IP allowlist/denylist +checks if an incoming request is from an allowed IP address before routing the request to a backend service. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure IP allowlist/denylist. +This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HTTPRoute], [GRPCRoute][GRPCRoute] or [TCPRoute][TCPRoute] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +### Create a SecurityPolicy + +The below SecurityPolicy restricts access to the backend service by allowing requests only from the IP addresses `10.0.1.0/24`. + +In this example, the default action is set to `Deny`, which means that only requests from the specified IP addresses with `Allow` +action are allowed, and all other requests are denied. You can also change the default action to `Allow` to allow all requests +except those from the specified IP addresses with `Deny` action. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/authorization-client-ip -o yaml +``` + +### Original Source IP + +It's important to note that the IP address used for allowlist/denylist is the original source IP address of the request. +You can use a [ClientTrafficPolicy] to configure how Envoy Gateway should determine the original source IP address. + +For example, the below ClientTrafficPolicy configures Envoy Gateway to use the `X-Forwarded-For` header to determine the original source IP address. +The `numTrustedHops` field specifies the number of trusted hops in the `X-Forwarded-For` header. In this example, the `numTrustedHops` is set to `1`, +which means that the first rightmost IP address in the `X-Forwarded-For` header is used as the original source IP address. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +Send a request to the backend service without the `X-Forwarded-For` header: + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/" +``` + +You should see `403 Forbidden` in the response, indicating that the request is not allowed. + +```shell +* Connected to 172.18.255.200 (172.18.255.200) port 80 +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.8.0-DEV +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 403 Forbidden +< content-length: 19 +< content-type: text/plain +< date: Mon, 08 Jul 2024 04:23:31 GMT +< +* Connection #0 to host 172.18.255.200 left intact +RBAC: access denied +``` + +Send a request to the backend service with the `X-Forwarded-For` header: + +```shell +curl -v -H "Host: www.example.com" -H "X-Forwarded-For: 10.0.1.1" "http://${GATEWAY_HOST}/" +``` + +The request should be allowed and you should see the response from the backend service. + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy and the ClientTrafficPolicy + +```shell +kubectl delete securitypolicy/authorization-client-ip +kubectl delete clientTrafficPolicy/enable-client-ip-detection +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[SecurityPolicy]: /community/design/security-policy +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute +[TCPRoute]: https://gateway-api.sigs.k8s.io/guides/tcp/ diff --git a/site/content/en/v1.8/tasks/security/secure-gateways.md b/site/content/en/v1.8/tasks/security/secure-gateways.md new file mode 100644 index 0000000000..bf5cab25a7 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/secure-gateways.md @@ -0,0 +1,781 @@ +--- +title: "Secure Gateways" +--- + +This task will help you get started using secure Gateways. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## TLS Certificates + +Generate the certificates and keys used by the Gateway to terminate client TLS connections. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt +``` + +Update the Gateway from the Quickstart to include an HTTPS listener that listens on port `443` and references the +`example-cert` Secret: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - kind: Secret + group: "" + name: example-cert + ' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## OCSP Stapling + +Online Certificate Status Protocol (OCSP) stapling allows the gateway to proactively attach proof that a certificate is still valid, eliminating the need for each client to query the certificate authority (CA) during the TLS handshake. This reduces latency and prevents client browsing information from being exposed to the CA. + +Envoy Gateway supports OCSP stapling by attaching an OCSP response during the TLS handshake whenever the Gateway listener’s certificate Secret includes one. Specifically, Envoy Gateway looks for the OCSP response in the Secret’s `tls.ocsp-staple` data field. If present, Envoy Gateway staples the response to the handshake automatically. + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through the Gateway: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 & +``` + +Query the example app through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get +``` + +{{% /tab %}} +{{< /tabpane >}} + + +## Multiple HTTPS Listeners + +Create a TLS cert/key for the additional HTTPS listener: + +```shell +openssl req -out foo.example.com.csr -newkey rsa:2048 -nodes -keyout foo.example.com.key -subj "/CN=foo.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in foo.example.com.csr -out foo.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls foo-cert --key=foo.example.com.key --cert=foo.example.com.crt +``` + +Create another HTTPS listener on the example Gateway: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: https-foo + protocol: HTTPS + port: 443 + hostname: foo.example.com + tls: + mode: Terminate + certificateRefs: + - kind: Secret + group: "" + name: foo-cert + ' +``` + +Update the HTTPRoute to route traffic for hostname `foo.example.com` to the example backend service: + +```shell +kubectl patch httproute backend --type=json --patch ' + - op: add + path: /spec/hostnames/- + value: foo.example.com + ' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +Follow the steps in the [Testing section](#testing) to test connectivity to the backend app through both Gateway +listeners. Replace `www.example.com` with `foo.example.com` to test the new HTTPS listener. + +## Cross Namespace Certificate References + +A Gateway can be configured to reference a certificate in a different namespace. This is allowed by a [ReferenceGrant][] +created in the target namespace. Without the ReferenceGrant, a cross-namespace reference is invalid. + +Before proceeding, ensure you can query the HTTPS backend service from the [Testing section](#testing). + +To demonstrate cross namespace certificate references, create a ReferenceGrant that allows Gateways from the "default" +namespace to reference Secrets in the "envoy-gateway-system" namespace: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Delete the previously created Secret: + +```shell +kubectl delete secret/example-cert +``` + +The Gateway HTTPS listener should now surface the `Ready: False` status condition and the example HTTPS backend should +no longer be reachable through the Gateway. + +```shell +kubectl get gateway/eg -o yaml +``` + +Recreate the example Secret in the `envoy-gateway-system` namespace: + +```shell +kubectl create secret tls example-cert -n envoy-gateway-system --key=www.example.com.key --cert=www.example.com.crt +``` + +Update the Gateway HTTPS listener with `namespace: envoy-gateway-system`, for example: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The Gateway HTTPS listener status should now surface the `Ready: True` condition and you should once again be able to +query the HTTPS backend through the Gateway. + +Lastly, test connectivity using the above [Testing section](#testing). + +## Clean-Up + +Follow the steps from the [Quickstart](../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the Secrets: + +```shell +kubectl delete secret/example-cert +kubectl delete secret/foo-cert +``` + +# RSA + ECDSA Dual stack certificates + +This section gives a walkthrough to generate RSA and ECDSA derived certificates and keys for the Server, which can then be configured in the Gateway listener, to terminate TLS traffic. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +Follow the steps in the [TLS Certificates](#tls-certificates) section to generate self-signed RSA derived Server certificate and private key, and configure those in the Gateway listener configuration to terminate HTTPS traffic. + +## Pre-checks + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through Envoy Proxy while enforcing an RSA cipher: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -Isv --ciphers ECDHE-RSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The call should succeed with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305 +... +... +``` + +Since the Secret configured at this point is an RSA based Secret, if we enforce the usage of an ECDSA cipher, the call should fail: + +```shell + curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -Isv --ciphers ECDHE-ECDSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The call above fails with the following message: +``` +* Added www.example.com:443:127.0.0.1 to DNS cache +* Hostname www.example.com was found in DNS cache +* Trying 127.0.0.1:443... +* Connected to www.example.com (127.0.0.1) port 443 +* ALPN: curl offers h2,http/1.1 +* Cipher selection: ECDHE-ECDSA-CHACHA20-POLY1305 +* TLSv1.2 (OUT), TLS handshake, Client hello (1): +* CAfile: example.com.crt +* CApath: none +* TLSv1.2 (IN), TLS alert, handshake failure (552): +* OpenSSL/3.0.14: error:0A000410:SSL routines::sslv3 alert handshake failure +* Closing connection +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Query the example app through Envoy proxy while enforcing an RSA cipher: +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get -Isv --ciphers ECDHE-RSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The command should succeed with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305 +... +``` + +Since the Secret configured at this point is an RSA based Secret, if we enforce the usage of an ECDSA cipher, the call should fail: + +```shell + curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -Isv --ciphers ECDHE-ECDSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The command above fails with the following message: +``` +* Added www.example.com:8443:127.0.0.1 to DNS cache +* Hostname www.example.com was found in DNS cache +* Trying 127.0.0.1:8443... +* Connected to www.example.com (127.0.0.1) port 8443 (#0) +* ALPN: offers h2 +* ALPN: offers http/1.1 +* Cipher selection: ECDHE-ECDSA-CHACHA20-POLY1305 +* CAfile: example.com.crt +* CApath: none +* (304) (OUT), TLS handshake, Client hello (1): +* error:1404B410:SSL routines:ST_CONNECT:sslv3 alert handshake failure +* Closing connection 0 +``` + +{{% /tab %}} +{{< /tabpane >}} + +Moving forward in the doc, we will be configuring the existing Gateway listener to accept both kinds of ciphers. + +## TLS Certificates + +Reuse the CA certificate and key pair generated in the [Secure Gateways](#tls-certificates) task and use this CA to sign both RSA and ECDSA Server certificates. +Note the CA certificate and key names are `example.com.crt` and `example.com.key` respectively. + + +Create an ECDSA certificate and a private key for `www.example.com`: + +```shell +openssl ecparam -noout -genkey -name prime256v1 -out www.example.com.ecdsa.key +openssl req -new -SHA384 -key www.example.com.ecdsa.key -nodes -out www.example.com.ecdsa.csr -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -SHA384 -days 365 -in www.example.com.ecdsa.csr -CA example.com.crt -CAkey example.com.key -CAcreateserial -out www.example.com.ecdsa.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert-ecdsa --key=www.example.com.ecdsa.key --cert=www.example.com.ecdsa.crt +``` + +Patch the Gateway with this additional ECDSA Secret: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/1/tls/certificateRefs/- + value: + name: example-cert-ecdsa + ' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through Envoy Proxy while enforcing an RSA cipher: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -Isv --ciphers ECDHE-RSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The call should succeed with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305 +... +... +``` + +Additionally, querying the example app while enforcing an ECDSA cipher should also work now: + +```shell + curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -Isv --ciphers ECDHE-ECDSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The call above succeeds with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-ECDSA-CHACHA20-POLY1305 +... +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Query the example app through Envoy proxy while enforcing an RSA cipher: +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get -Isv --ciphers ECDHE-RSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The command should succeed with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305 +... +``` + +Additionally, querying the example app while enforcing an ECDSA cipher should also work now: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get -Isv --ciphers ECDHE-ECDSA-CHACHA20-POLY1305 --tlsv1.2 --tls-max 1.2 +``` + +The command above succeeds with the following message: +``` +... +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-ECDSA-CHACHA20-POLY1305 +... +``` + +{{% /tab %}} +{{< /tabpane >}} + +# SNI based Certificate selection + +This sections gives a walkthrough to generate multiple certificates corresponding to different FQDNs. The same Gateway listener can then be configured to terminate TLS traffic for multiple FQDNs based on the SNI matching. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +Follow the steps in the [TLS Certificates](#tls-certificates) section to generate self-signed RSA derived Server certificate and private key, and configure those in the Gateway listener configuration to terminate HTTPS traffic. + +## Additional Configurations + +Using the [TLS Certificates](#tls-certificates) section, we first generate additional Secret for another Host `www.sample.com`. + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=sample Inc./CN=sample.com' -keyout sample.com.key -out sample.com.crt + +openssl req -out www.sample.com.csr -newkey rsa:2048 -nodes -keyout www.sample.com.key -subj "/CN=www.sample.com/O=sample organization" +openssl x509 -req -days 365 -CA sample.com.crt -CAkey sample.com.key -set_serial 0 -in www.sample.com.csr -out www.sample.com.crt + +kubectl create secret tls sample-cert --key=www.sample.com.key --cert=www.sample.com.crt +``` + +Note that all occurrences of `example.com` were just replaced with `sample.com` + + +Next we update the `Gateway` configuration to accommodate the new Certificate which will be used to Terminate TLS traffic: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/1/tls/certificateRefs/- + value: + name: sample-cert + ' +``` + +Finally, we update the HTTPRoute to route traffic for hostname `www.sample.com` to the example backend service: + +```shell +kubectl patch httproute backend --type=json --patch ' + - op: add + path: /spec/hostnames/- + value: www.sample.com + ' +``` + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through Envoy Proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get -I +``` + +Similarly, query the sample app through the same Envoy proxy: + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:443:${GATEWAY_HOST}" \ +--cacert sample.com.crt https://www.sample.com/get -I +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 & +``` + +Query the example app through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get -I +``` + +Similarly, query the sample app through the same Envoy proxy: + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:8443:127.0.0.1" \ +--cacert sample.com.crt https://www.sample.com:8443/get -I +``` + +{{% /tab %}} +{{< /tabpane >}} + +Since the multiple certificates are configured on the same Gateway listener, Envoy was able to provide the client with appropriate certificate based on the SNI in the client request. + +## Customize Gateway TLS Parameters + +In addition to enablement of TLS with Gateway-API, Envoy Gateway supports customizing TLS parameters. +To achieve this, the [ClientTrafficPolicy][] resource can be used to specify TLS parameters. +We will customize the minimum supported TLS version in this example to TLSv1.3. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +## Testing TLS Parameters + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Attempt to connect using an unsupported TLS version: + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:443:${GATEWAY_HOST}" \ +--cacert sample.com.crt --tlsv1.2 --tls-max 1.2 https://www.sample.com/get -I +``` + +You should receive the following error: +``` +[...] + +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version +* Closing connection +curl: (35) LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version +``` + +The output shows that the connection fails due to an unsupported TLS protocol version used by the client. Now, connect to the Gateway without specifying a client version, and note that the connection is established with TLSv1.3. + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:443:${GATEWAY_HOST}" \ +--cacert sample.com.crt https://www.sample.com/get -I +``` + +The command above should succeed and output the following: +``` +[...] +* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF +``` + + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Attempt to connecting using an unsupported TLS version: + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:8443:127.0.0.1" \ +--cacert sample.com.crt --tlsv1.2 --tls-max 1.2 https://www.sample.com:8443/get -I +``` + +You should receive the following error: +``` +[...] + +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version +* Closing connection +curl: (35) LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version +``` + +The output shows that the connection fails due to an unsupported TLS protocol version used by the client. Now, connect +to the Gateway without specifying a client version, and note that the connection is established with TLSv1.3. + +```shell +curl -v -HHost:www.sample.com --resolve "www.sample.com:8443:127.0.0.1" \ +--cacert sample.com.crt https://www.sample.com:8443/get -I +``` + +The command above should succeed and output the following: +``` +[...] +* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF +``` + +{{% /tab %}} +{{< /tabpane >}} + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[ReferenceGrant]: https://gateway-api.sigs.k8s.io/api-types/referencegrant/ +[ClientTrafficPolicy]: ../../api/extension_types#clienttrafficpolicy diff --git a/site/content/en/v1.8/tasks/security/threat-model.md b/site/content/en/v1.8/tasks/security/threat-model.md new file mode 100644 index 0000000000..195a7d2e0b --- /dev/null +++ b/site/content/en/v1.8/tasks/security/threat-model.md @@ -0,0 +1,665 @@ +--- +title: "Threat Model" +--- + +# Envoy Gateway Threat Model and End User Recommendations + +## About + +This work was performed by [ControlPlane](https://control-plane.io/) and commissioned by the [Linux Foundation](https://www.linuxfoundation.org/). ControlPlane is a global cloud native and open source cybersecurity consultancy, trusted as the partner of choice in securing: multinational banks; major public clouds; international financial institutions; critical national infrastructure programs; multinational oil and gas companies, healthcare and insurance providers; and global media firms. + +## Threat Modelling Team + +James Callaghan, Torin van den Bulk, Eduardo Olarte + +## Reviewers + +Arko Dasgupta, Matt Turner, Zack Butcher, Marco De Benedictis + +## Introduction + +As we embrace the proliferation of microservice-based architectures in the cloud-native landscape, simplicity in setup and configuration becomes paramount as DevOps teams face the challenge of choosing between numerous similar technologies. One such choice which every team deploying to Kubernetes faces is what to use as an ingress controller. With a plethora of options available, and the existence of vendor-specific annotations leading to small inconsistencies between implementations, the [Gateway API](https://gateway-api.sigs.k8s.io/) project was introduced by the SIG-NETWORK community, with the goal of eventually replacing the Ingress resource. + +Envoy Gateway is configured by Gateway API resources, and serves as an intuitive and feature-rich wrapper over the widely acclaimed Envoy Proxy. With a convenient setup based on Kubernetes (K8s) manifests, Envoy Gateway streamlines the management of Envoy Proxy instances in an edge-proxy setting, reducing the operational overhead of managing low-level Envoy configurations. Envoy Gateway benefits cloud-native DevOps teams through its role-oriented configuration, providing granular control based on Role-Based Access Control (RBAC) principles. These features form the basis of our exploration into Envoy Gateway and the rich feature set it brings to the table. + +In this threat model, we aim to provide an analysis of Envoy Gateway's design components and their capabilities (at version 1.0) through a threat-driven approach. It should be noted that this does not constitute a security audit of the Envoy Gateway project, but instead focuses on different possible deployment topologies for Envoy Gateway with the goal of deriving recommendations and best practice guidance for end users. + +The Envoy Gateway project recommends a [multi-tenancy model](../operations/deployment-mode#multi-tenancy) whereby each tenant deploys their own Envoy Gateway controller in a namespace which they own. We will also explore the implications and risks associated with multiple tenants using a shared controller. + +### Scope + +The primary focus of this threat model is to identify and assess security risks associated with deploying and operating Envoy Gateway within a multi-tenant Kubernetes (K8s) cluster. This model aims to provide a comprehensive understanding of the system, its transmission points, and potential vulnerabilities to enumerated threats. + +### In Scope + +**Envoy Gateway**: As the primary focus of this threat model, all aspects of Envoy Gateway, including its configuration, deployment, and operation will be analysed. This includes how the gateway manages TLS certificates, authentication, service-to-service traffic routing, and more. + +**Kubernetes Cluster**: Configuration and operation of the underlying Kubernetes cluster, including how it manages network policies, access control, and resource isolation for different namespaces/tenants in relation to Envoy will be considered. + +**Tenant Workloads**: Tenant workloads (and the pods they run on) will be considered, focusing on how they interact with the Envoy Gateway and potential vulnerabilities that could be exploited. + +#### Out of Scope + +This threat model will not consider security risks associated with the underlying infrastructure (e.g., EC2 compute instances and S3 buckets) or non-Envoy related components within the Kubernetes Cluster. It will focus solely on the Envoy Gateway and its interaction with the Kubernetes cluster and tenant workloads. + +Implementation of Envoy Gateway as an egress traffic controller is out of scope for this threat model and will not be considered in the report's findings. + +### Related Resources + +[Introducing Envoy Gateway](https://blog.envoyproxy.io/introducing-envoy-gateway-ad385cc59532) + +[Envoy Proxy Threat Model](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/threat_model#threat-model) + +[Configuring Envoy as an Edge Proxy](https://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/edge#best-practices-edge) + +[Envoy Gateway Deployment Mode](../operations/deployment-mode) + +[Kubernetes Gateway API Security Model](https://gateway-api.sigs.k8s.io/concepts/security/) + +## Architecture Overview + +### Summary + +To provide an in-depth look into both the system design and end-user deployment of Envoy Gateway, we will be focusing on the [Deployment Architecture Diagram](#deployment-architecture-diagram) below. + +The Deployment Architecture Diagram provides a high-level model of an end-user deployment of Envoy Gateway. For simplicity, we will look at different deployment topologies on a single multi-tenant Kubernetes cluster. Envoy Gateway operates as an edge proxy within this environment, handling the traffic flow between external interfaces and services within the cluster. The example will use two Envoy Gateway controllers - one dedicated controller for a single tenant, and one shared controller for two other tenants. Each Envoy Gateway controller will accept a single GatewayClass resource. + +### Deployment Architecture Diagram + +As Envoy Gateway implements the [Kubernetes GatewayAPI](https://gateway-api.sigs.k8s.io/concepts/api-overview/), this threat model will focus on the key objects in the Gateway API resource model: + +1. **GatewayClass:** defines a set of gateways with a commonconfiguration and behaviour. It is a cluster scoped resource. + +2. **Gateway:** requests a point where traffic can be translated to Services within the cluster. + +3. **Routes:** describe how traffic coming via the Gateway maps to theServices. + +At the time of writing, Envoy Gateway only supports a Kubernetes provider. As such, we will consider a reference architecture where multiple teams are working on the same Kubernetes cluster within different namespaces (Tenant A, B, & C). We will assume that some teams have similar security and performance needs, and a decision has been made to use a shared Gateway. However, we will also consider the case that some teams require dedicated Gateways, perhaps for compliance reasons or requirements driven by an internal threat model. + +We will consider the following organisational roles, as per the [Gateway API security model](https://gateway-api.sigs.k8s.io/concepts/security/): + +1. **Infrastructure provider**: The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider (AWS, Azure, GCP, ...) or the PaaS provider in a company. + +2. **Cluster operator**: The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. + +3. **Application developer**: The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). + +4. **Application admin**: The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole. + +Our threat model will be based on the high-level setup shown below, where Envoy is used in an edge-proxy scenario: + +![Architecture](/img/architecture_threat_model.png) + +The following use cases will be considered, in line with the [Envoy Gateway tasks](../quickstart): + +1. Routing and controlling traffic, including: + a. HTTP \ + b. TCP \ + c. UDP \ + d. gRPC \ + e.TLS passthrough +2. TLS termination +3. Request Authentication +4. Rate Limiting + +## Key Assumptions + +This section outlines the foundational premises that shape our analysis and recommendations for the deployment and management of Envoy Gateway within an organisation. The key assumptions are as follows: + +**1. Kubernetes Provider**: For the purposes of this analysis, we assume that a K8s provider will be used to host the cluster. + +**2. Multi-tenant cluster**: In order to produce a broad set of recommendations, it is assumed that within the single cluster, there is: + +- A dedicated cluster operation (ops) team responsible for maintaining the core cluster infrastructure. + +- Multiple application teams who wish to define their own Gateway resources, which will route traffic to their respective applications. + +**3. Soft multi-tenancy model**: It is assumed that co-tenants will have some level of trust between themselves, and will not act in an overtly hostile manner to each other. + +**4. Ingress Control**: It's assumed that Envoy Gateway is the only ingress controller in the K8s cluster as multiple controllers can lead to complex routing challenges and introduce out-of-scope security vulnerabilities. + +**5. Container Security**: This threat model focuses on evaluating the security of the Envoy Gateway and Envoy Proxy images. All other container images running in tenant clusters, not associated with the edge proxy deployment, are assumed to be secure and obtained from trusted registries such as Docker Hub or Google Container Registry (GCR). + +**6. Cloud Provider Security**: It is assumed that the K8s cluster is running on secure cloud infrastructure provided by a trusted Cloud Service Provider (CSP) such as AWS, GCP, or Azure Cloud. + +## Data + +### Data Dictionary + +Ultimately, the data of interest in a threat model is the business data processed by the system in question. However, in the case of this threat model, we are looking at a generic deployment architecture involving Envoy Gateway in order to draw out a set of generalised threats which can be considered by teams looking to adopt an implementation of Gateway API. As such, we do not know the business impacts of a compromise of confidentiality, integrity or availability that would typically be captured in a data impact assessment. Instead, will we base our threat assessment on high-level groupings of data structures used in the configuration and operation of the general use cases considered (e.g. HTTP routing, TLS termination, request authentication etc.). We will then assign a confidentiality, integrity and availability impact based on a worst-case scenario of how each compromise could potentially affect business data processed by the generic deployment. + +| Data Name / Type | Notes | Confidentiality | Integrity | Availability | +| ------------ | ------------ | ------------ |--------------- | ------------ | +| Static Configuration Data | Static configuration data is used to configure Envoy Gateway at startup. This data structure allows for a Provider to be set, which Envoy Gateway calls to establish its runtime configuration, resolve services and persist data. Unauthorised modification of static configuration data could enable the Envoy Gateway admin interface to be configured, logging parameters to be modified, global rate limiting configuration to be misconfigured, or malicious extensions registered for the Envoy Gateway Control Plane. A compromise of confidentiality could potentially give an attacker some useful reconnaissance information. A compromise of the availability of this information at startup time would result in Envoy Gateway starting with default parameters. | Medium | High | Low | +| Dynamic Configuration Data | Dynamic configuration data represents the desired state of the Data Plane, and is defined through Envoy Gateway and Gateway API Kubernetes resources. Unauthorised modification of this data could lead to vulnerabilities in an organisation’s Data Plane infrastructure via misconfiguration of an EnvoyProxy custom resource. Misconfiguration of Gateway API objects such as HTTPRoutes or TLSRoutes could result in traffic being directed to incorrect backends. A compromise of confidentiality could potentially give an attacker some useful reconnaissance information. A compromise of the availability of this information could result in tenant application traffic not being routable until the configuration is recovered and reapplied. | Medium | High | Medium | +| TLS Private Keys | TLS Private Keys, typically in PEM format, are used to initiate secure connections and encrypt communications. In the context of this threat model, private keys will be associated with the server side of an inbound TLS connection being terminated at a secure gateway configured through Envoy Gateway. Unauthorised exposure could lead to security threats such as person-in-the-middle attacks, whereby the confidentiality or integrity of business data could be compromised. A compromise of integrity may lead to similar consequences if an attacker could insert their own key material. An availability compromise could lead to tenant services being unavailable until new key material is generated and an appropriate CSR submitted. | High | High | Medium | +| TLS Certificates | X.509 certificates represent the binding of a public key (associated with the private key described above) to an identity in a TLS handshake. If an attacker could compromise the integrity of a certificate, they may be able to bind the identity of a TLS termination point to a key pair under their control, enabling person-in-the middle attacks. An availability compromise could lead to tenant services being unavailable until new key material is generated and an appropriate CSR submitted. | Low | High | Medium | +| JWKs | JWK (JSON Web Key) containing a public key used to validate JWTs for the client authentication use case considered in this threat model. If an attacker could compromise the integrity of a JWK or JSON web key set (JWKS), they could potentially authenticate to a service maliciously. Unavailability of an endpoint exposing JWKs could lead to client requests which require authentication being denied. | Low | High | Medium | +| JWTs | JWTs, formatted as compact, URL-safe JSON data structures, are utilised for the client authentication use case considered in this threat model. Maintaining their confidentiality and integrity is vital to prevent unauthorised access and ensure correct user identification. | High | High | Low | +| OIDC credentials | In OIDC authentication scenarios, the application credentials are represented by a client ID and a client secret. A compromise of its confidentiality or integrity could allow malicious actors to impersonate the application, potentially being able to access resources on behalf of the application and request ID tokens on behalf of users. Unavailability of this data would produce a rejection of the requests coming from legitimate users. | High | High | Medium | +| Basic authentiation password hashes | In basic authentication scenarios, passwords are stored as Kubernetes secrets in [htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html) format, where each entry is formed by the username and the hashed password. A compromise of these credentials' confidentiality and integrity could lead to unauthorised access to the application. Unavailability of these credentials will cause login failures from the application users. | High | High | Medium | + +### CIA Impact Assessment + +| Priority | Description | +| --- | --- | +| **Confidentiality** | | +| High | Compromise of sensitive client data | +| Medium | Information leaked which could be useful for attacker reconnaissance | +| Low | Non-sensitive information leakage | +| **Integrity** | | +| High | Compromise of source code repositories and gateway deployments | +| Medium | Traffic routing fails due to misconfiguration / invalid configuration | +| Low | Non-critical operation is blocked due to misconfiguration / invalid configuration | +| **Availability** | | +| High | Large scale DoS | +| Medium | Tenant application is blocked for a significant period | +| Low | Tenant application is blocked for a short period | + +### Data Flow Diagrams + +The Data Flow Diagrams (DFDs) below describe the flow of data between the various processes, entities and data stores in a system, as well as the trust boundaries between different user roles and network interfaces. The DFDs are drawn at two different levels, starting at L0 (high-level system view) and increasing in granularity (to L1). + +### DFD L0 + +![DFD L0](/img/DFDL0.png) + +### DFD L1 + +![DFD L1](/img/DFDL1.png) + +## Key Threats and Recommendations + +The scope of this threat model led to us categorising threats into priorities of High, Medium or Low; notably in a production implementation some of the threats' prioritisation may be upgraded or downgraded depending on the business context and data classification. + +### Risk vs. Threat + +For every finding, the risk and threat are stated. Risk defines the potential for negative outcome while threat defines the event that causes the negative outcome. + +### Threat Categorization + +Throughout this threat model, we categorised threats into different areas based on their origin and the segment of the system that they impact. Here's an overview of each category: + +**Container Security (CS)**: These threats are general to containerised applications. Therefore, they are not associated with Envoy Gateway or the Gateway API and could occur in most containerised workloads. They can originate from misconfigurations or vulnerabilities in the orchestrator or the container. + +**Gateway API (GW)**: These are threats related to the Gateway API that could affect any of its implementations. Malicious actors could benefit from misconfigurations or excessive permissions on the Gateway API resources (e.g. xRoutes or Gateways) to compromise the confidentiality, integrity, or availability of the application. + +**Envoy Gateway (EG)**: These threats are associated with specific configurations or features from Envoy Gateway or Envoy Proxy. If not set properly, these features could be leveraged to gain unauthorised access to protected resources. + +### Threat Actors + +In order to provide a realistic set of threats that is applicable to most organisations, we de-scoped the most advanced and hard to mitigate threat actors as described below: + +#### In Scope Threat Actors + +When considering internal threat actors, we chose to follow the [security model](https://gateway-api.sigs.k8s.io/concepts/security/) of the Kubernetes Gateway API. + +##### Internal Attacker + +- Cluster Operator: The cluster operator (ops) is responsible for administration of entire clusters. They manage policies, network access, application permissions. + +- Application Developer: The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request matching/filter) and Service composition (e.g. path routing to backends). + +- Application Administrator: The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole. + +##### External Attacker + +- Vandal: Script kiddie, trespasser + +- Motivated Individual: Political activist, thief, terrorist + +- Organised Crime: Syndicates, state-affiliated groups + +#### Out of Scope Threat Actors + +##### External Actors + +- Infrastructure Provider: The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. Examples include: the cloud provider, or the PaaS provider in a company. + +- Cloud Service Insider: Employee, external contractor, temporary worker + +- Foreign Intelligence Services (FIS): Nation states + +## High Priority Findings + +### EGTM-001 Usage of self-signed certificates + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-001|EGTM-GW-001|Gateway API|High| + + **Risk**: Self-signed certificates (which do not comply with PKI best practices) could lead to unauthorised access to the private key associated with the certificate used for inbound TLS termination at Envoy Proxy, compromising the confidentiality and integrity of proxied traffic. + + **Threat**: Compromise of the private key associated with the certificate used for inbound TLS terminating at Envoy Proxy. + + **Recommendation**: The Envoy Gateway quickstart demonstrates how to set up a Secure Gateway using an example where a self-signed root certificate is created using openssl. As stated in the Envoy Gateway documentation, this is not a suitable configuration for Production usage. It is recommended that PKI best practices are followed, whereby certificates are signed by an Intermediary CA which sits underneath an organisational \'offline\' Root CA. + + PKI best practices should also apply to the management of client certificates when using mTLS. The Envoy Gateway [mTLS](../security/mutual-tls) task shows how to set up client certificates using self-signed certificates. In the same way as gateway certificates and, as mentioned in the documentation, this configuration should not be used in production environments. + +### EGTM-002 Private keys are stored as Kubernetes secrets + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|--------------|------------------------|-----------------| +|EGTM-002|EGTM-CS-001|Container Security|High| + + **Risk**: There is a risk that a threat actor could compromise the Kubernetes secret containing the Envoy private key, allowing the attacker to decrypt Envoy Proxy traffic, compromising the confidentiality of proxied traffic. + + **Threat**: Kubernetes secret containing the Envoy private key is compromised and used to decrypt proxied traffic. + + **Recommendation**: Certificate management best practices mandate short-lived key material where practical, meaning that a mechanism for rotation of private keys and certificates is required, along with a way for certificates to be mounted into Envoy containers. If Kubernetes secrets are used, when a certificate expires, the associated secret must be updated, and Envoy containers must be redeployed. Instead of a manual configuration, it is recommended that [cert-manager](https://github.com/cert-manager/cert-manager) is used. + +### EGTM-004 Usage of ClusterRoles with wide permissions + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|--------------|------------------------|-----------------| +|EGTM-004|EGTM-K8-002|Container Security|High| + + **Risk**: There is a risk that a threat actor could abuse misconfigured RBAC to access the Envoy Gateway ClusterRole (envoy-gateway-role) and use it to expose all secrets across the cluster, thus compromising the confidentiality and integrity of tenant data. + + **Threat**: Compromised Envoy Gateway or misconfigured ClusterRoleBinding (envoy-gateway-rolebinding) to Envoy Gateway ClusterRole (envoy-gateway-role), provides access to resources and secrets in different namespaces. + + **Recommendation**: Users should be aware that Envoy Gateway uses a ClusterRole (envoy-gateway-role) when deployed via the Helm chart, to allow management of Envoy Proxies across different namespaces. This ClusterRole is powerful and includes the ability to read secrets in namespaces which may not be within the purview of Envoy Gateway. + + Kubernetes best-practices involve restriction of ClusterRoleBindings, with the use of RoleBindings where possible to limit access per namespace by specifying the namespace in metadata. Namespace isolation reduces the impact of compromise from cluster-scoped roles. Ideally, fine-grained K8s roles should be created per the principle of least privilege to ensure they have the minimum access necessary for role functions. + + The pull request \#[1656](https://github.com/envoyproxy/gateway/pull/1656) introduced the use of Roles and RoleBindings in [namespaced mode](https://gateway.envoyproxy.io/latest/api/extension_types/#kuberneteswatchmode). This feature can be leveraged to reduce the amount of permissions required by the Envoy Gateway. + +### EGTM-007 Misconfiguration of Envoy Gateway dynamic config + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-007|EGTM-EG-002|Envoy Gateway|High| + + **Risk**: There is a risk that a threat actor could exploit misconfigured Kubernetes RBAC to create or modify Gateway API resources with no business need, potentially leading to the compromise of the confidentiality, integrity, and availability of resources and traffic within the cluster. + + **Threat**: Unauthorised creation or misconfiguration of Gateway API resources by a threat actor with cluster-scoped access. + + **Recommendation**: Configure the apiGroup and resource fields in RBAC policies to restrict access to [Gateway](https://gateway-api.sigs.k8s.io/) and [GatewayClass](https://gateway-api.sigs.k8s.io/api-types/gatewayclass/) resources. Enable namespace isolation by using the namespace field, preventing unauthorised access to gateways in other namespaces. + +### EGTM-009 Co-tenant misconfigures resource across namespaces + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-009|EGTM-GW-002|Gateway API|High| + + **Risk**: There is a risk that a co-tenant misconfigures Gateway or Route resources, compromising the confidentiality, integrity, and availability of routed traffic through Envoy Gateway. + + **Threat**: Malicious or accidental co-tenant misconfiguration of Gateways and Routes associated with other application teams. + + **Recommendation**: Dedicated Envoy Gateways should be provided to each tenant within their respective namespace. A one-to-one relationship should be established between GatewayClass and Gateway resources, meaning that each tenant namespace should have their own GatewayClass watched by a unique Envoy Gateway Controller as defined here in the [Deployment Mode](../operations/deployment-mode) documentation. + + Application Admins should have write permissions on the Gateway resource, but only in their specific namespaces, and Application Developers should only hold write permissions on Route resources. To enact this access control schema, follow the [Write Permissions for Advanced 4 Tier Model](https://gateway-api.sigs.k8s.io/concepts/security/#write-permissions-for-advanced-4-tier-model) described in the Kubernetes Gateway API security model. Examples of secured gateway-route topologies can be found [here](https://gateway-api.sigs.k8s.io/concepts/api-overview/#attaching-routes-to-gateways) within the Kubernetes Gateway API docs. + + Optionally, consider a GitOps model, where only the GitOps operator has the permission to deploy or modify custom resources in production. + +### EGTM-014 Malicious image admission + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-014|EGTM-CS-006|Container Security|High| + + **Risk**: There is a risk that a supply chain attack on Envoy Gateway results in an arbitrary compromise of the confidentiality, integrity or availability of tenant data. + + **Threat**: Supply chain threat actor introduces malicious code into Envoy Gateway or Proxy. + + **Recommendation**: The Envoy Gateway project should continue to work towards conformance with supply-chain security best practices throughout the project lifecycle (for example, as set out in the [CNCF Software Supply Chain Best Practices Whitepaper](https://github.com/cncf/tag-security/blob/main/supply-chain-security/supply-chain-security-paper/CNCF_SSCP_v1.pdf)). Adherence to [Supply-chain Levels for Software Artefacts](https://slsa.dev/) (SLSA) standards is crucial for maintaining the security of the system. Employ version control systems to monitor the source and build platforms and assign responsibility to a specific stakeholder. + + Integrate a supply chain security tool such as Sigstore, which provides native capabilities for signing and verifying container images and software artefacts. [Software Bill of Materials](https://www.cisa.gov/sbom) (SBOM), [Vulnerability Exploitability eXchange](https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf) (VEX), and signed artefacts should also be incorporated into the security protocol. + +### EGTM-020 Out of date or misconfigured Envoy Proxy image + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-020|EGTM-CS-009|Container Security|High| + + **Risk**: There is a risk that a threat actor exploits an Envoy Proxy vulnerability to remote code execution (RCE) due to out of date or misconfigured Envoy Proxy pod deployment, compromising the confidentiality and integrity of Envoy Proxy along with the availability of the proxy service. + + **Threat**: Deployment of an Envoy Proxy or Gateway image containing exploitable CVEs. + + **Recommendation**: Always use the latest version of the Envoy Proxy image. Regularly check for updates and patch the system as soon as updates become available. Implement a CI/CD pipeline that includes security checks for images and prevents deployment of insecure configurations. A suitable tool should be chosen to provide container vulnerability scanning to mitigate the risk of known vulnerabilities. + + Utilise the [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/) controller to enforce [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) and configure the [pod security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) to limit its capabilities per the principle of least privilege. + +### EGTM-022 Credentials are stored as Kubernetes Secrets + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-022|EGTM-CS-010|Container Security|High| + + **Risk**: There is a risk that the OIDC client secret (for OIDC authentication) and user password hashes (for basic authentication) get leaked due to misconfigured RBAC permissions. + + **Threat**: Unauthorised access to the application due to credential leakage. + + **Recommendation**: Ensure that only authorised users and service accounts are able to access secrets. This is especially important in namespaces where SecurityPolicy objects are configured, since those namespaces are the ones to store secrets containing the client secret (in OIDC scenarios) and user password hashes (in basic authentication scenarios). + + To do so, minimise the use of ClusterRoles and Roles allowing listing and getting secrets. Perform periodic audits of RBAC permissions. + +### EGTM-023 Weak Authentication + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-023|EGTM-EG-007|Envoy Gateway|High| + + **Risk**: There is a risk of unauthorised access due to the use of basic authentication, which does not enforce any password restriction in terms of complexity and length. In addition, password hashes are stored in SHA1 format, which is a deprecated hashing function. + + **Threat**: Unauthorised access to the application due to weak authentication mechanisms. + + **Recommendation**: It is recommended to make use of stronger authentication mechanisms (i.e. JWT authentication and OIDC authentication) instead of basic authentication. These authentication mechanisms have many advantages, such as the use of short-lived credentials and a central management of security policies through the identity provider. + +## Medium Priority Findings + +### EGTM-008 Misconfiguration of Envoy Gateway static config + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-008|EGTM-EG-003|Envoy Gateway|Medium| + + **Risk**: There is a risk of a threat actor misconfiguring static config and compromising the integrity of Envoy Gateway, ultimately leading to the compromised confidentiality, integrity, or availability of tenant data and cluster resources. + + **Threat**: Accidental or deliberate misconfiguration of static configuration leads to a misconfigured deployment of Envoy Gateway, for example logging parameters could be modified or global rate limiting configuration misconfigured. + + **Recommendation**: Implement a GitOps model, utilising Kubernetes\' Role-Based Access Control (RBAC) and adhering to the principle of least privilege to minimise human intervention on the cluster. For instance, tools like [Flux](https://fluxcd.io/) and [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) can be used for declarative GitOps deployments, ensuring all changes are tracked and reviewed. Additionally, configure your source control management (SCM) system to include mandatory pull request (PR) reviews, commit signing, and protected branches to ensure only authorised changes can be committed to the start-up configuration. + +### EGTM-010 Weak pod security contexts and policies + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-010|EGTM-CS-005|Container Security|Medium| + + **Risk**: There is a risk that a threat actor exploits a weak pod security context, compromising the CIA of a node and the resources / services which run on it. + + **Threat**: Threat Actor who has compromised a pod exploits weak security context to escape to a node, potentially leading to the compromise of Envoy Proxy or Gateway running on the same node. + + **Recommendation**: To mitigate this risk, apply [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) at a minimum of [Baseline](https://kubernetes.io/docs/concepts/security/pod-security-standards/#baseline) level to all namespaces, especially those containing Envoy Gateway and Proxy Pods. Pod security standards are implemented through K8s [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/) to provide [admission control modes](https://kubernetes.io/docs/concepts/security/pod-security-admission/#pod-security-admission-labels-for-namespaces) (enforce, audit, and warn) for namespaces. Pod security standards can be enforced by namespace labels as shown [here](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/), to enforce a baseline level of pod security to specific namespaces. + + Further enhance the security by implementing a sandboxing solution such as [gVisor](https://gvisor.dev/) for Envoy Gateway and Proxy Pods to isolate the application from the host kernel. This can be set within the runtimeClassName of the Pod specification. + +### EGTM-012 ClusterRoles and Roles with permission to deploy ReferenceGrants + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|----------------|----------------------|-----------------| +|EGTM-012|EGTM-GW-004|Gateway API|Medium| + + **Risk**: There is a risk that a threat actor could abuse excessive RBAC privileges to create ReferenceGrant resources. These resources could then be used to create cross-namespace communication, leading to unauthorised access to the application. This could compromise the confidentiality and integrity of resources and configuration in the affected namespaces and potentially disrupt the availability of services that rely on these object references. + + **Threat**: A ReferenceGrant is created, which validates traffic to cross namespace trust boundaries without a valid business reason, such as a route in one tenant\'s namespace referencing a backend in another. + + **Recommendation**: Ensure that the ability to create ReferenceGrant resources is restricted to the minimum number of people. Pay special attention to ClusterRoles that allow that action. + +### EGTM-018 Network Denial of Service (DoS) + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|----------------|----------------------|-----------------| +|EGTM-018|EGTM-GW-006|Gateway API|Medium| + + **Risk**: There is a risk that malicious requests could lead to a Denial of Service (DoS) attack, thereby reducing API gateway availability due to misconfigurations in rate-limiting or load balancing controls, or a lack of route timeout enforcement. + + **Threat**: Reduced API gateway availability due to an attacker\'s maliciously crafted request (e.g., QoD) potentially inducing a Denial of Service (DoS) attack. + + **Recommendation**: To ensure high availability and mitigate potential security threats, follow the guidelines in the Envoy Gateway documentation for configuring [local rate limit](../traffic/local-rate-limit) filters, [global rate limit](../traffic/global-rate-limit) filters, and load balancing. + + Further, adhere to best practices for configuring Envoy Proxy as an edge proxy documented [here](https://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/edge#configuring-envoy-as-an-edge-proxy) within the EnvoyProxy docs. This involves configuring TCP and HTTP proxies with specific settings, including restricting access to the admin endpoint, setting the [overload manager](https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/overload_manager/overload_manager#config-overload-manager) and [listener](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes) / [cluster](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-field-config-cluster-v3-cluster-per-connection-buffer-limit-bytes) buffer limits, enabling [use_remote_address](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address), setting [connection and stream timeouts](https://www.envoyproxy.io/docs/envoy/latest/faq/configuration/timeouts#faq-configuration-timeouts), limiting [maximum concurrent streams](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-http2protocoloptions-max-concurrent-streams), setting [initial stream window size limit](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-http2protocoloptions-initial-stream-window-size), and configuring action on [headers_with_underscores](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-headers-with-underscores-action). + + [Path normalisation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path) should be enabled to minimise path confusion vulnerabilities. These measures help protect against volumetric threats such as Denial of Service (DoS) attacks. Utilise custom resources to implement policy attachment, thereby exposing request limit configuration for route types. + +### EGTM-019 JWT-based authentication replay attacks + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-019|EGTM-DP-004|Container Security|Medium| + + **Risk**: There is a risk that replay attacks using stolen or reused JSON Web Tokens (JWTs) can compromise transmission integrity, thereby undermining the confidentiality and integrity of the data plane. + + **Threat**: Transmission integrity is compromised due to replay attacks using stolen or reused JSON Web Tokens (JWTs). + + **Recommendation**: Comply with JWT best practices for enhanced security, paying special attention to the use of short-lived tokens, which reduce the window of opportunity for a replay attack. The [exp](https://datatracker.ietf.org/doc/html/rfc7519#page-9) claim can be used to set token expiration times. + +### EGTM-024 Excessive privileges via extension policies + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-024|EGTM-EG-008|Envoy Gateway|Medium| + + **Risk**: There is a risk of developers getting more privileges than required due to the use of SecurityPolicy, ClientTrafficPolicy, EnvoyPatchPolicy and BackendTrafficPolicy. These resources can be attached to a Gateway resource. Therefore, a developer with permission to deploy them would be able to modify a Gateway configuration by targeting the gateway in the policy manifest. This conflicts with the [Advanced 4 Tier Model](https://gateway-api.sigs.k8s.io/concepts/security/#write-permissions-for-advanced-4-tier-model), where developers do not have write permissions on Gateways. + + **Threat**: Excessive developer permissions lead to a misconfiguration and/or unauthorised access. + + **Recommendation**: Considering the Tenant C scenario (represented in the Architecture Diagram), if a developer can create SecurityPolicy, ClientTrafficPolicy, EnvoyPatchPolicy or BackendTrafficPolicy objects in namespace C, they would be able to modify a Gateway configuration by attaching the policy to the gateway. In such scenarios, it is recommended to either: + + a. Create a separate namespace, where developers have no permissions, to host tenant C\'s gateway. Note that, due to design decisions, the SecurityPolicy/EnvoyPatchPolicy/ClientTrafficPolicy/BackendTrafficPolicy object can only target resources deployed in the same namespace. Therefore, having a separate namespace for the gateway would prevent developers from attaching the policy to the gateway. + + b. Forbid the creation of these policies for developers in namespace C. + + On the other hand, in scenarios similar to tenants A and B, where a shared gateway namespace is in place, this issue is more limited. Note that in this scenario, developers don\'t have access to the shared gateway namespace. + + In addition, it is important to mention that EnvoyPatchPolicy resources can also be attached to GatewayClass resources. This means that, in order to comply with the Advanced 4 Tier model, individuals with the Application Administrator role should not have access to this resource either. + +## Low Priority Findings + +### EGTM-003 Misconfiguration leads to insecure TLS settings + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|--------------|------------------------|-----------------| +|EGTM-003|EGTM-EG-001|Envoy Gateway|Low| + + **Risk**: There is a risk that a threat actor could downgrade the security of proxied connections by configuring a weak set of cipher suites, compromising the confidentiality and integrity of proxied traffic. + + **Threat**: Exploit weak cipher suite configuration to downgrade security of proxied connections. + + **Recommendation**: Users operating in highly regulated environments may need to tightly control the TLS protocol and associated cipher suites, blocking non-conforming incoming connections to the gateway. + + EnvoyProxy bootstrap config can be customised as per the [customise EnvoyProxy](../operations/customize-envoyproxy) documentation. In addition, from v.1.0.0, it is possible to configure common TLS properties for a Gateway or XRoute through the [ClientTrafficPolicy](https://gateway.envoyproxy.io/latest/api/extension_types/#clienttrafficpolicy) object. + +### EGTM-005 Envoy Gateway Helm chart deployment does not set AppArmor and Seccomp profiles + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-005|EGTM-CP-002|Container Security|Low| + + **Risk**: Threat actor who has obtained access to Envoy Gateway pod could exploit the lack of AppArmor and Seccomp profiles in the Envoy Gateway deployment to attempt a container breakout, given the presence of an exploitable vulnerability, potentially impacting the confidentiality and integrity node resources. + + **Threat**: Unauthorised syscalls and malicious code running in the Envoy Gateway pod. + + **Recommendation**: Implement [AppArmor](https://kubernetes.io/docs/tutorials/security/apparmor/) policies by setting \: \ within container.apparmor.security.beta.kubernetes.io (note, this config is set *per container*). Well-defined AppArmor policies may provide greater protection from unknown threats. + + Enforce [Seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profiles by setting the seccompProfile under securityContext. Ideally, a [fine-grained](https://kubernetes.io/docs/tutorials/security/seccomp/#create-pod-with-a-seccomp-profile-that-only-allows-necessary-syscalls) profile should be used to restrict access to only necessary syscalls, however the \--seccomp-default flag can be set to resort to [RuntimeDefault](https://kubernetes.io/docs/tutorials/security/seccomp/#create-pod-that-uses-the-container-runtime-default-seccomp-profile) which provides a container runtime specific. Example seccomp profiles can be found [here](https://kubernetes.io/docs/tutorials/security/seccomp/#download-profiles). + + To further enhance pod security, consider implementing [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) via seLinuxOptions for additional syscall attack surface reduction. Setting readOnlyRootFilesystem == true enforces an immutable root filesystem, preventing the addition of malicious binaries to the PATH and increasing the attack cost. Together, these configuration items improve the pods [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). + +### EGTM-006 Envoy Proxy pods deployed with a shell enabled + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-006|EGTM-CS-004|Container Security|Low| + + **Risk**: There is a risk that a threat actor exploits a vulnerability in Envoy Proxy to expose a reverse shell, enabling them to compromise the confidentiality, integrity and availability of tenant data via a secondary attack. + + **Threat**: If an external attacker managed to exploit a vulnerability in Envoy, the presence of a shell would be greatly helpful for the attacker in terms of potentially pivoting, escalating, or establishing some form of persistence. + + **Recommendation**: By default, Envoy uses a [distroless](https://github.com/GoogleContainerTools/distroless) image since v.0.6.0, which does not ship a shell. Therefore, ensure EnvoyProxy image is up-to-date and patched with the latest stable version. + + If using private EnvoyProxy images, use a lightweight EnvoyProxy image without a shell or debugging tool(s) which may be useful for an attacker. + + An [AuditPolicy](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#audit-policy) (audit.k8s.io/v1beta1) can be configured to record API calls made within your cluster, allowing for identification of malicious traffic and enabling incident response. Requests are recorded based on stages which delineate between the lifecycle stage of the request made (e.g., RequestReceived, ResponseStarted, & ResponseComplete). + +### EGTM-011 Route Bindings on custom labels + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-011|EGTM-GW-003|Gateway API|Low| + + **Risk**: There is a risk that a gateway owner (or someone with the ability to set namespace labels) maliciously or accidentally binds routes across namespace boundaries, potentially compromising the confidentiality and integrity of traffic in a multitenant scenario. + + **Threat**: If a Route Binding within a Gateway Listener is configured based on a custom label, it could allow a malicious internal actor with the ability to label namespaces to change the set of namespaces supported by the Gateway. + + **Recommendation**: Consider the use of custom admission control to restrict what labels can be set on namespaces through tooling such as [Kubewarden](https://kyverno.io/policies/pod-security/), [Kyverno](https://github.com/kubewarden), and [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper). Route binding should follow the Kubernetes Gateway API security model, as shown [here](https://gateway-api.sigs.k8s.io/concepts/security/#1-route-binding), to connect gateways in different namespaces. + +### EGTM-013 GatewayClass namespace validation is not configured + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-013|EGTM-GW-005|Gateway API|Low| + + **Risk**: There is a risk that an unauthorised actor deploys an unauthorised GatewayClass due to GatewayClass namespace validation not being configured, leading to non-compliance with business and security requirements. + + **Threat**: Unauthorised deployment of Gateway resource via GatewayClass template which crosses namespace trust boundaries. + + **Recommendation**: Leverage GatewayClass namespace validation to limit the namespaces where GatewayClasses can be run through a tool such as [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper). Reference pull request \#[24](https://github.com/open-policy-agent/gatekeeper-library/pull/24) within gatekeeper-library which outlines how to add GatewayClass namespace validation through a GatewayClassNamespaces API resource kind within the constraints.gatekeeper.sh/v1beta1 apiGroup. + +### EGTM-015 ServiceAccount token authentication + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-015|EGTM-CS-007|Container Security|Low| + + **Risk**: There is a risk that threat actors could exploit ServiceAccount tokens for illegitimate authentication, thereby leading to privilege escalation and the undermining of gateway API resources\' integrity, confidentiality, and availability. + + **Threat**: The threat arises from threat actors impersonating the envoy-gateway ServiceAccount through the replay of ServiceAccount tokens, thereby achieving escalated privileges and gaining unauthorised access to Kubernetes resources. + + **Recommendation**: Limit the creation of ServiceAccounts to only when necessary, specifically refraining from using default service account tokens, especially for high-privilege service accounts. For legacy clusters running Kubernetes version 1.21 or earlier, note that ServiceAccount tokens are long-lived by default. To disable the automatic mounting of the service account token, set automountServiceAccountToken: false in the PodSpec. + +### EGTM-016 Misconfiguration leads to lack of Envoy Proxy access activity visibility + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-016|EGTM-EG-004|Envoy Gateway|Low| + + **Risk**: There is a risk that threat actors establish persistence and move laterally through the cluster unnoticed due to limited visibility into access and application-level activity. + + **Threat**: Threat actors establish persistence and move laterally through the cluster unnoticed. + + **Recommendation**: Configure [access logging](/community/design/proxy-accesslog) in the EnvoyProxy. Use [ProxyAccessLogFormatType](../../api/extension_types#proxyaccesslogformattype) (Text or JSON) to specify the log format and ensure that the logs are sent to the desired sink types by setting the [ProxyAccessLogSinkType](https://gateway.envoyproxy.io/latest/api/extension_types/#proxyaccesslogsinktype). Make use of [FileEnvoyProxyAccessLog](https://gateway.envoyproxy.io/latest/api/extension_types/#fileenvoyproxyaccesslog) or [OpenTelemetryEnvoyProxyAccessLog](https://gateway.envoyproxy.io/latest/api/extension_types/#opentelemetryenvoyproxyaccesslog) to configure File and OpenTelemetry sinks, respectively. If the settings aren\'t defined, the default format is sent to stdout. + + Additionally, consider leveraging a central logging mechanism such as [Fluentd](https://github.com/fluent/fluentd) to enhance visibility into access activity and enable effective incident response (IR). + +### EGTM-017 Misconfiguration leads to lack of Envoy Gateway activity visibility + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-017|EGTM-EG-005|Envoy Gateway|Low| + + **Risk**: There is a risk that an insider misconfigures an envoy gateway component and goes unnoticed due to a low-touch logging configuration (via default) which responsible stakeholders are not aptly aware of or have immediate access to. + + **Threat**: The threat emerges from an insider misconfiguring an Envoy Gateway component without detection. + + **Recommendation**: Configure the logging level of the Envoy Gateway using the \'level\' field in [EnvoyGatewayLogging](https://gateway.envoyproxy.io/latest/api/extension_types/#envoygatewaylogging). Ensure the appropriate logging levels are set for relevant components such as \'gateway-api\', \'xds-translator\', or \'global-ratelimit\'. If left unspecified, the logging level defaults to \"info\", which may not provide sufficient detail for security monitoring. + + Employ a centralised logging mechanism, like [Fluentd](https://github.com/fluent/fluentd), to enhance visibility into application-level activity and to enable efficient incident response. + +### EGTM-021 Exposed Envoy Proxy admin interface + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|---------------|-----------------------|-----------------| +|EGTM-021|EGTM-EG-006|Envoy Gateway|Low| + + **Risk**: There is a risk that the admin interface is exposed without valid business reason, increasing the attack surface. + + **Threat**: Exposed admin interfaces give internal attackers the option to affect production traffic in unauthorised ways, and the option to exploit any vulnerabilities which may be present in the admin interface (e.g. by orchestrating malicious GET requests to the admin interface through CSRF, compromising Envoy Proxy global configuration or shutting off the service entirely e.g. /quitquitquit). + + **Recommendation**: The Envoy Proxy admin interface is only exposed to localhost, meaning that it is secure by default. However, due to the risk of misconfiguration, this recommendation is included. + + Due to the importance of the admin interface, it is recommended to ensure that Envoy Proxies have not been accidentally misconfigured to expose the admin interface to untrusted networks. + +### EGTM-025 Envoy Proxy pods deployed running as root user in the container + +|**ID**|**UID**|**Category**|**Priority**| +|--------------|--------------|------------------------|-----------------| +|EGTM-025|EGTM-CS-011|Container Security|Low| + +**Risk**: The presence of a vulnerability, be it in the kernel or another system component, when coupled with containers running as root, could enable a threat actor to escape the container, thereby compromising the confidentiality, integrity, or availability of cluster resources + + **Threat**: The Envoy Proxy container's root-user configuration can be leveraged by an attacker to escalate privileges, execute a container breakout, and traverse across trust boundaries. + + **Recommendation**: By default, Envoy Gateway deployments do not use root users. Nonetheless, in case a custom image or deployment manifest is to be used, make sure Envoy Proxy pods run as a non-root user with a high UID within the container. + +Set runAsUser and runAsGroup security context options to specific UIDs (e.g., runAsUser: 1000 & runAsGroup: 3000) to ensure the container operates with the stipulated non-root user and group ID. If using helm chart deployment, define the user and group ID in the values.yaml file or via the command line during helm install / upgrade. + +## Appendix + +### In Scope Threat Actor Details + +|Threat Actor | Capability | Personal Motivation | Envoy Gateway Attack Samples| +|-|-|-|-| +|Application Developer | Leverage internal knowledge and personal access to the Envoy Gateway infrastructure to move laterally and transit trust boundaries | Disgruntled / personal grievances.

Financial incentives | Misconfigure XRoute resources to expose internal applications.

Misconfigure SecurityPolicy objects, reducing the security posture of an application.| +|Application Administrator | Abuse privileged status to disrupt operations and tenant cluster services through Envoy Gateway misconfig | Disgruntled / personal grievances.

Financial incentives | Create malicious routes to internal applications.

Introduce malicious Envoy Proxy images.

Expose the Envoy Proxy Admin interface.| +|Cluster Operator | Alter application-level deployments by misconfiguring resource dependencies & SCM to introduce vulnerabilities | Disgruntled / personal grievances.

Financial incentives.

Notoriety | Deploy malicious resources to expose internal applications.

Access authentication secrets.

Fall victim to phishing attacks and inadvertently share authentication credentials to cloud infrastructure or Kubernetes clusters.| +|Vandal: Script Kiddie, Trespasser | Uses publicly available tools and applications (Nmap,Metasploit, CVE PoCs) | Curiosity.

Personal fame through defacement / denial of service of prominent public facing web resources | Small scale DOS.

Launches prepackaged exploits, runs crypto mining tools.

Exploit public-facing application services such as the bastion host to gain an initial foothold in the environment| +|Motivated individual: Political activist, Thief, Terrorist | Write tools and exploits required for their means if sufficiently motivated.

Tend to use these in a targeted fashion against specific organisations. May combine publicly available exploits in a targeted fashion. Tamper with open source supply chains | Personal Gain (Political or Ideological) | Phishing, DDOS, exploit known vulnerabilities.

Compromise third-party components such as Helm charts and container images to inject malicious codes to propagate access throughout the environment.| +|Organised crime: syndicates, state-affiliated groups | Write tools and exploits required for their means.

Tend to use these in a non-targeted fashion, unless motivation is sufficiently high.

Devotes considerable resources, writes exploits, can bribe/coerce, can launch targeted attacks | Ransom.

Mass extraction of PII / credentials / PCI data.

Financial incentives | Social Engineering, phishing, ransomware, coordinated attacks.

Intercept and replay JWT tokens (via MiTM) between tenant user(s) and envoy gateway to modify app configs in-transit| + +### Identified Threats by Priority + +|ID|UID|Category|Risk|Threat|Priority| Recommendation | +|-|-|-|-|-|-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|EGTM-001|EGTM-GW-001|Gateway API| Self-signed certificates (which do not comply with PKI best practices) could lead to unauthorised access to the private key associated with the certificate used for inbound TLS termination at Envoy Proxy, compromising the confidentiality and integrity of proxied traffic.

| Compromise of the private key associated with the certificate used for inbound TLS terminating at Envoy Proxy.

|High| The Envoy Gateway quickstart demonstrates how to set up a Secure Gateway using an example where a self-signed root certificate is created using openssl. As stated in the Envoy Gateway documentation, this is not a suitable configuration for Production usage. It is recommended that PKI best practices are followed, whereby certificates are signed by an Intermediary CA which sits underneath an organisational \'offline\' Root CA.

PKI best practices should also apply to the management of client certificates when using mTLS. The Envoy Gateway [mTLS](../security/mutual-tls) task shows how to set up client certificates using self-signed certificates. In the same way as gateway certificates and, as mentioned in the documentation, this configuration should not be used in production environments. | +|EGTM-002|EGTM-CS-001|Container Security| There is a risk that a threat actor could compromise the Kubernetes secret containing the Envoy private key, allowing the attacker to decrypt Envoy Proxy traffic, compromising the confidentiality of proxied traffic.

| Kubernetes secret containing the Envoy private key is compromised and used to decrypt proxied traffic.

|High| Certificate management best practices mandate short-lived key material where practical, meaning that a mechanism for rotation of private keys and certificates is required, along with a way for certificates to be mounted into Envoy containers. If Kubernetes secrets are used, when a certificate expires, the associated secret must be updated, and Envoy containers must be redeployed. Instead of a manual configuration, it is recommended that [cert-manager](https://github.com/cert-manager/cert-manager) is used. | +|EGTM-004|EGTM-K8-002|Container Security| There is a risk that a threat actor could abuse misconfigured RBAC to access the Envoy Gateway ClusterRole (envoy-gateway-role) and use it to expose all secrets across the cluster, thus compromising the confidentiality and integrity of tenant data.

| Compromised Envoy Gateway or misconfigured ClusterRoleBinding (envoy-gateway-rolebinding) to Envoy Gateway ClusterRole (envoy-gateway-role), provides access to resources and secrets in different namespaces.

|High| Users should be aware that Envoy Gateway uses a ClusterRole (envoy-gateway-role) when deployed via the Helm chart, to allow management of Envoy Proxies across different namespaces. This ClusterRole is powerful and includes the ability to read secrets in namespaces which may not be within the purview of Envoy Gateway.

Kubernetes best-practices involve restriction of ClusterRoleBindings, with the use of RoleBindings where possible to limit access per namespace by specifying the namespace in metadata. Namespace isolation reduces the impact of compromise from cluster-scoped roles. Ideally, fine-grained K8s roles should be created per the principle of least privilege to ensure they have the minimum access necessary for role functions.

The pull request \#[1656](https://github.com/envoyproxy/gateway/pull/1656) introduced the use of Roles and RoleBindings in [namespaced mode](https://gateway.envoyproxy.io/latest/api/extension_types/#kuberneteswatchmode). This feature can be leveraged to reduce the amount of permissions required by the Envoy Gateway. | +|EGTM-007|EGTM-EG-002|Envoy Gateway| There is a risk that a threat actor could exploit misconfigured Kubernetes RBAC to create or modify Gateway API resources with no business need, potentially leading to the compromise of the confidentiality, integrity, and availability of resources and traffic within the cluster.

| Unauthorised creation or misconfiguration of Gateway API resources by a threat actor with cluster-scoped access.

|High| Configure the apiGroup and resource fields in RBAC policies to restrict access to [Gateway](https://gateway-api.sigs.k8s.io/) and [GatewayClass](https://gateway-api.sigs.k8s.io/api-types/gatewayclass/) resources. Enable namespace isolation by using the namespace field, preventing unauthorised access to gateways in other namespaces. | +|EGTM-009|EGTM-GW-002|Gateway API| There is a risk that a co-tenant misconfigures Gateway or Route resources, compromising the confidentiality, integrity, and availability of routed traffic through Envoy Gateway.

| Malicious or accidental co-tenant misconfiguration of Gateways and Routes associated with other application teams.

|High| Dedicated Envoy Gateways should be provided to each tenant within their respective namespace. A one-to-one relationship should be established between GatewayClass and Gateway resources, meaning that each tenant namespace should have their own GatewayClass watched by a unique Envoy Gateway Controller as defined here in the [Deployment Mode](../operations/deployment-mode) documentation.

Application Admins should have write permissions on the Gateway resource, but only in their specific namespaces, and Application Developers should only hold write permissions on Route resources. To enact this access control schema, follow the [Write Permissions for Advanced 4 Tier Model](https://gateway-api.sigs.k8s.io/concepts/security/#write-permissions-for-advanced-4-tier-model) described in the Kubernetes Gateway API security model. Examples of secured gateway-route topologies can be found [here](https://gateway-api.sigs.k8s.io/concepts/api-overview/#attaching-routes-to-gateways) within the Kubernetes Gateway API docs.

Optionally, consider a GitOps model, where only the GitOps operator has the permission to deploy or modify custom resources in production. | +|EGTM-014|EGTM-CS-006|Container Security| There is a risk that a supply chain attack on Envoy Gateway results in an arbitrary compromise of the confidentiality, integrity or availability of tenant data.

| Supply chain threat actor introduces malicious code into Envoy Gateway or Proxy.

|High| The Envoy Gateway project should continue to work towards conformance with supply-chain security best practices throughout the project lifecycle (for example, as set out in the [CNCF Software Supply Chain Best Practices Whitepaper](https://github.com/cncf/tag-security/blob/main/supply-chain-security/supply-chain-security-paper/CNCF_SSCP_v1.pdf). Adherence to [Supply-chain Levels for Software Artefacts](https://slsa.dev/) (SLSA) standards is crucial for maintaining the security of the system. Employ version control systems to monitor the source and build platforms and assign responsibility to a specific stakeholder.

Integrate a supply chain security tool such as Sigstore, which provides native capabilities for signing and verifying container images and software artefacts. [Software Bill of Materials](https://www.cisa.gov/sbom) (SBOM), [Vulnerability Exploitability eXchange](https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf) (VEX), and signed artefacts should also be incorporated into the security protocol. | +|EGTM-020|EGTM-CS-009|Container Security| There is a risk that a threat actor exploits an Envoy Proxy vulnerability to remote code execution (RCE) due to out of date or misconfigured Envoy Proxy pod deployment, compromising the confidentiality and integrity of Envoy Proxy along with the availability of the proxy service.

| Deployment of an Envoy Proxy or Gateway image containing exploitable CVEs.

|High| Always use the latest version of the Envoy Proxy image. Regularly check for updates and patch the system as soon as updates become available. Implement a CI/CD pipeline that includes security checks for images and prevents deployment of insecure configurations. A tool such as Snyk can be used to provide container vulnerability scanning to mitigate the risk of known vulnerabilities.

Utilise the [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/) controller to enforce [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) and configure the [pod security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) to limit its capabilities per the principle of least privilege. | +|EGTM-022|EGTM-CS-010|Container Security| There is a risk that the OIDC client secret (for OIDC authentication) and user password hashes (for basic authentication) get leaked due to misconfigured RBAC permissions.

| Unauthorised access to the application due to credential leakage.

|High| Ensure that only authorised users and service accounts are able to access secrets. This is especially important in namespaces where SecurityPolicy objects are configured, since those namespaces are the ones to store secrets containing the client secret (in OIDC scenarios) and user password hashes (in basic authentication scenarios).

To do so, minimise the use of ClusterRoles and Roles allowing listing and getting secrets. Perform periodic audits of RBAC permissions. | +|EGTM-023|EGTM-EG-007|Envoy Gateway| There is a risk of unauthorised access due to the use of basic authentication, which does not enforce any password restriction in terms of complexity and length. In addition, password hashes are stored in SHA1 format, which is a deprecated hashing function.

| Unauthorised access to the application due to weak authentication mechanisms.

|High| It is recommended to make use of stronger authentication mechanisms (i.e. JWT authentication and OIDC authentication) instead of basic authentication. These authentication mechanisms have many advantages, such as the use of short-lived credentials and a central management of security policies through the identity provider. | +|EGTM-008|EGTM-EG-003|Envoy Gateway| There is a risk of a threat actor misconfiguring static config and compromising the integrity of Envoy Gateway, ultimately leading to the compromised confidentiality, integrity, or availability of tenant data and cluster resources.

| Accidental or deliberate misconfiguration of static configuration leads to a misconfigured deployment of Envoy Gateway, for example logging parameters could be modified or global rate limiting configuration misconfigured.

|Medium| Implement a GitOps model, utilising Kubernetes\' Role-Based Access Control (RBAC) and adhering to the principle of least privilege to minimise human intervention on the cluster. For instance, tools like [Flux](https://fluxcd.io/) and [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) can be used for declarative GitOps deployments, ensuring all changes are tracked and reviewed. Additionally, configure your source control management (SCM) system to include mandatory pull request (PR) reviews, commit signing, and protected branches to ensure only authorised changes can be committed to the start-up configuration. | +|EGTM-010|EGTM-CS-005|Container Security| There is a risk that a threat actor exploits a weak pod security context, compromising the CIA of a node and the resources / services which run on it.

| Threat Actor who has compromised a pod exploits weak security context to escape to a node, potentially leading to the compromise of Envoy Proxy or Gateway running on the same node.

|Medium| To mitigate this risk, apply [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) at a minimum of [Baseline](https://kubernetes.io/docs/concepts/security/pod-security-standards/#baseline) level to all namespaces, especially those containing Envoy Gateway and Proxy Pods. Pod security standards are implemented through K8s [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/) to provide [admission control modes](https://kubernetes.io/docs/concepts/security/pod-security-admission/#pod-security-admission-labels-for-namespaces) (enforce, audit, and warn) for namespaces. Pod security standards can be enforced by namespace labels as shown [here](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/), to enforce a baseline level of pod security to specific namespaces.

Further enhance the security by implementing a sandboxing solution such as [gVisor](https://gvisor.dev/) for Envoy Gateway and Proxy Pods to isolate the application from the host kernel. This can be set within the runtimeClassName of the Pod specification. | +|EGTM-012|EGTM-GW-004|Gateway API| There is a risk that a threat actor could abuse excessive RBAC privileges to create ReferenceGrant resources. These resources could then be used to create cross-namespace communication, leading to unauthorised access to the application. This could compromise the confidentiality and integrity of resources and configuration in the affected namespaces and potentially disrupt the availability of services that rely on these object references.

| A ReferenceGrant is created, which validates traffic to cross namespace trust boundaries without a valid business reason, such as a route in one tenant\'s namespace referencing a backend in another.

|Medium| Ensure that the ability to create ReferenceGrant resources is restricted to the minimum number of people. Pay special attention to ClusterRoles that allow that action. | +|EGTM-018|EGTM-GW-006|Gateway API| There is a risk that malicious requests could lead to a Denial of Service (DoS) attack, thereby reducing API gateway availability due to misconfigurations in rate-limiting or load balancing controls, or a lack of route timeout enforcement.

| Reduced API gateway availability due to an attacker\'s maliciously crafted request (e.g., QoD) potentially inducing a Denial of Service (DoS) attack.

|Medium| To ensure high availability and to mitigate potential security threats, adhere to the Envoy Gateway documentation for the configuration of a [rate-limiting](../traffic/global-rate-limit) filter and load balancing.

Further, adhere to best practices for configuring Envoy Proxy as an edge proxy documented [here](https://www.envoyproxy.io/docs/envoy/latest/configuration/best_practices/edge#configuring-envoy-as-an-edge-proxy) within the EnvoyProxy docs. This involves configuring TCP and HTTP proxies with specific settings, including restricting access to the admin endpoint, setting the [overload manager](https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/overload_manager/overload_manager#config-overload-manager) and [listener](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#envoy-v3-api-field-config-listener-v3-listener-per-connection-buffer-limit-bytes) / [cluster](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-field-config-cluster-v3-cluster-per-connection-buffer-limit-bytes) buffer limits, enabling [use_remote_address](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-use-remote-address), setting [connection and stream timeouts](https://www.envoyproxy.io/docs/envoy/latest/faq/configuration/timeouts#faq-configuration-timeouts), limiting [maximum concurrent streams](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-http2protocoloptions-max-concurrent-streams), setting [initial stream window size limit](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-http2protocoloptions-initial-stream-window-size), and configuring action on [headers_with_underscores](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-headers-with-underscores-action).

[Path normalisation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-normalize-path) should be enabled to minimise path confusion vulnerabilities. These measures help protect against volumetric threats such as Denial of Service (DoS)nattacks. Utilise custom resources to implement policy attachment, thereby exposing request limit configuration for route types. | +|EGTM-019|EGTM-DP-004|Container Security| There is a risk that replay attacks using stolen or reused JSON Web Tokens (JWTs) can compromise transmission integrity, thereby undermining the confidentiality and integrity of the data plane.

| Transmission integrity is compromised due to replay attacks using stolen or reused JSON Web Tokens (JWTs).

|Medium| Comply with JWT best practices for enhanced security, paying special attention to the use of short-lived tokens, which reduce the window of opportunity for a replay attack. The [exp](https://datatracker.ietf.org/doc/html/rfc7519#page-9) claim can be used to set token expiration times. | +|EGTM-024|EGTM-EG-008|Envoy Gateway| There is a risk of developers getting more privileges than required due to the use of SecurityPolicy, ClientTrafficPolicy, EnvoyPatchPolicy and BackendTrafficPolicy. These resources can be attached to a Gateway resource. Therefore, a developer with permission to deploy them would be able to modify a Gateway configuration by targeting the gateway in the policy manifest. This conflicts with the [Advanced 4 Tier Model](https://gateway-api.sigs.k8s.io/concepts/security/#write-permissions-for-advanced-4-tier-model), where developers do not have write permissions on Gateways.

| Excessive developer permissions lead to a misconfiguration and/or unauthorised access.

|Medium| Considering the Tenant C scenario (represented in the Architecture Diagram), if a developer can create SecurityPolicy, ClientTrafficPolicy, EnvoyPatchPolicy or BackendTrafficPolicy objects in namespace C, they would be able to modify a Gateway configuration by attaching the policy to the gateway. In such scenarios, it is recommended to either:

a. Create a separate namespace, where developers have no permissions, > to host tenant C\'s gateway. Note that, due to design decisions, > the > SecurityPolicy/EnvoyPatchPolicy/ClientTrafficPolicy/BackendTrafficPolicy > object can only target resources deployed in the same namespace. > Therefore, having a separate namespace for the gateway would > prevent developers from attaching the policy to the gateway.

b. Forbid the creation of these policies for developers in namespace C.

On the other hand, in scenarios similar to tenants A and B, where a shared gateway namespace is in place, this issue is more limited. Note that in this scenario, developers don\'t have access to the shared gateway namespace.

In addition, it is important to mention that EnvoyPatchPolicy resources can also be attached to GatewayClass resources. This means that, in order to comply with the Advanced 4 Tier model, individuals with the Application Administrator role should not have access to this resource either. | +|EGTM-003|EGTM-EG-001|Envoy Gateway| There is a risk that a threat actor could downgrade the security of proxied connections by configuring a weak set of cipher suites, compromising the confidentiality and integrity of proxied traffic.

| Exploit weak cipher suite configuration to downgrade security of proxied connections.

|Low| Users operating in highly regulated environments may need to tightly control the TLS protocol and associated cipher suites, blocking non-conforming incoming connections to the gateway.

EnvoyProxy bootstrap config can be customised as per the [customise EnvoyProxy](../operations/customize-envoyproxy) documentation. In addition, from v.1.0.0, it is possible to configure common TLS properties for a Gateway or XRoute through the [ClientTrafficPolicy](https://gateway.envoyproxy.io/latest/api/extension_types/#clienttrafficpolicy) object. | +|EGTM-005|EGTM-CP-002|Container Security| Threat actor who has obtained access to Envoy Gateway pod could exploit the lack of AppArmor and Seccomp profiles in the Envoy Gateway deployment to attempt a container breakout, given the presence of an exploitable vulnerability, potentially impacting the confidentiality and integrity of namespace resources.

| Unauthorised syscalls and malicious code running in the Envoy Gateway pod.

|Low| Implement [AppArmor](https://kubernetes.io/docs/tutorials/security/apparmor/) policies by setting \: \ within container.apparmor.security.beta.kubernetes.io (note, this config is set *per container*). Well-defined AppArmor policies may provide greater protection from unknown threats.

Enforce [Seccomp](https://kubernetes.io/docs/tutorials/security/seccomp/) profiles by setting the seccompProfile under securityContext. Ideally, a [fine-grained](https://kubernetes.io/docs/tutorials/security/seccomp/#create-pod-with-a-seccomp-profile-that-only-allows-necessary-syscalls) profile should be used to restrict access to only necessary syscalls, however the \--seccomp-default flag can be set to resort to [RuntimeDefault](https://kubernetes.io/docs/tutorials/security/seccomp/#create-pod-that-uses-the-container-runtime-default-seccomp-profile) which provides a container runtime specific. Example seccomp profiles can be found [here](https://kubernetes.io/docs/tutorials/security/seccomp/#download-profiles).

To further enhance pod security, consider implementing [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) via seLinuxOptions for additional syscall attack surface reduction. Setting readOnlyRootFilesystem == true enforces an immutable root filesystem, preventing the addition of malicious binaries to the PATH and increasing the attack cost. Together, these configuration items improve the pods [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). | +|EGTM-006|EGTM-CS-004|Container Security| There is a risk that a threat actor exploits a vulnerability in Envoy Proxy to expose a reverse shell, enabling them to compromise the confidentiality, integrity and availability of tenant data via a secondary attack.

| If an external attacker managed to exploit a vulnerability in Envoy, the presence of a shell would be greatly helpful for the attacker in terms of potentially pivoting, escalating, or establishing some form of persistence.

|Low| By default, Envoy uses a [distroless](https://github.com/GoogleContainerTools/distroless) image since v.0.6.0, which does not ship a shell. Therefore, ensure EnvoyProxy image is up-to-date and patched with the latest stable version.

If using private EnvoyProxy images, use a lightweight EnvoyProxy image without a shell or debugging tool(s) which may be useful for an attacker.

An [AuditPolicy](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#audit-policy) (audit.k8s.io/v1beta1) can be configured to record API calls made within your cluster, allowing for identification of malicious traffic and enabling incident response. Requests are recorded based on stages which delineate between the lifecycle stage of the request made (e.g., RequestReceived, ResponseStarted, & ResponseComplete). | +|EGTM-011|EGTM-GW-003|Gateway API| There is a risk that a gateway owner (or someone with the ability to set namespace labels) maliciously or accidentally binds routes across namespace boundaries, potentially compromising the confidentiality and integrity of traffic in a multitenant scenario.

| If a Route Binding within a Gateway Listener is configured based on a custom label, it could allow a malicious internal actor with the ability to label namespaces to change the set of namespaces supported by the Gateway

|Low| Consider the use of custom admission control to restrict what labels can be set on namespaces through tooling such as [Kubewarden](https://kyverno.io/policies/pod-security/), [Kyverno](https://github.com/kubewarden), and [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper). Route binding should follow the Kubernetes Gateway API security model, as shown [here](https://gateway-api.sigs.k8s.io/concepts/security/#1-route-binding), to connect gateways in different namespaces. | +|EGTM-013|EGTM-GW-005|Gateway API| There is a risk that an unauthorised actor deploys an unauthorised GatewayClass due to GatewayClass namespace validation not being configured, leading to non-compliance with business and security requirements.

| Unauthorised deployment of Gateway resource via GatewayClass template which crosses namespace trust boundaries.

|Low| Leverage GatewayClass namespace validation to limit the namespaces where GatewayClasses can be run through a tool such as using [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper). Reference pull request \#[24](https://github.com/open-policy-agent/gatekeeper-library/pull/24) within gatekeeper-library which outlines how to add GatewayClass namespace validation through a GatewayClassNamespaces API resource kind within the constraints.gatekeeper.sh/v1beta1 apiGroup. | +|EGTM-015|EGTM-CS-007|Container Security| There is a risk that threat actors could exploit ServiceAccount tokens for illegitimate authentication, thereby leading to privilege escalation and the undermining of gateway API resources\' integrity, confidentiality, and availability.

| The threat arises from threat actors impersonating the envoy-gateway ServiceAccount through the replay of ServiceAccount tokens, thereby achieving escalated privileges and gaining unauthorised access to Kubernetes resources.

|Low| Limit the creation of ServiceAccounts to only when necessary, specifically refraining from using default service account tokens, especially for high-privilege service accounts. For legacy clusters running Kubernetes version 1.21 or earlier, note that ServiceAccount tokens are long-lived by default. To disable the automatic mounting of the service account token, set automountServiceAccountToken: false in the PodSpec. | +|EGTM-016|EGTM-EG-004|Envoy Gateway| There is a risk that threat actors establish persistence and move laterally through the cluster unnoticed due to limited visibility into access and application-level activity.

| Threat actors establish persistence and move laterally through the cluster unnoticed.

|Low| Configure [access logging](/community/design/proxy-accesslog) in the EnvoyProxy. Use [ProxyAccessLogFormatType](../../api/extension_types#proxyaccesslogformattype) (Text or JSON) to specify the log format and ensure that the logs are sent to the desired sink types by setting the [ProxyAccessLogSinkType](https://gateway.envoyproxy.io/latest/api/extension_types/#proxyaccesslogsinktype). Make use of [FileEnvoyProxyAccessLog](https://gateway.envoyproxy.io/latest/api/extension_types/#fileenvoyproxyaccesslog) or [OpenTelemetryEnvoyProxyAccessLog](https://gateway.envoyproxy.io/latest/api/extension_types/#opentelemetryenvoyproxyaccesslog) to configure File and OpenTelemetry sinks, respectively. If the settings aren\'t defined, the default format is sent to stdout.

Additionally, consider leveraging a central logging mechanism such as [Fluentd](https://github.com/fluent/fluentd) to enhance visibility into access activity and enable effective incident response (IR). | +|EGTM-017|EGTM-EG-005|Envoy Gateway| There is a risk that an insider misconfigures an envoy gateway component and goes unnoticed due to a low-touch logging configuration (via default) which responsible stakeholders are not aptly aware of or have immediate access to.

| The threat emerges from an insider misconfiguring an Envoy Gateway component without detection.

|Low| Configure the logging level of the Envoy Gateway using the \'level\' field in [EnvoyGatewayLogging](https://gateway.envoyproxy.io/latest/api/extension_types/#envoygatewaylogging). Ensure the appropriate logging levels are set for relevant components such as \'gateway-api\', \'xds-translator\', or \'global-ratelimit\'. If left unspecified, the logging level defaults to \"info\", which may not provide sufficient detail for security monitoring.

Employ a centralised logging mechanism, like [Fluentd](https://github.com/fluent/fluentd), to enhance visibility into application-level activity and to enable efficient incident response. | +|EGTM-021|EGTM-EG-006|Envoy Gateway| There is a risk that the admin interface is exposed without valid business reason, increasing the attack surface.

| Exposed admin interfaces give internal attackers the option to affect production traffic in unauthorised ways, and the option to exploit any vulnerabilities which may be present in the admin interface (e.g. by orchestrating malicious GET requests to the admin interface through CSRF, compromising Envoy Proxy global configuration or shutting off the service entirely (e.g., /quitquitquit).

|Low| The Envoy Proxy admin interface is only exposed to localhost, meaning that it is secure by default. However, due to the risk of misconfiguration, this recommendation is included.

Due to the importance of the admin interface, it is recommended to ensure that Envoy Proxies have not been accidentally misconfigured to expose the admin interface to untrusted networks. | +|EGTM-025 | EGTM-CS-011 | Container Security | The presence of a vulnerability, be it in the kernel or another system component, when coupled with containers running as root, could enable a threat actor to escape the container, thereby compromising the confidentiality, integrity, or availability of cluster resources. | The Envoy Proxy container's root-user configuration can be leveraged by an attacker to escalate privileges, execute a container breakout, and traverse across trust boundaries. | Low | By default, Envoy Gateway deployments do not use root users. Nonetheless, in case a custom image or deployment manifest is to be used, make sure Envoy Proxy pods run as a non-root user with a high UID within the container. Set runAsUser and runAsGroup security context options to specific UIDs (e.g., runAsUser: 1000 & runAsGroup: 3000) to ensure the container operates with the stipulated non-root user and group ID. If using helm chart deployment, define the user and group ID in the values.yaml file or via the command line during helm install / upgrade. | + + +## Attack Trees + +Attack trees offer a methodical way of describing the security of systems, based on varying attack patterns. It's important to approach the review of attack trees from a top-down perspective. The top node, also known as the root node, symbolises the attacker's primary objective. This goal is then broken down into subsidiary aims, each reflecting a different strategy to attain the root objective. This deconstruction persists until reaching the lowest level objectives or 'leaf nodes', which depict attacks that can be directly launched. + +It is essential to note that attack trees presented here are speculative paths for potential exploitation. The Envoy Gateway project is in a continuous development cycle, and as the project evolves, new vulnerabilities may be exposed, or additional controls could be introduced. Therefore, the threats illustrated in the attack trees should be perceived as point-in-time reflections of the project’s current state at the time of writing this threat model. + +### Node ID Schema + +Each node in the attack tree is assigned a unique identifier following the AT#-## schema. This allows easy reference to specific nodes in the attack trees throughout the threat model. The first part of the ID (AT#) signifies the attack tree number, while the second part (##) represents the node number within that tree. + +### Logical Operators + +Logical AND/OR operators are used to represent the relationship between parent and child nodes. An AND operator means that all child nodes must be achieved to satisfy the parent node. An OR operator between a parent node and its child nodes means that any of the child nodes can be achieved to satisfy the parent node. + +### Attack Tree Node Legend + +![AT Legend](/img/AT-legend.png) + +### AT0 + +![AT0](/img/AT0.png) + +### AT1 + +![AT1](/img/AT1.png) + +### AT2 + +![AT2](/img/AT2.png) + +### AT3 + +![AT3](/img/AT3.png) + +### AT4 + +![AT4](/img/AT4.png) + +### AT5 + +![AT5](/img/AT5.png) + +### AT6 + +![AT6](/img/AT6.png) diff --git a/site/content/en/v1.8/tasks/security/tls-cert-manager.md b/site/content/en/v1.8/tasks/security/tls-cert-manager.md new file mode 100644 index 0000000000..b0d80c58a6 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/tls-cert-manager.md @@ -0,0 +1,444 @@ +--- +title: "Using cert-manager For TLS Termination" +--- + +This task shows how to set up [cert-manager](https://cert-manager.io/) to automatically create certificates and secrets for use by Envoy Gateway. +It will first show how to enable the self-sign issuer, which is useful to test that cert-manager and Envoy Gateway can talk to each other. +Then it shows how to use [Let's Encrypt's staging environment](https://letsencrypt.org/docs/staging-environment/). +Changing to the Let's Encrypt production environment is straight-forward after that. + +## Prerequisites + +* A Kubernetes cluster and a configured `kubectl`. +* The `helm` command. +* The `curl` command or similar for testing HTTPS requests. +* For the ACME HTTP-01 challenge to work + * your Gateway must be reachable on the public Internet. + * the domain name you use (we use `www.example.com`) must point to the Gateway's external IP(s). + +## Installation + +{{< boilerplate prerequisites >}} + +## Deploying cert-manager + +*This is a summary of [cert-manager Installation with Helm](https://cert-manager.io/docs/installation/helm/).* + +Installing cert-manager is straight-forward and you can follow the below approach to install cert-manager in your cluster. Gateway API CRDs should either be installed before cert-manager starts or the cert-manager Deployment should be restarted after installing the Gateway API CRDs. Remember to enable the Gateway API support. You can refer this [page](https://cert-manager.io/docs/usage/gateway/) for more details. + +```console +$ helm repo add jetstack https://charts.jetstack.io +$ helm install \ + cert-manager jetstack/cert-manager \ + --version v1.17.0 \ + --create-namespace --namespace cert-manager \ + --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ + --set config.kind="ControllerConfiguration" \ + --set config.enableGatewayAPI=true +``` + +You should now have `cert-manager` running with nothing to do: + +```console +$ kubectl wait --for=condition=Available deployment -n cert-manager --all +deployment.apps/cert-manager condition met +deployment.apps/cert-manager-cainjector condition met +deployment.apps/cert-manager-webhook condition met + +$ kubectl get -n cert-manager deployment +NAME READY UP-TO-DATE AVAILABLE AGE +cert-manager 1/1 1 1 42m +cert-manager-cainjector 1/1 1 1 42m +cert-manager-webhook 1/1 1 1 42m +``` + +## A Self-Signing Issuer + +cert-manager can have any number of *issuer* configurations. +The simplest issuer type is [SelfSigned](https://cert-manager.io/docs/configuration/selfsigned/). +It simply takes the certificate request and signs it with the private key it generates for the TLS Secret. + +``` +Self-signed certificates don't provide any help in establishing trust between certificates. +However, they are great for initial testing, due to their simplicity. +``` + +To install self-signing, run + +```console +$ kubectl apply -f - <}} + +## TLS Certificates + +Generate the certificates and keys used by the Service to terminate client TLS connections. +For the application, we'll deploy a sample echoserver app, with the certificates loaded in the application Pod. + +__Note:__ These certificates will not be used by the Gateway, but will remain in the application scope. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `passthrough.example.com`: + +```shell +openssl req -out passthrough.example.com.csr -newkey rsa:2048 -nodes -keyout passthrough.example.com.key -subj "/CN=passthrough.example.com/O=some organization" +openssl x509 -req -sha256 -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in passthrough.example.com.csr -out passthrough.example.com.crt +``` + +Store the cert/keys in A Secret: + +```shell +kubectl create secret tls server-certs --key=passthrough.example.com.key --cert=passthrough.example.com.crt +``` + +## Deployment + +Deploy TLS Passthrough application Deployment, Service and TLSRoute: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/tls-passthrough.yaml +``` + +Patch the Gateway from the Quickstart to include a TLS listener that listens on port `6443` and is configured for +TLS mode Passthrough: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: tls + protocol: TLS + hostname: passthrough.example.com + port: 6443 + tls: + mode: Passthrough + ' +``` + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +You can also test the same functionality by sending traffic to the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Curl the example app through the Gateway, e.g. Envoy proxy: + +```shell +curl -v -HHost:passthrough.example.com --resolve "passthrough.example.com:6443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://passthrough.example.com:6443/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 6043:6443 & +``` + +Curl the example app through Envoy proxy: + +```shell +curl -v --resolve "passthrough.example.com:6043:127.0.0.1" https://passthrough.example.com:6043 \ +--cacert passthrough.example.com.crt +``` + +{{% /tab %}} +{{< /tabpane >}} + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the Secret: + +```shell +kubectl delete secret/server-certs +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. diff --git a/site/content/en/v1.8/tasks/security/tls-termination.md b/site/content/en/v1.8/tasks/security/tls-termination.md new file mode 100644 index 0000000000..1100b04699 --- /dev/null +++ b/site/content/en/v1.8/tasks/security/tls-termination.md @@ -0,0 +1,92 @@ +--- +title: "TLS Termination for TCP" +--- + +This task will walk through the steps required to configure TLS Terminate mode for TCP traffic via Envoy Gateway. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## TLS Certificates + +Generate the certificates and keys used by the Gateway to terminate client TLS connections. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt +``` + +Install the TLS Termination for TCP example resources: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/tls-termination.yaml +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through the Gateway: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" \ +--cacert example.com.crt https://www.example.com/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 & +``` + +Query the example app through Envoy proxy: + +```shell +curl -v -HHost:www.example.com --resolve "www.example.com:8443:127.0.0.1" \ +--cacert example.com.crt https://www.example.com:8443/get +``` + +{{% /tab %}} +{{< /tabpane >}} diff --git a/site/content/en/v1.8/tasks/traffic/_index.md b/site/content/en/v1.8/tasks/traffic/_index.md new file mode 100644 index 0000000000..f884ccdfcb --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/_index.md @@ -0,0 +1,5 @@ +--- +title: "Traffic" +weight: 1 +description: This section includes Traffic Management tasks. +--- diff --git a/site/content/en/v1.8/tasks/traffic/backend-utilization.md b/site/content/en/v1.8/tasks/traffic/backend-utilization.md new file mode 100644 index 0000000000..adbd19f787 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/backend-utilization.md @@ -0,0 +1,217 @@ +--- +title: "Backend Utilization Load Balancing" +--- + +BackendUtilization load balancing uses [Open Resource Cost Application (ORCA)][ORCA] load metrics reported by the backend to dynamically weight endpoints. Under the hood it is implemented as [Envoy's client-side weighted round-robin][client-side-wrr] policy: each endpoint's weight is derived from the utilization metrics it emits, so instances running hot receive proportionally less traffic than those with headroom. + +If no ORCA metrics are received from an endpoint, that endpoint is treated as evenly weighted. + +See the [Load Balancing concepts page][concepts-lb] for a deeper explanation of ORCA metric formats. + +## Prerequisites + +* Your backend (or a sidecar in front of it) must emit ORCA load metrics as response headers or trailers. See [Backend instrumentation](#backend-instrumentation) below. +* {{< boilerplate prerequisites >}} + +## Build and Deploy the Example Backend + +The Envoy Gateway repository includes a small HTTP server under `examples/backend-utilization/` that emits a fixed ORCA `cpu_utilization` value (set via the `ORCA_CPU_UTILIZATION` environment variable) on every response. The example manifest deploys two sets of pods — one reporting `0.1` (idle) and one reporting `0.9` (hot) — behind a single Service. This lets you observe the weighting effect without wiring real load into a backend. + +**Note:** The `envoyproxy/gateway-backend-utilization` image is not published to a public registry — you need to build it locally from a checkout of the Envoy Gateway repository. + +* Build the example backend image + + ```shell + make -C examples/backend-utilization docker-buildx + ``` + +* Make the image available to your cluster + + {{< tabpane text=true >}} + {{% tab header="local kind server" %}} + + ```shell + kind load docker-image --name envoy-gateway envoyproxy/gateway-backend-utilization:latest + ``` + + {{% /tab %}} + {{% tab header="other Kubernetes server" %}} + + ```shell + docker tag envoyproxy/gateway-backend-utilization:latest $YOUR_DOCKER_REPO/gateway-backend-utilization:latest + docker push $YOUR_DOCKER_REPO/gateway-backend-utilization:latest + ``` + + If you push to your own registry, update the `image:` field in `examples/kubernetes/backend-utilization.yaml` to match before applying. + + {{% /tab %}} + {{< /tabpane >}} + +* Apply the example manifest (Service, two Deployments, HTTPRoute) + + ```shell + kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default + ``` + +Verify the two Deployments are ready: + +```shell +kubectl get deployment/backend-utilization-low deployment/backend-utilization-high -n default +``` + +## Configure BackendUtilization + +Apply a [BackendTrafficPolicy][BackendTrafficPolicy] with `loadBalancer.type: BackendUtilization`: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + +Leaving `backendUtilization: {}` empty accepts the defaults, but the 10 s default `blackoutPeriod` means traffic will appear evenly split for the first 10 seconds of the test. The shorter values above make the weighting visible immediately. The `backendUtilization` field itself is required when `type: BackendUtilization` — omitting it will fail CEL validation. + +## Configuration Fields + +All fields on `backendUtilization` are optional. + +| Field | Default | Purpose | +|---|---|---| +| `blackoutPeriod` | `10s` | How long an endpoint must report metrics before its reported weight is trusted. Prevents traffic from shifting based on a single noisy sample. | +| `weightExpirationPeriod` | `3m` | If an endpoint stops reporting for this long, its reported weight is discarded and it reverts to the default weight. | +| `weightUpdatePeriod` | `1s` | How often Envoy recomputes the weight table. Values below `100ms` are capped at `100ms`. | +| `errorUtilizationPenaltyPercent` | `0` | Multiplier (as `percent × 100`) applied to an endpoint's effective utilization based on its error rate (eps/qps). `100` = 1.0×, `150` = 1.5×, `200` = 2.0×. Higher values push errant endpoints out of rotation faster. | +| `metricNamesForComputingUtilization` | _unset_ | Custom ORCA metric keys to feed into the weight formula when `application_utilization` isn't reported. Use `named_metrics.` for keys inside the ORCA proto's `named_metrics` map. | +| `keepResponseHeaders` | `false` | By default Envoy strips the ORCA headers/trailers before forwarding the response. Set to `true` to let downstream clients see them (useful for chained load balancers or debugging). | + +### Example: Tuned for a Bursty Backend + +```yaml +loadBalancer: + type: BackendUtilization + backendUtilization: + blackoutPeriod: 30s # ignore reports during slow-start + weightExpirationPeriod: 1m # shorter memory — react faster to silent endpoints + weightUpdatePeriod: 500ms # faster reweighting + errorUtilizationPenaltyPercent: 150 # 1.5× penalty for errant endpoints +``` + +### Example: Application-Defined Utilization + +If your backend reports a custom metric (for example, queue depth) instead of CPU utilization, wire it in through `metricNamesForComputingUtilization`: + +```yaml +loadBalancer: + type: BackendUtilization + backendUtilization: + metricNamesForComputingUtilization: + - named_metrics.queue_depth +``` + +The backend would then emit: + +```http +endpoint-load-metrics: TEXT named_metrics.queue_depth=0.42 +``` + +## Backend Instrumentation + +Your backend must emit ORCA load metrics. Envoy accepts metrics in three formats on response **headers or trailers**: + +| Format | Header | Payload | +|---|---|---| +| Binary | `endpoint-load-metrics-bin` | Base64-encoded serialized [`OrcaLoadReport`][orca-proto] proto | +| JSON | `endpoint-load-metrics` | `JSON {"cpu_utilization": 0.3, "mem_utilization": 0.8}` | +| TEXT | `endpoint-load-metrics` | `TEXT cpu=0.3,mem=0.8,named_metrics.queue_depth=0.42` | + +For gRPC backends, the [xDS ORCA][grpc-orca] libraries emit these automatically via the `orca_load_report` service. For HTTP backends, add a response middleware that measures and serializes your CPU/memory/custom metrics on each response. + +## Combining With Zone-Aware Routing + +`BackendUtilization` composes with `weightedZones` to produce locality-aware weighted round-robin (Envoy's `wrr_locality` policy). See the [WeightedZones example][zone-aware-weighted] on the zone-aware routing page. + +`preferLocal` is **not** supported with `BackendUtilization`. + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the Quickstart instructions to set the variable. + +Give Envoy a few seconds after applying the policy to collect ORCA samples and compute endpoint weights — until then, traffic will appear roughly even. Then send 200 requests and tally which deployment handled each. Because `backend-utilization-low` reports `cpu_utilization=0.1` and `backend-utilization-high` reports `0.9`, Envoy should weight the `low` pods roughly 9× more heavily. + +```shell +for i in $(seq 1 200); do + curl -s -H "Host: www.example.com" "http://${GATEWAY_HOST}/backend-utilization" | jq -r '.pod' +done | sort | uniq -c +``` + +Expected output (exact counts will vary, but `low` should dominate ~9:1): + +```console + 90 backend-utilization-low-6b9cf46b59-l7df7 + 87 backend-utilization-low-6b9cf46b59-xxrw2 + 12 backend-utilization-high-5fdb65cb87-mctlp + 11 backend-utilization-high-5fdb65cb87-rrdvq +``` + +If you instead see a roughly even split, the weights may not have stabilized yet — wait a few seconds and retry. You can verify the per-endpoint weights directly through the Envoy admin interface: + +```shell +ENVOY_POD=$(kubectl get pods -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +kubectl -n envoy-gateway-system port-forward pod/${ENVOY_POD} 19000:19000 & +curl -s localhost:19000/clusters | grep "backend-utilization" | grep weight +``` + +You should see weights roughly `10000` for the `low` pods and `1111` for the `high` pods (the inverse of the reported utilization). + +## Clean-Up + +```shell +kubectl delete backendtrafficpolicy/backend-utilization +kubectl delete -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/backend-utilization.yaml -n default +``` + +[ORCA]: https://docs.google.com/document/d/1NSnK3346BkBo1JUU3I9I5NYYnaJZQPt8_Z_XCBCI3uA +[orca-proto]: https://www.envoyproxy.io/docs/envoy/latest/xds/data/orca/v3/orca_load_report.proto +[client-side-wrr]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +[grpc-orca]: https://github.com/grpc/proposal/blob/master/A51-custom-backend-metrics.md +[concepts-lb]: ../../../concepts/load-balancing#backend-utilization-orca +[zone-aware-weighted]: ../zone-aware-routing#weightedzones +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy diff --git a/site/content/en/v1.8/tasks/traffic/backend.md b/site/content/en/v1.8/tasks/traffic/backend.md new file mode 100644 index 0000000000..752f8c9b62 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/backend.md @@ -0,0 +1,375 @@ +--- +title: "Backend Routing" +--- + +Envoy Gateway supports routing to native K8s resources such as `Service` and `ServiceImport`. The `Backend` API is a custom Envoy Gateway [extension resource][] that can used in Gateway-API [BackendObjectReference][]. + +## Motivation +The Backend API was added to support several use cases: +- Allowing users to integrate Envoy with services (Ext Auth, Rate Limit, ALS, ...) using Unix Domain Sockets, which are currently not supported by K8s. +- Simplify [routing to cluster-external backends][], which currently requires users to maintain both K8s `Service` and `EndpointSlice` resources. + +## Warning + +Similar to the K8s EndpointSlice API, the Backend API can be misused to allow traffic to be sent to otherwise restricted destinations, as described in [CVE-2021-25740][]. +A Backend resource can be used to: +- Expose a Service or Pod that should not be accessible +- Reference a Service or Pod by a Route without appropriate Reference Grants +- Expose the Envoy Proxy localhost (including the Envoy admin endpoint) +- When configured as the `DynamicResolver` type, it can route traffic to any destination, effectively exposing all potential endpoints to clients. This can introduce security risks if not properly managed. + +For these reasons, the Backend API is disabled by default in Envoy Gateway configuration. Envoy Gateway admins are advised to follow [upstream recommendations][] and restrict access to the Backend API using K8s RBAC. + +## Restrictions + +The Backend API is currently supported only in the following BackendReferences: +- [HTTPRoute]: IP and FQDN endpoints +- [TLSRoute]: IP and FQDN endpoints +- [Envoy Extension Policy] (ExtProc): IP, FQDN and unix domain socket endpoints +- [Security Policy]: IP and FQDN endpoints for the OIDC providers +- [EnvoyProxy]: IP, FQDN and unix domain socket endpoints + +The Backend API supports attachment the following policies: +- [Backend TLS Policy][] + +Certain restrictions apply on the value of hostnames and addresses. For example, the loopback IP address range and the localhost hostname are forbidden. + +Envoy Gateway does not manage the lifecycle of unix domain sockets referenced by the Backend resource. Envoy Gateway admins are responsible for creating and mounting the sockets into the envoy proxy pod. The latter can be achieved by patching the envoy deployment using the [EnvoyProxy][] resource. + +## Quickstart + +### Prerequisites + +{{< boilerplate prerequisites >}} + +### Enable Backend + +* By default [Backend][] is disabled. Lets enable it in the [EnvoyGateway][] startup configuration + +* The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and attaches it + using a `ConfigMap`. In the next step, we will update this resource to enable Backend. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +## Testing + +### Route to External Backend + +* In the following example, we will create a `Backend` resource that routes to httpbin.org:80 and a `HTTPRoute` that references this backend. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Get the Gateway address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Send a request and view the response: + +```shell +curl -I -HHost:www.example.com http://${GATEWAY_HOST}/headers +``` + +### Dynamic Forward Proxy + +Envoy Gateway can be configured as a dynamic forward proxy using the [Backend][] API by setting its type to `DynamicResolver`. +This allows Envoy Gateway to act as an HTTP proxy without needing prior knowledge of destination hostnames or IP addresses, +while still maintaining its advanced routing and traffic management capabilities. + +Under the hood, Envoy Gateway uses the Envoy [Dynamic Forward Proxy](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/http/http_proxy) +to implement this feature. + +In the following example, we will create a `HTTPRoute` that references a `Backend` resource of type `DynamicResolver`. +This setup allows Envoy Gateway to dynamically resolve the hostname in the request and forward the traffic to the original +destination of the request. + +#### Forwarding Based on the Original Host + +Note: the TLS configuration in the following example is optional. It's only required if you want to use TLS to connect +to the backend service. The example uses the system well-known CA certificate to validate the backend service's certificate. +You can also use a custom CA certificate by specifying the `caCertificate` field in the `tls` section. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Get the Gateway address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Send a request to `gateway.envoyproxy.io` and view the response: + +```shell +curl -HHost:gateway.envoyproxy.io http://${GATEWAY_HOST} +``` + +You can also send a request to any other domain, and Envoy Gateway will resolve the hostname and route the traffic accordingly: + +```shell +curl -HHost:httpbin.org http://${GATEWAY_HOST}/get +``` + +#### Host Rewriting from a Custom Header + +You can rewrite the host using a request header while still relying on the DynamicResolver backend to resolve that host. +Loopback hostnames/addresses (for example `localhost`, `127.0.0.1`, `::1`) are denied by default so rewritten hosts cannot +route to the proxy's own loopback interface. Add explicit allow/deny rules for other destinations with [SecurityPolicy][] +authorization when you want tighter controls. + +Example: rewrite from a custom header and deny rewrites to `forbidden.com`. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: HTTPRouteFilter +metadata: + name: host-rewrite-from-header + namespace: default +spec: + urlRewrite: + hostname: + type: Header + header: x-dynamic-host-header +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: my-dynamic-resolver-route + namespace: default +spec: + parentRefs: + - name: eg + rules: + - backendRefs: + - group: gateway.envoyproxy.io + kind: Backend + name: backend-dynamic-resolver + filters: + - type: ExtensionRef + extensionRef: + group: gateway.envoyproxy.io + kind: HTTPRouteFilter + name: host-rewrite-from-header +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: deny-forbidden-rewrites + namespace: default +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: my-dynamic-resolver-route + authorization: + defaultAction: Allow + rules: + - name: disallow-forbidden-hosts + action: Deny + principal: + headers: + - name: x-dynamic-host-header + values: + - forbidden.com +``` + +[Backend]: ../../../api/extension_types#backend +[routing to cluster-external backends]: ./../../tasks/traffic/routing-outside-kubernetes.md +[BackendObjectReference]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#backendobjectreference +[extension resource]: https://gateway-api.sigs.k8s.io/guides/getting-started/migrating-from-ingress/#approach-to-extensibility +[CVE-2021-25740]: https://nvd.nist.gov/vuln/detail/CVE-2021-25740 +[upstream recommendations]: https://github.com/kubernetes/kubernetes/issues/103675 +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[TLSRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#tlsroute +[Envoy Extension Policy]: ../../../api/extension_types#envoyextensionpolicy +[Security Policy]: ../../../api/extension_types#oidcprovider +[Backend TLS Policy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/ +[EnvoyProxy]: ../../../api/extension_types#envoyproxy +[EnvoyGateway]: ../../../api/extension_types#envoygateway +[SecurityPolicy]: ../../../api/extension_types#securitypolicy diff --git a/site/content/en/v1.8/tasks/traffic/circuit-breaker.md b/site/content/en/v1.8/tasks/traffic/circuit-breaker.md new file mode 100644 index 0000000000..caa31585a4 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/circuit-breaker.md @@ -0,0 +1,149 @@ +--- +title: "Circuit Breakers" +--- + +[Envoy Circuit Breakers][] can be used to fail quickly and apply back-pressure in response to upstream service degradation. + +Envoy Gateway supports the following circuit breaker thresholds: +- **Concurrent Connections**: limit the connections that Envoy can establish to the upstream service. When this threshold is met, new connections will not be established, and some requests will be queued until an existing connection becomes available. +- **Concurrent Requests**: limit on concurrent requests in-flight from Envoy to the upstream service. When this threshold is met, requests will be queued. +- **Pending Requests**: limit the pending request queue size. When this threshold is met, overflowing requests will be terminated with a `503` status code. + +Envoy's circuit breakers are distributed: counters are not synchronized across different Envoy processes. The default Envoy and Envoy Gateway circuit breaker threshold values (1024) may be too strict for high-throughput systems. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their desired circuit breaker thresholds. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +**Note**: There are distinct circuit breaker counters for each `BackendReference` in an `xRoute` rule. Even if a `BackendTrafficPolicy` targets a `Gateway`, each `BackendReference` in that gateway still has separate circuit breaker counter. + +## Prerequisites + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +### Install the hey load testing tool + +* The `hey` CLI will be used to generate load and measure response times. Follow the installation instruction from the [Hey project] docs. + +## Test and customize circuit breaker settings + +This example will simulate a degraded backend that responds within 10 seconds by adding the `?delay=10s` query parameter to API calls. The hey tool will be used to generate 100 concurrent requests. + +```shell +hey -n 100 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/?delay=10s +``` + +```console +Summary: + Total: 10.3426 secs + Slowest: 10.3420 secs + Fastest: 10.0664 secs + Average: 10.2145 secs + Requests/sec: 9.6687 + + Total data: 36600 bytes + Size/request: 366 bytes + +Response time histogram: + 10.066 [1] |■■■■ + 10.094 [4] |■■■■■■■■■■■■■■■ + 10.122 [9] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.149 [10] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.177 [10] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.204 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.232 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.259 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.287 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.314 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 10.342 [11] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ +``` + +The default circuit breaker threshold (1024) is not met. As a result, requests do not overflow: all requests are proxied upstream and both Envoy and clients wait for 10s. + +In order to fail fast, apply a `BackendTrafficPolicy` that limits concurrent requests to 10 and pending requests to 0. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Execute the load simulation again. + +```shell +hey -n 100 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/?delay=10s +``` + +```console +Summary: + Total: 10.1230 secs + Slowest: 10.1224 secs + Fastest: 0.0529 secs + Average: 1.0677 secs + Requests/sec: 9.8785 + + Total data: 10940 bytes + Size/request: 109 bytes + +Response time histogram: + 0.053 [1] | + 1.060 [89] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 2.067 [0] | + 3.074 [0] | + 4.081 [0] | + 5.088 [0] | + 6.095 [0] | + 7.102 [0] | + 8.109 [0] | + 9.115 [0] | + 10.122 [10] |■■■■ +``` + +With the new circuit breaker settings, and due to the slowness of the backend, only the first 10 concurrent requests were proxied, while the other 90 overflowed. +* Overflowing Requests failed fast, reducing proxy resource consumption. +* Upstream traffic was limited, alleviating the pressure on the degraded service. + +[Envoy Circuit Breakers]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Hey project]: https://github.com/rakyll/hey diff --git a/site/content/en/v1.8/tasks/traffic/client-traffic-policy.md b/site/content/en/v1.8/tasks/traffic/client-traffic-policy.md new file mode 100644 index 0000000000..13d7ac13b6 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/client-traffic-policy.md @@ -0,0 +1,661 @@ +--- +title: "Client Traffic Policy" +--- + +This task explains the usage of the [ClientTrafficPolicy][] API. + +## Introduction + +The [ClientTrafficPolicy][] API allows system administrators to configure +the behavior for how the Envoy Proxy server behaves with downstream clients. + +## Motivation + +This API was added as a new policy attachment resource that can be applied to Gateway resources and it is meant to hold settings for configuring behavior of the connection between the downstream client and Envoy Proxy listener. It is the counterpart to the [BackendTrafficPolicy][] API resource. + +## Quickstart + +### Prerequisites + +{{< boilerplate prerequisites >}} + +### Support TCP keepalive for downstream client + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify that ClientTrafficPolicy is Accepted: + +```shell +kubectl get clienttrafficpolicies.gateway.envoyproxy.io -n default +``` + +You should see the policy marked as accepted like this: + +```shell +NAME STATUS AGE +enable-tcp-keepalive-policy Accepted 5s +``` + +Curl the example app through Envoy proxy once again: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get --next --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +You should see the output like this: + +```shell +* Trying 172.18.255.202:80... +* Connected to 172.18.255.202 (172.18.255.202) port 80 (#0) +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.1.2 +> Accept: */* +> +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Fri, 01 Dec 2023 10:17:04 GMT +< content-length: 507 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.1.2" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "4d0d33e8-d611-41f0-9da0-6458eec20fa5" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-58d58f745-2zwvn" +* Connection #0 to host 172.18.255.202 left intact +}* Found bundle for host: 0x7fb9f5204ea0 [serially] +* Can not multiplex, even if we wanted to +* Reusing existing connection #0 with host 172.18.255.202 +> GET /headers HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.1.2 +> Accept: */* +> +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Fri, 01 Dec 2023 10:17:04 GMT +< content-length: 511 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/headers", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.1.2" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "9a8874c0-c117-481c-9b04-933571732ca5" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-58d58f745-2zwvn" +* Connection #0 to host 172.18.255.202 left intact +} +``` + +You can see keepalive connection marked by the output in: + +```shell +* Connection #0 to host 172.18.255.202 left intact +* Reusing existing connection #0 with host 172.18.255.202 +``` + +### Enable Proxy Protocol for downstream client + +This example configures Proxy Protocol for downstream clients. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify that ClientTrafficPolicy is Accepted: + +```shell +kubectl get clienttrafficpolicies.gateway.envoyproxy.io -n default +``` + +You should see the policy marked as accepted like this: + +```shell +NAME STATUS AGE +enable-proxy-protocol-policy Accepted 5s +``` + +Try the endpoint without using PROXY protocol with curl: + +```shell +curl -v --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +```shell +* Trying 172.18.255.202:80... +* Connected to 172.18.255.202 (172.18.255.202) port 80 (#0) +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.1.2 +> Accept: */* +> +* Recv failure: Connection reset by peer +* Closing connection 0 +curl: (56) Recv failure: Connection reset by peer +``` + +Curl the example app through Envoy proxy once again, now sending HAProxy PROXY protocol header at the beginning of the connection with --haproxy-protocol flag: + +```shell +curl --verbose --haproxy-protocol --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +You should now expect 200 response status and also see that source IP was preserved in the X-Forwarded-For header. + +```shell +* Trying 172.18.255.202:80... +* Connected to 172.18.255.202 (172.18.255.202) port 80 (#0) +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.1.2 +> Accept: */* +> +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Mon, 04 Dec 2023 21:11:43 GMT +< content-length: 510 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.1.2" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "192.168.255.6" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "290e4b61-44b7-4e5c-a39c-0ec76784e897" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-58d58f745-2zwvn" +* Connection #0 to host 172.18.255.202 left intact +} +``` + +### Configure Client IP Detection + +This example configures the number of hops from the right side of the X-Forwarded-For (XFF) to trust when determining the origin client's IP address and determines whether or not `x-forwarded-proto` headers will be trusted. Refer to https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for for details. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify that ClientTrafficPolicy is Accepted: + +```shell +kubectl get clienttrafficpolicies.gateway.envoyproxy.io -n default +``` + +You should see the policy marked as accepted like this: + +```shell +NAME STATUS AGE +http-client-ip-detection Accepted 5s +``` + +Curl the example app through Envoy proxy: + +```shell +curl -v http://$GATEWAY_HOST/get \ + -H "Host: www.example.com" \ + -H "X-Forwarded-Proto: https" \ + -H "X-Forwarded-For: 1.1.1.1,2.2.2.2" +``` + +If `numTrustedHops` is set to N, the client IP is taken from the Nth address from the right end of the XFF header. In this example, +we set `numTrustedHops` to 2, so the client IP will be taken from the second rightmost address in the XFF header. + +You should expect 200 response status, see that `X-Forwarded-Proto` was preserved and `X-Envoy-External-Address` was set to the +second rightmost address in the `X-Forwarded-For` header: + +```shell +* Trying [::1]:8888... +* Connected to localhost (::1) port 8888 +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> X-Forwarded-Proto: https +> X-Forwarded-For: 1.1.1.1,2.2.2.2 +> +Handling connection for 8888 +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Tue, 30 Jan 2024 15:19:22 GMT +< content-length: 535 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.4.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-External-Address": [ + "1.1.1.1" + ], + "X-Forwarded-For": [ + "1.1.1.1,2.2.2.2,10.244.0.9" + ], + "X-Forwarded-Proto": [ + "https" + ], + "X-Request-Id": [ + "53ccfad7-1899-40fa-9322-ddb833aa1ac3" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-58d58f745-8psnc" +* Connection #0 to host localhost left intact +} +``` + +### Enable HTTP Request Received Timeout + +This feature allows you to limit the time taken by the Envoy Proxy fleet to receive the entire request from the client, which is useful in preventing certain clients from consuming too much memory in Envoy +This example configures the HTTP request timeout for the client, please check out the details [here](https://www.envoyproxy.io/docs/envoy/latest/faq/configuration/timeouts#stream-timeouts). + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Curl the example app through Envoy proxy: + +```shell +curl -v http://$GATEWAY_HOST/get \ + -H "Host: www.example.com" \ + -H "Content-Length: 10000" +``` + +You should expect `428` response status after 2s: + +```shell +curl -v http://$GATEWAY_HOST/get \ + -H "Host: www.example.com" \ + -H "Content-Length: 10000" +* Trying 172.18.255.200:80... +* Connected to 172.18.255.200 (172.18.255.200) port 80 +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> Content-Length: 10000 +> +< HTTP/1.1 408 Request Timeout +< content-length: 15 +< content-type: text/plain +< date: Tue, 27 Feb 2024 07:38:27 GMT +< connection: close +< +* Closing connection +request timeout +``` + +### Configure Client HTTP Idle Timeout + +The idle timeout is defined as the period in which there are no active requests. When the idle timeout is reached the connection will be closed. +For more details see [here](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-idle-timeout:~:text=...%7D%0A%7D-,idle_timeout,-(Duration)%20The). + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Curl the example app through Envoy proxy: + +```shell +openssl s_client -crlf -connect $GATEWAY_HOST:443 +``` + +You should expect the connection to be closed after 5s. + +You can also check the number of connections closed due to idle timeout by using the following query: + +```shell +envoy_http_downstream_cx_idle_timeout{envoy_http_conn_manager_prefix=""} +``` + +The number of connections closed due to idle timeout should be increased by 1. + + +### Configure Downstream Per Connection Buffer Limit + +This feature allows you to set a soft limit on size of the listener’s new connection read and write buffers. +The size is configured using the `resource.Quantity` format, see examples [here](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory). + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy diff --git a/site/content/en/v1.8/tasks/traffic/connection-limit.md b/site/content/en/v1.8/tasks/traffic/connection-limit.md new file mode 100644 index 0000000000..8fadf993b0 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/connection-limit.md @@ -0,0 +1,135 @@ +--- +title: "Connection Limit" +--- + +The connection limit features allows users to limit the number of concurrently active TCP connections on a [Gateway][] or a [Listener][]. +When the [connection limit][] is reached, new connections are closed immediately by Envoy proxy. It's possible to configure a delay for connection rejection. + +Users may want to limit the number of connections for several reasons: +* Protect resources like CPU and Memory. +* Ensure that different listeners can receive a fair share of global resources. +* Protect from malicious activity like DoS attacks. + +Envoy Gateway introduces a new CRD called [Client Traffic Policy][] that allows the user to describe their desired connection limit settings. +This instantiated resource can be linked to a [Gateway][]. + +The Envoy [connection limit][] implementation is distributed: counters are not synchronized between different envoy proxies. + +When a [Client Traffic Policy][] is attached to a gateway, the connection limit will apply differently based on the +[Listener][] protocol in use: +- HTTP: all HTTP listeners in a [Gateway][] will share a common connection counter, and a limit defined by the policy. +- HTTPS/TLS: each HTTPS/TLS listener will have a dedicated connection counter, and a limit defined by the policy. + + +## Prerequisites + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +### Install the hey load testing tool + +* The `hey` CLI will be used to generate load and measure response times. Follow the installation instruction from the [Hey project] docs. + +## Test and customize connection limit settings + +This example we use `hey` to open 10 connections and execute 1 RPS per connection for 10 seconds. + +```shell +hey -c 10 -q 1 -z 10s -host "www.example.com" http://${GATEWAY_HOST}/get +``` + +```console +Summary: + Total: 10.0058 secs + Slowest: 0.0275 secs + Fastest: 0.0029 secs + Average: 0.0111 secs + Requests/sec: 9.9942 + +[...] + +Status code distribution: + [200] 100 responses +``` + +There are no connection limits, and so all 100 requests succeed. + +Next, we apply a limit of 5 connections. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Execute the load simulation again. + +```shell +hey -c 10 -q 1 -z 10s -host "www.example.com" http://${GATEWAY_HOST}/get +``` + +```console +Summary: + Total: 11.0327 secs + Slowest: 0.0361 secs + Fastest: 0.0013 secs + Average: 0.0088 secs + Requests/sec: 9.0640 + +[...] + +Status code distribution: + [200] 50 responses + +Error distribution: + [50] Get "http://localhost:8888/get": EOF +``` + +With the new connection limit, only 5 of 10 connections are established, and so only 50 requests succeed. + + +[Client Traffic Policy]: ../../../api/extension_types#clienttrafficpolicy +[Hey project]: https://github.com/rakyll/hey +[connection limit]: https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/network_filters/connection_limit_filter +[listener]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#listener +[gateway]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway diff --git a/site/content/en/v1.8/tasks/traffic/direct-response.md b/site/content/en/v1.8/tasks/traffic/direct-response.md new file mode 100644 index 0000000000..5a94614fff --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/direct-response.md @@ -0,0 +1,205 @@ +--- +title: "Direct Response" +--- + +Direct responses are valuable in cases where you want the gateway itself +to handle certain requests without forwarding them to backend services. +This task shows you how to configure them. + +## Installation + +Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## Testing Direct Response + +Note: the size of the response body (whether provided in-line or via a reference) cannot exceed 4096 bytes. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/inline +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 127.0.0.1 (127.0.0.1) port 80 +> GET /inline HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> +< HTTP/1.1 503 Service Unavailable +< content-type: text/plain +< content-length: 32 +< date: Sat, 02 Nov 2024 00:35:48 GMT +< +* Connection #0 to host 127.0.0.1 left intact +Oops! Your request is not found. +``` + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/value-ref +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 127.0.0.1 (127.0.0.1) port 80 +> GET /value-ref HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> +< HTTP/1.1 500 Internal Server Error +< content-type: application/json +< content-length: 34 +< date: Sat, 02 Nov 2024 00:35:55 GMT +< +* Connection #0 to host 127.0.0.1 left intact +{"error": "Internal Server Error"} +``` diff --git a/site/content/en/v1.8/tasks/traffic/failover.md b/site/content/en/v1.8/tasks/traffic/failover.md new file mode 100644 index 0000000000..b8a265dcfd --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/failover.md @@ -0,0 +1,572 @@ +--- +title: Failover +--- + +Active-passive failover in an API gateway setup is like having a backup plan in place to keep things +running smoothly if something goes wrong. Here’s why it’s valuable: + +* Staying Online: When the main (or "active") backend has issues or goes offline, +the fallback (or "passive") backend is ready to step in instantly. +This helps keep your API accessible and your services running, so users don’t even notice any interruptions. + +* Automatic Switch Over: If a problem occurs, the system can automatically switch traffic over to the fallback backend. +This avoids needing someone to jump in and fix things manually, which could take time and might even lead to mistakes. + +* Lower Costs: In an active-passive setup, the fallback backend doesn’t need to work all the time—it’s just on standby. +This can save on costs (like cloud egress costs) compared to setups where both backend are running at full capacity. + +* Peace of Mind with Redundancy: Although the fallback backend isn’t handling traffic daily, it's there as a safety net. +If something happens with the primary backend, the backup can take over immediately, ensuring your service doesn’t skip a beat. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Test + +* We'll first create two [services][Service] & [deployments][Deployment], called `active` and `passive`, representing an `active` and `passive` backend application. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +* Follow the instructions [here](./../../tasks/traffic/backend/#enable-backend) to enable the Backend API + +* Create two [Backend][] resources that are used to represent the `active` backend and `passive` backend. +Note, we've set `fallback: true` for the `passive` backend to indicate its a passive backend + + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +* Lets create an [HTTPRoute][] that can route to both these backends + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +* Lets configure a [BackendTrafficPolicy][] with a passive health check setting to detect an transient errors. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + + +* Lets send 10 requests. You should see that they all go to the `active` backend. + +```shell +for i in {1..10; do curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/test 2>/dev/null | jq .pod; done +``` + +```console +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +"active-5bb896774f-lz8s9" +``` + +* Lets simulate a failure in the `active` backend by changing the server listening port to `5000` + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +* Lets send 10 requests again. You should see them all being sent to the `passive` backend + +```shell +for i in {1..10; do curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/test 2>/dev/null | jq .pod; done +``` + +```console +parse error: Invalid numeric literal at line 1, column 9 +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +"passive-7ddbf945c9-wkc4f" +``` + +The first error can be avoided by configuring [retries](./../../tasks/traffic/retry.md). + +[Backend]: ../../../api/extension_types#backend +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[Deployment]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ diff --git a/site/content/en/v1.8/tasks/traffic/fault-injection.md b/site/content/en/v1.8/tasks/traffic/fault-injection.md new file mode 100644 index 0000000000..ded4f4c90a --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/fault-injection.md @@ -0,0 +1,382 @@ +--- +title: "Fault Injection" +--- + +[Envoy fault injection] can be used to inject delays and abort requests to mimic failure scenarios such as service failures and overloads. + +Envoy Gateway supports the following fault scenarios: +- **delay fault**: inject a custom fixed delay into the request with a certain probability to simulate delay failures. +- **abort fault**: inject a custom response code into the response with a certain probability to simulate abort failures. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their desired fault scenarios. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +For GRPC - follow the steps from the [GRPC Routing](../grpc-routing) example. + +### Install the hey load testing tool + +* The `hey` CLI will be used to generate load and measure response times. Follow the installation instruction from the [Hey project] docs. + +## Configuration + +Allow requests with a valid faultInjection by creating an [BackendTrafficPolicy][BackendTrafficPolicy] and attaching it to the example HTTPRoute or GRPCRoute. + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +Two HTTPRoute resources were created, one for `/foo` and another for `/bar`. `fault-injection-abort` BackendTrafficPolicy has been created and targeted HTTPRoute foo to abort requests for `/foo`. `fault-injection-delay` BackendTrafficPolicy has been created and targeted HTTPRoute foo to delay `2s` requests for `/bar`. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/foo -o yaml +kubectl get httproute/bar -o yaml +``` + +Verify the BackendTrafficPolicy configuration: + +```shell +kubectl get backendtrafficpolicy/fault-injection-50-percent-abort -o yaml +kubectl get backendtrafficpolicy/fault-injection-delay -o yaml +``` + +### GRPCRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +A BackendTrafficPolicy has been created and targeted GRPCRoute yages to abort requests for `yages` service.. + +Verify the GRPCRoute configuration and status: + +```shell +kubectl get grpcroute/yages -o yaml +``` + +Verify the BackendTrafficPolicy configuration: + +```shell +kubectl get backendtrafficpolicy/fault-injection-abort -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +Verify that requests to `foo` route are aborted. + +```shell +hey -n 1000 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/foo +``` + +```console +Status code distribution: + [200] 501 responses + [501] 499 responses +``` + +Verify that requests to `bar` route are delayed. + +```shell +hey -n 1000 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/bar +``` + +```console +Summary: + Total: 20.1493 secs + Slowest: 2.1020 secs + Fastest: 1.9940 secs + Average: 2.0123 secs + Requests/sec: 49.6295 + + Total data: 557000 bytes + Size/request: 557 bytes + +Response time histogram: + 1.994 [1] | + 2.005 [475] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 2.016 [419] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 2.026 [5] | + 2.037 [0] | + 2.048 [0] | + 2.059 [30] |■■■ + 2.070 [0] | + 2.080 [0] | + 2.091 [11] |■ + 2.102 [59] |■■■■■ +``` + +### GRPCRoute + +Verify that requests to `yages`service are aborted. + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +You should see the below response + +```shell +Error invoking method "yages.Echo/Ping": rpc error: code = Unavailable desc = failed to query for service descriptor "yages.Echo": fault filter abort +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the BackendTrafficPolicy: + +```shell +kubectl delete BackendTrafficPolicy/fault-injection-abort +``` + +[Envoy fault injection]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/fault_filter.html +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Hey project]: https://github.com/rakyll/hey diff --git a/site/content/en/v1.8/tasks/traffic/gateway-address.md b/site/content/en/v1.8/tasks/traffic/gateway-address.md new file mode 100644 index 0000000000..4c32d6ee15 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/gateway-address.md @@ -0,0 +1,70 @@ +--- +title: "Gateway Address" +--- + +The [Gateway API][] provides an optional [Addresses][] field through which Envoy Gateway can set addresses for Envoy Proxy Service. +Depending on the Service Type, the addresses of gateway can be used as: + +- [Prerequisites](#prerequisites) +- [External IPs](#external-ips) +- [Cluster IP](#cluster-ip) + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## External IPs + +Using the addresses in `Gateway.Spec.Addresses` as the [External IPs][] of Envoy Proxy Service, +this will __require__ the address to be of type `IPAddress` and the [ServiceType][] to be of `LoadBalancer` or `NodePort`. + +The Envoy Gateway deploys Envoy Proxy Service as `LoadBalancer` by default, +so you can set the address of the `Gateway` directly (the address settings here are for reference only): + +```shell +kubectl patch gateway eg --type=json --patch ' +- op: add + path: /spec/addresses + value: + - type: IPAddress + value: 1.2.3.4 +' +``` + +Verify the `Gateway` status: + +```shell +kubectl get gateway +``` + +```console +NAME CLASS ADDRESS PROGRAMMED AGE +eg eg 1.2.3.4 True 14m +``` + +Verify the Envoy Proxy Service status: + +```shell +kubectl get service -n envoy-gateway-system +``` + +```console +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy-default-eg-64656661 LoadBalancer 10.96.236.219 1.2.3.4 80:31017/TCP 15m +envoy-gateway ClusterIP 10.96.192.76 18000/TCP 15m +envoy-gateway-metrics-service ClusterIP 10.96.124.73 8443/TCP 15m +``` + +__Note:__ If the `Gateway.Spec.Addresses` is explicitly set, it will be the only addresses that populates the `Gateway` status. + +## Cluster IP + +Using the addresses in `Gateway.Spec.Addresses` as the [Cluster IP][] of Envoy Proxy Service, +this will __require__ the address to be of type `IPAddress` and the [ServiceType][] to be of `ClusterIP`. + + +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[Addresses]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gatewayaddress +[External IPs]: https://kubernetes.io/docs/concepts/services-networking/service/#external-ips +[Cluster IP]: https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip +[ServiceType]: ../../../api/extension_types#servicetype diff --git a/site/content/en/v1.8/tasks/traffic/gatewayapi-support.md b/site/content/en/v1.8/tasks/traffic/gatewayapi-support.md new file mode 100644 index 0000000000..b597639401 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/gatewayapi-support.md @@ -0,0 +1,120 @@ +--- +title: "Gateway API Support" +--- + +As mentioned in the [system design][] document, Envoy Gateway's managed data plane is configured dynamically through +Kubernetes resources, primarily [Gateway API][] objects. Envoy Gateway supports configuration using the following Gateway API resources. + +## GatewayClass + +A [GatewayClass][] represents a "class" of gateways, i.e. which Gateways should be managed by Envoy Gateway. +Envoy Gateway supports managing __a single__ GatewayClass resource that matches its configured `controllerName` and +follows Gateway API guidelines for [resolving conflicts][] when multiple GatewayClasses exist with a matching +`controllerName`. + +__Note:__ If specifying GatewayClass [parameters reference][], it must refer to an [EnvoyProxy][] resource. + +## Gateway + +When a [Gateway][] resource is created that references the managed GatewayClass, Envoy Gateway will create and manage a +new Envoy Proxy deployment. Gateway API resources that reference this Gateway will configure this managed Envoy Proxy +deployment. + +## HTTPRoute + +A [HTTPRoute][] configures routing of HTTP traffic through one or more Gateways. The following HTTPRoute filters are +supported by Envoy Gateway: + +- `requestHeaderModifier`: [RequestHeaderModifiers][http-filter] + can be used to modify or add request headers before the request is proxied to its destination. +- `responseHeaderModifier`: [ResponseHeaderModifiers][http-filter] + can be used to modify or add response headers before the response is sent back to the client. +- `requestMirror`: [RequestMirrors][http-filter] + configure destinations where the requests should also be mirrored to. Responses to mirrored requests will be ignored. +- `requestRedirect`: [RequestRedirects][http-filter] + configure policied for how requests that match the HTTPRoute should be modified and then redirected. +- `urlRewrite`: [UrlRewrites][http-filter] + allow for modification of the request's hostname and path before it is proxied to its destination. +- `extensionRef`: [ExtensionRefs][] are used by Envoy Gateway to implement extended filters. Currently, Envoy Gateway + supports rate limiting and request authentication filters. For more information about these filters, refer to the + [rate limiting][] and [request authentication][] documentation. + +__Notes:__ +- The only [BackendRef][] kind supported by Envoy Gateway is a [Service][]. Routing traffic to other destinations such + as arbitrary URLs is not possible. +- Only `requestHeaderModifier` and `responseHeaderModifier` filters are currently supported within [HTTPBackendRef][]. + +## TCPRoute + +A [TCPRoute][] configures routing of raw TCP traffic through one or more Gateways. Traffic can be forwarded to the +desired BackendRefs based on a TCP port number. + +__Note:__ A TCPRoute only supports proxying in non-transparent mode, i.e. the backend will see the source IP and port of +the Envoy Proxy instance instead of the client. + +## UDPRoute + +A [UDPRoute][] configures routing of raw UDP traffic through one or more Gateways. Traffic can be forwarded to the +desired BackendRefs based on a UDP port number. + +__Note:__ Similar to TCPRoutes, UDPRoutes only support proxying in non-transparent mode i.e. the backend will see the +source IP and port of the Envoy Proxy instance instead of the client. + +## GRPCRoute + +A [GRPCRoute][] configures routing of [gRPC][] requests through one or more Gateways. They offer request matching by +hostname, gRPC service, gRPC method, or HTTP/2 Header. Envoy Gateway supports the following filters on GRPCRoutes to +provide additional traffic processing: + +- `requestHeaderModifier`: [RequestHeaderModifiers][grpc-filter] + can be used to modify or add request headers before the request is proxied to its destination. +- `responseHeaderModifier`: [ResponseHeaderModifiers][grpc-filter] + can be used to modify or add response headers before the response is sent back to the client. +- `requestMirror`: [RequestMirrors][grpc-filter] + configure destinations where the requests should also be mirrored to. Responses to mirrored requests will be ignored. + +__Notes:__ +- The only [BackendRef][grpc-filter] kind supported by Envoy Gateway is a [Service][]. Routing traffic to other + destinations such as arbitrary URLs is not currently possible. +- Only `requestHeaderModifier` and `responseHeaderModifier` filters are currently supported within [GRPCBackendRef][]. + +## TLSRoute + +A [TLSRoute][] configures routing of TCP traffic through one or more Gateways. However, unlike TCPRoutes, TLSRoutes +can match against TLS-specific metadata. + +## ReferenceGrant + +A [ReferenceGrant][] is used to allow a resource to reference another resource in a different namespace. Normally an +HTTPRoute created in namespace `foo` is not allowed to reference a Service in namespace `bar`. A ReferenceGrant permits +these types of cross-namespace references. Envoy Gateway supports the following ReferenceGrant use-cases: + +- Allowing an HTTPRoute, GRPCRoute, TLSRoute, UDPRoute, or TCPRoute to reference a Service in a different namespace. +- Allowing an HTTPRoute's `requestMirror` filter to include a BackendRef that references a Service in a different + namespace. +- Allowing a Gateway's [SecretObjectReference][] to reference a secret in a different namespace. + +[system design]: /community/design/system-design +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#gatewayclass +[parameters reference]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#ParametersReference +[Gateway]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#Gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#HTTPRoute +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[BackendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#BackendRef +[HTTPBackendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#HTTPBackendRef +[TCPRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.TCPRoute +[UDPRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.UDPRoute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.GRPCRoute +[GRPCBackendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#GRPCBackendRef +[gRPC]: https://grpc.io/ +[TLSRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#tlsroute +[ReferenceGrant]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.ReferenceGrant +[SecretObjectReference]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#SecretObjectReference +[rate limiting]: /community/design/rate-limit +[request authentication]: ../security/jwt-authentication +[EnvoyProxy]: ../../../api/extension_types#envoyproxy +[resolving conflicts]: https://gateway-api.sigs.k8s.io/concepts/guidelines/?h=conflict#conflicts +[ExtensionRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#HTTPRouteFilterType +[grpc-filter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter +[http-filter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#HTTPRouteFilter diff --git a/site/content/en/v1.8/tasks/traffic/global-rate-limit.md b/site/content/en/v1.8/tasks/traffic/global-rate-limit.md new file mode 100644 index 0000000000..90ccae4422 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/global-rate-limit.md @@ -0,0 +1,1885 @@ +--- +title: "Global Rate Limit" +--- + +Rate limit is a feature that allows the user to limit the number of incoming requests to a predefined value based on attributes within the traffic flow. + +Here are some reasons why you may want to implement Rate limits + +* To prevent malicious activity such as DDoS attacks. +* To prevent applications and its resources (such as a database) from getting overloaded. +* To create API limits based on user entitlements. + +Envoy Gateway supports two types of rate limiting: [Global rate limiting][] and [Local rate limiting][]. + +[Global rate limiting][] applies a shared rate limit to the traffic flowing through all the instances of Envoy proxies where it is configured. +i.e. if the data plane has 2 replicas of Envoy running, and the rate limit is 10 requests/second, this limit is shared and will be hit +if 5 requests pass through the first replica and 5 requests pass through the second replica within the same second. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their rate limit intent. This instantiated resource +can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +**Note:** Limit is applied per route. Even if a [BackendTrafficPolicy][] targets a gateway, each route in that gateway +still has a separate rate limit bucket. For example, if a gateway has 2 routes, and the limit is 100r/s, then each route +has its own 100r/s rate limit bucket. + +## Prerequisites + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +### Install Redis + +* The global rate limit feature is based on [Envoy Ratelimit][] which requires a Redis instance as its caching layer. +Lets install a Redis deployment in the `redis-system` namespce. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Enable Global Rate limit in Envoy Gateway + +* The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and attaches it +using a `ConfigMap`. To enable global rate limit, we need to update this configuration to configure the Redis service +as the backend for rate limit. + +You can manually edit the `ConfigMap`: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: envoy-gateway-config + namespace: envoy-gateway-system +data: + envoy-gateway.yaml: | + apiVersion: gateway.envoyproxy.io/v1alpha1 + kind: EnvoyGateway + ... keep the existing configuration ... + rateLimit: + backend: + type: Redis + redis: + url: redis.redis-system.svc.cluster.local:6379 +``` + +Or use the `helm upgrade` command to update the configuration if you have installed Envoy Gateway using Helm: + +```bash +helm upgrade eg oci://docker.io/envoyproxy/gateway-helm \ + --set config.envoyGateway.rateLimit.backend.type=Redis \ + --set config.envoyGateway.rateLimit.backend.redis.url="redis.redis-system.svc.cluster.local:6379" \ + --reuse-values \ + -n envoy-gateway-system +``` + +{{< boilerplate rollout-envoy-gateway >}} + +## Rate Limit Specific User + +Here is an example of a rate limit implemented by the application developer to limit a specific user by matching on a custom `x-user-id` header +with a value set to `one`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-ratelimit -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Let's query `ratelimit.example/get` 4 times. We should receive a `200` response from the example Gateway for the first 3 requests +and then receive a `429` status code for the 4th request since the limit is set at 3 requests/Hour for the request which contains the header `x-user-id` +and value `one`. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: one" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +You should be able to send requests with the `x-user-id` header and a different value and receive successful responses from the server. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: two" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:39 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +``` + +## Rate Limit Distinct Users Except Admin + +Here is an example of a rate limit implemented by the application developer to limit distinct users who can be differentiated based on the +value in the `x-user-id` header. Here, user `one` (recognised from the traffic flow using the header `x-user-id` and value `one`) will be rate limited at 3 requests/hour +and so will user `two` (recognised from the traffic flow using the header `x-user-id` and value `two`). But if `x-user-id` is `admin`, it will not be rate limited even beyond 3 requests/hour. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Lets run the same command again with the header `x-user-id` and value `one` set in the request. We should the first 3 requests succeeding and +the 4th request being rate limited. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: one" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +You should see the same behavior when the value for header `x-user-id` is set to `two` and 4 requests are sent. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: two" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +But when the value for header `x-user-id` is set to `admin` and 4 requests are sent, all 4 of them should respond with 200 OK. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: admin" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +``` + +## Rate Limit All Requests + +This example shows you how to rate limit all requests matching the HTTPRoute rule at 3 requests/Hour by leaving the `clientSelectors` field unset. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +## Rate Limit Client IP Addresses + +Here is an example of a rate limit implemented by the application developer to limit distinct users who can be differentiated based on their + IP address (also reflected in the `X-Forwarded-For` header). + +Note: EG supports two kinds of rate limit for the IP address: Exact and Distinct. +* Exact means that all IP addresses within the specified Source IP CIDR share the same rate limit bucket. +* Distinct means that each IP address within the specified Source IP CIDR has its own rate limit bucket. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Tue, 28 Mar 2023 08:28:45 GMT +content-length: 512 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Tue, 28 Mar 2023 08:28:46 GMT +content-length: 512 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Tue, 28 Mar 2023 08:28:48 GMT +content-length: 512 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Tue, 28 Mar 2023 08:28:48 GMT +server: envoy +transfer-encoding: chunked + +``` + +## Rate Limit Based on Path + +Here is an example of a rate limit implemented by the application developer to limit requests based on the request path. In this case, we are limiting requests to `/api/users` to 3 requests/Hour. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The path matching supports three types: +- `Exact`: Matches the exact path (e.g., `/api/users`) +- `PathPrefix`: Matches paths with a specific prefix (e.g., `/api/`) +- `RegularExpression`: Matches paths using regex patterns (e.g., `/api/users/[0-9]+`) + +Let's query `/api/users` 4 times and `/api/products` 4 times. We should receive a `200` response for the first 3 requests to `/api/users` +and a `429` status code for the 4th request. Requests to `/api/products` should not be rate limited: + +```shell +# First, test the rate-limited path /api/users - 4 requests (4th should be rate limited) +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/users ; sleep 1; done + +# Now test a different path that should not be rate limited +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/products ; sleep 1; done +``` + +```console +# Requests to /api/users (rate limited after 3 requests) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +# Requests to /api/products (not rate limited) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:35 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy +``` + +You can see that requests to `/api/users` are rate limited after the 3rd request (returning 429), while all requests to `/api/products` succeed without any rate limit. + +## Rate Limit Based on HTTP Method + +Here is an example of a rate limit implemented by the application developer to limit requests based on the HTTP method. In this case, we are limiting POST requests to 3 requests/Hour. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Let's query the same path with POST and GET methods. We should receive a `200` response for the first 3 POST requests +and a `429` status code for the 4th POST request. GET requests should not be rate limited: + +```shell +# Send 4 POST requests - the 4th one should be rate limited +for i in {1..4}; do curl -X POST -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/data ; sleep 1; done + +# GET requests should not be rate limited +for i in {1..4}; do curl -X GET -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/data ; sleep 1; done +``` + +```console +# POST requests (rate limited after 3 requests) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +# GET requests (not rate limited) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:35 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy +``` + +You can see that POST requests are rate limited after the 3rd request (returning 429), while GET requests to the same path are not rate limited. + +## Rate Limit Jwt Claims + +Here is an example of a rate limit implemented by the application developer to limit distinct users who can be differentiated based on the value of the Jwt claims carried. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Get the JWT used for testing request authentication: + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode +``` + +```shell +TOKEN1=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/with-different-claim.jwt -s) && echo "$TOKEN1" | cut -d '.' -f2 - | base64 --decode +``` + +### Rate limit by carrying `TOKEN` + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "Authorization: Bearer $TOKEN" http://${GATEWAY_HOST}/foo ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:00:25 GMT +content-length: 561 +x-envoy-upstream-service-time: 0 +server: envoy + + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:00:26 GMT +content-length: 561 +x-envoy-upstream-service-time: 0 +server: envoy + + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:00:27 GMT +content-length: 561 +x-envoy-upstream-service-time: 0 +server: envoy + + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Mon, 12 Jun 2023 12:00:28 GMT +server: envoy +transfer-encoding: chunked + +``` + +### No Rate Limit by carrying `TOKEN1` + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "Authorization: Bearer $TOKEN1" http://${GATEWAY_HOST}/foo ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:02:34 GMT +content-length: 556 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:02:35 GMT +content-length: 556 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:02:36 GMT +content-length: 556 +x-envoy-upstream-service-time: 1 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 12 Jun 2023 12:02:37 GMT +content-length: 556 +x-envoy-upstream-service-time: 0 +server: envoy + +``` + +## Rate Limit Policy Merging + +This example demonstrates how to implement a layered rate limiting strategy using BackendTrafficPolicy merging. This approach allows platform teams to set global abuse prevention limits at the Gateway level, while application teams can define more specific rate limits for their individual routes. + +In this scenario: +- **Platform Team**: Manages a Gateway-level BackendTrafficPolicy that applies a global abuse rate limit (100 requests/second) across all traffic +- **Application Team**: Manages a Route-level BackendTrafficPolicy that applies a more restrictive limit (5 requests/minute) for their specific signup service + +The route-level policy uses `mergeType: StrategicMerge` to combine with the gateway-level policy, ensuring both limits are enforced. The global limit acts as an abuse prevention mechanism, while the route-specific limit protects the signup service from overload. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Key Configuration Details + +- **Gateway-level Policy**: Uses `shared: true` to create a shared rate limit bucket that applies across all routes in the Gateway +- **Route-level Policy**: Uses `shared: false` to create a dedicated rate limit bucket for this specific route +- **Merge Type**: The `mergeType: StrategicMerge` field enables the route policy to merge with the gateway policy rather than override it + +### Testing the Merged Rate Limits + +Let's verify that both rate limits are enforced. The signup service should be limited to 5 requests per minute, but also subject to the global 100 requests/second abuse limit. + +First, let's test the route-specific limit by sending 6 requests within a minute: + +```shell +for i in {1..6}; do curl -I --header "Host: signup.example" http://${GATEWAY_HOST}/signup ; sleep 1; done +``` + +You should see the first 5 requests succeed and the 6th request receive a `429 Too Many Requests` response: + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +... + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:36 GMT +server: envoy +transfer-encoding: chunked +``` + +The global abuse limit would activate if traffic across all routes in the Gateway exceeds 100 requests/second, providing an additional layer of protection managed by the platform team. + +### Use Cases and Team Responsibilities + +**Platform Team Responsibilities:** +- Define Gateway-level policies with global abuse rate limits +- Set reasonable baseline protections that apply to all applications +- Use `shared: true` for limits that should be enforced across multiple routes +- Monitor and adjust global limits based on infrastructure capacity + +**Application Team Responsibilities:** +- Define Route-level policies with application-specific rate limits +- Use `mergeType: StrategicMerge` to combine with platform policies +- Set `shared: false` for limits specific to their application's requirements +- Implement rate limits that protect their specific service from overload + +This layered approach ensures both infrastructure protection and application-specific controls work together effectively. + +### (Optional) Editing Kubernetes Resources settings for the Rate Limit Service + +* The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and provides the initial rate +limit kubernetes resources settings. such as `replicas` is 1, requests resources cpu is `100m`, memory is `512Mi`. the others +like container `image`, `securityContext`, `env` and pod `annotations` and `securityContext` can be modified by modifying the `ConfigMap`. + +* `tls.certificateRef` set the client certificate for redis server TLS connections. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +[Global Rate Limiting]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/global_rate_limiting +[Local rate limiting]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/local_rate_limiting +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Envoy Ratelimit]: https://github.com/envoyproxy/ratelimit +[EnvoyGateway]: ../../api/extension_types#envoygateway +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ diff --git a/site/content/en/v1.8/tasks/traffic/grpc-routing.md b/site/content/en/v1.8/tasks/traffic/grpc-routing.md new file mode 100644 index 0000000000..6cbd2f16e8 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/grpc-routing.md @@ -0,0 +1,293 @@ +--- +title: "GRPC Routing" +--- + +The [GRPCRoute][] resource allows users to configure gRPC routing by matching HTTP/2 traffic and forwarding it to backend gRPC servers. +To learn more about gRPC routing, refer to the [Gateway API documentation][]. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Installation + +Install the gRPC routing example resources: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/grpc-routing.yaml +``` + +The manifest installs a [GatewayClass][], [Gateway][], a Deployment, a Service, and a GRPCRoute resource. +The GatewayClass is a cluster-scoped resource that represents a class of Gateways that can be instantiated. + +__Note:__ Envoy Gateway is configured by default to manage a GatewayClass with +`controllerName: gateway.envoyproxy.io/gatewayclass-controller`. + +## Verification + +Check the status of the GatewayClass: + +```shell +kubectl get gc --selector=example=grpc-routing +``` + +The status should reflect "Accepted=True", indicating Envoy Gateway is managing the GatewayClass. + +A Gateway represents configuration of infrastructure. When a Gateway is created, [Envoy proxy][] infrastructure is +provisioned or configured by Envoy Gateway. The `gatewayClassName` defines the name of a GatewayClass used by this +Gateway. Check the status of the Gateway: + +```shell +kubectl get gateways --selector=example=grpc-routing +``` + +The status should reflect "Ready=True", indicating the Envoy proxy infrastructure has been provisioned. The status also +provides the address of the Gateway. This address is used later to test connectivity to proxied backend services. + +Check the status of the GRPCRoute: + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +The status for the GRPCRoute should surface "Accepted=True" and a `parentRef` that references the example Gateway. +The `example-route` matches any traffic for "grpc-example.com" and forwards it to the "yages" Service. + +## Testing the Configuration + +Before testing GRPC routing to the `yages` backend, get the Gateway's address. + +```shell +export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}') +``` + +Test GRPC routing to the `yages` backend using the [grpcurl][] command. + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +You should see the below response + +```shell +{ + "text": "pong" +} +``` + +Envoy Gateway also supports [gRPC-Web][] requests for this configuration. The below `curl` command can be used to send a grpc-Web request with over HTTP/2. You should receive the same response seen in the previous command. + +The data in the body `AAAAAAA=` is a base64 encoded representation of an empty message (data length 0) that the Ping RPC accepts. + +```shell +curl --http2-prior-knowledge -s ${GATEWAY_HOST}:80/yages.Echo/Ping -H 'Host: grpc-example.com' -H 'Content-Type: application/grpc-web-text' -H 'Accept: application/grpc-web-text' -XPOST -d'AAAAAAA=' | base64 -d +``` + +## GRPCRoute Match + +The `matches` field can be used to restrict the route to a specific set of requests based on GRPC's service and/or method names. +It supports two match types: `Exact` and `RegularExpression`. + +### Exact + +`Exact` match is the default match type. + +The following example shows how to match a request based on the service and method names for `grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo`, +as well as a match for all services with a method name `Ping` which matches `yages.Echo/Ping` in our deployment. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the GRPCRoute status: + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +Test GRPC routing to the `yages` backend using the [grpcurl][] command. + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +### RegularExpression + +The following example shows how to match a request based on the service and method names +with match type `RegularExpression`. It matches all the services and methods with pattern +`/.*.Echo/Pin.+`, which matches `yages.Echo/Ping` in our deployment. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the GRPCRoute status: + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +Test GRPC routing to the `yages` backend using the [grpcurl][] command. + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +## Configuring or disabling timeouts with `BackendTrafficPolicy` + +Streaming GRPC connections will often have lifespans longer than the default Envoy proxy timeout of 15 seconds. With Envoy Gateway, this timeout value can be configured using a [BackendTrafficPolicy][] resource: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: configure-timeout-policy +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: GRPCRoute + name: name-of-my-grpc-route + timeout: + http: + # Set to '0s' to disable timeouts + requestTimeout: 0s +``` + +[BackendTrafficPolicy]: ../../api/extension_types#backendtrafficpolicy +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[Envoy proxy]: https://www.envoyproxy.io/ +[grpcurl]: https://github.com/fullstorydev/grpcurl +[gRPC-Web]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2 diff --git a/site/content/en/v1.8/tasks/traffic/http-connect-tunnels.md b/site/content/en/v1.8/tasks/traffic/http-connect-tunnels.md new file mode 100644 index 0000000000..652e35e376 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-connect-tunnels.md @@ -0,0 +1,174 @@ +--- +title: "HTTP CONNECT Tunnels" +--- + +HTTP CONNECT tunnels are a mechanism that allows a client to establish a tunnel through an HTTP proxy server +to communicate directly with a destination server. This is commonly used for HTTPS traffic through proxies, +but can also be used for other protocols. + +This task will help you get started using HTTP Connect based tunnels using Envoy Gateway. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Proxy CONNECT request + +Envoy Gateway supports proxy CONNECT requests, allowing you to route traffic through a Gateway and HTTPRoute to a Backend service. + +```mermaid +graph LR + Client--CONNECT-->ProxyEnvoy[proxy the CONNECT request] + ProxyEnvoy[proxy the CONNECT request]--CONNECT-->Socat +``` + +Create a Gateway and HTTPRoute to route proxy CONNECT requests to a Backend service: + +```shell +cat <}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the Gateway: + +```shell +export PROXY_GATEWAY_HOST=$(kubectl get gateway/connect-proxy -o jsonpath='{.status.addresses[0].value}') +``` + +```shell +curl -ik -v -x ${PROXY_GATEWAY_HOST}:80 https://httpbin.org | grep -o ".*" +``` + +Verify the method from the access log: + +```shell +kubectl logs -n envoy-gateway-system deployments/envoy-default-connect-proxy-f7d7286e | tail -n 1 | jq | grep method +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=connect-proxy -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8080:80 & +``` + +```shell +curl -ik -v -x localhost:8080 https://httpbin.org +``` + +{{% /tab %}} +{{< /tabpane >}} + +## Clean up + +```shell +kubectl delete HTTPRoute connect-proxy +kubectl delete Gateway connect-proxy +kubectl delete BackendTrafficPolicy connect-proxy +kubectl delete deployment socat +kubectl delete service socat +kubectl delete serviceaccount socat +``` \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/traffic/http-redirect.md b/site/content/en/v1.8/tasks/traffic/http-redirect.md new file mode 100644 index 0000000000..b9b5e57a32 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-redirect.md @@ -0,0 +1,607 @@ +--- +title: "HTTP Redirects" +--- + +The [HTTPRoute][] resource can issue redirects to clients or rewrite paths sent upstream using filters. Note that +HTTPRoute rules cannot use both filter types at once. Currently, Envoy Gateway only supports __core__ +[HTTPRoute filters][] which consist of `RequestRedirect` and `RequestHeaderModifier` at the time of this writing. To +learn more about HTTP routing, refer to the [Gateway API documentation][]. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Redirects + +Redirects return HTTP 3XX responses to a client, instructing it to retrieve a different resource. A +[`RequestRedirect` filter][req_filter] instructs Gateways to emit a redirect response to requests that match the rule. +For example, to issue a permanent redirect (301) from HTTP to HTTPS, configure `requestRedirect.statusCode=301` and +`requestRedirect.scheme="https"`: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-to-https-filter-redirect -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `redirect.example/get` should result in a `301` response from the example Gateway and redirecting to the +configured redirect hostname. + +```console +$ curl -L -vvv --header "Host: redirect.example" "http://${GATEWAY_HOST}/get" +... +< HTTP/1.1 301 Moved Permanently +< location: https://www.example.com/get +... +``` + +If you followed the steps in the [Secure Gateways](../security/secure-gateways) task, you should be able to curl the redirect +location. + +## HTTP --> HTTPS + +Listeners expose the TLS setting on a per domain or subdomain basis. TLS settings of a listener are applied to all domains that satisfy the hostname criteria. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/CN=example.com' -keyout CA.key -out CA.crt +openssl req -out example.com.csr -newkey rsa:2048 -nodes -keyout tls.key -subj "/CN=example.com" +``` + +Generate a self-signed wildcard certificate for `example.com` with `*.example.com` extension + +```shell +cat <}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Check for any TLS certificate issues on the gateway. + +```bash +kubectl -n default describe gateway eg +``` + +Create two HTTPRoutes and attach them to the HTTP and HTTPS listeners using the [sectionName][] field. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Curl the example app through http listener: + +```bash +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +Curl the example app through https listener: + +```bash +curl -v -H 'Host:www.example.com' --resolve "www.example.com:443:$GATEWAY_HOST" \ +--cacert CA.crt https://www.example.com:443/get +``` + + +## Force HTTP --> HTTPS redirect + +All HTTP requests are forcibly redirected to HTTPS. Application Developers can't override this in their HTTPRoute resources. + +Assume Cluster Operators use the `eg` namespace to deploy the Gateway resource: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Define the gateway with both http and https listeners, but configure http listener to only accept routes from the same namespace: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Create the HTTPRoute to redirect requests to HTTPS and attach it to the HTTP listener using the [sectionName][] field. The HTTPRoute has to be in the same namespace as the Gateway to be accepted. +Do not set hostnames field in the HTTPRoute - it will accept any http request to any hostname and redirect it to the same hostname over https. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Any other HTTPRoute resources deployed by Application Developers in any other namespace will automatically attach to the https section only, no need to set sectionName for them. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + + +## Path Redirects + +Path redirects use an HTTP Path Modifier to replace either entire paths or path prefixes. For example, the HTTPRoute +below will issue a 302 redirect to all `path.redirect.example` requests whose path begins with `/get` to `/status/200`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-path-redirect -o yaml +``` + +Querying `path.redirect.example` should result in a `302` response from the example Gateway and a redirect location +containing the configured redirect path. + +Query the `path.redirect.example` host: + +```shell +curl -vvv --header "Host: path.redirect.example" "http://${GATEWAY_HOST}/get" +``` + +You should receive a `302` with a redirect location of `http://path.redirect.example/status/200`. + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[HTTPRoute filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutefilter +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[req_filter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httprequestredirectfilter +[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#commonroutespec diff --git a/site/content/en/v1.8/tasks/traffic/http-request-headers.md b/site/content/en/v1.8/tasks/traffic/http-request-headers.md new file mode 100644 index 0000000000..bd3c3c3c18 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-request-headers.md @@ -0,0 +1,627 @@ +--- +title: "HTTP Request Headers" +--- + +The [HTTPRoute][] resource can modify the headers of a request before forwarding it to the upstream service. HTTPRoute +rules cannot use both filter types at once. Currently, Envoy Gateway only supports __core__ [HTTPRoute filters][] which +consist of `RequestRedirect` and `RequestHeaderModifier` at the time of this writing. To learn more about HTTP routing, +refer to the [Gateway API documentation][]. + +A [`RequestHeaderModifier` filter][req_filter] instructs Gateways to modify the headers in requests that match the rule +before forwarding the request upstream. Note that the `RequestHeaderModifier` filter will only modify headers before the +request is sent from Envoy to the upstream service and will not affect response headers returned to the downstream +client. Header values support Envoy [format strings][envoy-format-strings], enabling dynamic values sourced from the +request and connection metadata. + +According to [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.1) and [RFC 7230](https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2), header names are case-insensitive, so each header only needs to be listed once (for example, `x-forwarded-for` also matches `X-Forwarded-For`). + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Adding Request Headers + +The `RequestHeaderModifier` filter can add new headers to a request before it is sent to the upstream. If the request +does not have the header configured by the filter, then that header will be added to the request. If the request already +has the header configured by the filter, then the value of the header in the filter will be appended to the value of the +header in the request. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +The `HTTPRoute]` status should indicate that it has been accepted and is bound to the example `Gateway`. + +```shell +kubectl get httproute/http-headers -o yaml +``` + +Get the `Gateway`'s address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `headers.example/get` should result in a `200` response from the example `Gateway` and the output from the +example app should indicate that the upstream example app received the header `add-header` with the value: +`something,foo` + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" --header "add-header: something" +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +... + "headers": { + "Accept": [ + "*/*" + ], + "Add-Header": [ + "something", + "foo" + ], +... +``` + +## Setting Request Headers + +Setting headers is similar to adding headers. If the request does not have the header configured by the filter, then it +will be added, but unlike [adding request headers](#adding-request-headers) which will append the value of the header if +the request already contains it, setting a header will cause the value to be replaced by the value configured in the +filter. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example `Gateway` and the output from the +example app should indicate that the upstream example app received the header `add-header` with the original value +`something` replaced by `foo`. + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" --header "set-header: something" +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< + "headers": { + "Accept": [ + "*/*" + ], + "Set-Header": [ + "foo" + ], +... +``` + +## Removing Request Headers + +Headers can be removed from a request by simply supplying a list of header names. + +Setting headers is similar to adding headers. If the request does not have the header configured by the filter, then it +will be added, but unlike [adding request headers](#adding-request-headers) which will append the value of the header if +the request already contains it, setting a header will cause the value to be replaced by the value configured in the +filter. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example `Gateway` and the output from the +example app should indicate that the upstream example app received the header `add-header`, but the header +`remove-header` that was sent by curl was removed before the upstream received the request. + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" --header "add-header: something" --header "remove-header: foo" +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< + + "headers": { + "Accept": [ + "*/*" + ], + "Add-Header": [ + "something" + ], +... +``` + +## Combining Filters + +Headers can be added/set/removed in a single filter on the same HTTPRoute and they will all perform as expected + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Early Header Modification + +In some cases, it could be necessary to modify headers before the proxy performs any sort of processing, routing or tracing. Envoy Gateway supports this functionality using the [ClientTrafficPolicy][] API. +The same Envoy [format strings][envoy-format-strings] used with `RequestHeaderModifier` values also apply to early +header modifications, allowing dynamic data to be populated ahead of routing. + +A [ClientTrafficPolicy][] resource can be attached to a [Gateway][] resource to configure early header modifications for all its routes. In the following example we will demonstrate how early header modification can be configured. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +Querying `headers.example/get` should result in a `200` response from the example `Gateway` and the output from the +example app should indicate that the upstream example app received the following headers: +- `early-added-header` contains early (ClientTrafficPolicy) and late (RouteFilter) values +- `early-set-header` contains only early (ClientTrafficPolicy) and late (RouteFilter) values, since the early modification overwritten the client value. +- `early-removed-header` contains only the late (RouteFilter) value, since the early modification deleted the client value. + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" --header "early-added-header: client" --header "early-set-header: client" --header "early-removed-header: client" +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< + + "headers": { + "Accept": [ + "*/*" + ], + "Early-Added-Header": [ + "client", + "early", + "late" + ], + "Early-Set-Header": [ + "early", + "late" + ], + "Early-removed-Header": [ + "late" + ] +... +``` + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[HTTPRoute filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutefilter +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[req_filter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpheaderfilter +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy +[envoy-format-strings]: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format diff --git a/site/content/en/v1.8/tasks/traffic/http-request-mirroring.md b/site/content/en/v1.8/tasks/traffic/http-request-mirroring.md new file mode 100644 index 0000000000..0d5c9f57a4 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-request-mirroring.md @@ -0,0 +1,444 @@ +--- +title: "HTTPRoute Request Mirroring" +--- + +The [HTTPRoute][] resource allows one or more [backendRefs][] to be provided. Requests will be routed to these upstreams. It is possible to divide the traffic between these backends using [Traffic Splitting][], but it is also possible to mirror requests to another Service instead. Request mirroring is accomplished using Gateway API's [HTTPRequestMirrorFilter][] on the `HTTPRoute`. + +When requests are made to a `HTTPRoute` that uses a `HTTPRequestMirrorFilter`, the response will never come from the `backendRef` defined in the filter. Responses from the mirror `backendRef` are always ignored. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Mirroring the Traffic + +Next, create a new `Deployment` and `Service` to mirror requests to. The following example will use +a second instance of the application deployed in the quickstart. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Then create an `HTTPRoute` that uses a `HTTPRequestMirrorFilter` to send requests to the original +service from the quickstart, and mirror request to the service that was just deployed. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-mirror -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `backends.example/get` should result in a `200` response from the example Gateway and the output from the +example app should indicate which pod handled the request. There is only one pod in the deployment for the example app +from the quickstart, so it will be the same on all subsequent requests. + +```console +$ curl -v --header "Host: backends.example" "http://${GATEWAY_HOST}/get" +... +> GET /get HTTP/1.1 +> Host: backends.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +... + + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-79665566f5-s589f" +... +``` + +Check the logs of the pods and you will see that the original deployment and the new deployment each got a request: + +```shell +$ kubectl logs deploy/backend && kubectl logs deploy/backend-2 +... +Starting server, listening on port 3000 (http) +Echoing back request made to /get to client (10.42.0.10:41566) +Starting server, listening on port 3000 (http) +Echoing back request made to /get to client (10.42.0.10:45096) +``` + +## Multiple BackendRefs + +When an `HTTPRoute` has multiple `backendRefs` and an `HTTPRequestMirrorFilter`, traffic splitting will still behave the same as it normally would for the main `backendRefs` while the `backendRef` of the `HTTPRequestMirrorFilter` will continue receiving mirrored copies of the incoming requests. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Multiple HTTPRequestMirrorFilters + +Multiple `HTTPRequestMirrorFilters` can be configured on the same `HTTPRoute` rule. Traffic splitting will work as expected, with mirrored requests being directed to `backendRefs` with `HTTPRequestMirrorFilter` filter and the actual requests to main `backendRefs`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + + +[Traffic Splitting]: ../http-traffic-splitting/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[backendRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#backendref +[HTTPRequestMirrorFilter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httprequestmirrorfilter diff --git a/site/content/en/v1.8/tasks/traffic/http-response-headers.md b/site/content/en/v1.8/tasks/traffic/http-response-headers.md new file mode 100644 index 0000000000..cd6723fd2c --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-response-headers.md @@ -0,0 +1,748 @@ +--- +title: "HTTP Response Headers" +--- + +The [HTTPRoute][] resource can modify the headers of a response before responding it to the downstream service. To learn +more about HTTP routing, refer to the [Gateway API documentation][]. + +A [`ResponseHeaderModifier` filter][req_filter] instructs Gateways to modify the headers in responses that match the +rule before responding to the downstream. Note that the `ResponseHeaderModifier` filter will only modify headers before +the response is returned from Envoy to the downstream client and will not affect request headers forwarding to the +upstream service. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Adding Response Headers + +The `ResponseHeaderModifier` filter can add new headers to a response before it is sent to the upstream. If the response +does not have the header configured by the filter, then that header will be added to the response. If the response +already has the header configured by the filter, then the value of the header in the filter will be appended to the +value of the header in the response. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-headers -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `headers.example/get` should result in a `200` response from the example Gateway and the output from the +example app should indicate that the downstream client received the header `add-header` with the value: `foo` + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" -H 'X-Echo-Set-Header: X-Foo: value1' +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> X-Echo-Set-Header: X-Foo: value1 +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< x-foo: value1 +< add-header: foo +< +... + "headers": { + "Accept": [ + "*/*" + ], + "X-Echo-Set-Header": [ + "X-Foo: value1" + ] +... +``` + +## Setting Response Headers + +Setting headers is similar to adding headers. If the response does not have the header configured by the filter, then it +will be added, but unlike [adding response headers](#adding-response-headers) which will append the value of the header +if the response already contains it, setting a header will cause the value to be replaced by the value configured in the +filter. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example Gateway and the output from the +example app should indicate that the downstream client received the header `set-header` with the original value `value1` +replaced by `foo`. + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" -H 'X-Echo-Set-Header: set-header: value1' +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> X-Echo-Set-Header: set-header: value1 +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< set-header: foo +< + "headers": { + "Accept": [ + "*/*" + ], + "X-Echo-Set-Header": [ + "set-header": value1" + ] +... +``` + +## Removing Response Headers + +Headers can be removed from a response by simply supplying a list of header names. + +Setting headers is similar to adding headers. If the response does not have the header configured by the filter, then it +will be added, but unlike [adding response headers](#adding-response-headers) which will append the value of the header +if the response already contains it, setting a header will cause the value to be replaced by the value configured in the +filter. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example Gateway and the output from the +example app should indicate that the header `remove-header` that was sent by curl was removed before the upstream +received the response. + +```console +$ curl -vvv --header "Host: headers.example" "http://${GATEWAY_HOST}/get" -H 'X-Echo-Set-Header: remove-header: value1' +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> X-Echo-Set-Header: remove-header: value1 +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< + + "headers": { + "Accept": [ + "*/*" + ], + "X-Echo-Set-Header": [ + "remove-header": value1" + ] +... +``` + +## Combining Filters + +Headers can be added/set/removed in a single filter on the same HTTPRoute and they will all perform as expected + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Late Header Modification + +In some cases it may be necessary to modify response headers globally. For example, you may want to add a security header (such as `Strict-Transport-Security`) to all routes. Envoy Gateway supports this functionality using the [ClientTrafficPolicy][] API. + +A [ClientTrafficPolicy][] resource can be attached to a [Gateway][] resource to configure late header modification for all its routes. In the following example we will demonstrate how late header modification can be configured. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example `Gateway` with the following headers: + +- `late-added-header` contains backend (example app), filter (RouteFilter), and late (ClientTrafficPolicy) values. +- `late-set-header` contains only the late value, since the ClientTrafficPolicy overwrote all others. +- `late-removed-header` is missing entirely - again, due to the ClientTrafficPolicy. + +```console +$ curl -vvv "http://${GATEWAY_HOST}/get" \ + --header "Host: headers.example" \ + --header "X-Echo-Set-Header: late-added-header:backend,late-set-header:backend,late-removed-header:backend" + +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> X-Echo-Set-Header: late-added-header:backend,late-set-header:backend,late-removed-header:backend +> + +< HTTP/1.1 200 OK +< content-type: application/json +< late-added-header: backend +< late-added-header: filter +< late-added-header: late +< late-set-header: late +< +... +``` + +## Adding Headers If Absent + +In some cases you may want to set default headers at the gateway level that can be overridden by backend responses. For example, you may want to add a default `Content-Security-Policy` header to all responses, but allow specific backends to provide their own policy. The `addIfAbsent` action adds headers only when they don't already exist in the response. + +Unlike `add` which appends to existing headers, or `set` which overwrites them, `addIfAbsent` is a no-op if the header is already present. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `headers.example/get` should result in a `200` response from the example `Gateway`. When the backend does not set these headers, the default values from the `ClientTrafficPolicy` are used: + +```console +$ curl -vvv "http://${GATEWAY_HOST}/get" \ + --header "Host: headers.example" + +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> + +< HTTP/1.1 200 OK +< content-type: application/json +< content-security-policy: default-src 'self' +< x-frame-options: DENY +< +... +``` + +However, when the backend sets these headers, the backend values are preserved and the gateway defaults are not applied: + +```console +$ curl -vvv "http://${GATEWAY_HOST}/get" \ + --header "Host: headers.example" \ + --header "X-Echo-Set-Header: content-security-policy:default-src 'self' https://trusted.example.com" + +... +> GET /get HTTP/1.1 +> Host: headers.example +> User-Agent: curl/7.81.0 +> Accept: */* +> X-Echo-Set-Header: content-security-policy:default-src 'self' https://trusted.example.com +> + +< HTTP/1.1 200 OK +< content-type: application/json +< content-security-policy: default-src 'self' https://trusted.example.com +< x-frame-options: DENY +< +... +``` + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[req_filter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpheaderfilter +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy diff --git a/site/content/en/v1.8/tasks/traffic/http-routing.md b/site/content/en/v1.8/tasks/traffic/http-routing.md new file mode 100644 index 0000000000..a54d75e47c --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-routing.md @@ -0,0 +1,399 @@ +--- +title: "HTTP Routing" +--- + +The [HTTPRoute][] resource allows users to configure HTTP routing by matching HTTP traffic and forwarding it to +Kubernetes backends. Currently, the only backend supported by Envoy Gateway is a [Service](https://kubernetes.io/docs/concepts/services-networking/service/) resource. This task +shows how to route traffic based on host, header, and path fields and forward the traffic to different Kubernetes +[Services](https://kubernetes.io/docs/concepts/services-networking/service/). To learn more about HTTP routing, refer to the [Gateway API documentation][]. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Installation + +Install the HTTP routing example resources: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/http-routing.yaml +``` + +The manifest installs a [GatewayClass][], [Gateway][], four [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), four [Services](https://kubernetes.io/docs/concepts/services-networking/service/), and three [HTTPRoute][] resources. +The [GatewayClass][] is a cluster-scoped resource that represents a class of [Gateway][]s that can be instantiated. + +__Note:__ Envoy Gateway is configured by default to manage a GatewayClass with +`controllerName: gateway.envoyproxy.io/gatewayclass-controller`. + +## Verification + +Check the status of the GatewayClass: + +```shell +kubectl get gc --selector=example=http-routing +``` + +The status should reflect "Accepted=True", indicating Envoy Gateway is managing the GatewayClass. + +A [Gateway][] represents configuration of infrastructure. When a [Gateway][] is created, [Envoy proxy][] infrastructure is +provisioned or configured by Envoy Gateway. The `gatewayClassName` defines the name of a [GatewayClass][] used by this +[Gateway][]. Check the status of the [Gateway][]: + +```shell +kubectl get gateways --selector=example=http-routing +``` + +The status should reflect "Ready=True", indicating the Envoy proxy infrastructure has been provisioned. The status also +provides the address of the Gateway. This address is used later to test connectivity to proxied backend +services. + +The three HTTPRoute resources create routing rules on the Gateway. In order to receive traffic from a Gateway, +an HTTPRoute must be configured with `parentRefs` which reference the parent Gateway(s) that it should be attached to. +An HTTPRoute can match against a [single set of hostnames][spec]. These hostnames are matched before any other matching +within the HTTPRoute takes place. Since `example.com`, `foo.example.com`, and `bar.example.com` are separate hosts with +different routing requirements, each is deployed as its own HTTPRoute - `example-route`, `foo-route`, and `bar-route`. + +Check the status of the HTTPRoutes: + +```shell +kubectl get httproutes --selector=example=http-routing -o yaml +``` + +The status for each HTTPRoute should surface "Accepted=True" and a `parentRef` that references the example Gateway. +The `example-route` matches any traffic for "example.com" and forwards it to the "example-svc" Service. + +## Testing the Configuration + +Before testing HTTP routing to the `example-svc` backend, get the Gateway's address. + +```shell +export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}') +``` + +Test HTTP routing to the `example-svc` backend. + +```shell +curl -vvv --header "Host: example.com" "http://${GATEWAY_HOST}/" +``` + +A `200` status code should be returned and the body should include `"pod": "example-backend-*"` indicating the traffic +was routed to the example backend service. If you change the hostname to a hostname not represented in any of the +HTTPRoutes, e.g. "www.example.com", the HTTP traffic will not be routed and a `404` should be returned. + +The `foo-route` matches any traffic for `foo.example.com` and applies its routing rules to forward the traffic to the +"foo-svc" Service. Since there is only one path prefix match for `/login`, only `foo.example.com/login/*` traffic will +be forwarded. Test HTTP routing to the `foo-svc` backend. + +```shell +curl -vvv --header "Host: foo.example.com" "http://${GATEWAY_HOST}/login" +``` + +A `200` status code should be returned and the body should include `"pod": "foo-backend-*"` indicating the traffic +was routed to the foo backend service. Traffic to any other paths that do not begin with `/login` will not be matched by +this HTTPRoute. Test this by removing `/login` from the request. + +```shell +curl -vvv --header "Host: foo.example.com" "http://${GATEWAY_HOST}/" +``` + +The HTTP traffic will not be routed and a `404` should be returned. + +Similarly, the `bar-route` HTTPRoute matches traffic for `bar.example.com`. All traffic for this hostname will be +evaluated against the routing rules. The most specific match will take precedence which means that any traffic with the +`env:canary` header will be forwarded to `bar-svc-canary` and if the header is missing or not `canary` then it'll be +forwarded to `bar-svc`. Test HTTP routing to the `bar-svc` backend. + +```shell +curl -vvv --header "Host: bar.example.com" "http://${GATEWAY_HOST}/" +``` + +A `200` status code should be returned and the body should include `"pod": "bar-backend-*"` indicating the traffic +was routed to the foo backend service. + +Test HTTP routing to the `bar-canary-svc` backend by adding the `env: canary` header to the request. + +```shell +curl -vvv --header "Host: bar.example.com" --header "env: canary" "http://${GATEWAY_HOST}/" +``` + +A `200` status code should be returned and the body should include `"pod": "bar-canary-backend-*"` indicating the +traffic was routed to the foo backend service. + +## JWT Claims Based Routing + +Users can route to a specific backend by matching on JWT claims. +This can be achieved, by defining a [SecurityPolicy](../../../api/extension_types#securitypolicy) with a jwt configuration that does the following +* Converts jwt claims to headers, which can be used for header based routing +* Sets the recomputeRoute field to `true`. This is required so that the incoming request matches on a fallback/catch all route where the JWT can be authenticated, the claims from the JWT can be converted to headers, and then the route match can be recomputed to match based on the updated headers. + +For this feature to work please make sure +* you have a fallback route rule defined, the backend for this route rule can be invalid. +* The SecurityPolicy is applied to both the fallback route as well as the route with the claim header matches, to avoid spoofing. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Get the JWT used for testing request authentication: + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode +``` + +Test routing to the `foo-svc` backend by specifying a JWT Token with a claim `name: John Doe`. + +```shell +curl -sS -H "Host: foo.example.com" -H "Authorization: Bearer $TOKEN" "http://${GATEWAY_HOST}/login" | jq .pod +``` +The request should return the pod name, for example `foo-backend-6df8cc6b9f-fmwcg` + + +Get another JWT used for testing request authentication: + +```shell +TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/with-different-claim.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode +``` + +Test HTTP routing to the `bar-svc` backend by specifying a JWT Token with a claim `name: Tom`. + +```shell +curl -sS -H "Host: bar.example.com" -H "Authorization: Bearer $TOKEN" "http://${GATEWAY_HOST}/" | jq .pod +``` +The request should return the pod name, for example `bar-backend-6688b8944c-s8htr` + +## Cookie Based Routing + +Users can route to a specific backend by matching on HTTP cookies. This is +achieved by defining an +[HTTPRouteFilter](../../../api/extension_types#httproutefilter) that specifies +the cookie matching criteria and referencing it in an [HTTPRoute][] rule. + +{{< tabpane text=true >}} {{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Test HTTP routing to the `foo-svc` backend by specifying the cookie +`choco=chip`. + +```shell +curl -vvv --header "Host: foo.example.com" --cookie "choco=chip" "http://${GATEWAY_HOST}/" +``` + +A `200` status code should be returned and the body should include +`"pod": "foo-backend-*"` indicating the traffic was routed to the foo backend +service. + +If the cookie is missing or has a different value, the request will not match +and a `404` should be returned. + +```shell +curl -vvv --header "Host: foo.example.com" "http://${GATEWAY_HOST}/" +``` + +The HTTP traffic will not be routed and a `404` should be returned. + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[Envoy proxy]: https://www.envoyproxy.io/ +[spec]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutespec diff --git a/site/content/en/v1.8/tasks/traffic/http-timeouts.md b/site/content/en/v1.8/tasks/traffic/http-timeouts.md new file mode 100644 index 0000000000..ac0ad7cc1b --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-timeouts.md @@ -0,0 +1,198 @@ +--- +title: "HTTP Timeouts" +--- + +The default request timeout is set to 15 seconds in Envoy Proxy. +The [HTTPRouteTimeouts][] resource allows users to configure request timeouts for an [HTTPRouteRule][]. +This task shows you how to configure timeouts. + +The [HTTPRouteTimeouts][] supports two kinds of timeouts: +- **request**: Request specifies the maximum duration for a gateway to respond to an HTTP request. +- **backendRequest**: BackendRequest specifies a timeout for an individual request from the gateway to a backend. + +__Note:__ The Request duration must be >= BackendRequest duration + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Verification + +backend has the ability to delay responses; we use it as the backend to control response time. + +### request timeout +We configure the backend to delay responses by 3 seconds, then we set the request timeout to 4 seconds. Envoy Gateway will successfully respond to the request. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +curl --header "Host: timeout.example.com" http://${GATEWAY_HOST}/?delay=3s -I +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Mon, 04 Mar 2024 02:34:21 GMT +content-length: 480 +``` + +Then we set the request timeout to 2 seconds. In this case, Envoy Gateway will respond with a timeout. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +curl --header "Host: timeout.example.com" http://${GATEWAY_HOST}/?delay=3s -v +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 127.0.0.1 (127.0.0.1) port 80 +> GET /?delay=3s HTTP/1.1 +> Host: timeout.example.com +> User-Agent: curl/8.6.0 +> Accept: */* +> + + +< HTTP/1.1 504 Gateway Timeout +< content-length: 24 +< content-type: text/plain +< date: Mon, 04 Mar 2024 02:35:03 GMT +< +* Connection #0 to host 127.0.0.1 left intact +upstream request timeout +``` + +[HTTPRouteTimeouts]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutetimeouts +[HTTPRouteRule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httprouterule diff --git a/site/content/en/v1.8/tasks/traffic/http-traffic-splitting.md b/site/content/en/v1.8/tasks/traffic/http-traffic-splitting.md new file mode 100644 index 0000000000..653c16dff6 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-traffic-splitting.md @@ -0,0 +1,526 @@ +--- +title: "HTTPRoute Traffic Splitting" +--- + +The [HTTPRoute][] resource allows one or more [backendRefs][] to be provided. Requests will be routed to these upstreams +if they match the rules of the HTTPRoute. If an invalid backendRef is configured, then HTTP responses will be returned +with status code `500` for all requests that would have been sent to that backend. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Single backendRef + +When a single backendRef is configured in a HTTPRoute, it will receive 100% of the traffic. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-headers -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `backends.example/get` should result in a `200` response from the example Gateway and the output from the +example app should indicate which pod handled the request. There is only one pod in the deployment for the example app +from the quickstart, so it will be the same on all subsequent requests. + +```console +$ curl -vvv --header "Host: backends.example" "http://${GATEWAY_HOST}/get" +... +> GET /get HTTP/1.1 +> Host: backends.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +... + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-79665566f5-s589f" +... +``` + +## Multiple backendRefs + +If multiple backendRefs are configured, then traffic will be split between the backendRefs equally unless a weight is +configured. + +First, create a second instance of the example app from the quickstart: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Then create an HTTPRoute that uses both the app from the quickstart and the second instance that was just created + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `backends.example/get` should result in `200` responses from the example Gateway and the output from the +example app that indicates which pod handled the request should switch between the first pod and the second one from the +new deployment on subsequent requests. + +```console +$ curl -vvv --header "Host: backends.example" "http://${GATEWAY_HOST}/get" +... +> GET /get HTTP/1.1 +> Host: backends.example +> User-Agent: curl/7.81.0 +> Accept: */* +> add-header: something +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< content-length: 474 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +... + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-75bcd4c969-lsxpz" +... +``` + +## Weighted backendRefs + +If multiple backendRefs are configured and an un-even traffic split between the backends is desired, then the `weight` +field can be used to control the weight of requests to each backend. If weight is not configured for a backendRef it is +assumed to be `1`. + +The [weight field in a backendRef][backendRefs] controls the distribution of the traffic split. The proportion of +requests to a single backendRef is calculated by dividing its `weight` by the sum of all backendRef weights in the +HTTPRoute. The weight is not a percentage and the sum of all weights does not need to add up to 100. + +The HTTPRoute below will configure the gateway to send 80% of the traffic to the backend service, and 20% to the +backend-2 service. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +## Invalid backendRefs + +backendRefs can be considered invalid for the following reasons: + +- The `group` field is configured to something other than `""`. Currently, only the core API group (specified by + omitting the group field or setting it to an empty string) is supported +- The `kind` field is configured to anything other than `Service`. Envoy Gateway currently only supports Kubernetes + Service backendRefs +- The backendRef configures a service with a `namespace` not permitted by any existing ReferenceGrants +- The `port` field is not configured or is configured to a port that does not exist on the Service +- The named Service configured by the backendRef cannot be found + +Modifying the above example to make the backend-2 backendRef invalid by using a port that does not exist on the Service +will result in 80% of the traffic being sent to the backend service, and 20% of the traffic receiving an HTTP response +with status code `500`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Querying `backends.example/get` should result in `200` responses 80% of the time, and `500` responses 20% of the time. + +```console +$ curl -vvv --header "Host: backends.example" "http://${GATEWAY_HOST}/get" +> GET /get HTTP/1.1 +> Host: backends.example +> User-Agent: curl/7.81.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 500 Internal Server Error +< server: envoy +< content-length: 0 +< +``` + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[backendRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#backendref diff --git a/site/content/en/v1.8/tasks/traffic/http-urlrewrite.md b/site/content/en/v1.8/tasks/traffic/http-urlrewrite.md new file mode 100644 index 0000000000..cbd15d816b --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http-urlrewrite.md @@ -0,0 +1,747 @@ +--- +title: "HTTP URL Rewrite" +--- + +[HTTPURLRewriteFilter][] defines a filter that modifies a request during forwarding. At most one of these filters may be +used on a Route rule. This MUST NOT be used on the same Route rule as a HTTPRequestRedirect filter. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Rewrite URL Prefix Path + +You can configure to rewrite the prefix in the url like below. In this example, any curls to +`http://${GATEWAY_HOST}/get/xxx` will be rewritten to `http://${GATEWAY_HOST}/replace/xxx`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-url-rewrite -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Querying `http://${GATEWAY_HOST}/get/origin/path` should rewrite to +`http://${GATEWAY_HOST}/replace/origin/path`. + +```console +$ curl -L -vvv --header "Host: path.rewrite.example" "http://${GATEWAY_HOST}/get/origin/path" +... +> GET /get/origin/path HTTP/1.1 +> Host: path.rewrite.example +> User-Agent: curl/7.85.0 +> Accept: */* +> + +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Wed, 21 Dec 2022 11:03:28 GMT +< content-length: 503 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/replace/origin/path", + "host": "path.rewrite.example", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.85.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Original-Path": [ + "/get/origin/path" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "fd84b842-9937-4fb5-83c7-61470d854b90" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-6fdd4b9bd8-8vlc5" +... +``` + +You can see that the `X-Envoy-Original-Path` is `/get/origin/path`, but the actual path is `/replace/origin/path`. + +## Rewrite URL Full Path + +You can configure to rewrite the fullpath in the url like below. In this example, any request sent to +`http://${GATEWAY_HOST}/get/origin/path/xxxx` will be rewritten to +`http://${GATEWAY_HOST}/force/replace/fullpath`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-url-rewrite -o yaml +``` + +Querying `http://${GATEWAY_HOST}/get/origin/path/extra` should rewrite the request to +`http://${GATEWAY_HOST}/force/replace/fullpath`. + +```console +$ curl -L -vvv --header "Host: path.rewrite.example" "http://${GATEWAY_HOST}/get/origin/path/extra" +... +> GET /get/origin/path/extra HTTP/1.1 +> Host: path.rewrite.example +> User-Agent: curl/7.85.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Wed, 21 Dec 2022 11:09:31 GMT +< content-length: 512 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/force/replace/fullpath", + "host": "path.rewrite.example", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.85.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Envoy-Original-Path": [ + "/get/origin/path/extra" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "8ab774d6-9ffa-4faa-abbb-f45b0db00895" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-6fdd4b9bd8-8vlc5" +... +``` + +You can see that the `X-Envoy-Original-Path` is `/get/origin/path/extra`, but the actual path is +`/force/replace/fullpath`. + +## Rewrite URL Path with Regex + +In addition to core Gateway-API rewrite options, Envoy Gateway supports extended rewrite options through the [HTTPRouteFilter][] API. +The `HTTPRouteFilter` API can be configured to use [RE2][]-compatible regex matchers and substitutions to rewrite a portion of the url. +In the example below, requests sent to `http://${GATEWAY_HOST}/service/xxx/yyy` (where `xxx` is a single path portion and `yyy` is one or more path portions) +are rewritten to `http://${GATEWAY_HOST}/yyy/instance/xxx`. The entire path is matched and rewritten using capture groups. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-url-regex-rewrite -o yaml +``` + +Querying `http://${GATEWAY_HOST}/service/foo/v1/api` should rewrite the request to +`http://${GATEWAY_HOST}/v1/api/instance/foo`. + +```console +$ curl -L -vvv --header "Host: path.regex.rewrite.example" "http://${GATEWAY_HOST}/service/foo/v1/api" +... +> GET /service/foo/v1/api HTTP/1.1 +> Host: path.regex.rewrite.example +> User-Agent: curl/8.7.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Mon, 16 Sep 2024 18:49:48 GMT +< content-length: 482 +< +{ + "path": "/v1/api/instance/foo", + "host": "path.regex.rewrite.example", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "10.244.0.37" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "24a5958f-1bfa-4694-a9c1-807d5139a18a" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-765694d47f-lzmpm" +... +``` + +You can see that the path is rewritten from `/service/foo/v1/api`, to `/v1/api/instance/foo`. + +## Rewrite Host Name + +You can configure to rewrite the hostname like below. In this example, any requests sent to +`http://${GATEWAY_HOST}/get` with `--header "Host: path.rewrite.example"` will rewrite host into `envoygateway.io`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-url-rewrite -o yaml +``` + +Querying `http://${GATEWAY_HOST}/get` with `--header "Host: path.rewrite.example"` will rewrite host into +`envoygateway.io`. + +```console +$ curl -L -vvv --header "Host: path.rewrite.example" "http://${GATEWAY_HOST}/get" +... +> GET /get HTTP/1.1 +> Host: path.rewrite.example +> User-Agent: curl/7.85.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Wed, 21 Dec 2022 11:15:15 GMT +< content-length: 481 +< x-envoy-upstream-service-time: 0 +< server: envoy +< +{ + "path": "/get", + "host": "envoygateway.io", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.85.0" + ], + "X-Envoy-Expected-Rq-Timeout-Ms": [ + "15000" + ], + "X-Forwarded-Host": [ + "path.rewrite.example" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "39aa447c-97b9-45a3-a675-9fb266ab1af0" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-6fdd4b9bd8-8vlc5" +... +``` + +You can see that the `X-Forwarded-Host` is `path.rewrite.example`, but the actual host is `envoygateway.io`. + +## Rewrite URL Host Name by Header or Backend + +In addition to core Gateway-API rewrite options, Envoy Gateway supports extended rewrite options through the [HTTPRouteFilter][] API. +The `HTTPRouteFilter` API can be configured to rewrite the Host header value to: +- The value of a different request header +- The DNS name of the backend that the request is routed to + +In the following example, the host header is rewritten to the value of the x-custom-host header. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-filter-header-host-rewrite -o yaml +``` + +Querying `http://${GATEWAY_HOST}/header` and providing a custom host rewrite header x-custom-host should rewrite the +request host header to the value of the x-custom-host header. + +```console +$ curl -L -vvv --header "Host: host.header.rewrite.example" --header "x-custom-host: foo" "http://${GATEWAY_HOST}/header" +... +> GET /header HTTP/1.1 +> Host: host.header.rewrite.example +> User-Agent: curl/8.7.1 +> Accept: */* +> x-custom-host: foo +> +* Request completely sent off +< HTTP/1.1 200 OK +< +{ + "path": "/header", + "host": "foo", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "X-Custom-Host": [ + "foo" + ], + "X-Forwarded-Host": [ + "host.header.rewrite.example" + ], + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-765694d47f-5t6f2" +... +``` + +You can see that the host is rewritten from `host.header.rewrite.example`, to the value of the provided +`x-custom-host` header `foo`. The original host header is preserved in the `X-Forwarded-Host` header. + +## Disabling X-Forwarded-Host Header + +By default, when hostname rewriting is configured, Envoy Gateway appends the original `Host` header value to the +`X-Forwarded-Host` header on upstream requests. You can disable this behavior by setting `appendXForwardedHost` to +`false` in the [HTTPRouteFilter][] API. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +When `appendXForwardedHost` is set to `false`, the `X-Forwarded-Host` header will not be added to the upstream +request even though the host is being rewritten. This is useful when the upstream service does not need or should +not receive the original host information. + +[HTTPURLRewriteFilter]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpurlrewritefilter +[HTTPRouteFilter]: ../../../api/extension_types#httproutefilter +[RE2]: https://github.com/google/re2/wiki/Syntax diff --git a/site/content/en/v1.8/tasks/traffic/http3.md b/site/content/en/v1.8/tasks/traffic/http3.md new file mode 100644 index 0000000000..fc8e087365 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/http3.md @@ -0,0 +1,137 @@ +--- +title: "HTTP3" +--- + +This task will help you get started using HTTP3 using EG. +This task uses a self-signed CA, so it should be used for testing and demonstration purposes only. + +## Prerequisites + +- OpenSSL to generate TLS assets. + +## Installation + +{{< boilerplate prerequisites >}} + +## TLS Certificates + +Generate the certificates and keys used by the Gateway to terminate client TLS connections. + +Create a root certificate and private key to sign certificates: + +```shell +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt +``` + +Create a certificate and a private key for `www.example.com`: + +```shell +openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" +openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt +``` + +Store the cert/key in a Secret: + +```shell +kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt +``` + +Update the [Gateway][] from the Quickstart to include an HTTPS listener that listens on port `443` and references the +`example-cert` [Secret][]: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - kind: Secret + group: "" + name: example-cert + ' +``` + +Apply the following [ClientTrafficPolicy][] to enable HTTP3 + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the [Gateway][] status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## Testing + +{{< tabpane text=true >}} +{{% tab header="With External LoadBalancer Support" %}} + +Get the External IP of the [Gateway][]: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Query the example app through the [Gateway][]: + +The below example uses a custom docker image with custom `curl` binary with built-in http3. + +```shell +docker run --net=host --rm ghcr.io/macbre/curl-http3 curl -kv --http3 -HHost:www.example.com --resolve "www.example.com:443:${GATEWAY_HOST}" https://www.example.com/get +``` + +{{% /tab %}} +{{% tab header="Without LoadBalancer Support" %}} + +It is not possible at the moment to port-forward UDP protocol in kubernetes service +check out https://github.com/kubernetes/kubernetes/issues/47862. +Hence we need external loadbalancer to test this feature out. + +{{% /tab %}} +{{< /tabpane >}} + +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy +[Secret]: https://kubernetes.io/docs/concepts/configuration/secret/ diff --git a/site/content/en/v1.8/tasks/traffic/load-balancing.md b/site/content/en/v1.8/tasks/traffic/load-balancing.md new file mode 100644 index 0000000000..7da465dd72 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/load-balancing.md @@ -0,0 +1,1052 @@ +--- +title: "Load Balancing" +--- + +[Envoy load balancing][] is a way of distributing traffic between multiple hosts within a single upstream cluster +in order to effectively make use of available resources. + +Envoy Gateway supports the following load balancing policies: + +- **Round Robin**: a simple policy in which each available upstream host is selected in round robin order. +- **Random**: load balancer selects a random available host. +- **Least Request**: load balancer uses different algorithms depending on whether hosts have the same or different weights. +- **Consistent Hash**: load balancer implements consistent hashing to upstream hosts. + +Additionally, Envoy Gateway supports **Endpoint Override** functionality that allows endpoint selection based on headers or metadata, which can be used with any of the above load balancing policies as a fallback. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their desired load balancing polices. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. If `loadBalancer` is not specified in [BackendTrafficPolicy][], the default load balancing policy is `Least Request`. + +## Prerequisites + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +For better testing the load balancer, you can add more hosts in upstream cluster by increasing the replicas of one deployment: + +```shell +kubectl patch deployment backend -n default -p '{"spec": {"replicas": 4}}' +``` + +### Install the hey load testing tool + +Install the `Hey` CLI tool, this tool will be used to generate load and measure response times. + +Follow the installation instruction from the [Hey project] docs. + +## Round Robin + +This example will create a Load Balancer with Round Robin policy via [BackendTrafficPolicy][]. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The `hey` tool will be used to generate 100 concurrent requests. + +```shell +hey -n 100 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/round +``` + +```console +Summary: + Total: 0.0487 secs + Slowest: 0.0440 secs + Fastest: 0.0181 secs + Average: 0.0307 secs + Requests/sec: 2053.1676 + + Total data: 50500 bytes + Size/request: 505 bytes + +Response time histogram: + 0.018 [1] |■■ + 0.021 [2] |■■■■ + 0.023 [10] |■■■■■■■■■■■■■■■■■■■■■■ + 0.026 [16] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.028 [7] |■■■■■■■■■■■■■■■■ + 0.031 [10] |■■■■■■■■■■■■■■■■■■■■■■ + 0.034 [17] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.036 [18] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.039 [11] |■■■■■■■■■■■■■■■■■■■■■■■■ + 0.041 [6] |■■■■■■■■■■■■■ + 0.044 [2] |■■■■ +``` + +As a result, you can see all available upstream hosts receive traffics evenly. + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-2gfp7: received 26 requests +backend-69fcff487f-69g8c: received 25 requests +backend-69fcff487f-bqwpr: received 24 requests +backend-69fcff487f-kbn8l: received 25 requests +``` + +You should note that this results may vary, the output here is for reference purpose only. + +## Random + +This example will create a Load Balancer with Random policy via [BackendTrafficPolicy][]. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The `hey` tool will be used to generate 1000 concurrent requests. + +```shell +hey -n 1000 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/random +``` + +```console +Summary: + Total: 0.2624 secs + Slowest: 0.0851 secs + Fastest: 0.0007 secs + Average: 0.0179 secs + Requests/sec: 3811.3020 + + Total data: 506000 bytes + Size/request: 506 bytes + +Response time histogram: + 0.001 [1] | + 0.009 [421] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.018 [219] |■■■■■■■■■■■■■■■■■■■■■ + 0.026 [118] |■■■■■■■■■■■ + 0.034 [64] |■■■■■■ + 0.043 [73] |■■■■■■■ + 0.051 [41] |■■■■ + 0.060 [22] |■■ + 0.068 [19] |■■ + 0.077 [13] |■ + 0.085 [9] |■ +``` + +As a result, you can see all available upstream hosts receive traffics randomly. + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-bf6lm: received 246 requests +backend-69fcff487f-gwmqk: received 256 requests +backend-69fcff487f-mzngr: received 230 requests +backend-69fcff487f-xghqq: received 268 requests +``` + +You should note that this results may vary, the output here is for reference purpose only. + +## Least Request + +This example will create a Load Balancer with Least Request policy via [BackendTrafficPolicy][]. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The `hey` tool will be used to generate 100 concurrent requests. + +```shell +hey -n 100 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/least +``` + +```console +Summary: + Total: 0.0489 secs + Slowest: 0.0479 secs + Fastest: 0.0054 secs + Average: 0.0297 secs + Requests/sec: 2045.9317 + + Total data: 50500 bytes + Size/request: 505 bytes + +Response time histogram: + 0.005 [1] |■■ + 0.010 [1] |■■ + 0.014 [8] |■■■■■■■■■■■■■■■ + 0.018 [6] |■■■■■■■■■■■ + 0.022 [11] |■■■■■■■■■■■■■■■■■■■■ + 0.027 [7] |■■■■■■■■■■■■■ + 0.031 [15] |■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.035 [13] |■■■■■■■■■■■■■■■■■■■■■■■■ + 0.039 [22] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.044 [12] |■■■■■■■■■■■■■■■■■■■■■■ + 0.048 [4] |■■■■■■■ +``` + +As a result, you can see all available upstream hosts receive traffics randomly, +and host `backend-69fcff487f-6l2pw` receives fewer requests than others. + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-59hvs: received 24 requests +backend-69fcff487f-6l2pw: received 19 requests +backend-69fcff487f-ktsx4: received 30 requests +backend-69fcff487f-nqxc7: received 27 requests +``` + +If you send one more requests to the `${GATEWAY_HOST}/least`, you can tell that host `backend-69fcff487f-6l2pw` is very likely +to get the attention of load balancer and receive this request. + +```console +backend-69fcff487f-59hvs: received 24 requests +backend-69fcff487f-6l2pw: received 20 requests +backend-69fcff487f-ktsx4: received 30 requests +backend-69fcff487f-nqxc7: received 27 requests +``` + +You should note that this results may vary, the output here is for reference purpose only. + +## Consistent Hash + +This example will create a Load Balancer with Consistent Hash policy via [BackendTrafficPolicy][]. + +The underlying consistent hash algorithm that Envoy Gateway utilise is [Maglev][], and it can derive hash from following aspects: + +- **SourceIP** +- **Header** +- **Cookie** + +They are also the supported value as consistent hash type. + +### Source IP + +This example will create a Load Balancer with Source IP based Consistent Hash policy. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The `hey` tool will be used to generate 100 concurrent requests. + +```shell +hey -n 100 -c 100 -host "www.example.com" http://${GATEWAY_HOST}/source +``` + +```console +Summary: + Total: 0.0539 secs + Slowest: 0.0500 secs + Fastest: 0.0198 secs + Average: 0.0340 secs + Requests/sec: 1856.5666 + + Total data: 50600 bytes + Size/request: 506 bytes + +Response time histogram: + 0.020 [1] |■■ + 0.023 [5] |■■■■■■■■■■■ + 0.026 [12] |■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.029 [16] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.032 [11] |■■■■■■■■■■■■■■■■■■■■■■■■ + 0.035 [7] |■■■■■■■■■■■■■■■■ + 0.038 [8] |■■■■■■■■■■■■■■■■■■ + 0.041 [18] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.044 [15] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.047 [4] |■■■■■■■■■ + 0.050 [3] |■■■■■■■ +``` + +As a result, you can see all traffics are routed to only one upstream host, since the client that send requests +has the same source IP. + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-grzkj: received 0 requests +backend-69fcff487f-n4d8w: received 100 requests +backend-69fcff487f-tb7zx: received 0 requests +backend-69fcff487f-wbzpg: received 0 requests +``` + +You can try different client to send out these requests, the upstream host that receives traffics may vary. + +### Header + +This example will create a Load Balancer with Header based Consistent Hash policy. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The `hey` tool will be used to generate 100 concurrent requests. + +```shell +hey -n 100 -c 100 -host "www.example.com" -H "FooBar: 1.2.3.4" http://${GATEWAY_HOST}/header +``` + +```console +Summary: + Total: 0.0579 secs + Slowest: 0.0510 secs + Fastest: 0.0323 secs + Average: 0.0431 secs + Requests/sec: 1728.6064 + + Total data: 53800 bytes + Size/request: 538 bytes + +Response time histogram: + 0.032 [1] |■■ + 0.034 [3] |■■■■■■ + 0.036 [1] |■■ + 0.038 [1] |■■ + 0.040 [7] |■■■■■■■■■■■■■■ + 0.042 [20] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.044 [20] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.045 [20] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.047 [16] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.049 [9] |■■■■■■■■■■■■■■■■■■ + 0.051 [2] |■■■■ +``` + +As a result, you can see all traffics are routed to only one upstream host, since the header of all requests are the same. + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-dvt9r: received 0 requests +backend-69fcff487f-f8qdl: received 100 requests +backend-69fcff487f-gnpm4: received 0 requests +backend-69fcff487f-t2pgm: received 0 requests +``` + +You can try to add different header to these requests, and the upstream host that receives traffics may vary. +The following output happens when you use `hey` to send another 100 requests with header `FooBar: 5.6.7.8`. + +```console +backend-69fcff487f-dvt9r: received 0 requests +backend-69fcff487f-f8qdl: received 100 requests +backend-69fcff487f-gnpm4: received 100 requests +backend-69fcff487f-t2pgm: received 0 requests +``` + +### Cookie + +This example will create a Load Balancer with Cookie based Consistent Hash policy. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +By sending 10 request with `curl` to the `${GATEWAY_HOST}/cookie`, you can see that all requests got routed to only +one upstream host, since they have same cookie setting. + +```shell +for i in {1..10}; do curl -I --header "Host: www.example.com" --cookie "FooBar=1.2.3.4" http://${GATEWAY_HOST}/cookie ; sleep 1; done +``` + +```shell +kubectl get pods -l app=backend --no-headers -o custom-columns=":metadata.name" | while read -r pod; do echo "$pod: received $(($(kubectl logs $pod | wc -l) - 2)) requests"; done +``` + +```console +backend-69fcff487f-5dxz9: received 0 requests +backend-69fcff487f-gpvl2: received 0 requests +backend-69fcff487f-pglgv: received 10 requests +backend-69fcff487f-qxr74: received 0 requests +``` + +You can try to set different cookie to these requests, the upstream host that receives traffics may vary. +The following output happens when you use `curl` to send another 10 requests with cookie `FooBar: 5.6.7.8`. + +```console +backend-69fcff487f-dvt9r: received 0 requests +backend-69fcff487f-f8qdl: received 0 requests +backend-69fcff487f-gnpm4: received 10 requests +backend-69fcff487f-t2pgm: received 10 requests +``` + +If the cookie has not been set in one request, Envoy Gateway will auto-generate a cookie for this request +according to the `ttl` and `attributes` field. + +In this example, the following cookie will be generated (see `set-cookie` header in response) if sending a request without cookie: + +```shell +curl -v --header "Host: www.example.com" http://${GATEWAY_HOST}/cookie +``` + +```console +> GET /cookie HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/7.74.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Fri, 19 Jul 2024 16:49:57 GMT +< content-length: 458 +< set-cookie: FooBar="88358b9442700c56"; Max-Age=60; SameSite=Strict; HttpOnly +< +{ + "path": "/cookie", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.74.0" + ], + "X-Envoy-Internal": [ + "true" + ], + "X-Forwarded-For": [ + "10.244.0.1" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "1adeaaf7-d45c-48c8-9a4d-eadbccb2fd50" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-69fcff487f-5dxz9" +``` + +## Endpoint Override + +This example will create a Load Balancer with Endpoint Override functionality via [BackendTrafficPolicy][]. + +The Endpoint Override feature allows endpoint selection based on headers. It can derive the target endpoint from HTTP request headers. + +When the specified override endpoint is not available or invalid, the load balancer will fall back to the configured load balancing policy. + +### Header-based Endpoint Override + +This example will create a Load Balancer with Header-based Endpoint Override functionality. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +First, get one of the backend pod IPs to use as the override endpoint: + +```shell +BACKEND_POD_IP=$(kubectl get pods -l app=backend -o jsonpath='{.items[0].status.podIP}') +echo "Backend Pod IP: $BACKEND_POD_IP" +``` + +Test with a valid pod IP in the header - all requests should go to the specific pod: + +```shell +for i in {1..10}; do + curl -s -H "Host: www.example.com" -H "x-custom-host: $BACKEND_POD_IP:3000" \ + http://${GATEWAY_HOST}/endpoint-override-header | jq -r '.pod' +done +``` + +All requests should return the same pod name, demonstrating that the endpoint override is working. + +Test with an invalid IP in the header - requests should fall back to round robin: + +```shell +for i in {1..10}; do + curl -s -H "Host: www.example.com" -H "x-custom-host: 192.168.1.100:3000" \ + http://${GATEWAY_HOST}/endpoint-override-header | jq -r '.pod' +done +``` + +You should see requests distributed across different pods using the round robin fallback policy. + +[Envoy load balancing]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/overview +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Hey project]: https://github.com/rakyll/hey +[Maglev]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#maglev diff --git a/site/content/en/v1.8/tasks/traffic/local-rate-limit.md b/site/content/en/v1.8/tasks/traffic/local-rate-limit.md new file mode 100644 index 0000000000..505bd01023 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/local-rate-limit.md @@ -0,0 +1,1021 @@ +--- +title: "Local Rate Limit" +--- + +Rate limit is a feature that allows the user to limit the number of incoming requests to a predefined value based on attributes within the traffic flow. + +Here are some reasons why you may want to implement Rate limits + +* To prevent malicious activity such as DDoS attacks. +* To prevent applications and its resources (such as a database) from getting overloaded. +* To create API limits based on user entitlements. + +Envoy Gateway supports two types of rate limiting: [Global rate limiting][] and [Local rate limiting][]. + +[Local rate limiting][] applies rate limits to the traffic flowing through a single instance of Envoy proxy. This means +that if the data plane has 2 replicas of Envoy running, and the rate limit is 10 requests/second, each replica will allow +10 requests/second. This is in contrast to [Global Rate Limiting][] which applies rate limits to the traffic flowing through +all instances of Envoy proxy. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their rate limit intent. +This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +**Note:** Limit is applied per route. Even if a [BackendTrafficPolicy][] targets a gateway, each route in that gateway +still has a separate rate limit bucket. For example, if a gateway has 2 routes, and the limit is 100r/s, then each route +has its own 100r/s rate limit bucket. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Rate Limit Specific User + +Here is an example of a rate limit implemented by the application developer to limit a specific user by matching on a custom `x-user-id` header +with a value set to `one`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-ratelimit -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Let's query `ratelimit.example/get` 4 times. We should receive a `200` response from the example Gateway for the first 3 requests +and then receive a `429` status code for the 4th request since the limit is set at 3 requests/Hour for the request which contains the header `x-user-id` +and value `one`. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: one" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +You should be able to send requests with the `x-user-id` header and a different value and receive successful responses from the server. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: two" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:34:39 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +``` + +## Rate Limit Specific User Unless within Test Org + +Here is an example of a rate limit implemented by the application developer to limit a specific user by matching on a custom `x-user-id` header +with a value set to `one`. But the user must not be limited if logging in within Test org, determined by custom header `x-org-id` set to `test`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The HTTPRoute status should indicate that it has been accepted and is bound to the example Gateway. + +```shell +kubectl get httproute/http-ratelimit -o yaml +``` + +Get the Gateway's address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Let's query `ratelimit.example/get` 4 times with `x-user-id` set to `one` and `x-org-id` set to `org1`. We should receive a `200` response from the example Gateway for the first 3 requests and the last request should be rate limited. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: one" --header "x-org-id: org1" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +Let's query `ratelimit.example/get` 4 times with `x-user-id` set to `one` and `x-org-id` set to `test`. We should receive a `200` response from the example Gateway for all the 4 requests, unlike previous example where the last request was rate limited. + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" --header "x-user-id: one" --header "x-org-id: test" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +``` + +## Rate Limit All Requests + +This example shows you how to rate limit all requests matching the HTTPRoute rule at 3 requests/Hour by leaving the `clientSelectors` field unset. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/get ; sleep 1; done +``` + +```console +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +``` + +**Note:** Local rate limiting does not support `distinct` matching. If you want to rate limit based on distinct values, +you should use [Global Rate Limiting][]. + +## Rate Limit Based on Path + +This example shows you how to rate limit requests based on the request path. In this case, we want to limit requests to `/api/users` to 3 requests/Hour. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +The path matching supports three types: +- `Exact`: Matches the exact path (e.g., `/api/users`) +- `PathPrefix`: Matches paths with a specific prefix (e.g., `/api/`) +- `RegularExpression`: Matches paths using regex patterns (e.g., `/api/users/[0-9]+`) + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Let's test the path-based rate limit by querying `/api/users` and `/api/products`. The rate limit of 3 requests/Hour is only applied to `/api/users`: + +```shell +# First, test the rate-limited path /api/users - 4 requests (4th should be rate limited) +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/users ; sleep 1; done + +# Now test a different path that should not be rate limited +for i in {1..4}; do curl -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/products ; sleep 1; done +``` + +```console +# Requests to /api/users (rate limited after 3 requests) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +# Requests to /api/products (not rate limited) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:35 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy +``` + +As you can see, requests to `/api/users` are rate limited after the 3rd request (returning 429), while all requests to `/api/products` succeed without any rate limit. + +## Rate Limit Based on HTTP Method + +This example shows you how to rate limit requests based on the HTTP method. In this case, we want to limit POST requests to 3 requests/Hour. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Let's test the method-based rate limit. POST requests are limited to 3 requests/Hour, while GET requests are not limited: + +```shell +# Send 4 POST requests - the 4th one should be rate limited +for i in {1..4}; do curl -X POST -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/data ; sleep 1; done + +# GET requests should not be rate limited +for i in {1..4}; do curl -X GET -I --header "Host: ratelimit.example" http://${GATEWAY_HOST}/api/data ; sleep 1; done +``` + +```console +# POST requests (rate limited after 3 requests) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:31 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:32 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:33 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 429 Too Many Requests +x-envoy-ratelimited: true +date: Wed, 08 Feb 2023 02:33:34 GMT +server: envoy +transfer-encoding: chunked + +# GET requests (not rate limited) +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:35 GMT +content-length: 460 +x-envoy-upstream-service-time: 4 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:36 GMT +content-length: 460 +x-envoy-upstream-service-time: 2 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:37 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy + +HTTP/1.1 200 OK +content-type: application/json +x-content-type-options: nosniff +date: Wed, 08 Feb 2023 02:33:38 GMT +content-length: 460 +x-envoy-upstream-service-time: 0 +server: envoy +``` + +As you can see, POST requests are rate limited after the 3rd request (returning 429), while GET requests to the same path are not rate limited. + +[Global Rate Limiting]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/global_rate_limiting +[Local rate limiting]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/local_rate_limiting +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ diff --git a/site/content/en/v1.8/tasks/traffic/multicluster-service.md b/site/content/en/v1.8/tasks/traffic/multicluster-service.md new file mode 100644 index 0000000000..690fa354bf --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/multicluster-service.md @@ -0,0 +1,86 @@ +--- +title: "Multicluster Service Routing" +--- + +The Multicluster Service API ServiceImport object can be used as part of the GatewayAPI backendRef for configuring routes. For more information about multicluster service API follow [sig documentation](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/). + +We will use [Submariner project](https://github.com/submariner-io/submariner) for setting up the multicluster environment for exporting the service to be routed from peer clusters. + +## Setting KIND clusters and installing Submariner. + +- We will be using KIND clusters to demonstrate this example. + +```shell +git clone https://github.com/submariner-io/submariner-operator +cd submariner-operator +make clusters +``` + +Note: remain in submariner-operator directory for the rest of the steps in this section + +- Install subctl: + +```shell +curl -Ls https://get.submariner.io | VERSION=v0.14.6 bash +``` + +- Set up multicluster service API and submariner for cross cluster traffic using ServiceImport + +```shell +subctl deploy-broker --kubeconfig output/kubeconfigs/kind-config-cluster1 --globalnet +subctl join --kubeconfig output/kubeconfigs/kind-config-cluster1 broker-info.subm --clusterid cluster1 --natt=false +subctl join --kubeconfig output/kubeconfigs/kind-config-cluster2 broker-info.subm --clusterid cluster2 --natt=false +``` + +Once the above steps are done and all the pods are up in both the clusters. We are ready for installing envoy gateway. + +## Install EnvoyGateway + +Install the Gateway API CRDs and Envoy Gateway in cluster1: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace --kubeconfig output/kubeconfigs/kind-config-cluster1 +``` + +Wait for Envoy Gateway to become available: + +```shell +kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available --kubeconfig output/kubeconfigs/kind-config-cluster1 +``` + +## Install Application + +Install the backend application in cluster2 and export it through subctl command. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/application.yaml --kubeconfig output/kubeconfigs/kind-config-cluster2 +subctl export service backend --namespace default --kubeconfig output/kubeconfigs/kind-config-cluster2 +``` + +## Create Gateway API Objects + +Create the Gateway API objects GatewayClass, Gateway and HTTPRoute in cluster1 to set up the routing. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/multicluster-service.yaml --kubeconfig output/kubeconfigs/kind-config-cluster1 +``` + +## Testing the Configuration + +Get the name of the Envoy service created the by the example Gateway: + +```shell +export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to the Envoy service: + +```shell +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 & +``` + +Curl the example app through Envoy proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://localhost:8888/get +``` diff --git a/site/content/en/v1.8/tasks/traffic/request-buffering.md b/site/content/en/v1.8/tasks/traffic/request-buffering.md new file mode 100644 index 0000000000..bf6477fd4e --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/request-buffering.md @@ -0,0 +1,211 @@ +--- +title: "Request Buffering" +--- + +The [Envoy buffer filter] is used to stop filter iteration and wait for a fully buffered complete request. This is useful in different situations including protecting some applications from having to deal with partial requests and high network latency. + +Enabling request buffering requires specifying a size limit for the buffer. Any requests that are larger than the limit will stop the buffering and return a HTTP 413 Content Too Large response. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to enable request buffering. +This instantiated resource can be linked to a [Gateway][], or [HTTPRoute][]. + +If the target of the BackendTrafficPolicy is a Gateway, the request buffering will be applied to all xRoutes under that Gateway. + +Warning: Request buffering requires Envoy to fully receive the request before forwarding it upstream. This does not work with streaming or +upgrade-based traffic such as gRPC streaming and WebSocket. Enabling `requestBuffer` for those routes can cause requests to hang indefinitely +because the request may never be forwarded upstream. Use request buffering only on non-streaming HTTP request flows. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +Enable request buffering by creating an [BackendTrafficPolicy][BackendTrafficPolicy] and attaching it to the example HTTPRoute. + +### HTTPRoute + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +A HTTPRoute resource is created for the `/foo` path prefix. The `request-buffer` BackendTrafficPolicy has been created and targeted HTTPRoute foo to enable request buffering. A small buffer limit of `4` bytes is purposely chosen to make testing easier. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/foo -o yaml +``` + +Verify the BackendTrafficPolicy configuration: + +```shell +kubectl get backendtrafficpolicy/request-buffer -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will try sending a request with an empty json object that is less than the buffer limit of 4 bytes + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/foo" -XPOST -d '{}' +``` + +We will see the following output. The `Content-Length` header will be added by the buffer filter. + +``` +{ + "path": "/foo", + "host": "www.example.com", + "method": "POST", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "Content-Length": [ + "2" + ], + "Content-Type": [ + "application/x-www-form-urlencoded" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "daf7067e-a9e5-48da-86d2-6f5d9ccfb57e" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-869c8646c5-9vm4l" +} +``` + +Next we will try sending a json object that is larger than 4 bytes. We will also write the status code to make it clear. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/foo" -XPOST -d '{"key": "value"}' -w "\nStatus Code: %{http_code}" +``` + +We will now see that sending a payload of `{"key": "value"}` which is larger than the request buffer limit of 4 bytes returns a +HTTP 413 Payload Too Large response + +``` +Payload Too Large +Status Code: 413 +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the BackendTrafficPolicy and HTTPRoute: + +```shell +kubectl delete httproute/foo +kubectl delete backendtrafficpolicy/request-buffer +``` + +[Envoy buffer filter]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/buffer_filter +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ diff --git a/site/content/en/v1.8/tasks/traffic/response-compression.md b/site/content/en/v1.8/tasks/traffic/response-compression.md new file mode 100644 index 0000000000..008783f03f --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/response-compression.md @@ -0,0 +1,165 @@ +--- +title: "Response Compression" +--- + +Response Compression allows you to compress the response from the backend before sending it to the client. This can be useful for scenarios where the backend sends large responses that can be compressed to reduce the network bandwidth. However, this comes with a trade-off of increased CPU usage on the Envoy side to compress the response. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Testing Response Compression + +You can enable compression by specifying the compression types in the `BackendTrafficPolicy` resource using the `compressor` field. +Multiple compression types can be defined within the resource, allowing Envoy Gateway to choose the most appropriate option based on the `Accept-Encoding header` provided by the client. + +Envoy Gateway currently supports Brotli, Gzip, and Zstd compression algorithms. Additional compression algorithms may be supported in the future. + +{{% alert title="Note" color="warning" %}} +The `compression` field is deprecated. Use the `compressor` field instead, which provides more granular control over compression configuration. +{{% /alert %}} + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### ETag Handling + +When a response is compressed, Envoy strips strong `ETag` headers by default (weak `ETag`s, prefixed with `W/`, are preserved). This is because compression changes the response body, so the original entity tag no longer identifies the representation that reaches the client. + +See the upstream [Envoy compressor filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/compressor_filter) for full details of the ETag handling options (`disable_on_etag_header`, `weaken_etag_on_compress`). + +### Configuring Minimum Content Length + +You can configure the minimum response size for compression using the `minContentLength` field. Responses smaller than this threshold will not be compressed. This can reduce CPU overhead for small responses. + +The minimum allowed value is 30 bytes (enforced by Envoy Proxy). If not specified, Envoy's default of 30 bytes is used. + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: response-compression +spec: + targetRef: + group: gateway.networking.k8s.io + kind: HTTPRoute + name: backend + compressor: + - type: Gzip + gzip: {} + minContentLength: 1024 +``` + +### Deprecated Configuration + +The following configuration uses the deprecated `compression` field. While still supported, it's recommended to migrate to the `compressor` field: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: response-compression-deprecated +spec: + targetRef: + group: gateway.networking.k8s.io + kind: HTTPRoute + name: backend + compression: + - type: Brotli + - type: Gzip + - type: Zstd +``` + +To specify the desired compression type, include the `Accept-Encoding` header in requests sent to the Envoy Gateway. The quality value (`q`) in the `Accept-Encoding` header determines the priority of each compression type. Envoy Gateway will select the compression type with the highest `q` value that matches a type configured in the `BackendTrafficPolicy` resource. + +```shell +curl --verbose --header "Host: www.example.com" --header "Accept-Encoding: br;q=1.0, gzip;q=0.8" http://$GATEWAY_HOST/ +``` + +```console +* Trying 172.18.0.200:80... +* Connected to 172.18.0.200 (172.18.0.200) port 80 +> GET / HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.5.0 +> Accept: */* +> Accept-Encoding: br;q=1.0, gzip;q=0.8 +> +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Wed, 15 Jan 2025 08:23:42 GMT +< vary: Accept-Encoding +< content-encoding: br +< transfer-encoding: chunked +``` + +```shell +curl --verbose --header "Host: www.example.com" --header "Accept-Encoding: br;q=0.8, gzip;q=1.0" http://$GATEWAY_HOST/ +``` + +```console +* Trying 172.18.0.200:80... +* Connected to 172.18.0.200 (172.18.0.200) port 80 +> GET / HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.5.0 +> Accept: */* +> Accept-Encoding: br;q=0.8, gzip;q=1.0 +> +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Wed, 15 Jan 2025 08:29:22 GMT +< content-encoding: gzip +< vary: Accept-Encoding +< transfer-encoding: chunked +``` diff --git a/site/content/en/v1.8/tasks/traffic/response-override.md b/site/content/en/v1.8/tasks/traffic/response-override.md new file mode 100644 index 0000000000..c3babf278c --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/response-override.md @@ -0,0 +1,440 @@ +--- +title: "Response Override" +--- + +Response Override allows you to override the response from the backend with a custom one. This can be useful for scenarios such as returning a custom 404 page when the requested resource is not found, a custom 500 error message when the backend is failing, or redirecting the client when the backend returns a 403 Forbidden. When using redirect, Envoy applies it internally: Envoy follows the redirect to the new URL, obtains the response from that URL, and sends that response to the client. + +Each rule accepts an optional `source` field that controls which responses the rule applies to: + +- `All` (default) — overrides both Envoy-generated responses (e.g. auth failures, rate-limit rejections) and upstream responses with the matched status code. +- `Backend` — overrides only responses from the upstream backend. +- `Local` — overrides only responses generated by Envoy itself (e.g. a 401 from JWT authentication, a 429 from rate limiting). This is useful when you want to customise error messages from Envoy policies without affecting legitimate upstream responses that happen to share the same status code. + +## Installation + +Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Testing Response Override + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/status/404 +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 172.18.0.200 (172.18.0.200) port 80 +> GET /status/404 HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.5.0 +> Accept: */* +> +< HTTP/1.1 404 Not Found +< content-type: text/plain +< content-length: 32 +< date: Thu, 07 Nov 2024 09:22:29 GMT +< +* Connection #0 to host 172.18.0.200 left intact +Oops! Your request is not found. +``` + +For 403, the policy redirects to `https://www.example.com/get`. Envoy follows the redirect internally and sends that response to the client: + +```shell +curl -L -v --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/status/403 +``` + +```console +* Host localhost:5000 was resolved. +* IPv6: ::1 +* IPv4: 127.0.0.1 +* Trying [::1]:5000... +* Connected to localhost (::1) port 5000 +> GET /status/403 HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.7.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 302 Found +< content-type: application/json +< x-content-type-options: nosniff +< date: Thu, 26 Feb 2026 14:36:01 GMT +< content-length: 467 +< +{ + "path": "/get", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.2.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "d69f627e-c454-46b2-86e1-25d4c18b68e4" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-869c8646c5-xfm84" +* Connection #0 to host localhost left intact +} +``` + +You receive the response body from the redirect target. Then verify the 500 override: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/status/500 +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 172.18.0.200 (172.18.0.200) port 80 +> GET /status/500 HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.5.0 +> Accept: */* +> +< HTTP/1.1 500 Internal Server Error +< content-type: application/json +< content-length: 34 +< date: Thu, 07 Nov 2024 09:23:02 GMT +< +* Connection #0 to host 172.18.0.200 left intact +{"error": "Internal Server Error"} +``` + +## Override Only Envoy-Generated Responses + +By default, a `responseOverride` rule matches any response with the given status code, whether it came from the upstream backend or was generated by Envoy itself (e.g. a 401 produced by JWT authentication). Use `source: Local` to restrict a rule to Envoy-generated responses only, leaving legitimate upstream responses with the same code untouched. + +The following example uses the `foo` HTTPRoute and `jwt-example` SecurityPolicy from the +[JWT Authentication](../../security/jwt-authentication) task. Follow that task first, then apply the +BackendTrafficPolicy below to replace Envoy's default 401 rejection with a structured JSON error. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify that a request to `/foo` without a JWT receives the custom JSON body instead of Envoy's default plain-text 401: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/foo +``` + +```console +< HTTP/1.1 401 Unauthorized +< content-type: application/json +< content-length: 67 +< +{"error": "Authentication required. Please provide a valid token."} +``` + +Now verify that a backend-generated 401 is **not** overridden. The `backend` HTTPRoute from the +[Prerequisites](#prerequisites) section routes all paths to the backend, which echoes back whichever +status code is in the URL. Sending a request to `/status/401` produces a 401 that originates from the +upstream, not from Envoy, so the `source: Local` rule on the `foo` route leaves it untouched: + +```shell +curl --verbose --header "Host: www.example.com" http://localhost:8888/status/401 +``` + +```console +< HTTP/1.1 401 Unauthorized +< content-type: text/plain +< content-length: 0 +< +``` + +The body is empty and the `content-type` is the backend's own — no custom JSON, confirming that +`source: Local` only intercepts Envoy-generated responses. + +To see the inverse behaviour, change `source` to `Backend`. Now the same custom JSON body is applied +to upstream 401s, but Envoy-generated 401s (e.g. from JWT authentication) pass through unchanged. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +A backend-generated 401 (via `/status/401`) is now overridden with the custom JSON body: + +```shell +curl --verbose --header "Host: www.example.com" http://localhost:8888/status/401 +``` + +```console +< HTTP/1.1 401 Unauthorized +< content-type: application/json +< content-length: 67 +< +{"error": "Authentication required. Please provide a valid token."} +``` + +However, a request to `/foo` without a JWT still receives Envoy's own plain-text rejection, +because `source: Backend` does not intercept Envoy-generated responses: + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/foo +``` + +```console +< HTTP/1.1 401 Unauthorized +< content-type: text/plain +< content-length: 15 +< +Jwt is missing +``` + +The body is Envoy's default message and the `content-type` is `text/plain` — no custom JSON, +confirming that `source: Backend` only intercepts responses from the upstream backend. diff --git a/site/content/en/v1.8/tasks/traffic/retry.md b/site/content/en/v1.8/tasks/traffic/retry.md new file mode 100644 index 0000000000..ee65c8df05 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/retry.md @@ -0,0 +1,156 @@ +--- +title: Retry +--- + +{{% alert color="warning" %}} +Starting from `v1.3`, Envoy Gateway supports [HTTPRoute Retries(GEP-1731)][], +this setting in the core Gateway API takes precedence over the BackendTrafficPolicy configuration. +{{% /alert %}} + +A retry setting specifies the maximum number of times an Envoy proxy attempts to connect to a service if the initial call fails. Retries can enhance service availability and application performance by making sure that calls don’t fail permanently because of transient problems such as a temporarily overloaded service or network. The interval between retries prevents the called service from being overwhelmed with requests. + +Envoy Gateway supports the following retry settings: +- **NumRetries**: is the number of retries to be attempted. Defaults to 2. +- **RetryOn**: specifies the retry trigger condition. +- **PerRetryPolicy**: is the retry policy to be applied per retry attempt. + +Envoy Gateway introduces a new CRD called [BackendTrafficPolicy][] that allows the user to describe their desired retry settings. This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRPCRoute][] resource. + +**Note**: There are distinct circuit breaker counters for each `BackendReference` in an `xRoute` rule. Even if a `BackendTrafficPolicy` targets a `Gateway`, each `BackendReference` in that gateway still has separate circuit breaker counter. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Test and customize retry settings + +Before applying a `BackendTrafficPolicy` with retry setting to a route, let's test the default retry settings. + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/status/500" +``` + +It will return `500` response immediately. + +```console +* Trying 172.18.255.200:80... +* Connected to 172.18.255.200 (172.18.255.200) port 80 +> GET /status/500 HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> +< HTTP/1.1 500 Internal Server Error +< date: Fri, 01 Mar 2024 15:12:55 GMT +< content-length: 0 +< +* Connection #0 to host 172.18.255.200 left intact +``` + +Let's create a `BackendTrafficPolicy` with a retry setting. + +The request will be retried 5 times with a 100ms base interval and a 10s maximum interval. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Execute the test again. + +```shell +curl -v -H "Host: www.example.com" "http://${GATEWAY_HOST}/status/500" +``` + +It will return `500` response after a few while. + +```console +* Trying 172.18.255.200:80... +* Connected to 172.18.255.200 (172.18.255.200) port 80 +> GET /status/500 HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.4.0 +> Accept: */* +> +< HTTP/1.1 500 Internal Server Error +< date: Fri, 01 Mar 2024 15:15:53 GMT +< content-length: 0 +< +* Connection #0 to host 172.18.255.200 left intact +``` + +Let's check the stats to see the retry behavior. + +```shell +egctl x stats envoy-proxy -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=eg,gateway.envoyproxy.io/owning-gateway-namespace=default | grep "envoy_cluster_upstream_rq_retry{envoy_cluster_name=\"httproute/default/backend/rule/0\"}" +``` + +You will expect to see the stats. + +```console +envoy_cluster_upstream_rq_retry{envoy_cluster_name="httproute/default/backend/rule/0"} 5 +``` + +[HTTPRoute Retries(GEP-1731)]: https://gateway-api.sigs.k8s.io/geps/gep-1731/ +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/ +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ diff --git a/site/content/en/v1.8/tasks/traffic/routing-outside-kubernetes.md b/site/content/en/v1.8/tasks/traffic/routing-outside-kubernetes.md new file mode 100644 index 0000000000..e584c2179c --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/routing-outside-kubernetes.md @@ -0,0 +1,168 @@ +--- +title: "Routing outside Kubernetes" +--- + +Routing to endpoints outside the Kubernetes cluster where Envoy Gateway and its corresponding Envoy Proxy fleet is +running is a common use case. This can be achieved by: +- defining FQDN addresses in a [EndpointSlice][] (covered in this document) +- defining a [Backend][] resource, as described in the [Backend Task][]. + +## Installation + +Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## Configuration + +Define a Service and EndpointSlice that represents https://httpbin.org + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Update the [Gateway][] to include a TLS Listener on port 443 + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: tls + protocol: TLS + port: 443 + tls: + mode: Passthrough + ' +``` + +Add a [TLSRoute][] that can route incoming traffic to the above backend that we created + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Get the Gateway address: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Send a request and view the response: + +```shell +curl -I -HHost:httpbin.org --resolve "httpbin.org:443:${GATEWAY_HOST}" https://httpbin.org/ +``` + +[EndpointSlice]: https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/ +[Backend]: ../../api/extension_types#backend +[Backend Task]: ./backend.md +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[TLSRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#tlsroute diff --git a/site/content/en/v1.8/tasks/traffic/session-persistence.md b/site/content/en/v1.8/tasks/traffic/session-persistence.md new file mode 100644 index 0000000000..efb5bd2cfd --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/session-persistence.md @@ -0,0 +1,225 @@ +--- +title: "Session Persistence" +--- + +Session Persistence allows client requests to be consistently routed to the same backend service instance. This is useful in many scenarios, such as when an application needs to maintain state across multiple requests. In Envoy Gateway, session persistence can be enabled by configuring [HTTPRoute][]. + +Envoy Gateway supports following session persistence types: +- **Cookie-based** Session Persistence: Session persistence is achieved based on specific cookie information in the request. +- **Header-based** Session Persistence: Session persistence is achieved based on specific header information in the request. + +## Prerequisites + +### Install Envoy Gateway + +{{< boilerplate prerequisites >}} + +For better testing the session persistence, you can add more hosts in upstream cluster by increasing the replicas of one deployment: + +```shell +kubectl patch deployment backend -n default -p '{"spec": {"replicas": 4}}' +``` + +## Cookie-based Session Persistence + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +{{< boilerplate rollout-envoy-gateway >}} + +### Testing + +Send a request to get a cookie and test: + +```shell +COOKIE=$(curl --verbose http://localhost:8888/get 2>&1 | grep "set-cookie" | awk '{print $3}') +for i in `seq 5`; do + curl -H "Cookie: $COOKIE" http://localhost:8888/get 2>/dev/null | grep pod +done +``` + +You can see all responses are from the same pod: + +```console + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-lxwdf" +``` + +Wait for cookie expiration, test again: + +```shell +sleep 10 && for i in `seq 5`; do + curl -H "Cookie: $COOKIE" -H "Host: www.example.com" http://localhost:8888/get 2>/dev/null | grep pod +done +``` + +```console + "pod": "backend-765694d47f-kvwqb" + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-kvwqb" + "pod": "backend-765694d47f-2ff9s" + "pod": "backend-765694d47f-lxwdf" +``` + +Due to cookie expiration, no session any more. + +## Header-based Session Persistence + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Testing + + +Send a request to get a cookie and test: + +```shell +HEADER=$(curl --verbose http://localhost:8888/get 2>&1 | grep "session-a" | awk '{print $3}') +for i in `seq 5`; do + curl -H "Session-A: $HEADER" http://localhost:8888/get 2>/dev/null | grep pod +done +``` + +You can see all responses are from the same pod: + +```console + "pod": "backend-765694d47f-gn7q2" + "pod": "backend-765694d47f-gn7q2" + "pod": "backend-765694d47f-gn7q2" + "pod": "backend-765694d47f-gn7q2" + "pod": "backend-765694d47f-gn7q2" +``` + +We remove the header and test again: + +```shell +for i in `seq 5`; do + curl http://localhost:8888/get 2>/dev/null | grep pod +done +``` + +```console + "pod": "backend-765694d47f-2ff9s" + "pod": "backend-765694d47f-kvwqb" + "pod": "backend-765694d47f-2ff9s" + "pod": "backend-765694d47f-lxwdf" + "pod": "backend-765694d47f-kvwqb" + +``` + +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute \ No newline at end of file diff --git a/site/content/en/v1.8/tasks/traffic/tcp-routing.md b/site/content/en/v1.8/tasks/traffic/tcp-routing.md new file mode 100644 index 0000000000..356e068148 --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/tcp-routing.md @@ -0,0 +1,486 @@ +--- +title: "TCP Routing" +--- + +[TCPRoute][] provides a way to route TCP requests. When combined with a Gateway listener, it can be used to forward +connections on the port specified by the listener to a set of backends specified by the TCPRoute. To learn more about +HTTP routing, refer to the [Gateway API documentation][]. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Configuration + +In this example, we have one [Gateway][] resource and two [TCPRoute][] resources that distribute the traffic with the following +rules: + +All TCP streams on port `8088` of the [Gateway][] are forwarded to port 3001 of `foo` Kubernetes [Service][]. +All TCP streams on port `8089` of the [Gateway][] are forwarded to port 3002 of `bar` Kubernetes [Service][]. +In this example two TCP listeners will be applied to the [Gateway][] in order to route them to two separate backend +[TCPRoute][]s, note that the protocol set for the listeners on the [Gateway][] is TCP: + +Install the [GatewayClass][] and a `tcp-gateway` [Gateway][] first. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Install two [Services][] `foo` and `bar`, which are bound to `backend-1` and `backend-2`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Install two [TCPRoute][]s `tcp-app-1` and `tcp-app-2` with different `sectionName`: + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +In the above example we separate the traffic for the two separate backend TCP Services by using the sectionName field in +the parentRefs: + +``` yaml +spec: + parentRefs: + - name: tcp-gateway + sectionName: foo +``` + +This corresponds directly with the name in the listeners in the [Gateway][]: + +``` yaml + listeners: + - name: foo + protocol: TCP + port: 8088 + - name: bar + protocol: TCP + port: 8089 +``` + +In this way each [TCPRoute][] "attaches" itself to a different port on the [Gateway][] so that the `foo` service +is taking traffic for port `8088` from outside the cluster and `bar` service takes the port `8089` traffic. + +Before testing, please get the tcp-gateway [Gateway][]'s address first: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/tcp-gateway -o jsonpath='{.status.addresses[0].value}') +``` + +You can try to use nc to test the TCP connections of envoy gateway with different ports, and you can see them succeeded: + +```shell +nc -zv ${GATEWAY_HOST} 8088 + +nc -zv ${GATEWAY_HOST} 8089 +``` + +You can also try to send requests to envoy gateway and get responses as shown below: + +```shell +curl -i "http://${GATEWAY_HOST}:8088" + +HTTP/1.1 200 OK +Content-Type: application/json +X-Content-Type-Options: nosniff +Date: Tue, 03 Jan 2023 10:18:36 GMT +Content-Length: 267 + +{ + "path": "/", + "host": "xxx.xxx.xxx.xxx:8088", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.85.0" + ] + }, + "namespace": "default", + "ingress": "", + "service": "foo", + "pod": "backend-1-c6c5fb958-dl8vl" +} +``` + +You can see that the traffic routing to `foo` service when sending request to `8088` port. + +```shell +curl -i "http://${GATEWAY_HOST}:8089" + +HTTP/1.1 200 OK +Content-Type: application/json +X-Content-Type-Options: nosniff +Date: Tue, 03 Jan 2023 10:19:28 GMT +Content-Length: 267 + +{ + "path": "/", + "host": "xxx.xxx.xxx.xxx:8089", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/7.85.0" + ] + }, + "namespace": "default", + "ingress": "", + "service": "bar", + "pod": "backend-2-98fcff498-hcmgb" +} +``` + +You can see that the traffic routing to `bar` service when sending request to `8089` port. + +[TCPRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.TCPRoute +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[Services]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/site/content/en/v1.8/tasks/traffic/udp-routing.md b/site/content/en/v1.8/tasks/traffic/udp-routing.md new file mode 100644 index 0000000000..b96f1c09bd --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/udp-routing.md @@ -0,0 +1,169 @@ +--- +title: "UDP Routing" +--- + +The [UDPRoute][] resource allows users to configure UDP routing by matching UDP traffic and forwarding it to Kubernetes +backends. This task will use CoreDNS example to walk you through the steps required to configure UDPRoute on Envoy +Gateway. + +__Note:__ UDPRoute allows Envoy Gateway to operate as a non-transparent proxy between a UDP client and server. The lack +of transparency means that the upstream server will see the source IP and port of the Gateway instead of the client. +For additional information, refer to Envoy's [UDP proxy documentation][]. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Installation + +Install CoreDNS in the Kubernetes cluster as the example backend. The installed CoreDNS is listening on +UDP port 53 for DNS lookups. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/udp-routing-example-backend.yaml +``` + +Wait for the CoreDNS deployment to become available: + +```shell +kubectl wait --timeout=5m deployment/coredns --for=condition=Available +``` + +Update the Gateway from the Quickstart to include a UDP listener that listens on UDP port `5300`: + +```shell +kubectl patch gateway eg --type=json --patch ' + - op: add + path: /spec/listeners/- + value: + name: coredns + protocol: UDP + port: 5300 + allowedRoutes: + kinds: + - kind: UDPRoute + ' +``` + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## Configuration + +Create a UDPRoute resource to route UDP traffic received on Gateway port 5300 to the CoredDNS backend. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the UDPRoute status: + +```shell +kubectl get udproute/coredns -o yaml +``` + +## Testing + +Get the External IP of the Gateway: + +```shell +export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}') +``` + +Use `dig` command to query the dns entry foo.bar.com through the Gateway. + +```shell +dig @${GATEWAY_HOST} -p 5300 foo.bar.com +``` + +You should see the result of the dns query as the below output, which means that the dns query has been successfully +routed to the backend CoreDNS. + +Note: 49.51.177.138 is the resolved address of GATEWAY_HOST. + +```bash +; <<>> DiG 9.18.1-1ubuntu1.1-Ubuntu <<>> @49.51.177.138 -p 5300 foo.bar.com +; (1 server found) +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58125 +;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 3 +;; WARNING: recursion requested but not available + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 1232 +; COOKIE: 24fb86eba96ebf62 (echoed) +;; QUESTION SECTION: +;foo.bar.com. IN A + +;; ADDITIONAL SECTION: +foo.bar.com. 0 IN A 10.244.0.19 +_udp.foo.bar.com. 0 IN SRV 0 0 42376 . + +;; Query time: 1 msec +;; SERVER: 49.51.177.138#5300(49.51.177.138) (UDP) +;; WHEN: Fri Jan 13 10:20:34 UTC 2023 +;; MSG SIZE rcvd: 114 +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway. + +Delete the CoreDNS example manifest and the UDPRoute: + +```shell +kubectl delete deploy/coredns +kubectl delete service/coredns +kubectl delete cm/coredns +kubectl delete udproute/coredns +``` + +## Next Steps + +Checkout the [Developer Guide](/community/develop) to get involved in the project. + +[UDPRoute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#udproute +[UDP proxy documentation]: https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/udp_filters/udp_proxy diff --git a/site/content/en/v1.8/tasks/traffic/zone-aware-routing.md b/site/content/en/v1.8/tasks/traffic/zone-aware-routing.md new file mode 100644 index 0000000000..67bf41f1dc --- /dev/null +++ b/site/content/en/v1.8/tasks/traffic/zone-aware-routing.md @@ -0,0 +1,359 @@ +--- +title: "Zone Aware Routing" +--- + +EnvoyGateway makes use of [Envoy Zone Aware Routing][Envoy Zone Aware Routing] to keep network traffic in the originating zone. +Preferring same-zone traffic between Pods in your cluster can help with reliability, performance (network latency and throughput), or cost. + +Zone-aware routing may be enabled in one of two ways: +1. Configuring a [BackendTrafficPolicy][BackendTrafficPolicy] with the `loadbalancer.zoneAware` field +2. Configuring a backendRef Kubernetes `Service` with [Traffic Distribution][Traffic Distribution] or [Topology Aware Routing][Topology Aware Routing] + +When both a backendRef and a [BackendTrafficPolicy][BackendTrafficPolicy] include a configuration for zone awareness, the [BackendTrafficPolicy][BackendTrafficPolicy] takes precedence. + +## Supported Combinations + +The `zoneAware` field supports two modes: `preferLocal` (prefer same-zone endpoints while maintaining overall balance) and `weightedZones` (explicit per-zone traffic weights). Not all load balancing policies support both modes: + +| LB Policy | `preferLocal` | `weightedZones` | +|---|---|---| +| `RoundRobin` | ✓ | ✓ | +| `LeastRequest` | ✓ | ✓ | +| `Random` | ✓ | ✓ | +| `ConsistentHash` | ✗ | ✓ | +| `BackendUtilization` | ✗ | ✓ | +| `DynamicModule` | ✗ | ✗ | + +**Why some combinations are unsupported:** + +- **`ConsistentHash` + `preferLocal`**: Envoy's consistent hashing policies (Maglev/RingHash) route based on a request hash rather than endpoint locality, so the prefer-local algorithm cannot be layered on top. Use `weightedZones` to influence traffic distribution across zones while preserving hash-based affinity. +- **`BackendUtilization` + `preferLocal`**: Envoy's `wrr_locality` extension, which wraps `BackendUtilization` with locality-weight support, does not implement the prefer-local routing algorithm. Only `weightedZones` is supported. +- **`DynamicModule` + any zone-aware mode**: Custom load balancing modules manage their own endpoint selection entirely. Zone-aware routing cannot be layered on top of an opaque third-party algorithm. + +`preferLocal` and `weightedZones` are mutually exclusive and cannot be set together for any policy. + +## Prerequisites +* The Kubernetes cluster's nodes must indicate topology information via the `topology.kubernetes.io/zone` [well-known label][Kubernetes well-known metadata]. +* There must be at least two valid topology zones for scheduling. +* {{< boilerplate prerequisites >}} + +## Configuration + +Choose one of the following configuration options. + +### Option 1: Kubernetes Service +Create the example Kubernetes Service with either topology aware routing or traffic distribution enabled. + +#### Topology Aware Routing +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + +#### Traffic Distribution +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + +### Option 2: BackendTrafficPolicy +Zone aware routing can also be enabled directly with a [BackendTrafficPolicy][BackendTrafficPolicy]. + +#### PreferLocal +The example below configures similar behavior to Kubernetes Traffic Distribution and forces all traffic to the local zone via the `force` field instead +of Envoy's default behavior which _prefers_ routing locally as much as possible while still achieving overall equal request distribution across all endpoints. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + +#### WeightedZones +`weightedZones` distributes traffic across zones proportionally according to explicit weights. Zones not listed receive a default weight of 1. +This mode is supported by `RoundRobin`, `LeastRequest`, `Random`, `ConsistentHash`, and `BackendUtilization`. + +The example below routes 70% of traffic to `us-east-1a` and 30% to `us-east-1b` using `BackendUtilization`, which combines ORCA-based backend load metrics with locality weighting via Envoy's `wrr_locality` extension. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} +```shell +cat <}} + + +### Example deployments and HTTPRoute +Next apply the example manifests to create two Deployments and an HTTPRoute. For the test configuration one Deployment +(zone-aware-routing-backend-local) includes affinity for EnvoyProxy Pods to ensure its Pods are scheduled in the same +zone and the second Deployment (zone-aware-routing-backend-nonlocal) uses anti-affinity to ensure its Pods _don't_ +schedule to the same zone in order to demonstrate functionality. +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/zone-aware-routing.yaml -n default +``` + +Ensure that both example Deployments are marked as ready and produces the following output: +```shell +kubectl get deployment/zone-aware-routing-backend-local deployment/zone-aware-routing-backend-nonlocal -n default +NAME READY UP-TO-DATE AVAILABLE AGE +zone-aware-routing-backend-local 3/3 3 3 9m1s +zone-aware-routing-backend-nonlocal 3/3 3 3 9m1s + +``` + +An HTTPRoute resource is created for the `/zone-aware-routing` path prefix along with two example Deployment resources that +are respectively configured with pod affinity/anti-affinity targeting the Envoy Proxy Pods for testing. + +Verify the HTTPRoute configuration and status: + +```shell +kubectl get httproute/zone-aware-routing -o yaml +``` + +If used during configuration, verify the [BackendTrafficPolicy][BackendTrafficPolicy]: + +```shell +kubectl get backendtrafficpolicy/zone-aware-routing -o yaml +``` + +## Testing + +Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) is set. If not, follow the +Quickstart instructions to set the variable. + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute + +We will now send a request and expect to be routed to backend in the same local zone as the Envoy Proxy Pods. + +```shell +curl -H "Host: www.example.com" "http://${GATEWAY_HOST}/zone-aware-routing" -XPOST -d '{}' +``` + +We will see the following output. The `pod` header identifies which backend received the request and should have +a name prefix of `zone-aware-routing-backend-local-`. We should see this behavior every time and the nonlocal backend should +not receive requests. + +``` +{ + "path": "/zone-aware-routing", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Envoy-External-Address": [ + "127.0.0.1" + ], + "X-Forwarded-For": [ + "10.244.1.5" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "0f4c5d28-52d0-4727-881f-abf2ac12b3b7" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "zone-aware-routing-backend-local-5586cd668d-md8sf" +} +``` + + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest. + +Delete the zone-aware-routing example resources and HTTPRoute: + +```shell +kubectl delete service/zone-aware-routing-backend +kubectl delete deployment/zone-aware-routing-backend-local +kubectl delete deployment/zone-aware-routing-backend-nonlocal +kubectl delete httproute/zone-aware-routing +kubectl delete backendtrafficpolicy/zone-aware-routing +``` + +[Traffic Distribution]: https://kubernetes.io/docs/concepts/services-networking/service/#traffic-distribution +[Topology Aware Routing]: https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/ +[Kubernetes well-known metadata]: https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone +[Envoy Zone Aware Routing]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/zone_aware +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy \ No newline at end of file diff --git a/site/content/en/v1.8/troubleshooting/_index.md b/site/content/en/v1.8/troubleshooting/_index.md new file mode 100644 index 0000000000..775b2f935c --- /dev/null +++ b/site/content/en/v1.8/troubleshooting/_index.md @@ -0,0 +1,5 @@ +--- +title: "Troubleshooting" +weight: 2 +description: Learn how to debug Envoy Gateway +--- diff --git a/site/content/en/v1.8/troubleshooting/admin-console.md b/site/content/en/v1.8/troubleshooting/admin-console.md new file mode 100644 index 0000000000..1289f75802 --- /dev/null +++ b/site/content/en/v1.8/troubleshooting/admin-console.md @@ -0,0 +1,171 @@ +--- +title: "Admin Console" +--- + +Envoy Gateway provides a built-in web-based admin console that offers a comprehensive interface for monitoring, debugging, and managing your Envoy Gateway deployment. The admin console provides real-time visibility into the control plane status, configuration state, performance metrics, and debugging capabilities. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +## Overview + +The admin console is automatically enabled and provides the following key features: + +- **Dashboard**: Overview of system status and quick access to all features +- **Server Information**: Detailed runtime information about Envoy Gateway components +- **Configuration Dump**: Real-time view of Gateway API resources and their status +- **Statistics**: Control plane metrics in Prometheus format +- **Performance Profiling**: pprof endpoints for debugging and performance analysis + +## Accessing the Admin Console + +By default, the admin console is available on `localhost:19000`. There are two ways to access it: + +### Method 1: Using kubectl port-forward + +```shell +kubectl port-forward -n envoy-gateway-system deployment/envoy-gateway 19000:19000 +``` + +Then open your browser and navigate to: + +```text +http://localhost:19000 +``` + +### Method 2: Using egctl dashboard command + +You can install egctl by following the [installation guide](../install/install-egctl). + +```shell +egctl x dashboard eg +``` + +This command will automatically set up port forwarding and open the admin console in your default browser. + +![Admin Console Main Dashboard](/img/admin_main.png) + +## Configuration + +The admin console can be configured through the `EnvoyGateway` configuration resource: + +### Development Configuration + +For development environments, you may want to enable additional debugging features: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyGateway +metadata: + name: envoy-gateway-dev + namespace: envoy-gateway-system +spec: + admin: + address: + # Allow external access (use with caution) + host: "0.0.0.0" + port: 19000 + + # Enable pprof for performance debugging + enablePprof: true +``` + +### Production Configuration + +For production environments, use more restrictive settings: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyGateway +metadata: + name: envoy-gateway-prod + namespace: envoy-gateway-system +spec: + admin: + address: + # Localhost only for security + host: "127.0.0.1" + port: 19000 + + # Disable pprof in production + enablePprof: false +``` + +## Features + +### Dashboard + +The main dashboard provides: + +- **System Information**: Version, uptime, and platform details +- **Component Status**: Real-time status of all Envoy Gateway components +- **Quick Navigation**: Easy access to all admin console features +- **Auto-refresh**: Automatic updates every 30 seconds + +![Admin Console Dashboard](/img/admin_main.png) + +### Server Information + +The server info page displays: + +- **Component Health**: Status of Provider Service, GatewayAPI Translator, xDS Translator, and Infrastructure Manager +- **Runtime Details**: Version information, uptime, and system metrics +- **Configuration**: Current EnvoyGateway configuration settings + +![Server Information Page](/img/admin_server_info.png) + +### Configuration Dump + +The config dump feature provides: + +- **Resource Explorer**: Browse all Gateway API resources (Gateways, HTTPRoutes, etc.) +- **Search Functionality**: Find resources by name or namespace +- **Real-time Updates**: Live view of configuration changes +- **JSON Export**: Download complete configuration as JSON + +![Configuration Dump Page](/img/admin_config_dump.png) + +The search functionality allows you to quickly find specific resources: + +![Configuration Search](/img/admin_config_dump_search.png) + +You can also view the complete configuration dump in JSON format: + +![Complete Configuration Dump](/img/admin_config_dump_all.png) + +### Statistics + +The statistics page offers: + +- **Prometheus Metrics**: All control plane metrics in Prometheus format +- **Metrics Categories**: Organized view of different metric types: + - Watching Components (event-driven architecture metrics) + - Status Updater (resource status update metrics) + - xDS Server (proxy configuration delivery metrics) + - Infrastructure Manager (Kubernetes resource operation metrics) + - Wasm (WebAssembly extension metrics) + - Topology Injector (node topology injection metrics) + +Access metrics directly via: `http://localhost:19000/api/metrics` + +![Statistics Page](/img/admin_stats.png) + +The metrics endpoint provides detailed Prometheus metrics: + +![Metrics Endpoint](/img/admin_metrics.png) + +### Performance Profiling + +When `enablePprof` is set to `true`, the profiling page provides: + +- **CPU Profile**: Analyze CPU usage patterns +- **Memory Heap**: Monitor memory allocation and identify leaks +- **Goroutines**: Debug concurrency issues and goroutine leaks +- **Mutex/Block**: Find contention points in the application + +![Performance Profiling Page](/img/admin_profiling.png) + +{{% alert title="Security Warning" color="warning" %}} +Only enable pprof endpoints in development or debugging scenarios. These endpoints can expose sensitive information and should not be enabled in production environments. +{{% /alert %}} diff --git a/site/content/en/v1.8/troubleshooting/configuration.md b/site/content/en/v1.8/troubleshooting/configuration.md new file mode 100644 index 0000000000..adc7f1c9d7 --- /dev/null +++ b/site/content/en/v1.8/troubleshooting/configuration.md @@ -0,0 +1,228 @@ ++++ +title = "Configuration Issues" ++++ + +## Overview +After configuring and applying resources, you might find that Envoy Gateway does not behave as expected. This guide helps troubleshoot configuration issues. + +Many **syntax errors and simple semantic issues** are caught during resource validation by the **Kubernetes API Server**, which rejects invalid resources. However, more complex configuration issues require additional debugging. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +To demonstrate debugging techniques, let’s apply an *intentionally incorrect* HTTPRoute configuration with a *non-existent* backend. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +### Checking Resource Status +The `status` field in your resource definitions is your primary troubleshooting tool. It provides insights into whether a resource has been **Accepted** or not, along with the reason for rejection. + +#### Using kubectl +This example below shows why an HTTPRoute has been **Accepted** but the **ResolvedRefs** condition is `false` because the backend does not exist. +**Note**: Almost all resources have a `status` field, so be sure to check them all. + +```shell +kubectl get httproute/backend -o yaml +``` + +```console +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: backend + namespace: default +spec: + hostnames: + - www.example.com + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: eg + rules: + - backendRefs: + - group: "" + kind: Service + name: backend-does-not-exist + port: 3000 + weight: 1 + matches: + - path: + type: PathPrefix + value: / +status: + parents: + - conditions: + - lastTransitionTime: "2025-03-08T02:07:53Z" + message: Route is accepted + observedGeneration: 3 + reason: Accepted + status: "True" + type: Accepted + - lastTransitionTime: "2025-03-08T02:07:53Z" + message: Service default/backend-does-not-exist not found + observedGeneration: 3 + reason: BackendNotFound + status: "False" + type: ResolvedRefs + controllerName: gateway.envoyproxy.io/gatewayclass-controller + parentRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg +``` + +#### Using egctl +The egctl CLI tool can quickly fetch the status of multiple resources at once: + +```shell +egctl x status all -A +``` + +```console +NAME TYPE STATUS REASON +gatewayclass/eg Accepted True Accepted + +NAMESPACE NAME TYPE STATUS REASON +default gateway/eg Programmed True Programmed + Accepted True Accepted + +NAMESPACE NAME TYPE STATUS REASON +default httproute/backend ResolvedRefs False BackendNotFound + Accepted True Accepted +``` + +Follow the instructions [here](./../install/install-egctl.md) to install `egctl`. + +#### Using kube-state-metrics +For large-scale deployments, kube-state-metrics can help monitor the status of Envoy Gateway resources. For more details, refer to the [Observability Guide](./../tasks/observability/gateway-api-metrics.md). + +### Traffic +If a configuration is not accepted, Envoy Gateway assigns a `direct_response` to the affected route, causing clients to receive an **HTTP 500 error**. + +```shell +curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get +``` + +```console +* Trying 127.0.0.1:80... +* Connected to 127.0.0.1 (127.0.0.1) port 80 +> GET /get HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.7.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 500 Internal Server Error +< date: Sat, 08 Mar 2025 02:25:32 GMT +< content-length: 0 +< +* Connection #0 to host 127.0.0.1 left intact +``` + +If you inspect the access logs in the pod logs: + +```shell +kubectl logs -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -c envoy | grep start_time | jq +``` + +```console +{ + ":authority": "www.example.com", + "bytes_received": 0, + "bytes_sent": 0, + "connection_termination_details": null, + "downstream_local_address": "10.1.21.65:10080", + "downstream_remote_address": "192.168.65.4:45050", + "duration": 0, + "method": "GET", + "protocol": "HTTP/1.1", + "requested_server_name": null, + "response_code": 500, + "response_code_details": "direct_response", + "response_flags": "-", + "route_name": "httproute/default/backend/rule/0/match/0/www_example_com", + "start_time": "2025-03-08T02:25:32.588Z", + "upstream_cluster": null, + "upstream_host": null, + "upstream_local_address": null, + "upstream_transport_failure_reason": null, + "user-agent": "curl/8.7.1", + "x-envoy-origin-path": "/get", + "x-envoy-upstream-service-time": null, + "x-forwarded-for": "192.168.65.4", + "x-request-id": "54c4c2f9-d209-4aa0-8870-342bc6622d1a" +} +``` + +and find the following entries + +```console +"response_code": "500", +"response_code_details": "direct_response" +``` + +this likely indicates a configuration issue. Review the relevant [resource status](#checking-resource-status) for resolution steps. diff --git a/site/content/en/v1.8/troubleshooting/envoy-proxy-admin-interface.md b/site/content/en/v1.8/troubleshooting/envoy-proxy-admin-interface.md new file mode 100644 index 0000000000..7c3e7a4d94 --- /dev/null +++ b/site/content/en/v1.8/troubleshooting/envoy-proxy-admin-interface.md @@ -0,0 +1,42 @@ ++++ +title = "Advanced: Envoy Proxy Admin Interface" ++++ + +## Overview +Platform admins looking to troubleshoot low level aspects of the data plane such as xDS config and heap dump, can directly connect to the Envoy Proxy Admin Interface. + +**Note**: Application Developers may not have access to the namespace where the Envoy Proxy fleet is running and should rely on [exported telemetry](https://gateway.envoyproxy.io/docs/tasks/observability/) instead for troubleshooting. + +## Prerequisites + +{{< boilerplate prerequisites >}} + +### Access + +You will need to port-forward to the admin interface port (currently 19000) on the Envoy deployment that corresponds to a Gateway, since it only listens on the `localhost` +address for security reasons. + +Get the name of the Envoy deployment. In this example its for Gateway `eg` in the `default` namespace: + +```shell +export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') +``` + +Port forward to it. + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 & +``` + +If you enter http://localhost:19000 in a browser, you should be able to access the admin interface. + + +Here's another example of accessing the [/config_dump](https://www.envoyproxy.io/docs/envoy/latest/operations/admin#get--config_dump) endpoint to get access of the loaded xDS configuration. + +```shell +curl http://127.0.0.1:19000/config_dump +``` + +### Next Steps + +There are many other endpoints in the [Envoy Proxy Admin interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin) that may be helpful when debugging. diff --git a/site/hugo.toml b/site/hugo.toml index 0515767122..05fe4a4390 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -112,7 +112,7 @@ archived_version = false # The version number for the version of the docs represented in this doc set. # Used in the "version-banner" partial to display a version number for the # current doc set. -version = "v1.7" +version = "v1.8" # A link to latest version of the docs. Used in the "version-banner" partial to # point people to the main doc site. @@ -239,6 +239,11 @@ enable = true url = "/latest" eol = "2099-12-31" +[[params.versions]] + version = "v1.8" + url = "/v1.8" + eol = "2026-11-08" + [[params.versions]] version = "v1.7" url = "/v1.7" diff --git a/site/layouts/shortcodes/helm-version.html b/site/layouts/shortcodes/helm-version.html index 8075c0da11..dc77b101f4 100644 --- a/site/layouts/shortcodes/helm-version.html +++ b/site/layouts/shortcodes/helm-version.html @@ -23,6 +23,9 @@ {{- with (strings.HasPrefix $pagePrefix "v1.7") -}} {{- "v1.7.3" -}} {{- end -}} +{{- with (strings.HasPrefix $pagePrefix "v1.8") -}} +{{- "v1.8.0" -}} +{{- end -}} {{- with (strings.HasPrefix $pagePrefix "docs") -}} {{- "v1.7.3" -}} {{- end -}} diff --git a/site/layouts/shortcodes/yaml-version.html b/site/layouts/shortcodes/yaml-version.html index b0094b0abb..7ce98ef8c0 100644 --- a/site/layouts/shortcodes/yaml-version.html +++ b/site/layouts/shortcodes/yaml-version.html @@ -23,6 +23,9 @@ {{- with (strings.HasPrefix $pagePrefix "v1.7") -}} {{- "v1.7.3" -}} {{- end -}} +{{- with (strings.HasPrefix $pagePrefix "v1.8") -}} +{{- "v1.8.0" -}} +{{- end -}} {{- with (strings.HasPrefix $pagePrefix "docs") -}} {{- "v1.7.3" -}} {{- end -}} diff --git a/tools/make/lint.mk b/tools/make/lint.mk index 4b15f68b46..529397c22c 100644 --- a/tools/make/lint.mk +++ b/tools/make/lint.mk @@ -110,7 +110,8 @@ lint.markdown: $(tools/markdownlint) --ignore site/content/en/v1.3/ \ --ignore site/content/en/v1.4/ \ --ignore site/content/en/v1.5/ \ - --ignore site/content/en/v1.6/ + --ignore site/content/en/v1.6/ \ + --ignore site/content/en/v1.8/