This is the multi-page printable view of this section. Click here to print.
API
1 - Config APIs
Packages
config.gateway.envoyproxy.io/v1alpha1
Package v1alpha1 contains API schema definitions for the config.gateway.envoyproxy.io API group.
Resource Types
EnvoyGateway
EnvoyGateway is the schema for the envoygateways API.
| Field | Description |
|---|---|
apiVersion string | config.gateway.envoyproxy.io/v1alpha1 |
kind string | EnvoyGateway |
EnvoyGatewaySpec EnvoyGatewaySpec | EnvoyGatewaySpec defines the desired state of EnvoyGateway. |
EnvoyGatewayFileProvider
EnvoyGatewayFileProvider defines configuration for the File provider.
Appears in:
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. |
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. |
file EnvoyGatewayFileProvider | File defines the configuration of the File provider. File provides runtime configuration defined by one or more files. This type is not implemented until https://github.com/envoyproxy/gateway/issues/1001 is fixed. |
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. |
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. |
extension Extension | Extension defines an extension to register for the Envoy Gateway Control Plane. |
EnvoyProxy
EnvoyProxy is the schema for the envoyproxies API.
| Field | Description |
|---|---|
apiVersion string | config.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. If unspecified, default settings apply. This type is not implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed. |
bootstrap string | 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. |
Extension
Extension defines the configuration for registering an extension 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. |
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 |
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. |
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/reference/spec/#gateway.networking.k8s.io/v1.GatewayClass |
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 |
KubernetesContainerSpec
KubernetesContainerSpec defines the desired state of the Kubernetes container resource.
Appears in:
| Field | Description |
|---|---|
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. |
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. |
pod KubernetesPodSpec | Pod defines the desired annotations and securityContext of container. |
container KubernetesContainerSpec | Container defines the resources and securityContext of container. |
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. |
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. |
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 and LoadBalancer. “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. |
LogComponent
Underlying type: string
LogComponent defines a component that supports a configured logging level. This type is not implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed.
Appears in:
LogLevel
Underlying type: string
LogLevel defines a log level for system logs. This type is not implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed.
Appears in:
ProviderType
Underlying type: string
ProviderType defines the types of providers supported by Envoy Gateway.
Appears in:
ProxyLogging
ProxyLogging defines logging parameters for managed proxies. This type is not implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed.
Appears in:
| Field | Description |
|---|---|
level object (keys:LogComponent, 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 “System: Info”. |
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. |
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 a Redis database.
Appears in:
| Field | Description |
|---|---|
url string | URL of the Redis Database. |
ServiceType
Underlying type: string
ServiceType string describes ingress methods for a service
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 |
2 - Extension APIs
Packages
gateway.envoyproxy.io/v1alpha1
Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group.
Resource Types
AuthenticationFilter
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | AuthenticationFilter |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec AuthenticationFilterSpec | Spec defines the desired state of the AuthenticationFilter type. |
AuthenticationFilterSpec
AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type.
Appears in:
| Field | Description |
|---|---|
type AuthenticationFilterType | Type defines the type of authentication provider to use. Supported provider types are “JWT”. |
jwtProviders JwtAuthenticationFilterProvider array | JWT defines the JSON Web Token (JWT) authentication provider type. When multiple jwtProviders 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. |
AuthenticationFilterType
Underlying type: string
AuthenticationFilterType is a type of authentication provider.
Appears in:
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. |
HeaderMatch
HeaderMatch defines the match attributes within the HTTP Headers of the request.
Appears in:
| Field | Description |
|---|---|
type HeaderMatchType | Type specifies how to match against the value of the header. |
name string | Name of the HTTP header. |
value string | Value within the HTTP header. Due to the case-insensitivity of header names, “foo” and “Foo” are considered equivalent. Do not set this field when Type=“Distinct”, implying matching on any/all unique values within the header. |
HeaderMatchType
Underlying type: string
HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are “Exact”, “RegularExpression”, and “Distinct”.
Appears in:
JwtAuthenticationFilterProvider
JwtAuthenticationFilterProvider defines the JSON Web Token (JWT) authentication provider type and how JWTs should 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. |
RateLimitFilter
RateLimitFilter allows the user to limit the number of incoming requests to a predefined value based on attributes within the traffic flow.
| Field | Description |
|---|---|
apiVersion string | gateway.envoyproxy.io/v1alpha1 |
kind string | RateLimitFilter |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec RateLimitFilterSpec | Spec defines the desired state of RateLimitFilter. |
RateLimitFilterSpec
RateLimitFilterSpec defines the desired state of RateLimitFilter.
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. |
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. |
sourceIP string | SourceIP is the IP CIDR that represents the range of Source IP Addresses of the client. These could also be the intermediate addresses through which the request has flown through and is part of the X-Forwarded-For header. For example, 192.168.0.1/32, 192.168.0.0/24, 001:db8::/64. All IP Addresses within the specified SourceIP CIDR are treated as a single client selector and share the same rate limit bucket. |
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 |
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. |