From 24a7c7a8830680715223a1cf5de5ab31cce45fea Mon Sep 17 00:00:00 2001 From: Daneyon Hansen Date: Thu, 9 Feb 2023 04:38:32 +0100 Subject: [PATCH] Updates API godocs for improved markdown rendering (#1010) Updates API godocs for improved html rendering Signed-off-by: danehans (cherry picked from commit b43574a2c2d3d7222867106763e2cdd9423ce1f6) Signed-off-by: bitliu --- api/config/v1alpha1/doc.go | 2 +- api/config/v1alpha1/envoygateway_types.go | 17 ++++--- api/config/v1alpha1/envoyproxy_types.go | 27 +++++++----- api/config/v1alpha1/shared_types.go | 3 +- api/v1alpha1/authenticationfilter_types.go | 44 +++++-------------- api/v1alpha1/doc.go | 2 +- api/v1alpha1/ratelimitfilter_types.go | 34 +++++++------- docs/latest/api/config_types.md | 31 ++++++------- docs/latest/api/extension_types.md | 32 +++++--------- ...ig.gateway.envoyproxy.io_envoyproxies.yaml | 20 +++++---- ...y.envoyproxy.io_authenticationfilters.yaml | 33 ++++++-------- ...ateway.envoyproxy.io_ratelimitfilters.yaml | 7 ++- 12 files changed, 109 insertions(+), 143 deletions(-) diff --git a/api/config/v1alpha1/doc.go b/api/config/v1alpha1/doc.go index 689a481106d..cbf70c5e359 100644 --- a/api/config/v1alpha1/doc.go +++ b/api/config/v1alpha1/doc.go @@ -3,7 +3,7 @@ // The full text of the Apache license is available in the LICENSE file at // the root of the repo. -// Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io +// Package v1alpha1 contains API schema definitions for the config.gateway.envoyproxy.io // API group. // // +kubebuilder:object:generate=true diff --git a/api/config/v1alpha1/envoygateway_types.go b/api/config/v1alpha1/envoygateway_types.go index 5d8adbcf0ee..86636da0d70 100644 --- a/api/config/v1alpha1/envoygateway_types.go +++ b/api/config/v1alpha1/envoygateway_types.go @@ -18,11 +18,11 @@ const ( //+kubebuilder:object:root=true -// EnvoyGateway is the Schema for the envoygateways API. +// EnvoyGateway is the schema for the envoygateways API. type EnvoyGateway struct { metav1.TypeMeta `json:",inline"` - // EnvoyGatewaySpec defines the desired state of Envoy Gateway. + // EnvoyGatewaySpec defines the desired state of EnvoyGateway. EnvoyGatewaySpec `json:",inline"` } @@ -45,7 +45,7 @@ type EnvoyGatewaySpec struct { // 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 will not be needed to enable Local Rate limiitng. + // This configuration is unneeded for "Local" rate limiting. // // +optional RateLimit *RateLimit `json:"rateLimit,omitempty"` @@ -56,8 +56,7 @@ type Gateway struct { // 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/v1alpha2.GatewayClass + // https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass // // +optional ControllerName string `json:"controllerName,omitempty"` @@ -66,12 +65,11 @@ type Gateway struct { // Provider defines the desired configuration of a provider. // +union type Provider struct { - // Type is the type of provider to use. Supported types are: - // - // * Kubernetes: A provider that provides runtime configuration via the Kubernetes API. + // Type is the type of provider to use. Supported types are "Kubernetes". // // +unionDiscriminator Type ProviderType `json:"type"` + // Kubernetes defines the configuration of the Kubernetes provider. Kubernetes // provides runtime configuration via the Kubernetes API. // @@ -79,7 +77,8 @@ type Provider struct { Kubernetes *KubernetesProvider `json:"kubernetes,omitempty"` // File defines the configuration of the File provider. File provides runtime - // configuration defined by one or more files. + // configuration defined by one or more files. This type is not implemented + // until https://github.com/envoyproxy/gateway/issues/1001 is fixed. // // +optional File *FileProvider `json:"file,omitempty"` diff --git a/api/config/v1alpha1/envoyproxy_types.go b/api/config/v1alpha1/envoyproxy_types.go index 8171069d6a1..1eed1b15272 100644 --- a/api/config/v1alpha1/envoyproxy_types.go +++ b/api/config/v1alpha1/envoyproxy_types.go @@ -17,12 +17,14 @@ const ( //+kubebuilder:object:root=true //+kubebuilder:subresource:status -// EnvoyProxy is the Schema for the envoyproxies API +// EnvoyProxy is the schema for the envoyproxies API. type EnvoyProxy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec EnvoyProxySpec `json:"spec,omitempty"` + // EnvoyProxySpec defines the desired state of EnvoyProxy. + Spec EnvoyProxySpec `json:"spec,omitempty"` + // EnvoyProxyStatus defines the actual state of EnvoyProxy. Status EnvoyProxyStatus `json:"status,omitempty"` } @@ -36,7 +38,8 @@ type EnvoyProxySpec struct { Provider *ResourceProvider `json:"provider,omitempty"` // Logging defines logging parameters for managed proxies. If unspecified, - // default settings apply. + // default settings apply. This type is not implemented until + // https://github.com/envoyproxy/gateway/issues/280 is fixed. // // +kubebuilder:default={level: {system: info}} Logging ProxyLogging `json:"logging,omitempty"` @@ -47,10 +50,7 @@ type EnvoyProxySpec struct { type ResourceProvider struct { // 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: Provides infrastructure resources for running the data plane, - // e.g. Envoy proxy. + // optional auxiliary control planes. Supported types are "Kubernetes". // // +unionDiscriminator Type ProviderType `json:"type"` @@ -74,7 +74,8 @@ type KubernetesResourceProvider struct { EnvoyDeployment *KubernetesDeploymentSpec `json:"envoyDeployment,omitempty"` } -// ProxyLogging defines logging parameters for managed proxies. +// ProxyLogging defines logging parameters for managed proxies. This type is not +// implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed. type ProxyLogging struct { // 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". @@ -84,7 +85,8 @@ type ProxyLogging struct { } // 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. // +kubebuilder:validation:Enum=system;upstream;http;connection;admin;client;filter;main;router;runtime type LogComponent string @@ -121,8 +123,8 @@ const ( LogComponentRuntime LogComponent = "runtime" ) -// LogLevel defines a log level for system logs. -// +// LogLevel defines a log level for system logs. This type is not implemented until +// https://github.com/envoyproxy/gateway/issues/280 is fixed. // +kubebuilder:validation:Enum=debug;info;error type LogLevel string @@ -137,7 +139,8 @@ const ( LogLevelError LogLevel = "error" ) -// EnvoyProxyStatus defines the observed state of EnvoyProxy +// EnvoyProxyStatus defines the observed state of EnvoyProxy. This type is not implemented +// until https://github.com/envoyproxy/gateway/issues/1007 is fixed. type EnvoyProxyStatus struct { // INSERT ADDITIONAL STATUS FIELDS - define observed state of cluster. // Important: Run "make" to regenerate code after modifying this file. diff --git a/api/config/v1alpha1/shared_types.go b/api/config/v1alpha1/shared_types.go index f9dfcf9eb92..25635097291 100644 --- a/api/config/v1alpha1/shared_types.go +++ b/api/config/v1alpha1/shared_types.go @@ -19,7 +19,8 @@ const ( // ProviderTypeKubernetes defines the "Kubernetes" provider. ProviderTypeKubernetes ProviderType = "Kubernetes" - // ProviderTypeFile defines the "File" provider. + // ProviderTypeFile defines the "File" provider. This type is not implemented + // until https://github.com/envoyproxy/gateway/issues/1001 is fixed. ProviderTypeFile ProviderType = "File" ) diff --git a/api/v1alpha1/authenticationfilter_types.go b/api/v1alpha1/authenticationfilter_types.go index d921445a248..80c4c348375 100644 --- a/api/v1alpha1/authenticationfilter_types.go +++ b/api/v1alpha1/authenticationfilter_types.go @@ -29,18 +29,16 @@ type AuthenticationFilter struct { // AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type. // +union type AuthenticationFilterSpec struct { - // Type defines the type of authentication provider to use. Supported provider types are: - // - // * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests. + // Type defines the type of authentication provider to use. Supported provider types + // are "JWT". // // +unionDiscriminator Type AuthenticationFilterType `json:"type"` // 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 + // successfully validate the JWT. For additional details, see + // https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html. // // +kubebuilder:validation:MaxItems=4 // +optional @@ -52,7 +50,8 @@ type AuthenticationFilterSpec struct { type AuthenticationFilterType string const ( - // JwtAuthenticationFilterProviderType is the JWT authentication provider type. + // JwtAuthenticationFilterProviderType is a provider that uses JSON Web Token (JWT) + // for authenticating requests.. JwtAuthenticationFilterProviderType AuthenticationFilterType = "JWT" ) @@ -67,33 +66,17 @@ type JwtAuthenticationFilterProvider struct { Name string `json:"name"` // Issuer is the principal that issued the JWT and takes the form of a URL or email address. - // For additional details, see: - // - // URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1 - // Email format: https://rfc-editor.org/rfc/rfc5322.html - // - // URL Example: - // issuer: https://auth.example.com - // - // Email Example: - // issuer: jdoe@example.com - // - // If not provided, the JWT issuer is not checked. + // 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. // // +kubebuilder:validation:MaxLength=253 // +optional Issuer string `json:"issuer,omitempty"` - // Audiences is a list of JWT audiences allowed to access. For additional details, see: - // - // https://tools.ietf.org/html/rfc7519#section-4.1.3 - // - // Example: - // audiences: - // - foo.apps.example.com - // bar.apps.example.com - // - // If not provided, JWT audiences are not checked. + // 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. // // +kubebuilder:validation:MaxItems=8 // +optional @@ -112,9 +95,6 @@ type RemoteJWKS struct { // URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to // validate the server certificate. // - // Example: - // uri: https://www.foo.com/oauth2/v1/certs - // // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=253 URI string `json:"uri"` diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go index 593b004a232..ba39955fc08 100644 --- a/api/v1alpha1/doc.go +++ b/api/v1alpha1/doc.go @@ -3,7 +3,7 @@ // The full text of the Apache license is available in the LICENSE file at // the root of the repo. -// Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group. +// Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group. // // +kubebuilder:object:generate=true // +groupName=gateway.envoyproxy.io diff --git a/api/v1alpha1/ratelimitfilter_types.go b/api/v1alpha1/ratelimitfilter_types.go index fa08d6de97c..6f87bc1c916 100644 --- a/api/v1alpha1/ratelimitfilter_types.go +++ b/api/v1alpha1/ratelimitfilter_types.go @@ -30,13 +30,11 @@ type RateLimitFilter struct { // +union type RateLimitFilterSpec struct { // Type decides the scope for the RateLimits. - // Valid RateLimitType values are: - // - // * "Global" - In this mode, the rate limits are applied across all Envoy proxy instances. + // Valid RateLimitType values are "Global". // // +unionDiscriminator Type RateLimitType `json:"type"` - // Global rate limit configuration. + // Global defines global rate limit configuration. // // +optional Global *GlobalRateLimit `json:"global,omitempty"` @@ -51,7 +49,7 @@ const ( GlobalRateLimitType RateLimitType = "Global" ) -// GlobalRateLimit defines the global rate limit configuration. +// GlobalRateLimit defines global rate limit configuration. type GlobalRateLimit struct { // Rules are a list of RateLimit selectors and limits. // Each rule and its associated limit is applied @@ -116,29 +114,33 @@ type HeaderMatch struct { // 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. + // Do not set this field when Type="Distinct", implying matching on any/all unique + // values within the header. + // // +optional // +kubebuilder:validation:MaxLength=1024 Value *string `json:"value,omitempty"` } -// HeaderMatchType specifies the semantics of how HTTP header values should be -// compared. Valid HeaderMatchType values are: -// -// - "Exact": Use this type to match the exact value of the Value field against the value of the specified HTTP Header. -// - "RegularExpression": Use this type to match a regular expression against the value of the specified HTTP Header. -// The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax. -// - "Distinct": Use this type to match any and all possible unique values encountered in the specified HTTP Header. -// Note that each unique value will receive its own rate limit bucket. +// HeaderMatchType specifies the semantics of how HTTP header values should be compared. +// Valid HeaderMatchType values are "Exact", "RegularExpression", and "Distinct". // // +kubebuilder:validation:Enum=Exact;RegularExpression;Distinct type HeaderMatchType string // HeaderMatchType constants. const ( - HeaderMatchExact HeaderMatchType = "Exact" + // HeaderMatchExact matches the exact value of the Value field against the value of + // the specified HTTP Header. + HeaderMatchExact HeaderMatchType = "Exact" + // HeaderMatchRegularExpression matches a regular expression against the value of the + // specified HTTP Header. The regex string must adhere to the syntax documented in + // https://github.com/google/re2/wiki/Syntax. HeaderMatchRegularExpression HeaderMatchType = "RegularExpression" - HeaderMatchDistinct HeaderMatchType = "Distinct" + // HeaderMatchDistinct matches any and all possible unique values encountered in the + // specified HTTP Header. Note that each unique value will receive its own rate limit + // bucket. + HeaderMatchDistinct HeaderMatchType = "Distinct" ) // RateLimitValue defines the limits for rate limiting. diff --git a/docs/latest/api/config_types.md b/docs/latest/api/config_types.md index 233a0df20d8..e1e08a15a60 100644 --- a/docs/latest/api/config_types.md +++ b/docs/latest/api/config_types.md @@ -6,7 +6,7 @@ ## config.gateway.envoyproxy.io/v1alpha1 -Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io +Package v1alpha1 contains API schema definitions for the config.gateway.envoyproxy.io API group. @@ -20,7 +20,7 @@ API group. -EnvoyGateway is the Schema for the envoygateways API. +EnvoyGateway is the schema for the envoygateways API. @@ -28,7 +28,7 @@ EnvoyGateway is the Schema for the envoygateways API. | --- | --- | | `apiVersion` _string_ | `config.gateway.envoyproxy.io/v1alpha1` | `kind` _string_ | `EnvoyGateway` -| `EnvoyGatewaySpec` _[EnvoyGatewaySpec](#envoygatewayspec)_ | EnvoyGatewaySpec defines the desired state of Envoy Gateway. | +| `EnvoyGatewaySpec` _[EnvoyGatewaySpec](#envoygatewayspec)_ | EnvoyGatewaySpec defines the desired state of EnvoyGateway. | ## EnvoyGatewaySpec @@ -44,14 +44,14 @@ _Appears in:_ | --- | --- | | `gateway` _[Gateway](#gateway)_ | Gateway defines desired Gateway API specific configuration. If unset, default configuration parameters will apply. | | `provider` _[Provider](#provider)_ | Provider defines the desired provider and provider-specific configuration. If unspecified, the Kubernetes provider is used with default configuration parameters. | -| `rateLimit` _[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 will not be needed to enable Local Rate limiitng. | +| `rateLimit` _[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. | ## EnvoyProxy -EnvoyProxy is the Schema for the envoyproxies API +EnvoyProxy is the schema for the envoyproxies API. @@ -60,7 +60,7 @@ EnvoyProxy is the Schema for the envoyproxies API | `apiVersion` _string_ | `config.gateway.envoyproxy.io/v1alpha1` | `kind` _string_ | `EnvoyProxy` | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| `spec` _[EnvoyProxySpec](#envoyproxyspec)_ | | +| `spec` _[EnvoyProxySpec](#envoyproxyspec)_ | EnvoyProxySpec defines the desired state of EnvoyProxy. | ## EnvoyProxySpec @@ -75,7 +75,7 @@ _Appears in:_ | Field | Description | | --- | --- | | `provider` _[ResourceProvider](#resourceprovider)_ | 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)_ | Logging defines logging parameters for managed proxies. If unspecified, default settings apply. | +| `logging` _[ProxyLogging](#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. | @@ -102,8 +102,7 @@ _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/v1alpha2.GatewayClass | +| `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/v1alpha2.GatewayClass | ## KubernetesDeploymentSpec @@ -149,7 +148,7 @@ _Appears in:_ _Underlying type:_ `string` -LogComponent defines a component that supports a configured logging level. +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:_ - [ProxyLogging](#proxylogging) @@ -160,7 +159,7 @@ _Appears in:_ _Underlying type:_ `string` -LogLevel defines a log level for system logs. +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:_ - [ProxyLogging](#proxylogging) @@ -178,10 +177,9 @@ _Appears in:_ | Field | Description | | --- | --- | -| `type` _[ProviderType](#providertype)_ | Type is the type of provider to use. Supported types are: - * Kubernetes: A provider that provides runtime configuration via the Kubernetes API. | +| `type` _[ProviderType](#providertype)_ | Type is the type of provider to use. Supported types are "Kubernetes". | | `kubernetes` _[KubernetesProvider](#kubernetesprovider)_ | Kubernetes defines the configuration of the Kubernetes provider. Kubernetes provides runtime configuration via the Kubernetes API. | -| `file` _[FileProvider](#fileprovider)_ | File defines the configuration of the File provider. File provides runtime configuration defined by one or more files. | +| `file` _[FileProvider](#fileprovider)_ | 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. | ## ProviderType @@ -200,7 +198,7 @@ _Appears in:_ -ProxyLogging defines logging parameters for managed proxies. +ProxyLogging defines logging parameters for managed proxies. This type is not implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed. _Appears in:_ - [EnvoyProxySpec](#envoyproxyspec) @@ -275,8 +273,7 @@ _Appears in:_ | Field | Description | | --- | --- | -| `type` _[ProviderType](#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: Provides infrastructure resources for running the data plane, e.g. Envoy proxy. | +| `type` _[ProviderType](#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` _[KubernetesResourceProvider](#kubernetesresourceprovider)_ | 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. | diff --git a/docs/latest/api/extension_types.md b/docs/latest/api/extension_types.md index c398dccb96a..9479da94da5 100644 --- a/docs/latest/api/extension_types.md +++ b/docs/latest/api/extension_types.md @@ -6,7 +6,7 @@ ## gateway.envoyproxy.io/v1alpha1 -Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group. +Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group. ### Resource Types @@ -42,10 +42,8 @@ _Appears in:_ | Field | Description | | --- | --- | -| `type` _[AuthenticationFilterType](#authenticationfiltertype)_ | Type defines the type of authentication provider to use. Supported provider types are: - * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests. | -| `jwtProviders` _[JwtAuthenticationFilterProvider](#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 | +| `type` _[AuthenticationFilterType](#authenticationfiltertype)_ | Type defines the type of authentication provider to use. Supported provider types are "JWT". | +| `jwtProviders` _[JwtAuthenticationFilterProvider](#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 @@ -63,7 +61,7 @@ _Appears in:_ -GlobalRateLimit defines the global rate limit configuration. +GlobalRateLimit defines global rate limit configuration. _Appears in:_ - [RateLimitFilterSpec](#ratelimitfilterspec) @@ -93,8 +91,7 @@ _Appears in:_ _Underlying type:_ `string` -HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are: - - "Exact": Use this type to match the exact value of the Value field against the value of the specified HTTP Header. - "RegularExpression": Use this type to match a regular expression against the value of the specified HTTP Header. The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax. - "Distinct": Use this type to match any and all possible unique values encountered in the specified HTTP Header. Note that each unique value will receive its own rate limit bucket. +HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are "Exact", "RegularExpression", and "Distinct". _Appears in:_ - [HeaderMatch](#headermatch) @@ -113,15 +110,8 @@ _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: - URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1 Email format: https://rfc-editor.org/rfc/rfc5322.html - URL Example: issuer: https://auth.example.com - Email Example: issuer: jdoe@example.com - If not provided, the JWT issuer is not checked. | -| `audiences` _string array_ | Audiences is a list of JWT audiences allowed to access. For additional details, see: - https://tools.ietf.org/html/rfc7519#section-4.1.3 - Example: audiences: - foo.apps.example.com bar.apps.example.com - If not provided, JWT audiences are not checked. | +| `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)_ | RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. | @@ -152,9 +142,8 @@ _Appears in:_ | Field | Description | | --- | --- | -| `type` _[RateLimitType](#ratelimittype)_ | Type decides the scope for the RateLimits. Valid RateLimitType values are: - * "Global" - In this mode, the rate limits are applied across all Envoy proxy instances. | -| `global` _[GlobalRateLimit](#globalratelimit)_ | Global rate limit configuration. | +| `type` _[RateLimitType](#ratelimittype)_ | Type decides the scope for the RateLimits. Valid RateLimitType values are "Global". | +| `global` _[GlobalRateLimit](#globalratelimit)_ | Global defines global rate limit configuration. | ## RateLimitRule @@ -234,7 +223,6 @@ _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. - Example: uri: https://www.foo.com/oauth2/v1/certs | +| `uri` _string_ | URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate. | diff --git a/internal/provider/kubernetes/config/crd/bases/config.gateway.envoyproxy.io_envoyproxies.yaml b/internal/provider/kubernetes/config/crd/bases/config.gateway.envoyproxy.io_envoyproxies.yaml index 3223dc8aae2..4267c21cd96 100644 --- a/internal/provider/kubernetes/config/crd/bases/config.gateway.envoyproxy.io_envoyproxies.yaml +++ b/internal/provider/kubernetes/config/crd/bases/config.gateway.envoyproxy.io_envoyproxies.yaml @@ -18,7 +18,7 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: EnvoyProxy is the Schema for the envoyproxies API + description: EnvoyProxy is the schema for the envoyproxies API. properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation @@ -40,11 +40,14 @@ spec: level: system: info description: Logging defines logging parameters for managed proxies. - If unspecified, default settings apply. + If unspecified, default settings apply. This type is not implemented + until https://github.com/envoyproxy/gateway/issues/280 is fixed. properties: level: additionalProperties: - description: LogLevel defines a log level for system logs. + description: LogLevel defines a log level for system logs. This + type is not implemented until https://github.com/envoyproxy/gateway/issues/280 + is fixed. enum: - debug - info @@ -82,11 +85,10 @@ spec: type: object type: object type: - description: "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: \n * Kubernetes: Provides infrastructure - resources for running the data plane, e.g. Envoy proxy." + description: 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". enum: - Kubernetes type: string @@ -95,7 +97,7 @@ spec: type: object type: object status: - description: EnvoyProxyStatus defines the observed state of EnvoyProxy + description: EnvoyProxyStatus defines the actual state of EnvoyProxy. type: object type: object served: true diff --git a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_authenticationfilters.yaml b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_authenticationfilters.yaml index 7bf8b8684c3..0be6709dcad 100644 --- a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_authenticationfilters.yaml +++ b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_authenticationfilters.yaml @@ -36,32 +36,29 @@ spec: type. properties: jwtProviders: - description: "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: \n https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html" + description: 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. items: description: 'JwtAuthenticationFilterProvider defines the JSON Web Token (JWT) authentication provider type and how JWTs should be verified:' properties: audiences: - description: "Audiences is a list of JWT audiences allowed to - access. For additional details, see: \n https://tools.ietf.org/html/rfc7519#section-4.1.3 - \n Example: audiences: - foo.apps.example.com bar.apps.example.com - \n If not provided, JWT audiences are not checked." + description: 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. items: type: string maxItems: 8 type: array issuer: - description: "Issuer is the principal that issued the JWT and + description: Issuer is the principal that issued the JWT and takes the form of a URL or email address. For additional details, - see: \n URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1 - Email format: https://rfc-editor.org/rfc/rfc5322.html \n URL - Example: issuer: https://auth.example.com \n Email Example: - issuer: jdoe@example.com \n If not provided, the JWT issuer - is not checked." + 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. maxLength: 253 type: string name: @@ -76,9 +73,8 @@ spec: Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. properties: uri: - description: "URI is the HTTPS URI to fetch the JWKS. Envoy's + description: URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate. - \n Example: uri: https://www.foo.com/oauth2/v1/certs" maxLength: 253 minLength: 1 type: string @@ -92,9 +88,8 @@ spec: maxItems: 4 type: array type: - description: "Type defines the type of authentication provider to - use. Supported provider types are: \n * JWT: A provider that uses - JSON Web Token (JWT) for authenticating requests." + description: Type defines the type of authentication provider to use. + Supported provider types are "JWT". enum: - JWT type: string diff --git a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml index 96bb3dddf7b..5414b0cd842 100644 --- a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml +++ b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml @@ -37,7 +37,7 @@ spec: description: Spec defines the desired state of RateLimitFilter. properties: global: - description: Global rate limit configuration. + description: Global defines global rate limit configuration. properties: rules: description: Rules are a list of RateLimit selectors and limits. @@ -140,9 +140,8 @@ spec: - rules type: object type: - description: "Type decides the scope for the RateLimits. Valid RateLimitType - values are: \n * \"Global\" - In this mode, the rate limits are - applied across all Envoy proxy instances." + description: Type decides the scope for the RateLimits. Valid RateLimitType + values are "Global". enum: - Global type: string