Merge remote-tracking branch 'origin/release-v2-dev' into chore/condition-assertion

# Conflicts:
#	internal/controller/httproutepolicy.go

Author: dspo

api/v1alpha1/backendtrafficpolicy_types.go

@@ -22,6 +22,8 @@ type BackendTrafficPolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// BackendTrafficPolicySpec defines traffic handling policies applied to backend services,
+	// such as load balancing strategy, connection settings, and failover behavior.
 	Spec   BackendTrafficPolicySpec `json:"spec,omitempty"`
 	Status PolicyStatus             `json:"status,omitempty"`
 }
@@ -37,57 +39,71 @@ type BackendTrafficPolicySpec struct {
 	// LoadBalancer represents the load balancer configuration for Kubernetes Service.
 	// The default strategy is round robin.
 	LoadBalancer *LoadBalancer `json:"loadbalancer,omitempty" yaml:"loadbalancer,omitempty"`
-	// The scheme used to talk with the upstream.
-	//
+	// Scheme is the protocol used to communicate with the upstream.
+	// Default is `http`.
+	// Can be one of `http`, `https`, `grpc`, or `grpcs`.
 	// +kubebuilder:validation:Enum=http;https;grpc;grpcs;
 	// +kubebuilder:default=http
 	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`
 
-	// How many times that the proxy (Apache APISIX) should do when
-	// errors occur (error, timeout or bad http status codes like 500, 502).
+	// Retries specify the number of times the gateway should retry sending
+	// requests when errors such as timeouts or 502 errors occur.
 	// +optional
 	Retries *int `json:"retries,omitempty" yaml:"retries,omitempty"`
 
-	// Timeout settings for the read, send and connect to the upstream.
+	// Timeout sets the read, send, and connect timeouts to the upstream.
 	Timeout *Timeout `json:"timeout,omitempty" yaml:"timeout,omitempty"`
 
-	// Configures the host when the request is forwarded to the upstream.
-	// Can be one of pass, node or rewrite.
+	// PassHost configures how the host header should be determined when a
+	// request is forwarded to the upstream.
+	// Default is `pass`.
+	// Can be one of `pass`, `node` or `rewrite`.
 	//
 	// +kubebuilder:validation:Enum=pass;node;rewrite;
 	// +kubebuilder:default=pass
 	PassHost string `json:"passHost,omitempty" yaml:"passHost,omitempty"`
 
-	// Specifies the host of the Upstream request. This is only valid if
-	// the passHost is set to rewrite
+	// UpstreamHost specifies the host of the Upstream request. Used only if
+	// passHost is set to `rewrite`.
 	Host Hostname `json:"upstreamHost,omitempty" yaml:"upstreamHost,omitempty"`
 }
 
 // LoadBalancer describes the load balancing parameters.
 // +kubebuilder:validation:XValidation:rule="!(has(self.key) && self.type != 'chash')"
 type LoadBalancer struct {
+	// Type specifies the load balancing algorithms.
+	// Default is `roundrobin`.
+	// Can be one of `roundrobin`, `chash`, `ewma`, or `least_conn`.
 	// +kubebuilder:validation:Enum=roundrobin;chash;ewma;least_conn;
 	// +kubebuilder:default=roundrobin
 	// +kubebuilder:validation:Required
 	Type string `json:"type" yaml:"type"`
-	// The HashOn and Key fields are required when Type is "chash".
-	// HashOn represents the key fetching scope.
+	// HashOn specified the type of field used for hashing, required when Type is `chash`.
+	// Default is `vars`.
+	// Can be one of `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`.
 	// +kubebuilder:validation:Enum=vars;header;cookie;consumer;vars_combinations;
 	// +kubebuilder:default=vars
 	HashOn string `json:"hashOn,omitempty" yaml:"hashOn,omitempty"`
-	// Key represents the hash key.
+	// Key is used with HashOn, generally required when Type is `chash`.
+	// When HashOn is `header` or `cookie`, specifies the name of the header or cookie.
+	// When HashOn is `consumer`, key is not required, as the consumer name is used automatically.
+	// When HashOn is `vars` or `vars_combinations`, key refers to one or a combination of
+	// [built-in variables](/enterprise/reference/built-in-variables).
 	Key string `json:"key,omitempty" yaml:"key,omitempty"`
 }
 
 type Timeout struct {
+	// Connection timeout. Default is `60s`.
 	// +kubebuilder:default="60s"
 	// +kubebuilder:validation:Pattern=`^[0-9]+s$`
 	// +kubebuilder:validation:Type=string
 	Connect metav1.Duration `json:"connect,omitempty" yaml:"connect,omitempty"`
+	// Send timeout. Default is `60s`.
 	// +kubebuilder:default="60s"
 	// +kubebuilder:validation:Pattern=`^[0-9]+s$`
 	// +kubebuilder:validation:Type=string
 	Send metav1.Duration `json:"send,omitempty" yaml:"send,omitempty"`
+	// Read timeout. Default is `60s`.
 	// +kubebuilder:default="60s"
 	// +kubebuilder:validation:Pattern=`^[0-9]+s$`
 	// +kubebuilder:validation:Type=string

api/v1alpha1/consumer_types.go

@@ -23,38 +23,54 @@ type Consumer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ConsumerSpec defines the configuration for a consumer, including consumer name,
+	// authentication credentials, and plugin settings.
 	Spec   ConsumerSpec `json:"spec,omitempty"`
 	Status Status       `json:"status,omitempty"`
 }
 
 type ConsumerSpec struct {
-	GatewayRef  GatewayRef   `json:"gatewayRef,omitempty"`
+	// GatewayRef specifies the gateway details.
+	GatewayRef GatewayRef `json:"gatewayRef,omitempty"`
+	// Credentials specifies the credential details of a consumer.
 	Credentials []Credential `json:"credentials,omitempty"`
-	Plugins     []Plugin     `json:"plugins,omitempty"`
+	// Plugins define the plugins associated with a consumer.
+	Plugins []Plugin `json:"plugins,omitempty"`
 }
 
 type GatewayRef struct {
+	// Name is the name of the gateway.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	Name string `json:"name"`
+	// Kind is the type of Kubernetes object. Default is `Gateway`.
 	// +kubebuilder:default=Gateway
 	Kind *string `json:"kind,omitempty"`
+	// Group is the API group the resource belongs to. Default is `gateway.networking.k8s.io`.
 	// +kubebuilder:default=gateway.networking.k8s.io
-	Group     *string `json:"group,omitempty"`
+	Group *string `json:"group,omitempty"`
+	// Namespace is namespace of the resource.
 	Namespace *string `json:"namespace,omitempty"`
 }
 
 type Credential struct {
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:Enum=jwt-auth;basic-auth;key-auth;hmac-auth;
-	Type      string               `json:"type"`
-	Config    apiextensionsv1.JSON `json:"config,omitempty"`
-	SecretRef *SecretReference     `json:"secretRef,omitempty"`
-	Name      string               `json:"name,omitempty"`
+	// Type specifies the type of authentication to configure credentials for.
+	// Can be one of `jwt-auth`, `basic-auth`, `key-auth`, or `hmac-auth`.
+	Type string `json:"type"`
+	// Config specifies the credential details for authentication.
+	Config apiextensionsv1.JSON `json:"config,omitempty"`
+	// SecretRef references to the Secret that contains the credentials.
+	SecretRef *SecretReference `json:"secretRef,omitempty"`
+	// Name is the name of the credential.
+	Name string `json:"name,omitempty"`
 }
 
 type SecretReference struct {
-	Name      string  `json:"name"`
+	// Name is the name of the secret.
+	Name string `json:"name"`
+	// Namespace is the namespace of the secret.
 	Namespace *string `json:"namespace,omitempty"`
 }
 

api/v1alpha1/gatewayproxy_types.go

@@ -20,125 +20,139 @@ import (
 // EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
 // NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
 
-// GatewayProxySpec defines the desired state of GatewayProxy
+// GatewayProxySpec defines the desired state of GatewayProxy.
 type GatewayProxySpec struct {
 	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	PublishService string                          `json:"publishService,omitempty"`
-	StatusAddress  []string                        `json:"statusAddress,omitempty"`
-	Provider       *GatewayProxyProvider           `json:"provider,omitempty"`
-	Plugins        []GatewayProxyPlugin            `json:"plugins,omitempty"`
+	// PublishService specifies the LoadBalancer-type Service whose external address the controller uses to
+	// update the status of Ingress resources.
+	PublishService string `json:"publishService,omitempty"`
+	// StatusAddress specifies the external IP addresses that the controller uses to populate the status field
+	// of GatewayProxy or Ingress resources for developers to access.
+	StatusAddress []string `json:"statusAddress,omitempty"`
+	// Provider configures the provider details.
+	Provider *GatewayProxyProvider `json:"provider,omitempty"`
+	// Plugins configure global plugins.
+	Plugins []GatewayProxyPlugin `json:"plugins,omitempty"`
+	// PluginMetadata configures common configurations shared by all plugin instances of the same name.
 	PluginMetadata map[string]apiextensionsv1.JSON `json:"pluginMetadata,omitempty"`
 }
 
-// ProviderType defines the type of provider
+// ProviderType defines the type of provider.
 // +kubebuilder:validation:Enum=ControlPlane
 type ProviderType string
 
 const (
-	// ProviderTypeControlPlane represents the control plane provider type
+	// ProviderTypeControlPlane represents the control plane provider type.
 	ProviderTypeControlPlane ProviderType = "ControlPlane"
 )
 
-// GatewayProxyProvider defines the provider configuration for GatewayProxy
+// GatewayProxyProvider defines the provider configuration for GatewayProxy.
 // +kubebuilder:validation:XValidation:rule="self.type == 'ControlPlane' ? has(self.controlPlane) : true",message="controlPlane must be specified when type is ControlPlane"
 type GatewayProxyProvider struct {
-	// Type specifies the type of provider
+	// Type specifies the type of provider. Can only be `ControlPlane`.
 	// +kubebuilder:validation:Required
 	Type ProviderType `json:"type"`
 
-	// ControlPlane specifies the configuration for control plane provider
+	// ControlPlane specifies the configuration for control plane provider.
 	// +optional
 	ControlPlane *ControlPlaneProvider `json:"controlPlane,omitempty"`
 }
 
-// AuthType defines the type of authentication
+// AuthType defines the type of authentication.
 // +kubebuilder:validation:Enum=AdminKey
 type AuthType string
 
 const (
-	// AuthTypeAdminKey represents the admin key authentication type
+	// AuthTypeAdminKey represents the admin key authentication type.
 	AuthTypeAdminKey AuthType = "AdminKey"
 )
 
-// SecretKeySelector defines a reference to a specific key within a Secret
+// SecretKeySelector defines a reference to a specific key within a Secret.
 type SecretKeySelector struct {
-	// Name is the name of the secret
+	// Name is the name of the secret.
 	// +kubebuilder:validation:Required
 	Name string `json:"name"`
 
-	// Key is the key in the secret
+	// Key is the key in the secret to retrieve the secret from.
 	// +kubebuilder:validation:Required
 	Key string `json:"key"`
 }
 
-// AdminKeyAuth defines the admin key authentication configuration
+// AdminKeyAuth defines the admin key authentication configuration.
 type AdminKeyAuth struct {
-	// Value specifies the admin key value directly (not recommended for production)
+	// Value sets the admin key value explicitly (not recommended for production).
 	// +optional
 	Value string `json:"value,omitempty"`
 
-	// ValueFrom specifies the source of the admin key
+	// ValueFrom specifies the source of the admin key.
 	// +optional
 	ValueFrom *AdminKeyValueFrom `json:"valueFrom,omitempty"`
 }
 
-// AdminKeyValueFrom defines the source of the admin key
+// AdminKeyValueFrom defines the source of the admin key.
 type AdminKeyValueFrom struct {
-	// SecretKeyRef references a key in a Secret
+	// SecretKeyRef references a key in a Secret.
 	// +optional
 	SecretKeyRef *SecretKeySelector `json:"secretKeyRef,omitempty"`
 }
 
-// ControlPlaneAuth defines the authentication configuration for control plane
+// ControlPlaneAuth defines the authentication configuration for control plane.
 type ControlPlaneAuth struct {
-	// Type specifies the type of authentication
+	// Type specifies the type of authentication.
+	// Can only be `AdminKey`.
 	// +kubebuilder:validation:Required
 	Type AuthType `json:"type"`
 
-	// AdminKey specifies the admin key authentication configuration
+	// AdminKey specifies the admin key authentication configuration.
 	// +optional
 	AdminKey *AdminKeyAuth `json:"adminKey,omitempty"`
 }
 
-// ControlPlaneProvider defines the configuration for control plane provider
+// ControlPlaneProvider defines the configuration for control plane provider.
 type ControlPlaneProvider struct {
-	// Endpoints specifies the list of control plane endpoints
+	// Endpoints specifies the list of control plane endpoints.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinItems=1
 	Endpoints []string `json:"endpoints"`
 
-	// TlsVerify specifies whether to verify the TLS certificate of the control plane
+	// TlsVerify specifies whether to verify the TLS certificate of the control plane.
 	// +optional
 	TlsVerify *bool `json:"tlsVerify,omitempty"`
 
-	// Auth specifies the authentication configuration
+	// Auth specifies the authentication configurations.
 	// +kubebuilder:validation:Required
 	Auth ControlPlaneAuth `json:"auth"`
 }
 
 // +kubebuilder:object:root=true
-// GatewayProxy is the Schema for the gatewayproxies API
+// GatewayProxy is the Schema for the gatewayproxies API.
 type GatewayProxy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// GatewayProxySpec defines the desired state and configuration of a GatewayProxy,
+	// including networking settings, global plugins, and plugin metadata.
 	Spec GatewayProxySpec `json:"spec,omitempty"`
 }
 
 // +kubebuilder:object:root=true
-// GatewayProxyList contains a list of GatewayProxy
+// GatewayProxyList contains a list of GatewayProxy.
 type GatewayProxyList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []GatewayProxy `json:"items"`
 }
 
+// GatewayProxyPlugin contains plugin configurations.
 type GatewayProxyPlugin struct {
-	Name    string               `json:"name,omitempty"`
-	Enabled bool                 `json:"enabled,omitempty"`
-	Config  apiextensionsv1.JSON `json:"config,omitempty"`
+	// Name is the name of the plugin.
+	Name string `json:"name,omitempty"`
+	// Enabled defines whether the plugin is enabled.
+	Enabled bool `json:"enabled,omitempty"`
+	// Config defines the plugin's configuration details.
+	Config apiextensionsv1.JSON `json:"config,omitempty"`
 }
 
 func init() {

api/v1alpha1/httproutepolicy_types.go

@@ -20,15 +20,14 @@ import (
 
 // HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy.
 type HTTPRoutePolicySpec struct {
-	// TargetRef identifies an API object (enum: HTTPRoute, Ingress) to apply HTTPRoutePolicy to.
-	//
-	// target references.
+	// TargetRef identifies an API object (i.e. HTTPRoute, Ingress) to apply HTTPRoutePolicy to.
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=16
 	TargetRefs []gatewayv1alpha2.LocalPolicyTargetReferenceWithSectionName `json:"targetRefs"`
-
-	Priority *int64                 `json:"priority,omitempty" yaml:"priority,omitempty"`
-	Vars     []apiextensionsv1.JSON `json:"vars,omitempty" yaml:"vars,omitempty"`
+	// Priority sets the priority for route. A higher value sets a higher priority in route matching.
+	Priority *int64 `json:"priority,omitempty" yaml:"priority,omitempty"`
+	// Vars sets the request matching conditions.
+	Vars []apiextensionsv1.JSON `json:"vars,omitempty" yaml:"vars,omitempty"`
 }
 
 // +kubebuilder:object:root=true
@@ -39,6 +38,8 @@ type HTTPRoutePolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// HTTPRoutePolicySpec defines the desired state and configuration of a HTTPRoutePolicy,
+	// including route priority and request matching conditions.
 	Spec   HTTPRoutePolicySpec `json:"spec,omitempty"`
 	Status PolicyStatus        `json:"status,omitempty"`
 }

api/v1alpha1/pluginconfig_types.go

@@ -22,32 +22,35 @@ import (
 
 // +kubebuilder:object:root=true
 
-// PluginConfig is the Schema for the PluginConfigs API
+// PluginConfig is the Schema for the PluginConfigs API.
 type PluginConfig struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// PluginConfigSpec defines the desired state of a PluginConfig,
+	// in which plugins and their configurations are specified.
 	Spec PluginConfigSpec `json:"spec,omitempty"`
 }
 
-// PluginConfigSpec defines the desired state of PluginConfig
+// PluginConfigSpec defines the desired state of PluginConfig.
 type PluginConfigSpec struct {
+	// Plugins are an array of plugins and their configurations to be applied.
 	Plugins []Plugin `json:"plugins"`
 }
 
 // +kubebuilder:object:root=true
 
-// PluginConfigList contains a list of PluginConfig
+// PluginConfigList contains a list of PluginConfig.
 type PluginConfigList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []PluginConfig `json:"items"`
 }
 
 type Plugin struct {
-	// The plugin name.
+	// Name is the name of the plugin.
 	Name string `json:"name" yaml:"name"`
-	// Plugin configuration.
+	// Config is plugin configuration details.
 	Config apiextensionsv1.JSON `json:"config,omitempty" yaml:"config,omitempty"`
 }