Skip to content

Commit d4053cc

Browse files
danehansdanehans
committed
Updates API godocs for improved html rendering
Signed-off-by: danehans <[email protected]>
1 parent d5a5b25 commit d4053cc

File tree

12 files changed

+109
-143
lines changed

12 files changed

+109
-143
lines changed

‎api/config/v1alpha1/doc.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// The full text of the Apache license is available in the LICENSE file at
44
// the root of the repo.
55

6-
// Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io
6+
// Package v1alpha1 contains API schema definitions for the config.gateway.envoyproxy.io
77
// API group.
88
//
99
// +kubebuilder:object:generate=true

‎api/config/v1alpha1/envoygateway_types.go‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ const (
1818

1919
//+kubebuilder:object:root=true
2020

21-
// EnvoyGateway is the Schema for the envoygateways API.
21+
// EnvoyGateway is the schema for the envoygateways API.
2222
type EnvoyGateway struct {
2323
metav1.TypeMeta `json:",inline"`
2424

25-
// EnvoyGatewaySpec defines the desired state of Envoy Gateway.
25+
// EnvoyGatewaySpec defines the desired state of EnvoyGateway.
2626
EnvoyGatewaySpec `json:",inline"`
2727
}
2828

@@ -45,7 +45,7 @@ type EnvoyGatewaySpec struct {
4545
// deployed by Envoy Gateway required to implement the Global Rate limiting
4646
// functionality. The specific rate limit service used here is the reference
4747
// implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.
48-
// This configuration will not be needed to enable Local Rate limiitng.
48+
// This configuration is unneeded for "Local" rate limiting.
4949
//
5050
// +optional
5151
RateLimit *RateLimit `json:"rateLimit,omitempty"`
@@ -56,8 +56,7 @@ type Gateway struct {
5656
// ControllerName defines the name of the Gateway API controller. If unspecified,
5757
// defaults to "gateway.envoyproxy.io/gatewayclass-controller". See the following
5858
// for additional details:
59-
//
60-
// https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass
59+
// https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass
6160
//
6261
// +optional
6362
ControllerName string `json:"controllerName,omitempty"`
@@ -66,20 +65,20 @@ type Gateway struct {
6665
// Provider defines the desired configuration of a provider.
6766
// +union
6867
type Provider struct {
69-
// Type is the type of provider to use. Supported types are:
70-
//
71-
// * Kubernetes: A provider that provides runtime configuration via the Kubernetes API.
68+
// Type is the type of provider to use. Supported types are "Kubernetes".
7269
//
7370
// +unionDiscriminator
7471
Type ProviderType `json:"type"`
72+
7573
// Kubernetes defines the configuration of the Kubernetes provider. Kubernetes
7674
// provides runtime configuration via the Kubernetes API.
7775
//
7876
// +optional
7977
Kubernetes *KubernetesProvider `json:"kubernetes,omitempty"`
8078

8179
// File defines the configuration of the File provider. File provides runtime
82-
// configuration defined by one or more files.
80+
// configuration defined by one or more files. This type is not implemented
81+
// until https://github.com/envoyproxy/gateway/issues/1001 is fixed.
8382
//
8483
// +optional
8584
File *FileProvider `json:"file,omitempty"`

‎api/config/v1alpha1/envoyproxy_types.go‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,14 @@ const (
1717
//+kubebuilder:object:root=true
1818
//+kubebuilder:subresource:status
1919

20-
// EnvoyProxy is the Schema for the envoyproxies API
20+
// EnvoyProxy is the schema for the envoyproxies API.
2121
type EnvoyProxy struct {
2222
metav1.TypeMeta `json:",inline"`
2323
metav1.ObjectMeta `json:"metadata,omitempty"`
2424

25-
Spec EnvoyProxySpec `json:"spec,omitempty"`
25+
// EnvoyProxySpec defines the desired state of EnvoyProxy.
26+
Spec EnvoyProxySpec `json:"spec,omitempty"`
27+
// EnvoyProxyStatus defines the actual state of EnvoyProxy.
2628
Status EnvoyProxyStatus `json:"status,omitempty"`
2729
}
2830

@@ -36,7 +38,8 @@ type EnvoyProxySpec struct {
3638
Provider *ResourceProvider `json:"provider,omitempty"`
3739

3840
// Logging defines logging parameters for managed proxies. If unspecified,
39-
// default settings apply.
41+
// default settings apply. This type is not implemented until
42+
// https://github.com/envoyproxy/gateway/issues/280 is fixed.
4043
//
4144
// +kubebuilder:default={level: {system: info}}
4245
Logging ProxyLogging `json:"logging,omitempty"`
@@ -47,10 +50,7 @@ type EnvoyProxySpec struct {
4750
type ResourceProvider struct {
4851
// Type is the type of resource provider to use. A resource provider provides
4952
// infrastructure resources for running the data plane, e.g. Envoy proxy, and
50-
// optional auxiliary control planes. Supported types are:
51-
//
52-
// * Kubernetes: Provides infrastructure resources for running the data plane,
53-
// e.g. Envoy proxy.
53+
// optional auxiliary control planes. Supported types are "Kubernetes".
5454
//
5555
// +unionDiscriminator
5656
Type ProviderType `json:"type"`
@@ -74,7 +74,8 @@ type KubernetesResourceProvider struct {
7474
EnvoyDeployment *KubernetesDeploymentSpec `json:"envoyDeployment,omitempty"`
7575
}
7676

77-
// ProxyLogging defines logging parameters for managed proxies.
77+
// ProxyLogging defines logging parameters for managed proxies. This type is not
78+
// implemented until https://github.com/envoyproxy/gateway/issues/280 is fixed.
7879
type ProxyLogging struct {
7980
// Level is a map of logging level per component, where the component is the key
8081
// and the log level is the value. If unspecified, defaults to "System: Info".
@@ -84,7 +85,8 @@ type ProxyLogging struct {
8485
}
8586

8687
// LogComponent defines a component that supports a configured logging level.
87-
//
88+
// This type is not implemented until https://github.com/envoyproxy/gateway/issues/280
89+
// is fixed.
8890
// +kubebuilder:validation:Enum=system;upstream;http;connection;admin;client;filter;main;router;runtime
8991
type LogComponent string
9092

@@ -121,8 +123,8 @@ const (
121123
LogComponentRuntime LogComponent = "runtime"
122124
)
123125

124-
// LogLevel defines a log level for system logs.
125-
//
126+
// LogLevel defines a log level for system logs. This type is not implemented until
127+
// https://github.com/envoyproxy/gateway/issues/280 is fixed.
126128
// +kubebuilder:validation:Enum=debug;info;error
127129
type LogLevel string
128130

@@ -137,7 +139,8 @@ const (
137139
LogLevelError LogLevel = "error"
138140
)
139141

140-
// EnvoyProxyStatus defines the observed state of EnvoyProxy
142+
// EnvoyProxyStatus defines the observed state of EnvoyProxy. This type is not implemented
143+
// until https://github.com/envoyproxy/gateway/issues/1007 is fixed.
141144
type EnvoyProxyStatus struct {
142145
// INSERT ADDITIONAL STATUS FIELDS - define observed state of cluster.
143146
// Important: Run "make" to regenerate code after modifying this file.

‎api/config/v1alpha1/shared_types.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ const (
1919
// ProviderTypeKubernetes defines the "Kubernetes" provider.
2020
ProviderTypeKubernetes ProviderType = "Kubernetes"
2121

22-
// ProviderTypeFile defines the "File" provider.
22+
// ProviderTypeFile defines the "File" provider. This type is not implemented
23+
// until https://github.com/envoyproxy/gateway/issues/1001 is fixed.
2324
ProviderTypeFile ProviderType = "File"
2425
)
2526

‎api/v1alpha1/authenticationfilter_types.go‎

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,16 @@ type AuthenticationFilter struct {
2929
// AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type.
3030
// +union
3131
type AuthenticationFilterSpec struct {
32-
// Type defines the type of authentication provider to use. Supported provider types are:
33-
//
34-
// * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests.
32+
// Type defines the type of authentication provider to use. Supported provider types
33+
// are "JWT".
3534
//
3635
// +unionDiscriminator
3736
Type AuthenticationFilterType `json:"type"`
3837

3938
// JWT defines the JSON Web Token (JWT) authentication provider type. When multiple
4039
// jwtProviders are specified, the JWT is considered valid if any of the providers
41-
// successfully validate the JWT. For additional details, see:
42-
//
43-
// https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html
40+
// successfully validate the JWT. For additional details, see
41+
// https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html.
4442
//
4543
// +kubebuilder:validation:MaxItems=4
4644
// +optional
@@ -52,7 +50,8 @@ type AuthenticationFilterSpec struct {
5250
type AuthenticationFilterType string
5351

5452
const (
55-
// JwtAuthenticationFilterProviderType is the JWT authentication provider type.
53+
// JwtAuthenticationFilterProviderType is a provider that uses JSON Web Token (JWT)
54+
// for authenticating requests..
5655
JwtAuthenticationFilterProviderType AuthenticationFilterType = "JWT"
5756
)
5857

@@ -67,33 +66,17 @@ type JwtAuthenticationFilterProvider struct {
6766
Name string `json:"name"`
6867

6968
// Issuer is the principal that issued the JWT and takes the form of a URL or email address.
70-
// For additional details, see:
71-
//
72-
// URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1
73-
// Email format: https://rfc-editor.org/rfc/rfc5322.html
74-
//
75-
// URL Example:
76-
// issuer: https://auth.example.com
77-
//
78-
// Email Example:
79-
// issuer: [email protected]
80-
//
81-
// If not provided, the JWT issuer is not checked.
69+
// For additional details, see https://tools.ietf.org/html/rfc7519#section-4.1.1 for
70+
// URL format and https://rfc-editor.org/rfc/rfc5322.html for email format. If not provided,
71+
// the JWT issuer is not checked.
8272
//
8373
// +kubebuilder:validation:MaxLength=253
8474
// +optional
8575
Issuer string `json:"issuer,omitempty"`
8676

87-
// Audiences is a list of JWT audiences allowed to access. For additional details, see:
88-
//
89-
// https://tools.ietf.org/html/rfc7519#section-4.1.3
90-
//
91-
// Example:
92-
// audiences:
93-
// - foo.apps.example.com
94-
// bar.apps.example.com
95-
//
96-
// If not provided, JWT audiences are not checked.
77+
// Audiences is a list of JWT audiences allowed access. For additional details, see
78+
// https://tools.ietf.org/html/rfc7519#section-4.1.3. If not provided, JWT audiences
79+
// are not checked.
9780
//
9881
// +kubebuilder:validation:MaxItems=8
9982
// +optional
@@ -112,9 +95,6 @@ type RemoteJWKS struct {
11295
// URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to
11396
// validate the server certificate.
11497
//
115-
// Example:
116-
// uri: https://www.foo.com/oauth2/v1/certs
117-
//
11898
// +kubebuilder:validation:MinLength=1
11999
// +kubebuilder:validation:MaxLength=253
120100
URI string `json:"uri"`

‎api/v1alpha1/doc.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// The full text of the Apache license is available in the LICENSE file at
44
// the root of the repo.
55

6-
// Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group.
6+
// Package v1alpha1 contains API schema definitions for the gateway.envoyproxy.io API group.
77
//
88
// +kubebuilder:object:generate=true
99
// +groupName=gateway.envoyproxy.io

‎api/v1alpha1/ratelimitfilter_types.go‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,11 @@ type RateLimitFilter struct {
3030
// +union
3131
type RateLimitFilterSpec struct {
3232
// Type decides the scope for the RateLimits.
33-
// Valid RateLimitType values are:
34-
//
35-
// * "Global" - In this mode, the rate limits are applied across all Envoy proxy instances.
33+
// Valid RateLimitType values are "Global".
3634
//
3735
// +unionDiscriminator
3836
Type RateLimitType `json:"type"`
39-
// Global rate limit configuration.
37+
// Global defines global rate limit configuration.
4038
//
4139
// +optional
4240
Global *GlobalRateLimit `json:"global,omitempty"`
@@ -51,7 +49,7 @@ const (
5149
GlobalRateLimitType RateLimitType = "Global"
5250
)
5351

54-
// GlobalRateLimit defines the global rate limit configuration.
52+
// GlobalRateLimit defines global rate limit configuration.
5553
type GlobalRateLimit struct {
5654
// Rules are a list of RateLimit selectors and limits.
5755
// Each rule and its associated limit is applied
@@ -116,29 +114,33 @@ type HeaderMatch struct {
116114

117115
// Value within the HTTP header. Due to the
118116
// case-insensitivity of header names, "foo" and "Foo" are considered equivalent.
119-
// Do not set this field when Type="Distinct", implying matching on any/all unique values within the header.
117+
// Do not set this field when Type="Distinct", implying matching on any/all unique
118+
// values within the header.
119+
//
120120
// +optional
121121
// +kubebuilder:validation:MaxLength=1024
122122
Value *string `json:"value,omitempty"`
123123
}
124124

125-
// HeaderMatchType specifies the semantics of how HTTP header values should be
126-
// compared. Valid HeaderMatchType values are:
127-
//
128-
// - "Exact": Use this type to match the exact value of the Value field against the value of the specified HTTP Header.
129-
// - "RegularExpression": Use this type to match a regular expression against the value of the specified HTTP Header.
130-
// The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax.
131-
// - "Distinct": Use this type to match any and all possible unique values encountered in the specified HTTP Header.
132-
// Note that each unique value will receive its own rate limit bucket.
125+
// HeaderMatchType specifies the semantics of how HTTP header values should be compared.
126+
// Valid HeaderMatchType values are "Exact", "RegularExpression", and "Distinct".
133127
//
134128
// +kubebuilder:validation:Enum=Exact;RegularExpression;Distinct
135129
type HeaderMatchType string
136130

137131
// HeaderMatchType constants.
138132
const (
139-
HeaderMatchExact HeaderMatchType = "Exact"
133+
// HeaderMatchExact matches the exact value of the Value field against the value of
134+
// the specified HTTP Header.
135+
HeaderMatchExact HeaderMatchType = "Exact"
136+
// HeaderMatchRegularExpression matches a regular expression against the value of the
137+
// specified HTTP Header. The regex string must adhere to the syntax documented in
138+
// https://github.com/google/re2/wiki/Syntax.
140139
HeaderMatchRegularExpression HeaderMatchType = "RegularExpression"
141-
HeaderMatchDistinct HeaderMatchType = "Distinct"
140+
// HeaderMatchDistinct matches any and all possible unique values encountered in the
141+
// specified HTTP Header. Note that each unique value will receive its own rate limit
142+
// bucket.
143+
HeaderMatchDistinct HeaderMatchType = "Distinct"
142144
)
143145

144146
// RateLimitValue defines the limits for rate limiting.

0 commit comments

Comments
 (0)