API Reference
28 minute read
Packages
gateway.envoyproxy.io/v1alpha1
Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group.
Resource Types
- BackendTrafficPolicy
- BackendTrafficPolicyList
- ClientTrafficPolicy
- ClientTrafficPolicyList
- EnvoyGateway
- EnvoyPatchPolicy
- EnvoyPatchPolicyList
- EnvoyProxy
- SecurityPolicy
- SecurityPolicyList
BackendTrafficPolicy
BackendTrafficPolicy allows the user to configure the behavior of the connection between the downstream client and Envoy Proxy listener.
Appears in:
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | BackendTrafficPolicy |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec BackendTrafficPolicySpec | spec defines the desired state of BackendTrafficPolicy. |
BackendTrafficPolicyList
BackendTrafficPolicyList contains a list of BackendTrafficPolicy resources.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | BackendTrafficPolicyList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items BackendTrafficPolicy array |
BackendTrafficPolicySpec
spec defines the desired state of BackendTrafficPolicy.
Appears in:
| Field | Description |
|---|---|
targetRef PolicyTargetReferenceWithSectionName | 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 | 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 policy to apply when routing traffic from the gateway to the backend endpoints |
BootstrapType
Underlying type: string
BootstrapType defines the types of bootstrap supported by Envoy Gateway.
Appears in:
CORS
CORS defines the configuration for Cross-Origin Resource Sharing (CORS).
Appears in:
| Field | Description |
|---|---|
allowOrigins StringMatch array | AllowOrigins defines the origins that are allowed to make requests. |
allowMethods string array | AllowMethods defines the methods that are allowed to make requests. |
allowHeaders string array | AllowHeaders defines the headers that are allowed to be sent with requests. |
exposeHeaders string array | ExposeHeaders defines the headers that can be exposed in the responses. |
maxAge Duration | MaxAge defines how long the results of a preflight request can be cached. |
ClaimToHeader
ClaimToHeader defines a configuration to convert JWT claims into HTTP headers
Appears in:
| Field | Description |
|---|---|
header string | Header defines the name of the HTTP request header that the JWT Claim will be saved into. |
claim string | 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. |
ClientTrafficPolicy
ClientTrafficPolicy allows the user to configure the behavior of the connection between the downstream client and Envoy Proxy listener.
Appears in:
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | ClientTrafficPolicy |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec ClientTrafficPolicySpec | Spec defines the desired state of ClientTrafficPolicy. |
ClientTrafficPolicyList
ClientTrafficPolicyList contains a list of ClientTrafficPolicy resources.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | ClientTrafficPolicyList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items ClientTrafficPolicy array |
ClientTrafficPolicySpec
ClientTrafficPolicySpec defines the desired state of ClientTrafficPolicy.
Appears in:
| Field | Description |
|---|---|
targetRef PolicyTargetReferenceWithSectionName | 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 settings associated with the downstream client connection. If defined, sets SO_KEEPALIVE on the listener socket to enable TCP Keepalives. Disabled by default. |
ConsistentHash
ConsistentHash defines the configuration related to the consistent hash load balancer policy
Appears in:
| Field | Description |
|---|---|
type ConsistentHashType |
ConsistentHashType
Underlying type: string
ConsistentHashType defines the type of input to hash on.
Appears in:
CustomTag
Appears in:
| Field | Description |
|---|---|
type CustomTagType | Type defines the type of custom tag. |
literal LiteralCustomTag | Literal adds hard-coded value to each span. It’s required when the type is “Literal”. |
environment EnvironmentCustomTag | Environment adds value from environment variable to each span. It’s required when the type is “Environment”. |
requestHeader RequestHeaderCustomTag | RequestHeader adds value from request header to each span. It’s required when the type is “RequestHeader”. |
CustomTagType
Underlying type: string
Appears in:
EnvironmentCustomTag
EnvironmentCustomTag adds value from environment variable to each span.
Appears in:
| Field | Description |
|---|---|
name string | Name defines the name of the environment variable which to extract the value from. |
defaultValue string | DefaultValue defines the default value to use if the environment variable is not set. |
EnvoyGateway
EnvoyGateway is the schema for the envoygateways API.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | EnvoyGateway |
gateway Gateway | Gateway defines desired Gateway API specific configuration. If unset, default configuration parameters will apply. |
provider EnvoyGatewayProvider | Provider defines the desired provider and provider-specific configuration. If unspecified, the Kubernetes provider is used with default configuration parameters. |
logging EnvoyGatewayLogging | Logging defines logging parameters for Envoy Gateway. |
admin EnvoyGatewayAdmin | Admin defines the desired admin related abilities. If unspecified, the Admin is used with default configuration parameters. |
telemetry EnvoyGatewayTelemetry | Telemetry defines the desired control plane telemetry related abilities. If unspecified, the telemetry is used with default configuration. |
rateLimit RateLimit | 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 defines an extension manager to register for the Envoy Gateway Control Plane. |
extensionApis ExtensionAPISettings | ExtensionAPIs defines the settings related to specific Gateway API Extensions implemented by Envoy Gateway |
EnvoyGatewayAdmin
EnvoyGatewayAdmin defines the Envoy Gateway Admin configuration.
Appears in:
| Field | Description |
|---|---|
address EnvoyGatewayAdminAddress | Address defines the address of Envoy Gateway Admin Server. |
enableDumpConfig boolean | EnableDumpConfig defines if enable dump config in Envoy Gateway logs. |
enablePprof boolean | EnablePprof defines if enable pprof in Envoy Gateway Admin Server. |
EnvoyGatewayAdminAddress
EnvoyGatewayAdminAddress defines the Envoy Gateway Admin Address configuration.
Appears in:
| Field | Description |
|---|---|
port integer | Port defines the port the admin server is exposed on. |
host string | Host defines the admin server hostname. |
EnvoyGatewayCustomProvider
EnvoyGatewayCustomProvider defines configuration for the Custom provider.
Appears in:
| Field | Description |
|---|---|
resource EnvoyGatewayResourceProvider | 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 | 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:
| Field | Description |
|---|---|
paths string array | 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 defines configuration for the Custom Infrastructure provider.
Appears in:
| Field | Description |
|---|---|
type InfrastructureProviderType | Type is the type of infrastructure providers to use. Supported types are “Host”. |
host EnvoyGatewayHostInfrastructureProvider | 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:
| Field | Description |
|---|---|
rateLimitDeployment KubernetesDeploymentSpec | 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 | Watch holds configuration of which input resources should be watched and reconciled. |
deploy KubernetesDeployMode | Deploy holds configuration of how output managed resources such as the Envoy Proxy data plane should be deployed |
overwrite_control_plane_certs boolean | 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 defines logging for Envoy Gateway.
Appears in:
| Field | Description |
|---|---|
level object (keys:EnvoyGatewayLogComponent, values:LogLevel) | 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:
| Field | Description |
|---|---|
type MetricSinkType | Type defines the metric sink type. EG control plane currently supports OpenTelemetry. |
openTelemetry EnvoyGatewayOpenTelemetrySink | 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:
| Field | Description |
|---|---|
sinks EnvoyGatewayMetricSink array | Sinks defines the metric sinks where metrics are sent to. |
prometheus EnvoyGatewayPrometheusProvider | Prometheus defines the configuration for prometheus endpoint. |
EnvoyGatewayOpenTelemetrySink
Appears in:
| Field | Description |
|---|---|
host string | Host define the sink service hostname. |
protocol string | Protocol define the sink service protocol. |
port integer | Port defines the port the sink service is exposed on. |
EnvoyGatewayPrometheusProvider
EnvoyGatewayPrometheusProvider will expose prometheus endpoint in pull mode.
Appears in:
| Field | Description |
|---|---|
disable boolean | Disable defines if disables the prometheus metrics in pull mode. |
EnvoyGatewayProvider
EnvoyGatewayProvider defines the desired configuration of a provider.
Appears in:
| Field | Description |
|---|---|
type ProviderType | Type is the type of provider to use. Supported types are “Kubernetes”. |
kubernetes EnvoyGatewayKubernetesProvider | Kubernetes defines the configuration of the Kubernetes provider. Kubernetes provides runtime configuration via the Kubernetes API. |
custom EnvoyGatewayCustomProvider | 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:
| Field | Description |
|---|---|
type ResourceProviderType | Type is the type of resource provider to use. Supported types are “File”. |
file EnvoyGatewayFileResourceProvider | 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:
| Field | Description |
|---|---|
gateway Gateway | Gateway defines desired Gateway API specific configuration. If unset, default configuration parameters will apply. |
provider EnvoyGatewayProvider | Provider defines the desired provider and provider-specific configuration. If unspecified, the Kubernetes provider is used with default configuration parameters. |
logging EnvoyGatewayLogging | Logging defines logging parameters for Envoy Gateway. |
admin EnvoyGatewayAdmin | Admin defines the desired admin related abilities. If unspecified, the Admin is used with default configuration parameters. |
telemetry EnvoyGatewayTelemetry | Telemetry defines the desired control plane telemetry related abilities. If unspecified, the telemetry is used with default configuration. |
rateLimit RateLimit | 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 defines an extension manager to register for the Envoy Gateway Control Plane. |
extensionApis ExtensionAPISettings | 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:
| Field | Description |
|---|---|
metrics EnvoyGatewayMetrics | Metrics defines metrics configuration for envoy gateway. |
EnvoyJSONPatchConfig
EnvoyJSONPatchConfig defines the configuration for patching a Envoy xDS Resource using JSONPatch semantic
Appears in:
| Field | Description |
|---|---|
type EnvoyResourceType | Type is the typed URL of the Envoy xDS Resource |
name string | Name is the name of the resource |
operation JSONPatchOperation | 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:
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | EnvoyPatchPolicy |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec EnvoyPatchPolicySpec | Spec defines the desired state of EnvoyPatchPolicy. |
EnvoyPatchPolicyList
EnvoyPatchPolicyList contains a list of EnvoyPatchPolicy resources.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | EnvoyPatchPolicyList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items EnvoyPatchPolicy array |
EnvoyPatchPolicySpec
EnvoyPatchPolicySpec defines the desired state of EnvoyPatchPolicy.
Appears in:
| Field | Description |
|---|---|
type EnvoyPatchType | Type decides the type of patch. Valid EnvoyPatchType values are “JSONPatch”. |
jsonPatches EnvoyJSONPatchConfig array | JSONPatch defines the JSONPatch configuration. |
targetRef PolicyTargetReference | TargetRef is the name of the Gateway API resource this policy is being attached to. Currently only attaching to Gateway is supported 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 | 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:
EnvoyProxy
EnvoyProxy is the schema for the envoyproxies API.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | EnvoyProxy |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec EnvoyProxySpec | EnvoyProxySpec defines the desired state of EnvoyProxy. |
EnvoyProxyKubernetesProvider
EnvoyProxyKubernetesProvider defines configuration for the Kubernetes resource provider.
Appears in:
| Field | Description |
|---|---|
envoyDeployment KubernetesDeploymentSpec | EnvoyDeployment defines the desired state of the Envoy deployment resource. If unspecified, default settings for the managed Envoy deployment resource are applied. |
envoyService KubernetesServiceSpec | EnvoyService defines the desired state of the Envoy service resource. If unspecified, default settings for the managed Envoy service resource are applied. |
EnvoyProxyProvider
EnvoyProxyProvider defines the desired state of a resource provider.
Appears in:
| Field | Description |
|---|---|
type ProviderType | 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 | 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:
| Field | Description |
|---|---|
provider EnvoyProxyProvider | Provider defines the desired resource provider and provider-specific configuration. If unspecified, the “Kubernetes” resource provider is used with default configuration parameters. |
logging ProxyLogging | Logging defines logging parameters for managed proxies. |
telemetry ProxyTelemetry | Telemetry defines telemetry parameters for managed proxies. |
bootstrap ProxyBootstrap | 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 | Concurrency defines the number of worker threads to run. If unset, it defaults to the number of cpuset threads on the platform. |
mergeGateways boolean | 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. |
EnvoyResourceType
Underlying type: string
EnvoyResourceType specifies the type URL of the Envoy resource.
Appears in:
ExtensionAPISettings
ExtensionAPISettings defines the settings specific to Gateway API Extensions.
Appears in:
| Field | Description |
|---|---|
enableEnvoyPatchPolicy boolean | EnableEnvoyPatchPolicy enables Envoy Gateway to reconcile and implement the EnvoyPatchPolicy resources. |
ExtensionHooks
ExtensionHooks defines extension hooks across all supported runners
Appears in:
| Field | Description |
|---|---|
xdsTranslator XDSTranslatorHooks | 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:
| Field | Description |
|---|---|
resources GroupVersionKind array | Resources defines the set of K8s resources the extension will handle. |
hooks ExtensionHooks | Hooks defines the set of hooks the extension supports |
service ExtensionService | 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:
| Field | Description |
|---|---|
host string | Host define the extension service hostname. |
port integer | Port defines the port the extension service is exposed on. |
tls ExtensionTLS | 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:
| Field | Description |
|---|---|
certificateRef SecretObjectReference | 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. |
FileEnvoyProxyAccessLog
Appears in:
| Field | Description |
|---|---|
path string | Path defines the file path used to expose envoy access log(e.g. /dev/stdout). |
Gateway
Gateway defines the desired Gateway API configuration of Envoy Gateway.
Appears in:
| Field | Description |
|---|---|
controllerName string | 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/v1alpha2/references/spec/#gateway.networking.k8s.io/v1.GatewayClass |
GlobalRateLimit
GlobalRateLimit defines global rate limit configuration.
Appears in:
| Field | Description |
|---|---|
rules RateLimitRule array | Rules are a list of RateLimit selectors and limits. Each rule and its associated limit is applied in a mutually exclusive way i.e. if multiple rules get selected, each of their associated limits get applied, so a single traffic request might increase the rate limit counters for multiple rules if selected. |
GroupVersionKind
GroupVersionKind unambiguously identifies a Kind. It can be converted to k8s.io/apimachinery/pkg/runtime/schema.GroupVersionKind
Appears in:
| Field | Description |
|---|---|
group string | |
version string | |
kind string |
HeaderMatch
HeaderMatch defines the match attributes within the HTTP Headers of the request.
Appears in:
InfrastructureProviderType
Underlying type: string
InfrastructureProviderType defines the types of custom infrastructure providers supported by Envoy Gateway.
Appears in:
JSONPatchOperation
JSONPatchOperation defines the JSON Patch Operation as defined in https://datatracker.ietf.org/doc/html/rfc6902
Appears in:
| Field | Description |
|---|---|
op JSONPatchOperationType | Op is the type of operation to perform |
path string | 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. |
value JSON | Value is the new value of the path location. |
JSONPatchOperationType
Underlying type: string
JSONPatchOperationType specifies the JSON Patch operations that can be performed.
Appears in:
JWT
JWT defines the configuration for JSON Web Token (JWT) authentication.
Appears in:
| Field | Description |
|---|---|
providers JWTProvider array | 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. |
JWTProvider
JWTProvider defines how a JSON Web Token (JWT) can be verified.
Appears in:
| Field | Description |
|---|---|
name string | 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 | 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 | 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 defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. |
claimToHeaders ClaimToHeader array | 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 |
KubernetesContainerSpec
KubernetesContainerSpec defines the desired state of the Kubernetes container resource.
Appears in:
| Field | Description |
|---|---|
env EnvVar array | List of environment variables to set in the container. |
resources ResourceRequirements | Resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |
securityContext SecurityContext | 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 | Image specifies the EnvoyProxy container image to be used, instead of the default image. |
volumeMounts VolumeMount array | 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:
KubernetesDeploymentSpec
KubernetesDeploymentSpec defines the desired state of the Kubernetes deployment resource.
Appears in:
| Field | Description |
|---|---|
replicas integer | Replicas is the number of desired pods. Defaults to 1. |
strategy DeploymentStrategy | The deployment strategy to use to replace existing pods with new ones. |
pod KubernetesPodSpec | Pod defines the desired specification of pod. |
container KubernetesContainerSpec | Container defines the desired specification of main container. |
initContainers Container array | List of initialization containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ |
KubernetesPodSpec
KubernetesPodSpec defines the desired state of the Kubernetes pod resource.
Appears in:
| Field | Description |
|---|---|
annotations object (keys:string, values:string) | Annotations are the annotations that should be appended to the pods. By default, no pod annotations are appended. |
labels object (keys:string, values:string) | Labels are the additional labels that should be tagged to the pods. By default, no additional pod labels are tagged. |
securityContext PodSecurityContext | 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 | If specified, the pod’s scheduling constraints. |
tolerations Toleration array | If specified, the pod’s tolerations. |
volumes Volume array | Volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes |
KubernetesServiceSpec
KubernetesServiceSpec defines the desired state of the Kubernetes service resource.
Appears in:
| Field | Description |
|---|---|
annotations object (keys:string, values:string) | Annotations that should be appended to the service. By default, no annotations are appended. |
type ServiceType | 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 | 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 | 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 | 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. |
KubernetesWatchMode
KubernetesWatchMode holds the configuration for which input resources to watch and reconcile.
Appears in:
| Field | Description |
|---|---|
Type KubernetesWatchModeType | Type indicates what watch mode to use. KubernetesWatchModeTypeNamespaces and KubernetesWatchModeTypeNamespaceSelectors 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 | 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 NamespaceSelectors must be set |
namespaces string array | NamespaceSelectors holds a list of labels that namespaces have to have in order to be watched. Note this doesn’t set the informer to watch the namespaces with the given labels. Informer still watches all namespaces. But the events for objects whois namespce have no given labels will be filtered out. Precisely one of Namespaces and NamespaceSelectors must be set |
KubernetesWatchModeType
Underlying type: string
KubernetesWatchModeType defines the type of KubernetesWatchMode
Appears in:
LiteralCustomTag
LiteralCustomTag adds hard-coded value to each span.
Appears in:
| Field | Description |
|---|---|
value string | Value defines the hard-coded value to add to each span. |
LoadBalancer
LoadBalancer defines the load balancer policy to be applied.
Appears in:
| Field | Description |
|---|---|
type LoadBalancerType | Type decides the type of Load Balancer policy. Valid LoadBalancerType values are “ConsistentHash”, “LeastRequest”, “Random”, “RoundRobin”, |
consistentHash ConsistentHash | ConsistentHash defines the configuration when the load balancer type is set to ConsistentHash |
LoadBalancerType
Underlying type: string
LoadBalancerType specifies the types of LoadBalancer.
Appears in:
LogLevel
Underlying type: string
LogLevel defines a log level for Envoy Gateway and EnvoyProxy system logs.
Appears in:
Match
Match defines the stats match configuration.
Appears in:
| Field | Description |
|---|---|
type MatcherType | MatcherType defines the stats matcher type |
value string |
MatchType
Underlying type: string
MatchType specifies the semantics of how a string value should be compared. Valid MatchType values are “Exact”, “Prefix”, “Suffix”, “RegularExpression”.
Appears in:
MatcherType
Underlying type: string
Appears in:
MetricSinkType
Underlying type: string
Appears in:
OpenTelemetryEnvoyProxyAccessLog
TODO: consider reuse ExtensionService?
Appears in:
| Field | Description |
|---|---|
host string | Host define the extension service hostname. |
port integer | Port defines the port the extension service is exposed on. |
resources object (keys:string, values:string) | 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. |
ProviderType
Underlying type: string
ProviderType defines the types of providers supported by Envoy Gateway.
Appears in:
ProxyAccessLog
Appears in:
| Field | Description |
|---|---|
disable boolean | Disable disables access logging for managed proxies if set to true. |
settings ProxyAccessLogSetting array | 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:
| Field | Description |
|---|---|
type ProxyAccessLogFormatType | Type defines the type of accesslog format. |
text string | Text defines the text accesslog format, following Envoy accesslog formatting, It’s required when the format type is “Text”. Envoy command operators may be used in the format. The format string documentation provides more information. |
json object (keys:string, values:string) | JSON is additional attributes that describe the specific event occurrence. Structured format for the envoy access logs. Envoy 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:
ProxyAccessLogSetting
Appears in:
| Field | Description |
|---|---|
format ProxyAccessLogFormat | Format defines the format of accesslog. |
sinks ProxyAccessLogSink array | Sinks defines the sinks of accesslog. |
ProxyAccessLogSink
Appears in:
| Field | Description |
|---|---|
type ProxyAccessLogSinkType | Type defines the type of accesslog sink. |
file FileEnvoyProxyAccessLog | File defines the file accesslog sink. |
openTelemetry OpenTelemetryEnvoyProxyAccessLog | OpenTelemetry defines the OpenTelemetry accesslog sink. |
ProxyAccessLogSinkType
Underlying type: string
Appears in:
ProxyBootstrap
ProxyBootstrap defines Envoy Bootstrap configuration.
Appears in:
| Field | Description |
|---|---|
type BootstrapType | Type is the type of the bootstrap configuration, it should be either Replace or Merge. If unspecified, it defaults to Replace. |
value string | 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 defines logging parameters for managed proxies.
Appears in:
| Field | Description |
|---|---|
level object (keys:ProxyLogComponent, values:LogLevel) | 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
Appears in:
| Field | Description |
|---|---|
type MetricSinkType | Type defines the metric sink type. EG currently only supports OpenTelemetry. |
openTelemetry ProxyOpenTelemetrySink | OpenTelemetry defines the configuration for OpenTelemetry sink. It’s required if the sink type is OpenTelemetry. |
ProxyMetrics
Appears in:
| Field | Description |
|---|---|
prometheus ProxyPrometheusProvider | Prometheus defines the configuration for Admin endpoint /stats/prometheus. |
sinks ProxyMetricSink array | Sinks defines the metric sinks where metrics are sent to. |
matches Match array | 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.<cluster_name>.membership_total,cluster.<cluster_name>.membership_healthy, cluster.<cluster_name>.membership_degraded，reference https://github.com/envoyproxy/envoy/issues/9856, https://github.com/envoyproxy/envoy/issues/14610 |
enableVirtualHostStats boolean | EnableVirtualHostStats enables envoy stat metrics for virtual hosts. |
ProxyOpenTelemetrySink
Appears in:
| Field | Description |
|---|---|
host string | Host define the service hostname. |
port integer | Port defines the port the service is exposed on. |
ProxyPrometheusProvider
Appears in:
| Field | Description |
|---|---|
disable boolean | Disable the Prometheus endpoint. |
ProxyTelemetry
Appears in:
| Field | Description |
|---|---|
accessLog ProxyAccessLog | AccessLogs defines accesslog parameters for managed proxies. If unspecified, will send default format to stdout. |
tracing ProxyTracing | Tracing defines tracing configuration for managed proxies. If unspecified, will not send tracing data. |
metrics ProxyMetrics | Metrics defines metrics configuration for managed proxies. |
ProxyTracing
Appears in:
| Field | Description |
|---|---|
samplingRate integer | 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) | CustomTags defines the custom tags to add to each span. If provider is kubernetes, pod name and namespace are added by default. |
provider TracingProvider | 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:
| Field | Description |
|---|---|
backend RateLimitDatabaseBackend | Backend holds the configuration associated with the database backend used by the rate limit service to store state associated with global ratelimiting. |
timeout Duration | Timeout specifies the timeout period for the proxy to access the ratelimit server If not set, timeout is 20ms. |
failClosed boolean | 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. |
RateLimitDatabaseBackend
RateLimitDatabaseBackend defines the configuration associated with the database backend used by the rate limit service.
Appears in:
| Field | Description |
|---|---|
type RateLimitDatabaseBackendType | Type is the type of database backend to use. Supported types are: * Redis: Connects to a Redis database. |
redis RateLimitRedisSettings | 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:
RateLimitRedisSettings
RateLimitRedisSettings defines the configuration for connecting to redis database.
Appears in:
| Field | Description |
|---|---|
url string | URL of the Redis Database. |
tls RedisTLSSettings | 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:
| Field | Description |
|---|---|
clientSelectors RateLimitSelectCondition array | 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 this field is empty, it is equivalent to True, and the limit is applied. |
limit RateLimitValue | 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:
| Field | Description |
|---|---|
headers HeaderMatch array | Headers is a list of request headers to match. Multiple header values are ANDed together, meaning, a request MUST match all the specified headers. |
sourceCIDR SourceMatch | SourceCIDR is the client IP Address range to match on. |
RateLimitSpec
RateLimitSpec defines the desired state of RateLimitSpec.
Appears in:
| Field | Description |
|---|---|
type RateLimitType | Type decides the scope for the RateLimits. Valid RateLimitType values are “Global”. |
global GlobalRateLimit | Global defines global rate limit configuration. |
RateLimitType
Underlying type: string
RateLimitType specifies the types of RateLimiting.
Appears in:
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 defines the limits for rate limiting.
Appears in:
| Field | Description |
|---|---|
requests integer | |
unit RateLimitUnit |
RedisTLSSettings
RedisTLSSettings defines the TLS configuration for connecting to redis database.
Appears in:
| Field | Description |
|---|---|
certificateRef SecretObjectReference | 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:
| Field | Description |
|---|---|
uri string | 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:
| Field | Description |
|---|---|
name string | Name defines the name of the request header which to extract the value from. |
defaultValue string | 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:
SecurityPolicy
SecurityPolicy allows the user to configure various security settings for a Gateway.
Appears in:
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | SecurityPolicy |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec SecurityPolicySpec | Spec defines the desired state of SecurityPolicy. |
SecurityPolicyList
SecurityPolicyList contains a list of SecurityPolicy resources.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | SecurityPolicyList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items SecurityPolicy array |
SecurityPolicySpec
SecurityPolicySpec defines the desired state of SecurityPolicy.
Appears in:
| Field | Description |
|---|---|
targetRef PolicyTargetReferenceWithSectionName | 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 |
cors CORS | CORS defines the configuration for Cross-Origin Resource Sharing (CORS). |
jwt JWT | JWT defines the configuration for JSON Web Token (JWT) authentication. |
ServiceType
Underlying type: string
ServiceType string describes ingress methods for a service
Appears in:
SourceMatch
Appears in:
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:
| Field | Description |
|---|---|
type MatchType | Type specifies how to match against a string. |
value string | Value specifies the string value that the match must have. |
TCPKeepalive
TCPKeepalive define the TCP Keepalive configuration.
Appears in:
| Field | Description |
|---|---|
probes integer | The total number of unacknowledged probes to send before deciding the connection is dead. Defaults to 9. |
idleTime Duration | The duration a connection needs to be idle before keep-alive probes start being sent. The duration format is Defaults to 7200s. |
interval Duration | The duration between keep-alive probes. Defaults to 75s. |
TracingProvider
Appears in:
| Field | Description |
|---|---|
type TracingProviderType | Type defines the tracing provider type. EG currently only supports OpenTelemetry. |
host string | Host define the provider service hostname. |
port integer | Port defines the port the provider service is exposed on. |
TracingProviderType
Underlying type: string
Appears in:
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 contains all the pre and post hooks for the xds-translator runner.
Appears in:
| Field | Description |
|---|---|
pre XDSTranslatorHook array | |
post XDSTranslatorHook array |
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.