docs: update getting started docs (RC2)

.github/workflows/golangci-lint.yml

@@ -60,7 +60,7 @@ jobs:
           make generate-crd-docs
       - name: Check CRD Docs Diff
         run: |
-          if ! git diff --exit-code -- docs/en/latest/api-reference.md; then
-            echo "docs/en/latest/api-reference.md has changed. Please run 'make generate-crd-docs' and commit the updated file."
+          if ! git diff --exit-code -- docs/en/latest/reference/api-reference.md; then
+            echo "docs/en/latest/reference/api-reference.md has changed. Please run 'make generate-crd-docs' and commit the updated file."
             exit 1
           fi

.github/workflows/lint-checker.yml

@@ -96,7 +96,7 @@ jobs:
           markdownlint '**/*.md' \
             --ignore node_modules \
             --ignore CHANGELOG.md \
-            --ignore docs/en/latest/api-reference.md
+            --ignore docs/en/latest/reference/api-reference.md
   markdown-link-check:
     needs: changes
     if: |

Makefile

@@ -39,7 +39,7 @@ E2E_NODES ?= 2
 CRD_REF_DOCS_VERSION ?= v0.1.0
 CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
 CRD_DOCS_CONFIG ?= docs/assets/crd/config.yaml
-CRD_DOCS_OUTPUT ?= docs/en/latest/api-reference.md
+CRD_DOCS_OUTPUT ?= docs/en/latest/reference/api-reference.md
 CRD_DOCS_TEMPLATE ?= docs/assets/template
 
 # go 

api/adc/types.go

@@ -244,7 +244,7 @@ type ClientTLS struct {
 	Key  string `json:"client_key,omitempty" yaml:"client_key,omitempty"`
 }
 
-// UpstreamActiveHealthCheck defines the active kind of upstream health check.
+// UpstreamActiveHealthCheck defines the active upstream health check configuration.
 // +k8s:deepcopy-gen=true
 type UpstreamActiveHealthCheck struct {
 	Type               string                             `json:"type,omitempty" yaml:"type,omitempty"`
@@ -259,33 +259,35 @@ type UpstreamActiveHealthCheck struct {
 	Unhealthy          UpstreamActiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
 }
 
-// UpstreamPassiveHealthCheck defines the passive kind of upstream health check.
+// UpstreamPassiveHealthCheck defines the passive health check configuration for an upstream.
+// Passive health checks rely on analyzing live traffic to determine the health status of upstream nodes.
 // +k8s:deepcopy-gen=true
 type UpstreamPassiveHealthCheck struct {
-	Type      string                              `json:"type,omitempty" yaml:"type,omitempty"`
-	Healthy   UpstreamPassiveHealthCheckHealthy   `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+	// Type is the passive health check type. For example: `http`.
+	Type string `json:"type,omitempty" yaml:"type,omitempty"`
+	// Healthy defines the conditions under which an upstream node is considered healthy.
+	Healthy UpstreamPassiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+	// Unhealthy defines the conditions under which an upstream node is considered unhealthy.
 	Unhealthy UpstreamPassiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
 }
 
-// UpstreamActiveHealthCheckHealthy defines the conditions to judge whether
-// an upstream node is healthy with the active manner.
+// UpstreamActiveHealthCheckHealthy defines the conditions used to actively determine whether an upstream node is healthy.
 // +k8s:deepcopy-gen=true
 type UpstreamActiveHealthCheckHealthy struct {
 	UpstreamPassiveHealthCheckHealthy `json:",inline" yaml:",inline"`
 
+	// Interval defines the time interval for checking targets, in seconds.
 	Interval int `json:"interval,omitempty" yaml:"interval,omitempty"`
 }
 
-// UpstreamPassiveHealthCheckHealthy defines the conditions to judge whether
-// an upstream node is healthy with the passive manner.
+// UpstreamPassiveHealthCheckHealthy defines the conditions used to passively determine whether an upstream node is healthy.
 // +k8s:deepcopy-gen=true
 type UpstreamPassiveHealthCheckHealthy struct {
 	HTTPStatuses []int `json:"http_statuses,omitempty" yaml:"http_statuses,omitempty"`
 	Successes    int   `json:"successes,omitempty" yaml:"successes,omitempty"`
 }
 
-// UpstreamPassiveHealthCheckUnhealthy defines the conditions to judge whether
-// an upstream node is unhealthy with the passive manager.
+// UpstreamPassiveHealthCheckUnhealthy defines the conditions used to passively determine whether an upstream node is unhealthy.
 // +k8s:deepcopy-gen=true
 type UpstreamPassiveHealthCheckUnhealthy struct {
 	HTTPStatuses []int `json:"http_statuses,omitempty" yaml:"http_statuses,omitempty"`
@@ -294,12 +296,12 @@ type UpstreamPassiveHealthCheckUnhealthy struct {
 	Timeouts     int   `json:"timeouts,omitempty" yaml:"timeouts,omitempty"`
 }
 
-// UpstreamActiveHealthCheckUnhealthy defines the conditions to judge whether
-// an upstream node is unhealthy with the active manager.
+// UpstreamActiveHealthCheckHealthy defines the conditions used to actively determine whether an upstream node is unhealthy.
 // +k8s:deepcopy-gen=true
 type UpstreamActiveHealthCheckUnhealthy struct {
 	UpstreamPassiveHealthCheckUnhealthy `json:",inline" yaml:",inline"`
 
+	// Interval defines the time interval for checking targets, in seconds.
 	Interval int `json:"interval,omitempty" yaml:"interval,omitempty"`
 }
 
@@ -315,21 +317,38 @@ type TrafficSplitConfigRule struct {
 	WeightedUpstreams []TrafficSplitConfigRuleWeightedUpstream `json:"weighted_upstreams"`
 }
 
-// TrafficSplitConfigRuleWeightedUpstream is the weighted upstream config in
-// the traffic split plugin rule.
+// TrafficSplitConfigRuleWeightedUpstream defines a weighted backend in a traffic split rule.
+// This is used by the APISIX traffic-split plugin to distribute traffic
+// across multiple upstreams based on weight.
 // +k8s:deepcopy-gen=true
 type TrafficSplitConfigRuleWeightedUpstream struct {
-	UpstreamID string    `json:"upstream_id,omitempty"`
-	Upstream   *Upstream `json:"upstream,omitempty"`
-	Weight     int       `json:"weight"`
+	// UpstreamID is the identifier of a pre-defined upstream.
+	UpstreamID string `json:"upstream_id,omitempty"`
+
+	// Upstream specifies upstream configuration.
+	// If provided, it overrides UpstreamID.
+	Upstream *Upstream `json:"upstream,omitempty"`
+
+	// Weight defines the percentage of traffic routed to this upstream.
+	// The final routing decision is based on relative weights.
+	Weight int `json:"weight"`
 }
 
+// TLSClass defines the client TLS configuration for mutual TLS (mTLS) authentication.
 // +k8s:deepcopy-gen=true
 type TLSClass struct {
-	ClientCERT   string `json:"client_cert,omitempty"`
+	// ClientCERT is the PEM-encoded client certificate.
+	ClientCERT string `json:"client_cert,omitempty"`
+
+	// ClientCERTID is the reference ID to a stored client certificate.
 	ClientCERTID string `json:"client_cert_id,omitempty"`
-	ClientKey    string `json:"client_key,omitempty"`
-	Verify       *bool  `json:"verify,omitempty"`
+
+	// ClientKey is the PEM-encoded private key for the client certificate.
+	ClientKey string `json:"client_key,omitempty"`
+
+	// Verify indicates whether the server's certificate should be verified.
+	// If false, TLS verification is skipped.
+	Verify *bool `json:"verify,omitempty"`
 }
 
 // +k8s:deepcopy-gen=true

api/v1alpha1/backendtrafficpolicy_types.go

@@ -23,6 +23,7 @@ import (
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// BackendTrafficPolicy defines configuration for traffic handling policies applied to backend services.
 type BackendTrafficPolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -46,7 +47,7 @@ type BackendTrafficPolicySpec struct {
 	LoadBalancer *LoadBalancer `json:"loadbalancer,omitempty" yaml:"loadbalancer,omitempty"`
 	// Scheme is the protocol used to communicate with the upstream.
 	// Default is `http`.
-	// Can be one of `http`, `https`, `grpc`, or `grpcs`.
+	// Can be `http`, `https`, `grpc`, or `grpcs`.
 	// +kubebuilder:validation:Enum=http;https;grpc;grpcs;
 	// +kubebuilder:default=http
 	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`
@@ -61,8 +62,10 @@ type BackendTrafficPolicySpec struct {
 
 	// 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`.
+	// Default is `pass`. Can be `pass`, `node` or `rewrite`:
+	// * `pass`: preserve the original Host header
+	// * `node`: use the upstream node’s host
+	// * `rewrite`: set to a custom host via `upstreamHost`
 	//
 	// +kubebuilder:validation:Enum=pass;node;rewrite;
 	// +kubebuilder:default=pass
@@ -76,20 +79,20 @@ type BackendTrafficPolicySpec struct {
 // 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.
+	// Type specifies the load balancing algorithms to route traffic to the backend.
 	// Default is `roundrobin`.
-	// Can be one of `roundrobin`, `chash`, `ewma`, or `least_conn`.
+	// Can be `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"`
-	// HashOn specified the type of field used for hashing, required when Type is `chash`.
+	// 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`.
+	// Can be `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 is used with HashOn, generally required when Type is `chash`.
+	// 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

api/v1alpha1/consumer_types.go

@@ -24,11 +24,12 @@ import (
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// Consumer defines configuration for a consumer.
 type Consumer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	// ConsumerSpec defines the configuration for a consumer, including consumer name,
+	// ConsumerSpec defines configuration for a consumer, including consumer name,
 	// authentication credentials, and plugin settings.
 	Spec   ConsumerSpec   `json:"spec,omitempty"`
 	Status ConsumerStatus `json:"status,omitempty"`
@@ -65,7 +66,7 @@ type Credential struct {
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:Enum=jwt-auth;basic-auth;key-auth;hmac-auth;
 	// Type specifies the type of authentication to configure credentials for.
-	// Can be one of `jwt-auth`, `basic-auth`, `key-auth`, or `hmac-auth`.
+	// Can be `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"`

api/v1alpha1/gatewayproxy_types.go

@@ -37,7 +37,7 @@ type GatewayProxySpec struct {
 	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 configures common configuration shared by all plugin instances of the same name.
 	PluginMetadata map[string]apiextensionsv1.JSON `json:"pluginMetadata,omitempty"`
 }
 
@@ -112,7 +112,7 @@ type ControlPlaneAuth struct {
 	AdminKey *AdminKeyAuth `json:"adminKey,omitempty"`
 }
 
-// ControlPlaneProvider defines the configuration for control plane provider.
+// ControlPlaneProvider defines configuration for control plane provider.
 // +kubebuilder:validation:XValidation:rule="has(self.endpoints) != has(self.service)"
 type ControlPlaneProvider struct {
 	// Endpoints specifies the list of control plane endpoints.
@@ -125,26 +125,28 @@ type ControlPlaneProvider struct {
 	// +optional
 	TlsVerify *bool `json:"tlsVerify,omitempty"`
 
-	// Auth specifies the authentication configurations.
+	// Auth specifies the authentication configuration.
 	// +kubebuilder:validation:Required
 	Auth ControlPlaneAuth `json:"auth"`
 }
 
 type ProviderService struct {
+	// Name is the name of the provider.
 	Name string `json:"name"`
 
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
+	// Port is the port of the provider.
 	Port int32 `json:"port,omitempty"`
 }
 
 // +kubebuilder:object:root=true
-// GatewayProxy is the Schema for the gatewayproxies API.
+// GatewayProxy defines configuration for the gateway proxy instances used to route traffic to services.
 type GatewayProxy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	// GatewayProxySpec defines the desired state and configuration of a GatewayProxy,
+	// GatewayProxySpec defines configuration of gateway proxy instances,
 	// including networking settings, global plugins, and plugin metadata.
 	Spec GatewayProxySpec `json:"spec,omitempty"`
 }
@@ -157,7 +159,7 @@ type GatewayProxyList struct {
 	Items           []GatewayProxy `json:"items"`
 }
 
-// GatewayProxyPlugin contains plugin configurations.
+// GatewayProxyPlugin contains plugin configuration.
 type GatewayProxyPlugin struct {
 	// Name is the name of the plugin.
 	Name string `json:"name,omitempty"`

api/v1alpha1/groupversion_info.go

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-// Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group
+// Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group.
 // +kubebuilder:object:generate=true
 // +groupName=apisix.apache.org
 package v1alpha1

api/v1alpha1/httproutepolicy_types.go

@@ -29,7 +29,8 @@ type HTTPRoutePolicySpec struct {
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=16
 	TargetRefs []gatewayv1alpha2.LocalPolicyTargetReferenceWithSectionName `json:"targetRefs"`
-	// Priority sets the priority for route. A higher value sets a higher priority in route matching.
+	// Priority sets the priority for route. when multiple routes have the same URI path,
+	// 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"`
@@ -38,12 +39,12 @@ type HTTPRoutePolicySpec struct {
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 
-// HTTPRoutePolicy is the Schema for the httproutepolicies API.
+// HTTPRoutePolicy defines configuration of traffic policies.
 type HTTPRoutePolicy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	// HTTPRoutePolicySpec defines the desired state and configuration of a HTTPRoutePolicy,
+	// HTTPRoutePolicySpec defines 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

@@ -27,19 +27,19 @@ import (
 
 // +kubebuilder:object:root=true
 
-// PluginConfig is the Schema for the PluginConfigs API.
+// PluginConfig defines plugin configuration.
 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.
+	// in which plugins and their configuration are specified.
 	Spec PluginConfigSpec `json:"spec,omitempty"`
 }
 
 // PluginConfigSpec defines the desired state of PluginConfig.
 type PluginConfigSpec struct {
-	// Plugins are an array of plugins and their configurations to be applied.
+	// Plugins are an array of plugins and their configuration to be applied.
 	Plugins []Plugin `json:"plugins"`
 }