diff --git a/site/content/en/docs/_index.md b/site/content/en/docs/_index.md new file mode 100644 index 00000000000..92ae8586885 --- /dev/null +++ b/site/content/en/docs/_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/docs/api/_index.md b/site/content/en/docs/api/_index.md new file mode 100644 index 00000000000..396d9ffcefc --- /dev/null +++ b/site/content/en/docs/api/_index.md @@ -0,0 +1,5 @@ +--- +title: "API" +description: This section includes APIs of Envoy Gateway. +weight: 80 +--- diff --git a/site/content/en/docs/api/extension_types.md b/site/content/en/docs/api/extension_types.md new file mode 100644 index 00000000000..3691505f1a1 --- /dev/null +++ b/site/content/en/docs/api/extension_types.md @@ -0,0 +1,2573 @@ ++++ +title = "API Reference" ++++ + + +## 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 +- [BackendTrafficPolicy](#backendtrafficpolicy) +- [BackendTrafficPolicyList](#backendtrafficpolicylist) +- [ClientTrafficPolicy](#clienttrafficpolicy) +- [ClientTrafficPolicyList](#clienttrafficpolicylist) +- [EnvoyGateway](#envoygateway) +- [EnvoyPatchPolicy](#envoypatchpolicy) +- [EnvoyPatchPolicyList](#envoypatchpolicylist) +- [EnvoyProxy](#envoyproxy) +- [SecurityPolicy](#securitypolicy) +- [SecurityPolicyList](#securitypolicylist) + + + +#### ALPNProtocol + +_Underlying type:_ _string_ + +ALPNProtocol specifies the protocol to be negotiated using ALPN + +_Appears in:_ +- [TLSSettings](#tlssettings) + + + +#### 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 | Description | +| --- | --- | --- | --- | +| `timeout` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | Timeout defines the time to wait for a health check response. | +| `interval` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | Interval defines the time between active health checks. | +| `unhealthyThreshold` | _integer_ | false | UnhealthyThreshold defines the number of unhealthy health checks required before a backend host is marked unhealthy. | +| `healthyThreshold` | _integer_ | false | 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. | + + +#### ActiveHealthCheckPayload + + + +ActiveHealthCheckPayload defines the encoding of the payload bytes in the payload. + +_Appears in:_ +- [HTTPActiveHealthChecker](#httpactivehealthchecker) +- [TCPActiveHealthChecker](#tcpactivehealthchecker) + +| Field | Type | Required | 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) + + + +#### ActiveHealthCheckerType + +_Underlying type:_ _string_ + +ActiveHealthCheckerType is the type of health checker. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + + + +#### BackOffPolicy + + + + + +_Appears in:_ +- [PerRetryPolicy](#perretrypolicy) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `baseInterval` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | true | BaseInterval is the base interval between retries. | +| `maxInterval` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | 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 | + + +#### BackendTrafficPolicy + + + +BackendTrafficPolicy allows the user to configure the behavior of the connection between the Envoy Proxy listener and the backend service. + +_Appears in:_ +- [BackendTrafficPolicyList](#backendtrafficpolicylist) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`BackendTrafficPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | true | spec defines the desired state of BackendTrafficPolicy. | + + +#### BackendTrafficPolicyList + + + +BackendTrafficPolicyList contains a list of BackendTrafficPolicy resources. + + + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`BackendTrafficPolicyList` +| `metadata` | _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#listmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` | _[BackendTrafficPolicy](#backendtrafficpolicy) array_ | true | | + + +#### BackendTrafficPolicySpec + + + +spec defines the desired state of BackendTrafficPolicy. + +_Appears in:_ +- [BackendTrafficPolicy](#backendtrafficpolicy) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `targetRef` | _[PolicyTargetReferenceWithSectionName](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReferenceWithSectionName)_ | 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 and be applied to the Gateway. | +| `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. | +| `loadBalancer` | _[LoadBalancer](#loadbalancer)_ | false | LoadBalancer policy to apply when routing traffic from the gateway to the backend endpoints | +| `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. | +| `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 | +| `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 | +| `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. | +| `timeout` | _[Timeout](#timeout)_ | false | Timeout settings for the backend connections. | +| `compression` | _[Compression](#compression) array_ | false | The compression config for the http streams. | + + +#### BasicAuth + + + +BasicAuth defines the configuration for the HTTP Basic Authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `users` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.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.

Note: The secret must be in the same namespace as the SecurityPolicy. | + + +#### BootstrapType + +_Underlying type:_ _string_ + +BootstrapType defines the types of bootstrap supported by Envoy Gateway. + +_Appears in:_ +- [ProxyBootstrap](#proxybootstrap) + + + +#### CORS + + + +CORS defines the configuration for Cross-Origin Resource Sharing (CORS). + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `allowOrigins` | _[Origin](#origin) array_ | true | AllowOrigins defines the origins that are allowed to make requests. | +| `allowMethods` | _string array_ | true | AllowMethods defines the methods that are allowed to make requests. | +| `allowHeaders` | _string array_ | true | AllowHeaders defines the headers that are allowed to be sent with requests. | +| `exposeHeaders` | _string array_ | true | ExposeHeaders defines the headers that can be exposed in the responses. | +| `maxAge` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | true | MaxAge defines how long the results of a preflight request can be cached. | +| `allowCredentials` | _boolean_ | true | AllowCredentials indicates whether a request can include user credentials like cookies, authentication headers, or TLS client certificates. | + + +#### CircuitBreaker + + + +CircuitBreaker defines the Circuit Breaker configuration. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `maxConnections` | _integer_ | false | The maximum number of connections that Envoy will establish to the referenced backend defined within a xRoute rule. | +| `maxPendingRequests` | _integer_ | false | The maximum number of pending requests that Envoy will queue to the referenced backend defined within a xRoute rule. | +| `maxParallelRequests` | _integer_ | false | The maximum number of parallel requests that Envoy will make to the referenced backend defined within a xRoute rule. | +| `maxParallelRetries` | _integer_ | false | 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. | + + +#### ClaimToHeader + + + +ClaimToHeader defines a configuration to convert JWT claims into HTTP headers + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | 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. | + + +#### ClientIPDetectionSettings + + + +ClientIPDetectionSettings provides configuration for determining the original client IP address for requests. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | 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 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. | + + +#### ClientTimeout + + + + + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `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. + +_Appears in:_ +- [ClientTrafficPolicyList](#clienttrafficpolicylist) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`ClientTrafficPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[ClientTrafficPolicySpec](#clienttrafficpolicyspec)_ | true | Spec defines the desired state of ClientTrafficPolicy. | + + +#### ClientTrafficPolicyList + + + +ClientTrafficPolicyList contains a list of ClientTrafficPolicy resources. + + + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`ClientTrafficPolicyList` +| `metadata` | _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#listmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` | _[ClientTrafficPolicy](#clienttrafficpolicy) array_ | true | | + + +#### ClientTrafficPolicySpec + + + +ClientTrafficPolicySpec defines the desired state of ClientTrafficPolicy. + +_Appears in:_ +- [ClientTrafficPolicy](#clienttrafficpolicy) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `targetRef` | _[PolicyTargetReferenceWithSectionName](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReferenceWithSectionName)_ | true | TargetRef is the name of the Gateway resource this policy is being attached to. This Policy and the TargetRef MUST be in the same namespace for this Policy to have effect and be applied to the Gateway. TargetRef | +| `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. | +| `clientIPDetection` | _[ClientIPDetectionSettings](#clientipdetectionsettings)_ | false | ClientIPDetectionSettings provides configuration for determining the original client IP address for requests. | +| `http3` | _[HTTP3Settings](#http3settings)_ | false | HTTP3 provides HTTP/3 configuration on the listener. | +| `tls` | _[TLSSettings](#tlssettings)_ | 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. | +| `http1` | _[HTTP1Settings](#http1settings)_ | false | HTTP1 provides HTTP/1 configuration on the listener. | +| `headers` | _[HeaderSettings](#headersettings)_ | false | HeaderSettings provides configuration for header management. | +| `timeout` | _[ClientTimeout](#clienttimeout)_ | false | Timeout settings for the client connections. | + + +#### 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:_ +- [TLSSettings](#tlssettings) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `caCertificateRefs` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.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. | + + +#### Compression + + + +Compression defines the config of enabling compression. This can help reduce the bandwidth at the expense of higher CPU. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[CompressorType](#compressortype)_ | true | CompressorType defines the compressor type to use for compression. | +| `gzip` | _[GzipCompressor](#gzipcompressor)_ | false | The configuration for GZIP compressor. | + + +#### CompressorType + +_Underlying type:_ _string_ + +CompressorType defines the types of compressor library supported by Envoy Gateway. + +_Appears in:_ +- [Compression](#compression) + + + +#### ConsistentHash + + + +ConsistentHash defines the configuration related to the consistent hash load balancer policy + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[ConsistentHashType](#consistenthashtype)_ | true | | + + +#### ConsistentHashType + +_Underlying type:_ _string_ + +ConsistentHashType defines the type of input to hash on. + +_Appears in:_ +- [ConsistentHash](#consistenthash) + + + +#### CustomHeaderExtensionSettings + + + +CustomHeader 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 | 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. | + + +#### CustomTag + + + + + +_Appears in:_ +- [ProxyTracing](#proxytracing) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[CustomTagType](#customtagtype)_ | true | 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) + + + +#### EnvironmentCustomTag + + + +EnvironmentCustomTag adds value from environment variable to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | 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. | + + +#### EnvoyGateway + + + +EnvoyGateway is the schema for the envoygateways API. + + + +| Field | Type | Required | 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 | 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. | +| `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. | +| `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ | false | ExtensionAPIs defines the settings related to specific Gateway API Extensions implemented by Envoy Gateway | + + +#### EnvoyGatewayAdmin + + + +EnvoyGatewayAdmin defines the Envoy Gateway Admin configuration. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | 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 | Description | +| --- | --- | --- | --- | +| `port` | _integer_ | false | Port defines the port the admin server is exposed on. | +| `host` | _string_ | false | Host defines the admin server hostname. | + + +#### EnvoyGatewayCustomProvider + + + +EnvoyGatewayCustomProvider defines configuration for the Custom provider. + +_Appears in:_ +- [EnvoyGatewayProvider](#envoygatewayprovider) + +| Field | Type | Required | 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)_ | true | 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. | + + +#### EnvoyGatewayFileResourceProvider + + + +EnvoyGatewayFileResourceProvider defines configuration for the File Resource provider. + +_Appears in:_ +- [EnvoyGatewayResourceProvider](#envoygatewayresourceprovider) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `paths` | _string array_ | true | Paths are the paths to a directory or file containing the resource configuration. Recursive sub directories are not currently supported. | + + +#### EnvoyGatewayHostInfrastructureProvider + + + +EnvoyGatewayHostInfrastructureProvider defines configuration for the Host Infrastructure provider. + +_Appears in:_ +- [EnvoyGatewayInfrastructureProvider](#envoygatewayinfrastructureprovider) + + + +#### EnvoyGatewayInfrastructureProvider + + + +EnvoyGatewayInfrastructureProvider defines configuration for the Custom Infrastructure provider. + +_Appears in:_ +- [EnvoyGatewayCustomProvider](#envoygatewaycustomprovider) + +| Field | Type | Required | 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 | 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. | +| `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 | +| `overwriteControlPlaneCerts` | _boolean_ | false | OverwriteControlPlaneCerts updates the secrets containing the control plane certs, when set. | + + +#### EnvoyGatewayLogComponent + +_Underlying type:_ _string_ + +EnvoyGatewayLogComponent defines a component that supports a configured logging level. + +_Appears in:_ +- [EnvoyGatewayLogging](#envoygatewaylogging) + + + +#### EnvoyGatewayLogging + + + +EnvoyGatewayLogging defines logging for Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `level` | _object (keys:[EnvoyGatewayLogComponent](#envoygatewaylogcomponent), values:[LogLevel](#loglevel))_ | true | 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. | + + +#### EnvoyGatewayMetricSink + + + +EnvoyGatewayMetricSink defines control plane metric sinks where metrics are sent to. + +_Appears in:_ +- [EnvoyGatewayMetrics](#envoygatewaymetrics) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[MetricSinkType](#metricsinktype)_ | true | 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 | 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) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `host` | _string_ | true | Host define the sink service hostname. | +| `protocol` | _string_ | true | Protocol define the sink service protocol. | +| `port` | _integer_ | false | Port defines the port the sink service is exposed on. | + + +#### EnvoyGatewayPrometheusProvider + + + +EnvoyGatewayPrometheusProvider will expose prometheus endpoint in pull mode. + +_Appears in:_ +- [EnvoyGatewayMetrics](#envoygatewaymetrics) + +| Field | Type | Required | 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 | Description | +| --- | --- | --- | --- | +| `type` | _[ProviderType](#providertype)_ | true | Type is the type of provider to use. Supported types are "Kubernetes". | +| `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 a infrastructure provider. | + + +#### EnvoyGatewayResourceProvider + + + +EnvoyGatewayResourceProvider defines configuration for the Custom Resource provider. + +_Appears in:_ +- [EnvoyGatewayCustomProvider](#envoygatewaycustomprovider) + +| Field | Type | Required | 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 | 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 | 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. | +| `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. | +| `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ | false | ExtensionAPIs defines the settings related to specific Gateway API Extensions implemented by Envoy Gateway | + + +#### 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 | Description | +| --- | --- | --- | --- | +| `metrics` | _[EnvoyGatewayMetrics](#envoygatewaymetrics)_ | true | Metrics defines metrics configuration for envoy gateway. | + + +#### EnvoyJSONPatchConfig + + + +EnvoyJSONPatchConfig defines the configuration for patching a Envoy xDS Resource using JSONPatch semantic + +_Appears in:_ +- [EnvoyPatchPolicySpec](#envoypatchpolicyspec) + +| Field | Type | Required | 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 + +_Appears in:_ +- [EnvoyPatchPolicyList](#envoypatchpolicylist) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyPatchPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[EnvoyPatchPolicySpec](#envoypatchpolicyspec)_ | true | Spec defines the desired state of EnvoyPatchPolicy. | + + +#### EnvoyPatchPolicyList + + + +EnvoyPatchPolicyList contains a list of EnvoyPatchPolicy resources. + + + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyPatchPolicyList` +| `metadata` | _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#listmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` | _[EnvoyPatchPolicy](#envoypatchpolicy) array_ | true | | + + +#### EnvoyPatchPolicySpec + + + +EnvoyPatchPolicySpec defines the desired state of EnvoyPatchPolicy. + +_Appears in:_ +- [EnvoyPatchPolicy](#envoypatchpolicy) + +| Field | Type | Required | 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` | _[PolicyTargetReference](#policytargetreference)_ | 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) + + + +#### EnvoyProxy + + + +EnvoyProxy is the schema for the envoyproxies API. + + + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`EnvoyProxy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[EnvoyProxySpec](#envoyproxyspec)_ | true | EnvoyProxySpec defines the desired state of EnvoyProxy. | + + +#### EnvoyProxyKubernetesProvider + + + +EnvoyProxyKubernetesProvider defines configuration for the Kubernetes resource provider. + +_Appears in:_ +- [EnvoyProxyProvider](#envoyproxyprovider) + +| Field | Type | Required | 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. | +| `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. Once the HPA is being set, Replicas field from EnvoyDeployment will be ignored. | + + +#### EnvoyProxyProvider + + + +EnvoyProxyProvider defines the desired state of a resource provider. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[ProviderType](#providertype)_ | 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". | +| `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. | + + +#### EnvoyProxySpec + + + +EnvoyProxySpec defines the desired state of EnvoyProxy. + +_Appears in:_ +- [EnvoyProxy](#envoyproxy) + +| Field | Type | Required | 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 | 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. | +| `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. | + + + + +#### EnvoyResourceType + +_Underlying type:_ _string_ + +EnvoyResourceType specifies the type URL of the Envoy resource. + +_Appears in:_ +- [EnvoyJSONPatchConfig](#envoyjsonpatchconfig) + + + +#### ExtAuth + + + +ExtAuth defines the configuration for External Authorization. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | 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. | + + +#### ExtensionAPISettings + + + +ExtensionAPISettings defines the settings specific to Gateway API Extensions. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enableEnvoyPatchPolicy` | _boolean_ | true | EnableEnvoyPatchPolicy enables Envoy Gateway to reconcile and implement the EnvoyPatchPolicy resources. | + + +#### ExtensionHooks + + + +ExtensionHooks defines extension hooks across all supported runners + +_Appears in:_ +- [ExtensionManager](#extensionmanager) + +| Field | Type | Required | 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 | Description | +| --- | --- | --- | --- | +| `resources` | _[GroupVersionKind](#groupversionkind) array_ | false | Resources defines the set of K8s resources the extension will handle. | +| `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. | + + +#### ExtensionService + + + +ExtensionService defines the configuration for connecting to a registered extension service. + +_Appears in:_ +- [ExtensionManager](#extensionmanager) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `host` | _string_ | true | Host define the extension service hostname. | +| `port` | _integer_ | false | Port defines the port the extension service is exposed on. | +| `tls` | _[ExtensionTLS](#extensiontls)_ | false | TLS defines TLS configuration for communication between Envoy Gateway and the extension service. | + + +#### ExtensionTLS + + + +ExtensionTLS defines the TLS configuration when connecting to an extension service + +_Appears in:_ +- [ExtensionService](#extensionservice) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `certificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.SecretObjectReference)_ | true | CertificateRef contains a references to objects (Kubernetes objects or otherwise) that contains a TLS certificate and private keys. These certificates are used to establish a TLS handshake to the extension server.

CertificateRef can only reference a Kubernetes Secret at this time. | + + +#### 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 | 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 | 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 | 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 | Description | +| --- | --- | --- | --- | +| `fixedDelay` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | true | FixedDelay specifies the fixed delay duration | +| `percentage` | _float_ | false | 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 | Description | +| --- | --- | --- | --- | +| `path` | _string_ | true | Path defines the file path used to expose envoy access log(e.g. /dev/stdout). | + + +#### 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 | Description | +| --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](#backendobjectreference)_ | true | BackendRef references a Kubernetes object that represents the backend server to which the authorization request will be sent. Only service Kind is supported for now. | + + +#### Gateway + + + +Gateway defines the desired Gateway API configuration of Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Type | Required | 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/references/spec/#gateway.networking.k8s.io/v1.GatewayClass | + + +#### GlobalRateLimit + + + +GlobalRateLimit defines global rate limit configuration. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + +| Field | Type | Required | 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 | 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 | Description | +| --- | --- | --- | --- | +| `useDefaultHost` | _boolean_ | false | UseDefaultHost defines if the HTTP/1.0 request is missing the Host header, then the hostname associated with the listener should be injected into the request. If this is not set and an HTTP/1.0 request arrives without a host, then it will be rejected. | + + +#### HTTP1Settings + + + +HTTP1Settings provides HTTP/1 configuration on the listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | 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. | + + +#### 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 | Description | +| --- | --- | --- | --- | +| `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 | +| `expectedResponse` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | ExpectedResponse defines a list of HTTP expected responses to match. | + + +#### HTTPClientTimeout + + + + + +_Appears in:_ +- [ClientTimeout](#clienttimeout) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `requestReceivedTimeout` | _[Duration](#duration)_ | false | 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. | + + +#### HTTPExtAuthService + + + +HTTPExtAuthService defines the HTTP External Authorization service + +_Appears in:_ +- [ExtAuth](#extauth) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `backendRef` | _[BackendObjectReference](#backendobjectreference)_ | true | BackendRef references a Kubernetes object that represents the backend server to which the authorization request will be sent. Only service Kind is supported for now. | +| `path` | _string_ | true | 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 be sent to the root path. | +| `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. | + + +#### HTTPStatus + +_Underlying type:_ _integer_ + +HTTPStatus defines the http status code. + +_Appears in:_ +- [HTTPActiveHealthChecker](#httpactivehealthchecker) +- [RetryOn](#retryon) + + + +#### HTTPTimeout + + + + + +_Appears in:_ +- [Timeout](#timeout) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `connectionIdleTimeout` | _[Duration](#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](#duration)_ | false | The maximum duration of an HTTP connection. Default: unlimited. | + + + + +#### 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) + + + +#### HeaderSettings + + + +HeaderSettings providess configuration options for headers on the listener. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enableEnvoyHeaders` | _boolean_ | false | EnableEnvoyHeaders configures Envoy Proxy to add the "X-Envoy-" headers to requests and responses. | + + +#### HealthCheck + + + +HealthCheck configuration to decide which endpoints are healthy and can be used for routing. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `active` | _[ActiveHealthCheck](#activehealthcheck)_ | false | Active health check configuration | +| `passive` | _[PassiveHealthCheck](#passivehealthcheck)_ | false | Passive passive check configuration | + + +#### InfrastructureProviderType + +_Underlying type:_ _string_ + +InfrastructureProviderType defines the types of custom infrastructure providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayInfrastructureProvider](#envoygatewayinfrastructureprovider) + + + +#### JSONPatchOperation + + + +JSONPatchOperation defines the JSON Patch Operation as defined in https://datatracker.ietf.org/doc/html/rfc6902 + +_Appears in:_ +- [EnvoyJSONPatchConfig](#envoyjsonpatchconfig) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `op` | _[JSONPatchOperationType](#jsonpatchoperationtype)_ | true | Op is the type of operation to perform | +| `path` | _string_ | true | Path is the location of the target document/field where the operation will be performed Refer to https://datatracker.ietf.org/doc/html/rfc6901 for more details. | +| `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](#json)_ | 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 | Description | +| --- | --- | --- | --- | +| `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. | + + +#### 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 | 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 | 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. | + + +#### JWTProvider + + + +JWTProvider defines how a JSON Web Token (JWT) can be verified. + +_Appears in:_ +- [JWT](#jwt) + +| Field | Type | Required | 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)_ | true | RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. | +| `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. | + + +#### KubernetesContainerSpec + + + +KubernetesContainerSpec defines the desired state of the Kubernetes container resource. + +_Appears in:_ +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `env` | _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#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.26/#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.26/#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, instead of the default image. | +| `volumeMounts` | _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core) array_ | false | VolumeMounts are volumes to mount into the container's filesystem. Cannot be updated. | + + +#### KubernetesDeployMode + + + +KubernetesDeployMode holds configuration for how to deploy managed resources such as the Envoy Proxy data plane fleet. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + + + +#### KubernetesDeploymentSpec + + + +KubernetesDeploymentSpec defines the desired state of the Kubernetes deployment resource. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | 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.26/#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.26/#container-v1-core) array_ | false | List of initialization containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ | + + +#### 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:_ +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | 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.26/#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.26/#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. | + + +#### KubernetesPatchSpec + + + +KubernetesPatchSpec defines how to perform the patch operation + +_Appears in:_ +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) +- [KubernetesServiceSpec](#kubernetesservicespec) + +| Field | Type | Required | 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](#json)_ | true | Object contains the raw configuration for merged object | + + +#### KubernetesPodSpec + + + +KubernetesPodSpec defines the desired state of the Kubernetes pod resource. + +_Appears in:_ +- [KubernetesDeploymentSpec](#kubernetesdeploymentspec) + +| Field | Type | Required | 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.26/#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.26/#affinity-v1-core)_ | false | If specified, the pod's scheduling constraints. | +| `tolerations` | _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core) array_ | false | If specified, the pod's tolerations. | +| `volumes` | _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#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.26/#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.26/#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. | + + +#### KubernetesServiceSpec + + + +KubernetesServiceSpec defines the desired state of the Kubernetes service resource. + +_Appears in:_ +- [EnvoyProxyKubernetesProvider](#envoyproxykubernetesprovider) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `annotations` | _object (keys:string, values:string)_ | false | Annotations that should be appended to the service. By default, no annotations are appended. | +| `type` | _[ServiceType](#servicetype)_ | false | 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. | +| `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 | 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 | + + +#### KubernetesWatchMode + + + +KubernetesWatchMode holds the configuration for which input resources to watch and reconcile. + +_Appears in:_ +- [EnvoyGatewayKubernetesProvider](#envoygatewaykubernetesprovider) + +| Field | Type | Required | 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.26/#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) + + + +#### LiteralCustomTag + + + +LiteralCustomTag adds hard-coded value to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | 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) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[LoadBalancerType](#loadbalancertype)_ | true | Type decides the type of Load Balancer policy. Valid LoadBalancerType values are "ConsistentHash", "LeastRequest", "Random", "RoundRobin", | +| `consistentHash` | _[ConsistentHash](#consistenthash)_ | false | ConsistentHash defines the configuration when the load balancer type is set to ConsistentHash | +| `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. Currently this is only supported for RoundRobin and LeastRequest load balancers | + + +#### LoadBalancerType + +_Underlying type:_ _string_ + +LoadBalancerType specifies the types of LoadBalancer. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + + + +#### LocalRateLimit + + + +LocalRateLimit defines local rate limit configuration. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + +| Field | Type | Required | 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) + + + + + +#### MetricSinkType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [EnvoyGatewayMetricSink](#envoygatewaymetricsink) +- [ProxyMetricSink](#proxymetricsink) + + + +#### OIDC + + + +OIDC defines the configuration for the OpenID Connect (OIDC) authentication. + +_Appears in:_ +- [SecurityPolicySpec](#securitypolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `provider` | _[OIDCProvider](#oidcprovider)_ | true | The OIDC Provider configuration. | +| `clientID` | _string_ | true | The client ID to be used in the OIDC [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). | +| `clientSecret` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.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". | +| `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. | +| `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" | +| `logoutPath` | _string_ | true | The path to log a user out, clearing their credential cookies. If not specified, uses a default logout path "/logout" | + + +#### OIDCProvider + + + +OIDCProvider defines the OIDC Provider configuration. + +_Appears in:_ +- [OIDC](#oidc) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `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). | + + +#### OpenTelemetryEnvoyProxyAccessLog + + + +TODO: consider reuse ExtensionService? + +_Appears in:_ +- [ProxyAccessLogSink](#proxyaccesslogsink) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `host` | _string_ | true | Host define the extension service hostname. | +| `port` | _integer_ | false | Port defines the port the extension service is exposed on. | +| `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/). | + + +#### 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) + + + +#### 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 | Description | +| --- | --- | --- | --- | +| `splitExternalLocalOriginErrors` | _boolean_ | false | SplitExternalLocalOriginErrors enables splitting of errors between external and local origin. | +| `interval` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | Interval defines the time between passive health checks. | +| `consecutiveLocalOriginFailures` | _integer_ | false | 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 | Consecutive5xxErrors sets the number of consecutive 5xx errors triggering ejection. | +| `baseEjectionTime` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | BaseEjectionTime defines the base duration for which a host will be ejected on consecutive failures. | +| `maxEjectionPercent` | _integer_ | false | MaxEjectionPercent sets the maximum percentage of hosts in a cluster that can be ejected. | + + +#### 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) + + + +#### PathSettings + + + +PathSettings provides settings that managing how the incoming path set by clients is handled. + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | 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. | + + +#### PerRetryPolicy + + + + + +_Appears in:_ +- [Retry](#retry) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `timeout` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | 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 | + + +#### ProviderType + +_Underlying type:_ _string_ + +ProviderType defines the types of providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayProvider](#envoygatewayprovider) +- [EnvoyProxyProvider](#envoyproxyprovider) + + + +#### ProxyAccessLog + + + + + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `disable` | _boolean_ | true | 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 | Description | +| --- | --- | --- | --- | +| `type` | _[ProxyAccessLogFormatType](#proxyaccesslogformattype)_ | true | Type defines the type of accesslog format. | +| `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) + + + +#### ProxyAccessLogSetting + + + + + +_Appears in:_ +- [ProxyAccessLog](#proxyaccesslog) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `format` | _[ProxyAccessLogFormat](#proxyaccesslogformat)_ | true | Format defines the format of accesslog. | +| `sinks` | _[ProxyAccessLogSink](#proxyaccesslogsink) array_ | true | Sinks defines the sinks of accesslog. | + + +#### ProxyAccessLogSink + + + +ProxyAccessLogSink defines the sink of accesslog. + +_Appears in:_ +- [ProxyAccessLogSetting](#proxyaccesslogsetting) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[ProxyAccessLogSinkType](#proxyaccesslogsinktype)_ | true | Type defines the type of accesslog 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) + + + +#### ProxyBootstrap + + + +ProxyBootstrap defines Envoy Bootstrap configuration. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[BootstrapType](#bootstraptype)_ | false | Type is the type of the bootstrap configuration, it should be either Replace or Merge. If unspecified, it defaults to Replace. | +| `value` | _string_ | true | Value is a YAML string of the bootstrap. | + + +#### ProxyLogComponent + +_Underlying type:_ _string_ + +ProxyLogComponent defines a component that supports a configured logging level. + +_Appears in:_ +- [ProxyLogging](#proxylogging) + + + +#### ProxyLogging + + + +ProxyLogging defines logging parameters for managed proxies. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `level` | _object (keys:[ProxyLogComponent](#proxylogcomponent), values:[LogLevel](#loglevel))_ | true | 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 | Description | +| --- | --- | --- | --- | +| `type` | _[MetricSinkType](#metricsinktype)_ | true | 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 | 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_ | true | EnableVirtualHostStats enables envoy stat metrics for virtual hosts. | + + +#### ProxyOpenTelemetrySink + + + + + +_Appears in:_ +- [ProxyMetricSink](#proxymetricsink) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `host` | _string_ | true | Host define the service hostname. | +| `port` | _integer_ | false | Port defines the port the service is exposed on. | + + +#### ProxyPrometheusProvider + + + + + +_Appears in:_ +- [ProxyMetrics](#proxymetrics) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `disable` | _boolean_ | true | Disable the Prometheus endpoint. | + + +#### ProxyProtocol + + + +ProxyProtocol defines the configuration related to the proxy protocol when communicating with the backend. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `version` | _[ProxyProtocolVersion](#proxyprotocolversion)_ | true | Version of ProxyProtol Valid ProxyProtocolVersion values are "V1" "V2" | + + +#### ProxyProtocolVersion + +_Underlying type:_ _string_ + +ProxyProtocolVersion defines the version of the Proxy Protocol to use. + +_Appears in:_ +- [ProxyProtocol](#proxyprotocol) + + + +#### ProxyTelemetry + + + + + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | 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. | + + +#### ProxyTracing + + + + + +_Appears in:_ +- [ProxyTelemetry](#proxytelemetry) + +| Field | Type | Required | 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. | +| `customTags` | _object (keys:string, values:[CustomTag](#customtag))_ | true | CustomTags defines the custom tags to add to each span. If provider is kubernetes, pod name and namespace are added by default. | +| `provider` | _[TracingProvider](#tracingprovider)_ | true | Provider defines the tracing provider. Only OpenTelemetry is supported currently. | + + +#### 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 | 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://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | 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. | + + +#### RateLimitDatabaseBackend + + + +RateLimitDatabaseBackend defines the configuration associated with the database backend used by the rate limit service. + +_Appears in:_ +- [RateLimit](#ratelimit) + +| Field | Type | Required | 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) + + + +#### RateLimitMetrics + + + + + +_Appears in:_ +- [RateLimitTelemetry](#ratelimittelemetry) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `prometheus` | _[RateLimitMetricsPrometheusProvider](#ratelimitmetricsprometheusprovider)_ | true | Prometheus defines the configuration for prometheus endpoint. | + + +#### RateLimitMetricsPrometheusProvider + + + + + +_Appears in:_ +- [RateLimitMetrics](#ratelimitmetrics) + +| Field | Type | Required | 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 | Description | +| --- | --- | --- | --- | +| `url` | _string_ | true | URL of the Redis Database. | +| `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 | 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. | + + +#### 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. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Type | Required | 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. At least one of headers or sourceCIDR condition must be specified. | +| `sourceCIDR` | _[SourceMatch](#sourcematch)_ | false | SourceCIDR is the client IP Address range to match on. At least one of headers or sourceCIDR condition must be specified. | + + +#### RateLimitSpec + + + +RateLimitSpec defines the desired state of RateLimitSpec. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[RateLimitType](#ratelimittype)_ | true | Type decides the scope for the RateLimits. Valid RateLimitType values are "Global" or "Local". | +| `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 | Description | +| --- | --- | --- | --- | +| `metrics` | _[RateLimitMetrics](#ratelimitmetrics)_ | true | Metrics defines metrics configuration for RateLimit. | + + +#### RateLimitType + +_Underlying type:_ _string_ + +RateLimitType specifies the types of RateLimiting. + +_Appears in:_ +- [RateLimitSpec](#ratelimitspec) + + + +#### RateLimitUnit + +_Underlying type:_ _string_ + +RateLimitUnit specifies the intervals for setting rate limits. Valid RateLimitUnit values are "Second", "Minute", "Hour", and "Day". + +_Appears in:_ +- [RateLimitValue](#ratelimitvalue) + + + +#### RateLimitValue + + + +RateLimitValue defines the limits for rate limiting. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `requests` | _integer_ | true | | +| `unit` | _[RateLimitUnit](#ratelimitunit)_ | true | | + + +#### RedisTLSSettings + + + +RedisTLSSettings defines the TLS configuration for connecting to redis database. + +_Appears in:_ +- [RateLimitRedisSettings](#ratelimitredissettings) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `certificateRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.SecretObjectReference)_ | false | CertificateRef defines the client certificate reference for TLS connections. Currently only a Kubernetes Secret of type TLS is supported. | + + +#### RemoteJWKS + + + +RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. + +_Appears in:_ +- [JWTProvider](#jwtprovider) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `uri` | _string_ | true | URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate. | + + +#### RequestHeaderCustomTag + + + +RequestHeaderCustomTag adds value from request header to each span. + +_Appears in:_ +- [CustomTag](#customtag) + +| Field | Type | Required | 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. | + + +#### ResourceProviderType + +_Underlying type:_ _string_ + +ResourceProviderType defines the types of custom resource providers supported by Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewayResourceProvider](#envoygatewayresourceprovider) + + + +#### Retry + + + +Retry defines the retry strategy to be applied. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `numRetries` | _integer_ | false | NumRetries is the number of retries to be attempted. Defaults to 2. | +| `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. | + + +#### RetryOn + + + + + +_Appears in:_ +- [Retry](#retry) + +| Field | Type | Required | 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. | + + +#### SecurityPolicy + + + +SecurityPolicy allows the user to configure various security settings for a Gateway. + +_Appears in:_ +- [SecurityPolicyList](#securitypolicylist) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`SecurityPolicy` +| `metadata` | _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` | _[SecurityPolicySpec](#securitypolicyspec)_ | true | Spec defines the desired state of SecurityPolicy. | + + +#### SecurityPolicyList + + + +SecurityPolicyList contains a list of SecurityPolicy resources. + + + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `apiVersion` | _string_ | |`gateway.envoyproxy.io/v1alpha1` +| `kind` | _string_ | |`SecurityPolicyList` +| `metadata` | _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#listmeta-v1-meta)_ | true | Refer to Kubernetes API documentation for fields of `metadata`. | +| `items` | _[SecurityPolicy](#securitypolicy) array_ | true | | + + +#### SecurityPolicySpec + + + +SecurityPolicySpec defines the desired state of SecurityPolicy. + +_Appears in:_ +- [SecurityPolicy](#securitypolicy) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `targetRef` | _[PolicyTargetReferenceWithSectionName](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReferenceWithSectionName)_ | true | TargetRef is the name of the Gateway resource this policy is being attached to. This Policy and the TargetRef MUST be in the same namespace for this Policy to have effect and be applied to the Gateway. | +| `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. | + + + + +#### 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) + + + +#### ServiceType + +_Underlying type:_ _string_ + +ServiceType string describes ingress methods for a service + +_Appears in:_ +- [KubernetesServiceSpec](#kubernetesservicespec) + + + +#### ShutdownConfig + + + +ShutdownConfig defines configuration for graceful envoy shutdown process. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `drainTimeout` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | DrainTimeout defines the graceful drain timeout. This should be less than the pod's terminationGracePeriodSeconds. If unspecified, defaults to 600 seconds. | +| `minDrainDuration` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | false | MinDrainDuration defines the minimum drain duration allowing time for endpoint deprogramming to complete. If unspecified, defaults to 5 seconds. | + + +#### SlowStart + + + +SlowStart defines the configuration related to the slow start load balancer policy. + +_Appears in:_ +- [LoadBalancer](#loadbalancer) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `window` | _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#duration-v1-meta)_ | 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 | + + + + +#### SourceMatchType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [SourceMatch](#sourcematch) + + + +#### 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:_ +- [ProxyMetrics](#proxymetrics) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[StringMatchType](#stringmatchtype)_ | false | 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:_ +- [StringMatch](#stringmatch) + + + +#### TCPActiveHealthChecker + + + +TCPActiveHealthChecker defines the settings of tcp health check. + +_Appears in:_ +- [ActiveHealthCheck](#activehealthcheck) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `send` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | Send defines the request payload. | +| `receive` | _[ActiveHealthCheckPayload](#activehealthcheckpayload)_ | false | Receive defines the expected response payload. | + + +#### TCPKeepalive + + + +TCPKeepalive define the TCP Keepalive configuration. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `probes` | _integer_ | false | The total number of unacknowledged probes to send before deciding the connection is dead. Defaults to 9. | +| `idleTime` | _[Duration](#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](#duration)_ | false | The duration between keep-alive probes. Defaults to `75s`. | + + +#### TCPTimeout + + + + + +_Appears in:_ +- [Timeout](#timeout) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `connectTimeout` | _[Duration](#duration)_ | false | The timeout for network connection establishment, including TCP and TLS handshakes. Default: 10 seconds. | + + +#### TLSSettings + + + + + +_Appears in:_ +- [ClientTrafficPolicySpec](#clienttrafficpolicyspec) + +| Field | Type | Required | 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. 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. By default h2 and http/1.1 are enabled. Supported values are: - http/1.0 - http/1.1 - h2 | +| `clientValidation` | _[ClientValidationContext](#clientvalidationcontext)_ | false | ClientValidation specifies the configuration to validate the client initiating the TLS connection to the Gateway listener. | + + +#### TLSVersion + +_Underlying type:_ _string_ + +TLSVersion specifies the TLS version + +_Appears in:_ +- [TLSSettings](#tlssettings) + + + +#### Timeout + + + +Timeout defines configuration for timeouts related to connections. + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `tcp` | _[TCPTimeout](#tcptimeout)_ | false | Timeout settings for TCP. | +| `http` | _[HTTPTimeout](#httptimeout)_ | false | Timeout settings for HTTP. | + + +#### TracingProvider + + + + + +_Appears in:_ +- [ProxyTracing](#proxytracing) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | _[TracingProviderType](#tracingprovidertype)_ | true | Type defines the tracing provider type. EG currently only supports OpenTelemetry. | +| `host` | _string_ | true | Host define the provider service hostname. | +| `port` | _integer_ | false | Port defines the port the provider service is exposed on. | + + +#### TracingProviderType + +_Underlying type:_ _string_ + + + +_Appears in:_ +- [TracingProvider](#tracingprovider) + + + +#### TriggerEnum + +_Underlying type:_ _string_ + +TriggerEnum specifies the conditions that trigger retries. + +_Appears in:_ +- [RetryOn](#retryon) + + + +#### 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) + + + +#### XDSTranslatorHooks + + + +XDSTranslatorHooks contains all the pre and post hooks for the xds-translator runner. + +_Appears in:_ +- [ExtensionHooks](#extensionhooks) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `pre` | _[XDSTranslatorHook](#xdstranslatorhook) array_ | true | | +| `post` | _[XDSTranslatorHook](#xdstranslatorhook) array_ | true | | + + +#### XForwardedForSettings + + + +XForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address. + +_Appears in:_ +- [ClientIPDetectionSettings](#clientipdetectionsettings) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `numTrustedHops` | _integer_ | false | NumTrustedHops controls the number of additional ingress proxy hops from the right side of XFF HTTP headers to trust when determining the origin client's IP address. Refer to https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for for more details. | + + diff --git a/site/content/en/docs/install/_index.md b/site/content/en/docs/install/_index.md new file mode 100644 index 00000000000..b4c6f79c6fd --- /dev/null +++ b/site/content/en/docs/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/docs/install/api.md b/site/content/en/docs/install/api.md new file mode 100644 index 00000000000..a1eb0a554f4 --- /dev/null +++ b/site/content/en/docs/install/api.md @@ -0,0 +1,55 @@ ++++ +title = "gateway-helm" ++++ + + +![Version: v1.0.0](https://img.shields.io/badge/Version-v1.0.0-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 + +* + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| certgen.job.annotations | object | `{}` | | +| certgen.job.resources | object | `{}` | | +| certgen.job.ttlSecondsAfterFinished | int | `0` | | +| certgen.rbac.annotations | object | `{}` | | +| certgen.rbac.labels | object | `{}` | | +| config.envoyGateway.gateway.controllerName | string | `"gateway.envoyproxy.io/gatewayclass-controller"` | | +| config.envoyGateway.logging.level.default | string | `"info"` | | +| config.envoyGateway.provider.type | string | `"Kubernetes"` | | +| createNamespace | bool | `false` | | +| deployment.envoyGateway.image.repository | string | `"${ImageRepository}"` | | +| deployment.envoyGateway.image.tag | string | `"${ImageTag}"` | | +| deployment.envoyGateway.imagePullPolicy | string | `"Always"` | | +| deployment.envoyGateway.imagePullSecrets | list | `[]` | | +| deployment.envoyGateway.resources.limits.cpu | string | `"500m"` | | +| deployment.envoyGateway.resources.limits.memory | string | `"1024Mi"` | | +| deployment.envoyGateway.resources.requests.cpu | string | `"100m"` | | +| deployment.envoyGateway.resources.requests.memory | string | `"256Mi"` | | +| deployment.pod.affinity | object | `{}` | | +| deployment.pod.annotations | object | `{}` | | +| deployment.pod.labels | object | `{}` | | +| 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.replicas | int | `1` | | +| envoyGatewayMetricsService.port | int | `19001` | | +| kubernetesClusterDomain | string | `"cluster.local"` | | diff --git a/site/content/en/docs/install/custom-cert.md b/site/content/en/docs/install/custom-cert.md new file mode 100644 index 00000000000..c521e61d27d --- /dev/null +++ b/site/content/en/docs/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. + +In this guide, we'll 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 guide, 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 <}} +{{% 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_latest_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 + +# install the latest development version of egctl +bash VERSION=latest get-egctl.sh +``` + +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=latest 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/docs/install/install-helm.md b/site/content/en/docs/install/install-helm.md new file mode 100644 index 00000000000..e1d3d266a89 --- /dev/null +++ b/site/content/en/docs/install/install-helm.md @@ -0,0 +1,144 @@ ++++ +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 %}} + +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 `v1.0.2` 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 + +Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one. + +{{% alert title="Developer Guide" color="primary" %}} +Refer to the [Developer Guide](../../contributions/develop) to learn more. +{{% /alert %}} + +Install the Gateway API CRDs and Envoy Gateway: + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.0.2 -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/latest/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/latest/quickstart.yaml + +## Helm chart customizations + +Some of the quick ways of using the helm install command for envoy gateway installation are below. + +### Increase the replicas + +```shell +helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.0.2 -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 v1.0.2 -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 v1.0.2 -n envoy-gateway-system --create-namespace -f values.yaml +``` + +{{% 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](./api). +{{% /alert %}} + +## 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 | +| Heath Check | 0.0.0.0 | 19001 | + +{{% alert title="Next Steps" color="warning" %}} +Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [Tasks](../tasks). +{{% /alert %}} diff --git a/site/content/en/docs/install/install-yaml.md b/site/content/en/docs/install/install-yaml.md new file mode 100644 index 00000000000..83afd64f540 --- /dev/null +++ b/site/content/en/docs/install/install-yaml.md @@ -0,0 +1,39 @@ ++++ +title = "Install with Kubernetes YAML" +weight = -99 ++++ + +In this guide, we'll walk you through installing Envoy Gateway in your Kubernetes cluster. + +The manual install process does not allow for as much control over configuration +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 + +Envoy Gateway is designed to run in Kubernetes for production. The most essential requirements are: + +* Kubernetes 1.25 or later +* The `kubectl` command-line tool + +{{% alert title="Compatibility Matrix" color="warning" %}} +Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more. +{{% /alert %}} + +## Install with YAML + +Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one. + +{{% alert title="Developer Guide" color="primary" %}} +Refer to the [Developer Guide](../../contributions/develop) to learn more. +{{% /alert %}} + +1. In your terminal, run the following command: + + ```shell + kubectl apply --server-side -f https://github.com/envoyproxy/gateway/releases/download/v1.0.2/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). diff --git a/site/content/en/docs/tasks/_index.md b/site/content/en/docs/tasks/_index.md new file mode 100644 index 00000000000..49e8595328b --- /dev/null +++ b/site/content/en/docs/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/docs/tasks/extensibility/_index.md b/site/content/en/docs/tasks/extensibility/_index.md new file mode 100644 index 00000000000..0a6db282139 --- /dev/null +++ b/site/content/en/docs/tasks/extensibility/_index.md @@ -0,0 +1,5 @@ +--- +title: "Extensibility" +weight: 4 +description: This section includes extensibility tasks +--- diff --git a/site/content/en/docs/tasks/extensibility/envoy-patch-policy.md b/site/content/en/docs/tasks/extensibility/envoy-patch-policy.md new file mode 100644 index 00000000000..83b95065a82 --- /dev/null +++ b/site/content/en/docs/tasks/extensibility/envoy-patch-policy.md @@ -0,0 +1,241 @@ +--- +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. + +## Quickstart + +### Prerequisites + +* Follow the steps from the [Quickstart](../../quickstart) task to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +### 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. + + +```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 +``` + +When mergeGateways is enabled, there will be one Envoy deployment for all Gateways in the cluster. +Then the EnvoyPatchPolicy should target a specific GatewayClass. + +```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 +``` + +* 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` + +``` +$ curl --header "Host: www.example.com" http://localhost:8888/find +Handling connection for 8888 +could not find what you are looking for +``` + +## 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 + namespace: default + 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 garunteed +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 +[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/docs/tasks/observability/_index.md b/site/content/en/docs/tasks/observability/_index.md new file mode 100644 index 00000000000..7f77113331c --- /dev/null +++ b/site/content/en/docs/tasks/observability/_index.md @@ -0,0 +1,5 @@ +--- +title: "Observability" +weight: 4 +description: This section includes observability tasks. +--- diff --git a/site/content/en/docs/tasks/observability/gateway-api-metrics.md b/site/content/en/docs/tasks/observability/gateway-api-metrics.md new file mode 100644 index 00000000000..bd9e5b89317 --- /dev/null +++ b/site/content/en/docs/tasks/observability/gateway-api-metrics.md @@ -0,0 +1,59 @@ +--- +title: "Gateway API Metrics" +--- + +Resource metrics for Gateway API objects are available using the [Gateway API State Metrics][gasm] project. +The project also provides example dashboard for visualising the metrics using Grafana, and example alerts using Prometheus & Alertmanager. + +## Prerequisites + +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. + +Run the following commands to install the metrics stack, with the Gateway API State Metrics configuration, on your kubernetes cluster: + +```shell +kubectl apply --server-side -f https://raw.githubusercontent.com/Kuadrant/gateway-api-state-metrics/main/config/examples/kube-prometheus/bundle_crd.yaml +kubectl apply -f https://raw.githubusercontent.com/Kuadrant/gateway-api-state-metrics/main/config/examples/kube-prometheus/bundle.yaml +``` + +## Metrics and Alerts + +To access the Prometheus UI, wait for the statefulset to be ready, then use the port-forward command: + +```shell +# This first command may fail if the statefulset has not been created yet. +# In that case, try again until you get a message like 'Waiting for 2 pods to be ready...' +# or 'statefulset rolling update complete 2 pods...' +kubectl -n monitoring rollout status --watch --timeout=5m statefulset/prometheus-k8s +kubectl -n monitoring port-forward service/prometheus-k8s 9090:9090 > /dev/null & +``` + +Navigate to `http://localhost:9090`. +Metrics can be queried from the 'Graph' tab e.g. `gatewayapi_gateway_created` +See the [Gateway API State Metrics README][gasm-readme] for the full list of Gateway API metrics available. + +Alerts can be seen in the 'Alerts' tab. +Gateway API specific alerts will be grouped under the 'gateway-api.rules' heading. + +***Note:*** Alerts are defined in a PrometheusRules custom resource in the 'monitoring' namespace. You can modify the alert rules by updating this resource. + +## Dashboards + +To view the dashboards in Grafana, wait for the deployment to be ready, then use the port-forward command: + +```shell +kubectl -n monitoring wait --timeout=5m deployment/grafana --for=condition=Available +kubectl -n monitoring port-forward service/grafana 3000:3000 > /dev/null & +``` + +Navigate to `http://localhost:3000` and sign in with admin/admin. +The Gateway API State dashboards will be available in the 'Default' folder and tagged with 'gateway-api'. +See the [Gateway API State Metrics README][gasm-dashboards] for further information on available dashboards. + +***Note:*** Dashboards are loaded from configmaps. You can modify the dashboards in the Grafana UI, however you will need to export them from the UI and update the json in the configmaps to persist changes. + + +[gasm]: https://github.com/Kuadrant/gateway-api-state-metrics +[gasm-readme]: https://github.com/Kuadrant/gateway-api-state-metrics/tree/main#metrics +[gasm-dashboards]: https://github.com/Kuadrant/gateway-api-state-metrics/tree/main#dashboards diff --git a/site/content/en/docs/tasks/observability/grafana-integration.md b/site/content/en/docs/tasks/observability/grafana-integration.md new file mode 100644 index 00000000000..e2da53b308a --- /dev/null +++ b/site/content/en/docs/tasks/observability/grafana-integration.md @@ -0,0 +1,65 @@ +--- +title: "Visualising metrics using Grafana" +--- + +Envoy Gateway provides support for exposing Envoy Proxy metrics to a Prometheus instance. +This guide shows you how to visualise the metrics exposed to prometheus using grafana. + +## Prerequisites + +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. + +Follow the steps from the [Proxy Observability](../proxy-observability#Metrics) to enable prometheus metrics. + +[Prometheus](https://prometheus.io) is used to scrape metrics from the Envoy Proxy instances. Install Prometheus: + +```shell +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts +helm repo update +helm upgrade --install prometheus prometheus-community/prometheus -n monitoring --create-namespace +``` + +[Grafana](https://grafana.com/grafana/) is used to visualise the metrics exposed by the envoy proxy instances. +Install Grafana: + +```shell +helm repo add grafana https://grafana.github.io/helm-charts +helm repo update +helm upgrade --install grafana grafana/grafana -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/grafana/helm-values.yaml -n monitoring --create-namespace +``` + +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 from the command +from prerequisites sections, the prometheus datasource should be already configured. + +You can also add the data source manually by following the instructions from [Grafana Docs](https://grafana.com/docs/grafana/latest/datasources/prometheus/configure-prometheus-data-source/). + +## 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: + +### [Envoy Global](https://raw.githubusercontent.com/envoyproxy/gateway/main/charts/gateway-addons-helm/dashboards/envoy-global.json) + +![Envoy Global](/img/envoy-global-dashboard.png) + +### [Envoy Clusters](https://raw.githubusercontent.com/envoyproxy/gateway/main/charts/gateway-addons-helm/dashboards/envoy-clusters.json) + +![Envoy Clusters](/img/envoy-clusters-dashboard.png) + +### [Envoy Pod Resources](https://raw.githubusercontent.com/envoyproxy/gateway/main/charts/gateway-addons-helm/dashboards/envoy-pod-resource.json) + +![Envoy Pod Resources](/img/envoy-pod-resources-dashboard.png) + +You can load the above dashboards in your Grafana to get started. Please refer to Grafana docs for [importing dashboards](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard). diff --git a/site/content/en/docs/tasks/observability/proxy-observability.md b/site/content/en/docs/tasks/observability/proxy-observability.md new file mode 100644 index 00000000000..3dbd3aed18a --- /dev/null +++ b/site/content/en/docs/tasks/observability/proxy-observability.md @@ -0,0 +1,142 @@ +--- +title: "Proxy Observability" +--- + +Envoy Gateway provides observability for the ControlPlane and the underlying EnvoyProxy instances. +This guide show you how to config proxy observability, includes metrics, logs, and traces. + +## Prerequisites + +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. + +[FluentBit](https://fluentbit.io/) is used to collect logs from the EnvoyProxy instances and forward them to Loki. Install FluentBit: + +```shell +helm repo add fluent https://fluent.github.io/helm-charts +helm repo update +helm upgrade --install fluent-bit fluent/fluent-bit -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/fluent-bit/helm-values.yaml -n monitoring --create-namespace --version 0.30.4 +``` + +[Loki](https://grafana.com/oss/loki/) is used to store logs. Install Loki: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/loki/loki.yaml -n monitoring +``` + +[Tempo](https://grafana.com/oss/tempo/) is used to store traces. Install Tempo: + +```shell +helm repo add grafana https://grafana.github.io/helm-charts +helm repo update +helm upgrade --install tempo grafana/tempo -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/tempo/helm-values.yaml -n monitoring --create-namespace --version 1.3.1 +``` + +[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) offers a vendor-agnostic implementation of how to receive, process and export telemetry data. +Install OTel-Collector: + +```shell +helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts +helm repo update +helm upgrade --install otel-collector open-telemetry/opentelemetry-collector -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/otel-collector/helm-values.yaml -n monitoring --create-namespace --version 0.60.0 +``` + +Expose endpoints: + +```shell +LOKI_IP=$(kubectl get svc loki -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +TEMPO_IP=$(kubectl get svc tempo -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + +## Metrics + +By default, Envoy Gateway expose metrics with prometheus endpoint. + +Verify metrics: + +```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 + +# check metrics +curl localhost:19001/stats/prometheus | grep "default/backend/rule/0/match/0-www" +``` + +You can disable metrics by setting the `telemetry.metrics.prometheus.disable` to `true` in the `EnvoyProxy` CRD. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/metric/disable-prometheus.yaml +``` + +Envoy Gateway can send metrics to OpenTelemetry Sink. +Send metrics to OTel-Collector: + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/metric/otel-sink.yaml +``` + +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 | grep "default/backend/rule/0/match/0-www" +``` + +## Logs + +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' +``` + +If you want to disable it, set the `telemetry.accesslog.disable` to `true` in the `EnvoyProxy` CRD. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/accesslog/disable-accesslog.yaml +``` + +Envoy Gateway can send logs to OpenTelemetry Sink. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/accesslog/otel-accesslog.yaml +``` + +Verify logs from loki: + +```shell +curl -s "http://$LOKI_IP:3100/loki/api/v1/query_range" --data-urlencode "query={exporter=\"OTLP\"}" | jq '.data.result[0].values' +``` + +## Traces + +By default, Envoy Gateway doesn't send traces to OpenTelemetry Sink. +You can enable traces by setting the `telemetry.tracing` in the `EnvoyProxy` CRD. + +***Note:*** Envoy Gateway use 100% sample rate, which means all requests will be traced. This may cause performance issues. + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/tracing/default.yaml +``` + +Verify traces from tempo: + +```shell +curl -s "http://$TEMPO_IP:3100/api/search" --data-urlencode "q={ component=envoy }" | jq .traces +``` + +```shell +curl -s "http://$TEMPO_IP:3100/api/traces/" | jq +``` diff --git a/site/content/en/docs/tasks/operations/_index.md b/site/content/en/docs/tasks/operations/_index.md new file mode 100644 index 00000000000..58ff129f35d --- /dev/null +++ b/site/content/en/docs/tasks/operations/_index.md @@ -0,0 +1,5 @@ +--- +title: "Operations" +weight: 4 +description: This section includes operations-related tasks. +--- diff --git a/site/content/en/docs/tasks/operations/customize-envoyproxy.md b/site/content/en/docs/tasks/operations/customize-envoyproxy.md new file mode 100644 index 00000000000..152f9e7ff44 --- /dev/null +++ b/site/content/en/docs/tasks/operations/customize-envoyproxy.md @@ -0,0 +1,828 @@ +--- +title: "Customize EnvoyProxy" +--- + +Envoy Gateway provides an [EnvoyProxy][] CRD that can be linked to the ParametersRef +in 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][]. + +## 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. + +## Add GatewayClass ParametersRef + +First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config: + +{{< 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_GATEWAY_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 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 two 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. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +You can use [egctl 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 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. + +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. + +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[EnvoyProxy]: ../../../api/extension_types#envoyproxy +[egctl translate]: ../egctl/#validating-gateway-api-configuration + diff --git a/site/content/en/docs/tasks/operations/deployment-mode.md b/site/content/en/docs/tasks/operations/deployment-mode.md new file mode 100644 index 00000000000..069fbfcb009 --- /dev/null +++ b/site/content/en/docs/tasks/operations/deployment-mode.md @@ -0,0 +1,805 @@ +--- +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). + +### 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**. +* Support for alternate deployment modes is being tracked [here][issue1117]. + +### 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 v1.0.2 -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. + +```shell +cat < 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 v1.0.2 -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. + +```shell +cat < 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/latest/quickstart.yaml -n default +``` + +Lets create also and additional `Gateway` linked to the GatewayClass and `backend` application from Quickstart example. + +```shell +cat < 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 +[issue1231]: https://github.com/envoyproxy/gateway/issues/1231 +[issue1117]: https://github.com/envoyproxy/gateway/issues/1117 diff --git a/site/content/en/docs/tasks/operations/egctl.md b/site/content/en/docs/tasks/operations/egctl.md new file mode 100644 index 00000000000..75855ad68d9 --- /dev/null +++ b/site/content/en/docs/tasks/operations/egctl.md @@ -0,0 +1,862 @@ +--- +title: "Use egctl" +--- + +`egctl` is a command line tool to provide additional functionality for Envoy Gateway users. + + + +## 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 <}} +{{% 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](https://gateway-api.sigs.k8s.io/api-types/gateway/) and [HttpRoute](https://gateway-api.sigs.k8s.io/api-types/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](./) 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/v1.0.2/quickstart.yaml --ignore-not-found=true +``` + +Delete the Gateway API CRDs and Envoy Gateway: + +```shell +helm uninstall eg -n envoy-gateway-system +``` + +## Next Steps + +Checkout the [Developer Guide](../../contributions/develop) to get involved in the project. diff --git a/site/content/en/docs/tasks/security/_index.md b/site/content/en/docs/tasks/security/_index.md new file mode 100644 index 00000000000..9863f81300e --- /dev/null +++ b/site/content/en/docs/tasks/security/_index.md @@ -0,0 +1,5 @@ +--- +title: "Security" +weight: 2 +description: This section includes security-related tasks. +--- diff --git a/site/content/en/docs/tasks/security/backend-tls.md b/site/content/en/docs/tasks/security/backend-tls.md new file mode 100644 index 00000000000..9eadf4dd9d8 --- /dev/null +++ b/site/content/en/docs/tasks/security/backend-tls.md @@ -0,0 +1,212 @@ +--- +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 + +Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. + +## 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`: + +```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 ca.crt -CAkey ca.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 +``` + +Store the CA Cert in another Secret: + +```shell +kubectl create configmap example-ca --from-file=ca.crt +``` + +## 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. + +```shell +cat < 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. + +```shell + +## 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](../../../contributions/develop) to get involved in the project. + +[SecurityPolicy]: ../../../contributions/design/security-policy +[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/docs/tasks/security/cors.md b/site/content/en/docs/tasks/security/cors.md new file mode 100644 index 00000000000..b66077d5e28 --- /dev/null +++ b/site/content/en/docs/tasks/security/cors.md @@ -0,0 +1,141 @@ +--- +title: "CORS" +--- + +This guide 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][SecurityPolicy] that allows the user to configure CORS. +This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HTTPRoute] or [GRPCRoute][GRPCRoute] resource. + +## Prerequisites + +Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## 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. + +The below example defines a SecurityPolicy that allows CORS for all HTTP requests originating from `www.foo.com`. + +```shell +cat < /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-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 +```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) guide to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy: + +```shell +kubectl delete securitypolicy/cors-example +``` + +## Next Steps + +Checkout the [Developer Guide](../../../contributions/develop) to get involved in the project. + +[SecurityPolicy]: ../../../contributions/design/security-policy +[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 diff --git a/site/content/en/docs/tasks/security/ext-auth.md b/site/content/en/docs/tasks/security/ext-auth.md new file mode 100644 index 00000000000..5cc55964853 --- /dev/null +++ b/site/content/en/docs/tasks/security/ext-auth.md @@ -0,0 +1,311 @@ +--- +title: "External Authorization" +--- + +This guide provides instructions for configuring external authentication. + +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][SecurityPolicy] that allows the user to configure external authorization. +This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute][HTTPRoute] resource. + +## Prerequisites + +Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +Verify the Gateway status: + +```shell +kubectl get gateway/eg -o yaml +``` + +## 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. + +```shell +cat < 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 `Authentication` 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. + +```shell +cat < 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 `Authentication` 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) guide 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](../../../contributions/develop) to get involved in the project. + +[SecurityPolicy]: ../../../contributions/design/security-policy +[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/docs/tasks/security/jwt-authentication.md b/site/content/en/docs/tasks/security/jwt-authentication.md new file mode 100644 index 00000000000..26caabf3ad7 --- /dev/null +++ b/site/content/en/docs/tasks/security/jwt-authentication.md @@ -0,0 +1,170 @@ +--- +title: "JWT Authentication" +--- + +This guide 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 + +Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest. +For GRPC - follow the steps from the [GRPC Routing](../traffic/grpc-routing) example. +Before proceeding, you should be able to query the example backend using HTTP or GRPC. + +## 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) guide 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" +} +``` + +## Clean-Up + +Follow the steps from the [Quickstart](../../quickstart) guide to uninstall Envoy Gateway and the example manifest. + +Delete the SecurityPolicy: + +```shell +kubectl delete securitypolicy/jwt-example +``` + +## Next Steps + +Checkout the [Developer Guide](../../../contributions/develop) to get involved in the project. + +[SecurityPolicy]: ../../../contributions/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 diff --git a/site/content/en/docs/tasks/security/mutual-tls.md b/site/content/en/docs/tasks/security/mutual-tls.md new file mode 100644 index 00000000000..c57b6f8b2ba --- /dev/null +++ b/site/content/en/docs/tasks/security/mutual-tls.md @@ -0,0 +1,150 @@ +--- +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 + +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. + +## 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. + +```shell +cat <}} +{{% 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 `http://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 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 +two HTTPRoutes associated with it, one with the host `www.example.com` and the path `/myapp`, and the other with the host +`www.example.com` and the path `/`. Either one of the HTTPRoutes can be used to match the `redirectURL` and `logoutPath`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/oidc-example -o yaml +``` + +### 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. + +Open a browser and navigate to the `https://www.example.com:8443/foo` 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://www.example.com:8443/myapp` address. You should be able to see this page since the +path `/myapp` is protected by the same OIDC policy. + +## 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 +``` + +## Next Steps + +Checkout the [Developer Guide](../../../../contributions/develop) to get involved in the project. + +[oidc]: https://openid.net/connect/ +[google-oidc]: https://developers.google.com/identity/protocols/oauth2/openid-connect +[SecurityPolicy]: ../../../../contributions/design/security-policy +[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/docs/tasks/security/secure-gateways.md b/site/content/en/docs/tasks/security/secure-gateways.md new file mode 100644 index 00000000000..52bf8c9cb78 --- /dev/null +++ b/site/content/en/docs/tasks/security/secure-gateways.md @@ -0,0 +1,447 @@ +--- +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 + +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. + +## 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 +``` + +## Testing + +### Clusters without External 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 +``` + +### Clusters 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 +``` + +## 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: + +```shell +cat <: \ 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-model/#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](../../../contributions/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 guide 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) guide 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-model/#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 [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](https://gateway.envoyproxy.io/v0.6.0/user/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-model/#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-model/#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](../../../contributions/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/docs/tasks/security/tls-cert-manager.md b/site/content/en/docs/tasks/security/tls-cert-manager.md new file mode 100644 index 00000000000..07aaf5b4ad8 --- /dev/null +++ b/site/content/en/docs/tasks/security/tls-cert-manager.md @@ -0,0 +1,436 @@ +--- +title: "Using cert-manager For TLS Termination" +--- + +This guide 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 + +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. + +## 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, but currently (v1.12) requires setting a feature gate to enable the Gateway API support. + +```console +$ helm repo add jetstack https://charts.jetstack.io +$ helm upgrade --install --create-namespace --namespace cert-manager --set installCRDs=true --set featureGates=ExperimentalGatewayAPISupport=true cert-manager jetstack/cert-manager +``` + +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 - < 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 +* Re-using 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 +* Re-using existing connection #0 with host 172.18.255.202 +``` + +### Enable Proxy Protocol for downstream client + +This example configures Proxy Protocol for downstream clients. + +```shell +cat < 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 additional ingress proxy hops from the right side of XFF HTTP headers 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. + +```shell +cat < 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). + +```shell +cat < 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 +``` + +[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy +[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy diff --git a/site/content/en/docs/tasks/traffic/fault-injection.md b/site/content/en/docs/tasks/traffic/fault-injection.md new file mode 100644 index 00000000000..c033d12aed3 --- /dev/null +++ b/site/content/en/docs/tasks/traffic/fault-injection.md @@ -0,0 +1,254 @@ +--- +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 + +Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest. +For GRPC - follow the steps from the [GRPC Routing](../grpc-routing) example. +Before proceeding, you should be able to query the example backend using HTTP or GRPC. + +### 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 + +```shell +cat < 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`. + + +[Addresses]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.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/docs/tasks/traffic/gatewayapi-support.md b/site/content/en/docs/tasks/traffic/gatewayapi-support.md new file mode 100644 index 00000000000..7ea0e91e54b --- /dev/null +++ b/site/content/en/docs/tasks/traffic/gatewayapi-support.md @@ -0,0 +1,119 @@ +--- +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. +- The `filters` field within [HTTPBackendRef][] is not supported. + +## 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. +- The `filters` field within [HTTPBackendRef][] is not supported. + +## 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]: ../../../contributions/design/system-design +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GatewayClass +[parameters reference]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.ParametersReference +[Gateway]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[BackendRef]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.BackendRef +[HTTPBackendRef]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPBackendRef +[TCPRoute]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute +[UDPRoute]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.UDPRoute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute +[gRPC]: https://grpc.io/ +[TLSRoute]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute +[ReferenceGrant]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant +[SecretObjectReference]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.SecretObjectReference +[rate limiting]: ../../../contributions/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/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilterType +[grpc-filter]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter +[http-filter]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter diff --git a/site/content/en/docs/tasks/traffic/global-rate-limit.md b/site/content/en/docs/tasks/traffic/global-rate-limit.md new file mode 100644 index 00000000000..d65d972678b --- /dev/null +++ b/site/content/en/docs/tasks/traffic/global-rate-limit.md @@ -0,0 +1,833 @@ +--- +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 + +* Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the HTTPRoute example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +### 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. + +```shell +cat <}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +__Note:__ `301` (default) and `302` are the only supported statusCodes. + +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 +``` + + +## 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/references/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter +[Gateway API documentation]: https://gateway-api.sigs.k8s.io/ +[req_filter]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.HTTPRequestRedirectFilter +[sectionName]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.CommonRouteSpec diff --git a/site/content/en/docs/tasks/traffic/http-request-headers.md b/site/content/en/docs/tasks/traffic/http-request-headers.md new file mode 100644 index 00000000000..05cb770c4a7 --- /dev/null +++ b/site/content/en/docs/tasks/traffic/http-request-headers.md @@ -0,0 +1,285 @@ +--- +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. + +## Prerequisites + +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. + +## 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. + +```shell +cat < 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. + +```shell +cat < 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. + +```shell +cat < 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 + +```shell +cat < 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. + +```shell +cat < 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. + +```shell +cat < 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. + +```shell +cat < 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 + +```shell +cat <= BackendRequest duration + +## 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. + +## 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/spec/#gateway.networking.k8s.io/v1.HTTPRouteTimeouts +[HTTPRouteRule]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteRule diff --git a/site/content/en/docs/tasks/traffic/http-traffic-splitting.md b/site/content/en/docs/tasks/traffic/http-traffic-splitting.md new file mode 100644 index 00000000000..924d36970e9 --- /dev/null +++ b/site/content/en/docs/tasks/traffic/http-traffic-splitting.md @@ -0,0 +1,313 @@ +--- +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. + +## 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. + +## Single backendRef + +When a single backendRef is configured in a HTTPRoute, it will receive 100% of the traffic. + +```shell +cat < 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: + +```shell +cat < 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. + +```shell +cat < 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/spec/#gateway.networking.k8s.io/v1.BackendRef diff --git a/site/content/en/docs/tasks/traffic/http-urlrewrite.md b/site/content/en/docs/tasks/traffic/http-urlrewrite.md new file mode 100644 index 00000000000..5acca036714 --- /dev/null +++ b/site/content/en/docs/tasks/traffic/http-urlrewrite.md @@ -0,0 +1,297 @@ +--- +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 + +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. + +## 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`. + +```shell +cat < 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`. + +```shell +cat < 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 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`. + +```shell +cat < 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`. + +[HTTPURLRewriteFilter]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPURLRewriteFilter diff --git a/site/content/en/docs/tasks/traffic/http3.md b/site/content/en/docs/tasks/traffic/http3.md new file mode 100644 index 00000000000..e9367c72f10 --- /dev/null +++ b/site/content/en/docs/tasks/traffic/http3.md @@ -0,0 +1,106 @@ +--- +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 + +Follow the steps from the [Quickstart](../quickstart.md) to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +## 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 + +```shell +kubectl apply -f - < 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. + +```shell +cat < 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 +``` diff --git a/site/content/en/docs/tasks/traffic/routing-outside-kubernetes.md b/site/content/en/docs/tasks/traffic/routing-outside-kubernetes.md new file mode 100644 index 00000000000..e43052073cb --- /dev/null +++ b/site/content/en/docs/tasks/traffic/routing-outside-kubernetes.md @@ -0,0 +1,97 @@ +--- +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][]. + +## 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 + +```shell +cat <> 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](../../../contributions/develop) to get involved in the project. + +[UDPRoute]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.UDPRoute +[UDP proxy documentation]: https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/udp_filters/udp_proxy diff --git a/site/content/en/v0.6.0/user/grafana-integration.md b/site/content/en/v0.6.0/user/grafana-integration.md index ec2d9ce5c70..7223a35e942 100644 --- a/site/content/en/v0.6.0/user/grafana-integration.md +++ b/site/content/en/v0.6.0/user/grafana-integration.md @@ -40,7 +40,7 @@ GRAFANA_IP=$(kubectl get svc grafana -n monitoring -o jsonpath='{.status.loadBal To visualise metrics from Prometheus, we have to connect Grafana with Prometheus. If you installed Grafana from the command from prerequisites sections, the prometheus datasource should be already configured. -You can also add the data source manually by following the instructions from [Grafana Docs](https://grafana.com/docs/grafana/v0.6.0/datasources/prometheus/configure-prometheus-data-source/). +You can also add the data source manually by following the instructions from [Grafana Docs](https://grafana.com/docs/grafana/latest/datasources/prometheus/configure-prometheus-data-source/). ## Accessing Grafana diff --git a/site/hugo.toml b/site/hugo.toml index 58f35b567d6..45e40ba9109 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -253,7 +253,7 @@ enable = true [[menu.main]] name = "Documentation" weight = -102 - url = "/v1.0.2" + url = "/docs" # i18n for Chinese [[languages.zh.menu.main]] @@ -279,7 +279,7 @@ enable = true [[params.versions]] version = "v1.0.2" - url = "/v1.0.2" + url = "/docs" [[params.versions]] version = "v0.6.0" diff --git a/tools/make/common.mk b/tools/make/common.mk index 7bbf7ff964e..4d5d42a7626 100644 --- a/tools/make/common.mk +++ b/tools/make/common.mk @@ -38,7 +38,7 @@ endif REV=$(shell git rev-parse --short HEAD) # Supported Platforms for building multiarch binaries. -PLATFORMS ?= darwin_amd64 darwin_arm64 linux_amd64 linux_arm64 +PLATFORMS ?= darwin_amd64 darwin_arm64 linux_amd64 linux_arm64 # Set a specific PLATFORM ifeq ($(origin PLATFORM), undefined) @@ -94,20 +94,20 @@ endef define USAGE_OPTIONS Options: - \033[36mBINS\033[0m + \033[36mBINS\033[0m The binaries to build. Default is all of cmd. This option is available when using: make build|build-multiarch Example: \033[36mmake build BINS="envoy-gateway"\033[0m - \033[36mIMAGES\033[0m + \033[36mIMAGES\033[0m Backend images to make. Default is all of cmds. This option is available when using: make image|image-multiarch|push|push-multiarch Example: \033[36mmake image-multiarch IMAGES="envoy-gateway"\033[0m - \033[36mPLATFORM\033[0m + \033[36mPLATFORM\033[0m The specified platform to build. This option is available when using: make build|image Example: \033[36mmake build BINS="envoy-gateway" PLATFORM="linux_amd64""\033[0m Supported Platforms: linux_amd64 linux_arm64 darwin_amd64 darwin_arm64 - \033[36mPLATFORMS\033[0m + \033[36mPLATFORMS\033[0m The multiple platforms to build. This option is available when using: make build-multiarch Example: \033[36mmake build-multiarch BINS="envoy-gateway" PLATFORMS="linux_amd64 linux_arm64"\033[0m @@ -119,7 +119,7 @@ export USAGE_OPTIONS .PHONY: generate generate: ## Generate go code from templates and tags -generate: kube-generate docs-api helm-generate go.generate release-notes-docs +generate: kube-generate docs-api helm-generate go.generate release-notes-docs copy-current-release-docs ## help: Show this help info. .PHONY: help diff --git a/tools/make/docs.mk b/tools/make/docs.mk index 43afb95853d..1a7900095a2 100644 --- a/tools/make/docs.mk +++ b/tools/make/docs.mk @@ -6,17 +6,26 @@ CLEAN_NODE_MODULES ?= true ##@ Docs .PHONY: docs -docs: docs.clean helm-readme-gen docs-api ## Generate Envoy Gateway Docs Sources +docs: docs.clean helm-readme-gen docs-api copy-current-release-docs ## Generate Envoy Gateway Docs Sources @$(LOG_TARGET) cd $(ROOT_DIR)/site && npm install cd $(ROOT_DIR)/site && npm run build:production cp tools/hack/get-egctl.sh $(DOCS_OUTPUT_DIR) +.PHONY: copy-current-release-docs +copy-current-release-docs: ## Copy the current release docs to the docs folder + @$(LOG_TARGET) + @CURRENT_RELEASE=$(shell ls $(ROOT_DIR)/site/content/en | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$$' | sort | tail -n 1); \ + echo "Copying the current release $$CURRENT_RELEASE docs to the docs folder"; \ + rm -rf $(ROOT_DIR)/site/content/en/docs; \ + mkdir -p $(ROOT_DIR)/site/content/en/docs; \ + cp -r $(ROOT_DIR)/site/content/en/$$CURRENT_RELEASE/** $(ROOT_DIR)/site/content/en/docs + .PHONY: docs-release docs-release: docs-release-prepare release-notes-docs docs-release-gen docs ## Generate Envoy Gateway Release Docs .PHONY: docs-serve -docs-serve: ## Start Envoy Gateway Site Locally +docs-serve: copy-current-release-docs ## Start Envoy Gateway Site Locally @$(LOG_TARGET) cd $(ROOT_DIR)/site && npm run serve