You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2025/07/22 04:17:49 UTC

(apisix-ingress-controller) branch v2.0.0 updated: docs: update getting started docs (RC2) (#2481) (#2487)

This is an automated email from the ASF dual-hosted git repository.

juzhiyuan pushed a commit to branch v2.0.0
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git


The following commit(s) were added to refs/heads/v2.0.0 by this push:
     new b13215c9 docs: update getting started docs (RC2) (#2481) (#2487)
b13215c9 is described below

commit b13215c933505248ab31699968b55d2fbe34f99c
Author: Traky Deng <tr...@gmail.com>
AuthorDate: Tue Jul 22 12:17:45 2025 +0800

    docs: update getting started docs (RC2) (#2481) (#2487)
---
 .github/workflows/golangci-lint.yml                |    4 +-
 .github/workflows/lint-checker.yml                 |    2 +-
 Makefile                                           |    2 +-
 api/adc/types.go                                   |   59 +-
 api/v1alpha1/backendtrafficpolicy_types.go         |   19 +-
 api/v1alpha1/consumer_types.go                     |    5 +-
 api/v1alpha1/gatewayproxy_types.go                 |   14 +-
 api/v1alpha1/groupversion_info.go                  |    2 +-
 api/v1alpha1/httproutepolicy_types.go              |    7 +-
 api/v1alpha1/pluginconfig_types.go                 |    6 +-
 api/v2/apisixconsumer_types.go                     |  149 +-
 api/v2/apisixglobalrule_types.go                   |    9 +-
 api/v2/apisixpluginconfig_types.go                 |    7 +-
 api/v2/apisixroute_types.go                        |  268 ++--
 api/v2/apisixtls_types.go                          |   37 +-
 api/v2/apisixupstream_types.go                     |  183 ++-
 api/v2/shared_types.go                             |    2 +-
 .../bases/apisix.apache.org_apisixconsumers.yaml   |  123 +-
 .../bases/apisix.apache.org_apisixglobalrules.yaml |    8 +-
 .../apisix.apache.org_apisixpluginconfigs.yaml     |   10 +-
 .../crd/bases/apisix.apache.org_apisixroutes.yaml  |  239 +--
 .../crd/bases/apisix.apache.org_apisixtlses.yaml   |   36 +-
 .../bases/apisix.apache.org_apisixupstreams.yaml   |  361 +++--
 .../apisix.apache.org_backendtrafficpolicies.yaml  |   20 +-
 config/crd/bases/apisix.apache.org_consumers.yaml  |    5 +-
 .../bases/apisix.apache.org_gatewayproxies.yaml    |   13 +-
 .../bases/apisix.apache.org_httproutepolicies.yaml |    9 +-
 .../crd/bases/apisix.apache.org_pluginconfigs.yaml |    6 +-
 docs/assets/template/gv_details.tpl                |    2 +-
 docs/assets/template/gv_list.tpl                   |    4 +-
 docs/en/latest/api-reference.md                    | 1589 --------------------
 docs/en/latest/config.json                         |   21 +-
 docs/en/latest/getting-started/configure-routes.md |  198 +++
 .../get-apisix-ingress-controller.md               |  135 ++
 .../latest/getting-started/key-authentication.md   |  250 +++
 docs/en/latest/getting-started/load-balancing.md   |  177 +++
 docs/en/latest/getting-started/rate-limiting.md    |  206 +++
 docs/en/latest/{getting-started.md => overview.md} |  131 +-
 docs/en/latest/reference/api-reference.md          | 1589 ++++++++++++++++++++
 docs/en/latest/reference/example.md                | 1024 +++++++++++++
 40 files changed, 4610 insertions(+), 2321 deletions(-)

diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml
index cd150346..91f028d9 100644
--- a/.github/workflows/golangci-lint.yml
+++ b/.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
diff --git a/.github/workflows/lint-checker.yml b/.github/workflows/lint-checker.yml
index 2cfff073..3bfbf0f7 100644
--- a/.github/workflows/lint-checker.yml
+++ b/.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: |
diff --git a/Makefile b/Makefile
index 15b7ecf1..f2b10472 100644
--- a/Makefile
+++ b/Makefile
@@ -37,7 +37,7 @@ TEST_DIR ?= ./test/e2e/apisix/
 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 
diff --git a/api/adc/types.go b/api/adc/types.go
index 0eb7d12a..d561abf8 100644
--- a/api/adc/types.go
+++ b/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
diff --git a/api/v1alpha1/backendtrafficpolicy_types.go b/api/v1alpha1/backendtrafficpolicy_types.go
index 790f16b9..44d5239d 100644
--- a/api/v1alpha1/backendtrafficpolicy_types.go
+++ b/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
diff --git a/api/v1alpha1/consumer_types.go b/api/v1alpha1/consumer_types.go
index d6665ac3..83914ad3 100644
--- a/api/v1alpha1/consumer_types.go
+++ b/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"`
diff --git a/api/v1alpha1/gatewayproxy_types.go b/api/v1alpha1/gatewayproxy_types.go
index bf8b802a..18117903 100644
--- a/api/v1alpha1/gatewayproxy_types.go
+++ b/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"`
diff --git a/api/v1alpha1/groupversion_info.go b/api/v1alpha1/groupversion_info.go
index 3be29433..bcb0ada8 100644
--- a/api/v1alpha1/groupversion_info.go
+++ b/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
diff --git a/api/v1alpha1/httproutepolicy_types.go b/api/v1alpha1/httproutepolicy_types.go
index b28e3efe..0a1d2e6e 100644
--- a/api/v1alpha1/httproutepolicy_types.go
+++ b/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"`
diff --git a/api/v1alpha1/pluginconfig_types.go b/api/v1alpha1/pluginconfig_types.go
index 678a3ed8..600cb9a4 100644
--- a/api/v1alpha1/pluginconfig_types.go
+++ b/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"`
 }
 
diff --git a/api/v2/apisixconsumer_types.go b/api/v2/apisixconsumer_types.go
index 83f73129..89163c5b 100644
--- a/api/v2/apisixconsumer_types.go
+++ b/api/v2/apisixconsumer_types.go
@@ -25,11 +25,10 @@ import (
 // ApisixConsumerSpec defines the desired state of ApisixConsumer.
 type ApisixConsumerSpec struct {
 	// IngressClassName is the name of an IngressClass cluster resource.
-	// controller implementations use this field to know whether they should be
-	// serving this ApisixConsumer resource, by a transitive connection
-	// (controller -> IngressClass -> ApisixConsumer resource).
+	// The controller uses this field to decide whether the resource should be managed.
 	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
 
+	// AuthParameter defines the authentication credentials and configuration for this consumer.
 	AuthParameter ApisixConsumerAuthParameter `json:"authParameter" yaml:"authParameter"`
 }
 
@@ -40,11 +39,12 @@ type ApisixConsumerStatus = ApisixStatus
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:shortName=ac
 
-// ApisixConsumer is the Schema for the apisixconsumers API.
+// ApisixConsumer defines configuration of a consumer and their authentication details.
 type ApisixConsumer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixConsumerSpec defines the consumer authentication configuration.
 	Spec   ApisixConsumerSpec   `json:"spec,omitempty"`
 	Status ApisixConsumerStatus `json:"status,omitempty"`
 }
@@ -59,95 +59,138 @@ type ApisixConsumerList struct {
 }
 
 type ApisixConsumerAuthParameter struct {
+	// BasicAuth configures the basic authentication details.
 	BasicAuth *ApisixConsumerBasicAuth `json:"basicAuth,omitempty" yaml:"basicAuth"`
-	KeyAuth   *ApisixConsumerKeyAuth   `json:"keyAuth,omitempty" yaml:"keyAuth"`
-	WolfRBAC  *ApisixConsumerWolfRBAC  `json:"wolfRBAC,omitempty" yaml:"wolfRBAC"`
-	JwtAuth   *ApisixConsumerJwtAuth   `json:"jwtAuth,omitempty" yaml:"jwtAuth"`
-	HMACAuth  *ApisixConsumerHMACAuth  `json:"hmacAuth,omitempty" yaml:"hmacAuth"`
-	LDAPAuth  *ApisixConsumerLDAPAuth  `json:"ldapAuth,omitempty" yaml:"ldapAuth"`
-}
-
-// ApisixConsumerBasicAuth defines the configuration for basic auth.
+	// KeyAuth configures the key authentication details.
+	KeyAuth *ApisixConsumerKeyAuth `json:"keyAuth,omitempty" yaml:"keyAuth"`
+	// WolfRBAC configures the Wolf RBAC authentication details.
+	WolfRBAC *ApisixConsumerWolfRBAC `json:"wolfRBAC,omitempty" yaml:"wolfRBAC"`
+	// JwtAuth configures the JWT authentication details.
+	JwtAuth *ApisixConsumerJwtAuth `json:"jwtAuth,omitempty" yaml:"jwtAuth"`
+	// HMACAuth configures the HMAC authentication details.
+	HMACAuth *ApisixConsumerHMACAuth `json:"hmacAuth,omitempty" yaml:"hmacAuth"`
+	// LDAPAuth configures the LDAP authentication details.
+	LDAPAuth *ApisixConsumerLDAPAuth `json:"ldapAuth,omitempty" yaml:"ldapAuth"`
+}
+
+// ApisixConsumerBasicAuth defines configuration for basic authentication.
 type ApisixConsumerBasicAuth struct {
-	SecretRef *corev1.LocalObjectReference  `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
-	Value     *ApisixConsumerBasicAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
+	// SecretRef references a Kubernetes Secret containing the basic authentication credentials.
+	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
+	// Value specifies the basic authentication credentials.
+	Value *ApisixConsumerBasicAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerBasicAuthValue defines the in-place username and password configuration for basic auth.
+// ApisixConsumerBasicAuthValue defines the username and password configuration for basic authentication.
 type ApisixConsumerBasicAuthValue struct {
+	// Username is the basic authentication username.
 	Username string `json:"username" yaml:"username"`
+	// Password is the basic authentication password.
 	Password string `json:"password" yaml:"password"`
 }
 
-// ApisixConsumerKeyAuth defines the configuration for the key auth.
+// ApisixConsumerKeyAuth defines configuration for the key auth.
 type ApisixConsumerKeyAuth struct {
+	// SecretRef references a Kubernetes Secret containing the key authentication credentials.
 	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
-	Value     *ApisixConsumerKeyAuthValue  `json:"value,omitempty" yaml:"value,omitempty"`
+	// Value specifies the key authentication credentials.
+	Value *ApisixConsumerKeyAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerKeyAuthValue defines the in-place configuration for basic auth.
+// ApisixConsumerKeyAuthValue defines configuration for key authentication.
 type ApisixConsumerKeyAuthValue struct {
+	// Key is the credential used for key authentication.
 	Key string `json:"key" yaml:"key"`
 }
 
-// ApisixConsumerWolfRBAC defines the configuration for the wolf-rbac auth.
+// ApisixConsumerWolfRBAC defines configuration for the Wolf RBAC authentication.
 type ApisixConsumerWolfRBAC struct {
+	// SecretRef references a Kubernetes Secret containing the Wolf RBAC token.
 	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
-	Value     *ApisixConsumerWolfRBACValue `json:"value,omitempty" yaml:"value,omitempty"`
+	// Value specifies the Wolf RBAC token.
+	Value *ApisixConsumerWolfRBACValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerWolfRBAC defines the in-place server and appid and header_prefix configuration for wolf-rbac auth.
+// ApisixConsumerWolfRBACValue defines configuration for Wolf RBAC authentication.
 type ApisixConsumerWolfRBACValue struct {
-	Server       string `json:"server,omitempty" yaml:"server,omitempty"`
-	Appid        string `json:"appid,omitempty" yaml:"appid,omitempty"`
+	// Server is the URL of the Wolf RBAC server.
+	Server string `json:"server,omitempty" yaml:"server,omitempty"`
+	// Appid is the application identifier used when communicating with the Wolf RBAC server.
+	Appid string `json:"appid,omitempty" yaml:"appid,omitempty"`
+	// HeaderPrefix is the prefix added to request headers for RBAC enforcement.
 	HeaderPrefix string `json:"header_prefix,omitempty" yaml:"header_prefix,omitempty"`
 }
 
-// ApisixConsumerJwtAuth defines the configuration for the jwt auth.
+// ApisixConsumerJwtAuth defines configuration for JWT authentication.
 type ApisixConsumerJwtAuth struct {
+	// SecretRef references a Kubernetes Secret containing JWT authentication credentials.
 	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
-	Value     *ApisixConsumerJwtAuthValue  `json:"value,omitempty" yaml:"value,omitempty"`
+	// Value specifies JWT authentication credentials.
+	Value *ApisixConsumerJwtAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerJwtAuthValue defines the in-place configuration for jwt auth.
+// ApisixConsumerJwtAuthValue defines configuration for JWT authentication.
 type ApisixConsumerJwtAuthValue struct {
-	Key                 string `json:"key" yaml:"key"`
-	Secret              string `json:"secret,omitempty" yaml:"secret,omitempty"`
-	PublicKey           string `json:"public_key,omitempty" yaml:"public_key,omitempty"`
-	PrivateKey          string `json:"private_key" yaml:"private_key,omitempty"`
-	Algorithm           string `json:"algorithm,omitempty" yaml:"algorithm,omitempty"`
-	Exp                 int64  `json:"exp,omitempty" yaml:"exp,omitempty"`
-	Base64Secret        bool   `json:"base64_secret,omitempty" yaml:"base64_secret,omitempty"`
-	LifetimeGracePeriod int64  `json:"lifetime_grace_period,omitempty" yaml:"lifetime_grace_period,omitempty"`
-}
-
-// ApisixConsumerHMACAuth defines the configuration for the hmac auth.
+	// Key is the unique identifier for the JWT credential.
+	Key string `json:"key" yaml:"key"`
+	// Secret is the shared secret used to sign the JWT (for symmetric algorithms).
+	Secret string `json:"secret,omitempty" yaml:"secret,omitempty"`
+	// PublicKey is the public key used to verify JWT signatures (for asymmetric algorithms).
+	PublicKey string `json:"public_key,omitempty" yaml:"public_key,omitempty"`
+	// PrivateKey is the private key used to sign the JWT (for asymmetric algorithms).
+	PrivateKey string `json:"private_key" yaml:"private_key,omitempty"`
+	// Algorithm specifies the signing algorithm.
+	// Can be `HS256`, `HS512`, `RS256`, or `ES256`.
+	Algorithm string `json:"algorithm,omitempty" yaml:"algorithm,omitempty"`
+	// Exp is the token expiration period in seconds.
+	Exp int64 `json:"exp,omitempty" yaml:"exp,omitempty"`
+	// Base64Secret indicates whether the secret is base64-encoded.
+	Base64Secret bool `json:"base64_secret,omitempty" yaml:"base64_secret,omitempty"`
+	// LifetimeGracePeriod is the allowed clock skew in seconds for token expiration.
+	LifetimeGracePeriod int64 `json:"lifetime_grace_period,omitempty" yaml:"lifetime_grace_period,omitempty"`
+}
+
+// ApisixConsumerHMACAuth defines configuration for the HMAC authentication.
 type ApisixConsumerHMACAuth struct {
+	// SecretRef references a Kubernetes Secret containing the HMAC credentials.
 	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
-	Value     *ApisixConsumerHMACAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
+	// Value specifies HMAC authentication credentials.
+	Value *ApisixConsumerHMACAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerHMACAuthValue defines the in-place configuration for hmac auth.
+// ApisixConsumerHMACAuthValue defines configuration for HMAC authentication.
 type ApisixConsumerHMACAuthValue struct {
-	AccessKey           string   `json:"access_key" yaml:"access_key"`
-	SecretKey           string   `json:"secret_key" yaml:"secret_key"`
-	Algorithm           string   `json:"algorithm,omitempty" yaml:"algorithm,omitempty"`
-	ClockSkew           int64    `json:"clock_skew,omitempty" yaml:"clock_skew,omitempty"`
-	SignedHeaders       []string `json:"signed_headers,omitempty" yaml:"signed_headers,omitempty"`
-	KeepHeaders         bool     `json:"keep_headers,omitempty" yaml:"keep_headers,omitempty"`
-	EncodeURIParams     bool     `json:"encode_uri_params,omitempty" yaml:"encode_uri_params,omitempty"`
-	ValidateRequestBody bool     `json:"validate_request_body,omitempty" yaml:"validate_request_body,omitempty"`
-	MaxReqBody          int64    `json:"max_req_body,omitempty" yaml:"max_req_body,omitempty"`
-}
-
-// ApisixConsumerLDAPAuth defines the configuration for the ldap auth.
+	// AccessKey is the identifier used to look up the HMAC secret.
+	AccessKey string `json:"access_key" yaml:"access_key"`
+	// SecretKey is the HMAC secret used to sign the request.
+	SecretKey string `json:"secret_key" yaml:"secret_key"`
+	// Algorithm specifies the hashing algorithm (e.g., "hmac-sha256").
+	Algorithm string `json:"algorithm,omitempty" yaml:"algorithm,omitempty"`
+	// ClockSkew is the allowed time difference (in seconds) between client and server clocks.
+	ClockSkew int64 `json:"clock_skew,omitempty" yaml:"clock_skew,omitempty"`
+	// SignedHeaders lists the headers that must be included in the signature.
+	SignedHeaders []string `json:"signed_headers,omitempty" yaml:"signed_headers,omitempty"`
+	// KeepHeaders determines whether the HMAC signature headers are preserved after verification.
+	KeepHeaders bool `json:"keep_headers,omitempty" yaml:"keep_headers,omitempty"`
+	// EncodeURIParams indicates whether URI parameters are encoded when calculating the signature.
+	EncodeURIParams bool `json:"encode_uri_params,omitempty" yaml:"encode_uri_params,omitempty"`
+	// ValidateRequestBody enables HMAC validation of the request body.
+	ValidateRequestBody bool `json:"validate_request_body,omitempty" yaml:"validate_request_body,omitempty"`
+	// MaxReqBody sets the maximum size (in bytes) of the request body that can be validated.
+	MaxReqBody int64 `json:"max_req_body,omitempty" yaml:"max_req_body,omitempty"`
+}
+
+// ApisixConsumerLDAPAuth defines configuration for the LDAP authentication.
 type ApisixConsumerLDAPAuth struct {
+	// SecretRef references a Kubernetes Secret containing the LDAP credentials.
 	SecretRef *corev1.LocalObjectReference `json:"secretRef" yaml:"secret"`
-	Value     *ApisixConsumerLDAPAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
+	// Value specifies LDAP authentication credentials.
+	Value *ApisixConsumerLDAPAuthValue `json:"value,omitempty" yaml:"value,omitempty"`
 }
 
-// ApisixConsumerLDAPAuthValue defines the in-place configuration for ldap auth.
+// ApisixConsumerLDAPAuthValue defines configuration for LDAP authentication.
 type ApisixConsumerLDAPAuthValue struct {
+	// UserDN is the distinguished name (DN) of the LDAP user.
 	UserDN string `json:"user_dn" yaml:"user_dn"`
 }
 
diff --git a/api/v2/apisixglobalrule_types.go b/api/v2/apisixglobalrule_types.go
index 44126b72..8af35cac 100644
--- a/api/v2/apisixglobalrule_types.go
+++ b/api/v2/apisixglobalrule_types.go
@@ -21,12 +21,12 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// ApisixGlobalRuleSpec defines the desired state of ApisixGlobalRule.
+// ApisixGlobalRuleSpec defines configuration for global plugins.
 type ApisixGlobalRuleSpec struct {
 	// IngressClassName is the name of an IngressClass cluster resource.
-	// The controller uses this field to decide whether the resource should be managed or not.
+	// The controller uses this field to decide whether the resource should be managed.
 	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
-	// Plugins contains a list of ApisixRoutePlugin
+	// Plugins contain a list of global plugins.
 	// +kubebuilder:validation:Required
 	Plugins []ApisixRoutePlugin `json:"plugins" yaml:"plugins"`
 }
@@ -38,11 +38,12 @@ type ApisixGlobalRuleStatus = ApisixStatus
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:shortName=agr
 
-// ApisixGlobalRule is the Schema for the apisixglobalrules API.
+// ApisixGlobalRule defines configuration for global plugins.
 type ApisixGlobalRule struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixGlobalRuleSpec defines the global plugin configuration.
 	Spec   ApisixGlobalRuleSpec   `json:"spec,omitempty"`
 	Status ApisixGlobalRuleStatus `json:"status,omitempty"`
 }
diff --git a/api/v2/apisixpluginconfig_types.go b/api/v2/apisixpluginconfig_types.go
index fc6742e6..d31b8364 100644
--- a/api/v2/apisixpluginconfig_types.go
+++ b/api/v2/apisixpluginconfig_types.go
@@ -24,10 +24,10 @@ import (
 // ApisixPluginConfigSpec defines the desired state of ApisixPluginConfigSpec.
 type ApisixPluginConfigSpec struct {
 	// IngressClassName is the name of an IngressClass cluster resource.
-	// The controller uses this field to decide whether the resource should be managed or not.
+	// The controller uses this field to decide whether the resource should be managed.
 	// +kubebuilder:validation:Optional
 	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
-	// Plugins contain a list of ApisixRoutePlugin
+	// Plugins contain a list of plugins.
 	// +kubebuilder:validation:Required
 	Plugins []ApisixRoutePlugin `json:"plugins" yaml:"plugins"`
 }
@@ -39,11 +39,12 @@ type ApisixPluginConfigStatus = ApisixStatus
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:shortName=apc
 
-// ApisixPluginConfig is the Schema for the apisixpluginconfigs API.
+// ApisixPluginConfig defines a reusable set of plugin configuration that can be referenced by routes.
 type ApisixPluginConfig struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixPluginConfigSpec defines the plugin config configuration.
 	Spec   ApisixPluginConfigSpec   `json:"spec,omitempty"`
 	Status ApisixPluginConfigStatus `json:"status,omitempty"`
 }
diff --git a/api/v2/apisixroute_types.go b/api/v2/apisixroute_types.go
index fe2db13b..5f7ef7b1 100644
--- a/api/v2/apisixroute_types.go
+++ b/api/v2/apisixroute_types.go
@@ -28,11 +28,18 @@ import (
 	"github.com/apache/apisix-ingress-controller/api/adc"
 )
 
-// ApisixRouteSpec is the spec definition for ApisixRouteSpec.
+// ApisixRouteSpec is the spec definition for ApisixRoute.
+// It defines routing rules for both HTTP and stream traffic.
 type ApisixRouteSpec struct {
-	IngressClassName string              `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
-	HTTP             []ApisixRouteHTTP   `json:"http,omitempty" yaml:"http,omitempty"`
-	Stream           []ApisixRouteStream `json:"stream,omitempty" yaml:"stream,omitempty"`
+	// IngressClassName is the name of the IngressClass this route belongs to.
+	// It allows multiple controllers to watch and reconcile different routes.
+	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
+	// HTTP defines a list of HTTP route rules.
+	// Each rule specifies conditions to match HTTP requests and how to forward them.
+	HTTP []ApisixRouteHTTP `json:"http,omitempty" yaml:"http,omitempty"`
+	// Stream defines a list of stream route rules.
+	// Each rule specifies conditions to match TCP/UDP traffic and how to forward them.
+	Stream []ApisixRouteStream `json:"stream,omitempty" yaml:"stream,omitempty"`
 }
 
 // ApisixRouteStatus defines the observed state of ApisixRoute.
@@ -48,11 +55,12 @@ type ApisixRouteStatus = ApisixStatus
 // +kubebuilder:printcolumn:name="Target Service (TCP)",type="string",JSONPath=".spec.tcp[].match.backend.serviceName",description="Backend Service for TCP",priority=1
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp",description="Creation time",priority=0
 
-// ApisixRoute is the Schema for the apisixroutes API.
+// ApisixRoute is defines configuration for HTTP and stream routes.
 type ApisixRoute struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixRouteSpec defines HTTP and stream route configuration.
 	Spec   ApisixRouteSpec   `json:"spec,omitempty"`
 	Status ApisixRouteStatus `json:"status,omitempty"`
 }
@@ -66,80 +74,88 @@ type ApisixRouteList struct {
 	Items           []ApisixRoute `json:"items"`
 }
 
-// ApisixRouteHTTP represents a single route in for HTTP traffic.
+// ApisixRouteHTTP represents a single HTTP route configuration.
 type ApisixRouteHTTP struct {
-	// The rule name, cannot be empty.
+	// Name is the unique rule name and cannot be empty.
 	Name string `json:"name" yaml:"name"`
-	// Route priority, when multiple routes contains
-	// same URI path (for path matching), route with
-	// higher priority will take effect.
-	Priority int                  `json:"priority,omitempty" yaml:"priority,omitempty"`
-	Timeout  *UpstreamTimeout     `json:"timeout,omitempty" yaml:"timeout,omitempty"`
-	Match    ApisixRouteHTTPMatch `json:"match,omitempty" yaml:"match,omitempty"`
-	// Backends represents potential backends to proxy after the route
-	// rule matched. When number of backends are more than one, traffic-split
-	// plugin in APISIX will be used to split traffic based on the backend weight.
+	// Priority defines the route priority when multiple routes share the same URI path.
+	// Higher values mean higher priority in route matching.
+	Priority int `json:"priority,omitempty" yaml:"priority,omitempty"`
+	// Timeout specifies upstream timeout settings.
+	Timeout *UpstreamTimeout `json:"timeout,omitempty" yaml:"timeout,omitempty"`
+	// Match defines the HTTP request matching criteria.
+	Match ApisixRouteHTTPMatch `json:"match,omitempty" yaml:"match,omitempty"`
+	// Backends lists potential backend services to proxy requests to.
+	// If more than one backend is specified, the `traffic-split` plugin is used
+	// to distribute traffic according to backend weights.
 	Backends []ApisixRouteHTTPBackend `json:"backends,omitempty" yaml:"backends,omitempty"`
-	// Upstreams refer to ApisixUpstream CRD
+	// Upstreams references ApisixUpstream CRDs.
 	Upstreams []ApisixRouteUpstreamReference `json:"upstreams,omitempty" yaml:"upstreams,omitempty"`
 
+	// Websocket enables or disables websocket support for this route.
 	// +kubebuilder:validation:Optional
-	Websocket        bool   `json:"websocket" yaml:"websocket"`
+	Websocket bool `json:"websocket" yaml:"websocket"`
+	// PluginConfigName specifies the name of the plugin config to apply.
 	PluginConfigName string `json:"plugin_config_name,omitempty" yaml:"plugin_config_name,omitempty"`
-	// By default, PluginConfigNamespace will be the same as the namespace of ApisixRoute
-	PluginConfigNamespace string                    `json:"plugin_config_namespace,omitempty" yaml:"plugin_config_namespace,omitempty"`
-	Plugins               []ApisixRoutePlugin       `json:"plugins,omitempty" yaml:"plugins,omitempty"`
-	Authentication        ApisixRouteAuthentication `json:"authentication,omitempty" yaml:"authentication,omitempty"`
+	// PluginConfigNamespace specifies the namespace of the plugin config.
+	// Defaults to the namespace of the ApisixRoute if not set.
+	PluginConfigNamespace string `json:"plugin_config_namespace,omitempty" yaml:"plugin_config_namespace,omitempty"`
+	// Plugins lists additional plugins applied to this route.
+	Plugins []ApisixRoutePlugin `json:"plugins,omitempty" yaml:"plugins,omitempty"`
+	// Authentication holds authentication-related configuration for this route.
+	Authentication ApisixRouteAuthentication `json:"authentication,omitempty" yaml:"authentication,omitempty"`
 }
 
-// ApisixRouteStream is the configuration for level 4 route
+// ApisixRouteStream defines the configuration for a Layer 4 (TCP/UDP) route.
 type ApisixRouteStream struct {
-	// The rule name cannot be empty.
-	Name     string                   `json:"name" yaml:"name"`
-	Protocol string                   `json:"protocol" yaml:"protocol"`
-	Match    ApisixRouteStreamMatch   `json:"match" yaml:"match"`
-	Backend  ApisixRouteStreamBackend `json:"backend" yaml:"backend"`
-	Plugins  []ApisixRoutePlugin      `json:"plugins,omitempty" yaml:"plugins,omitempty"`
+	// Name is a unique identifier for the route. This field must not be empty.
+	Name string `json:"name" yaml:"name"`
+	// Protocol specifies the L4 protocol to match. Can be `tcp` or `udp`.
+	Protocol string `json:"protocol" yaml:"protocol"`
+	// Match defines the criteria used to match incoming TCP or UDP connections.
+	Match ApisixRouteStreamMatch `json:"match" yaml:"match"`
+	// Backend specifies the destination service to which traffic should be forwarded.
+	Backend ApisixRouteStreamBackend `json:"backend" yaml:"backend"`
+	// Plugins defines a list of plugins to apply to this route.
+	Plugins []ApisixRoutePlugin `json:"plugins,omitempty" yaml:"plugins,omitempty"`
 }
 
-// UpstreamTimeout is settings for the read, send and connect to the upstream.
+// UpstreamTimeout defines timeout settings for connecting, sending, and reading from the upstream.
 type UpstreamTimeout struct {
+	// Connect timeout for establishing a connection to the upstream.
 	Connect metav1.Duration `json:"connect,omitempty" yaml:"connect,omitempty"`
-	Send    metav1.Duration `json:"send,omitempty" yaml:"send,omitempty"`
-	Read    metav1.Duration `json:"read,omitempty" yaml:"read,omitempty"`
+	// Send timeout for sending data to the upstream.
+	Send metav1.Duration `json:"send,omitempty" yaml:"send,omitempty"`
+	// Read timeout for reading data from the upstream.
+	Read metav1.Duration `json:"read,omitempty" yaml:"read,omitempty"`
 }
 
-// ApisixRouteHTTPMatch represents the match condition for hitting this route.
+// ApisixRouteHTTPMatch defines the conditions used to match incoming HTTP requests.
 type ApisixRouteHTTPMatch struct {
-	// URI path predicates, at least one path should be
-	// configured, path could be exact or prefix, for prefix path,
-	// append "*" after it, for instance, "/foo*".
+	// Paths is a list of URI path patterns to match.
+	// At least one path must be specified.
+	// Supports exact matches and prefix matches.
+	// For prefix matches, append `*` to the path, such as `/foo*`.
 	Paths []string `json:"paths" yaml:"paths"`
-	// HTTP request method predicates.
+
+	// Methods specifies the HTTP methods to match.
 	Methods []string `json:"methods,omitempty" yaml:"methods,omitempty"`
-	// HTTP Host predicates, host can be a wildcard domain or
-	// an exact domain. For wildcard domain, only one generic
-	// level is allowed, for instance, "*.foo.com" is valid but
-	// "*.*.foo.com" is not.
+
+	// Hosts specifies Host header values to match.
+	// Supports exact and wildcard domains.
+	// Only one level of wildcard is allowed (e.g., `*.example.com` is valid,
+	// but `*.*.example.com` is not).
 	Hosts []string `json:"hosts,omitempty" yaml:"hosts,omitempty"`
-	// Remote address predicates, items can be valid IPv4 address
-	// or IPv6 address or CIDR.
+
+	// RemoteAddrs is a list of source IP addresses or CIDR ranges to match.
+	// Supports both IPv4 and IPv6 formats.
 	RemoteAddrs []string `json:"remoteAddrs,omitempty" yaml:"remoteAddrs,omitempty"`
-	// NginxVars represents generic match predicates,
-	// it uses Nginx variable systems, so any predicate
-	// like headers, querystring and etc can be leveraged
-	// here to match the route.
-	// For instance, it can be:
-	// nginxVars:
-	//   - subject: "$remote_addr"
-	//     op: in
-	//     value:
-	//       - "127.0.0.1"
-	//       - "10.0.5.11"
+
+	// NginxVars defines match conditions based on Nginx variables.
 	NginxVars ApisixRouteHTTPMatchExprs `json:"exprs,omitempty" yaml:"exprs,omitempty"`
-	// Matches based on a user-defined filtering function.
-	// These functions can accept an input parameter `vars`
-	// which can be used to access the Nginx variables.
+
+	// FilterFunc is a user-defined function for advanced request filtering.
+	// The function can use Nginx variables through the `vars` parameter.
 	FilterFunc string `json:"filter_func,omitempty" yaml:"filter_func,omitempty"`
 }
 
@@ -158,84 +174,99 @@ type ApisixRoutePlugin struct {
 	SecretRef string `json:"secretRef" yaml:"secretRef"`
 }
 
-// ApisixRouteHTTPBackend represents an HTTP backend (a Kubernetes Service).
+// ApisixRouteHTTPBackend represents an HTTP backend (Kubernetes Service).
 type ApisixRouteHTTPBackend struct {
-	// The name (short) of the service, note cross namespace is forbidden,
-	// so be sure the ApisixRoute and Service are in the same namespace.
+	// ServiceName is the name of the Kubernetes Service.
+	// Cross-namespace references are not supported—ensure the ApisixRoute
+	// and the Service are in the same namespace.
 	ServiceName string `json:"serviceName" yaml:"serviceName"`
-	// The service port, could be the name or the port number.
+	// ServicePort is the port of the Kubernetes Service.
+	// This can be either the port name or port number.
 	ServicePort intstr.IntOrString `json:"servicePort" yaml:"servicePort"`
-	// The resolve granularity, can be "endpoints" or "service",
-	// when set to "endpoints", the pod ips will be used; other
-	// wise, the service ClusterIP or ExternalIP will be used,
-	// default is endpoints.
+	// ResolveGranularity determines how the backend service is resolved.
+	// Valid values are `endpoints` and `service`. When set to `endpoints`,
+	// individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used.
+	// The default is `endpoints`.
 	ResolveGranularity string `json:"resolveGranularity,omitempty" yaml:"resolveGranularity,omitempty"`
-	// Weight of this backend.
+	// Weight specifies the relative traffic weight for this backend.
 	// +kubebuilder:validation:Optional
 	Weight *int `json:"weight" yaml:"weight"`
-	// Subset specifies a subset for the target Service. The subset should be pre-defined
-	// in ApisixUpstream about this service.
+	// Subset specifies a named subset of the target Service.
+	// The subset must be pre-defined in the corresponding ApisixUpstream resource.
 	Subset string `json:"subset,omitempty" yaml:"subset,omitempty"`
 }
 
-// ApisixRouteUpstreamReference contains a ApisixUpstream CRD reference
+// ApisixRouteUpstreamReference references an ApisixUpstream CRD to be used as a backend.
+// It can be used in traffic-splitting scenarios or to select a specific upstream configuration.
 type ApisixRouteUpstreamReference struct {
+	// Name is the name of the ApisixUpstream resource.
 	Name string `json:"name,omitempty" yaml:"name"`
+	// Weight is the weight assigned to this upstream.
 	// +kubebuilder:validation:Optional
 	Weight *int `json:"weight,omitempty" yaml:"weight"`
 }
 
-// ApisixRouteAuthentication is the authentication-related
-// configuration in ApisixRoute.
+// ApisixRouteAuthentication represents authentication-related configuration in ApisixRoute.
 type ApisixRouteAuthentication struct {
-	Enable   bool                              `json:"enable" yaml:"enable"`
-	Type     string                            `json:"type" yaml:"type"`
-	KeyAuth  ApisixRouteAuthenticationKeyAuth  `json:"keyAuth,omitempty" yaml:"keyAuth,omitempty"`
-	JwtAuth  ApisixRouteAuthenticationJwtAuth  `json:"jwtAuth,omitempty" yaml:"jwtAuth,omitempty"`
+	// Enable toggles authentication on or off.
+	Enable bool `json:"enable" yaml:"enable"`
+	// Type specifies the authentication type.
+	Type string `json:"type" yaml:"type"`
+	// KeyAuth defines configuration for key authentication.
+	KeyAuth ApisixRouteAuthenticationKeyAuth `json:"keyAuth,omitempty" yaml:"keyAuth,omitempty"`
+	// JwtAuth defines configuration for JWT authentication.
+	JwtAuth ApisixRouteAuthenticationJwtAuth `json:"jwtAuth,omitempty" yaml:"jwtAuth,omitempty"`
+	// LDAPAuth defines configuration for LDAP authentication.
 	LDAPAuth ApisixRouteAuthenticationLDAPAuth `json:"ldapAuth,omitempty" yaml:"ldapAuth,omitempty"`
 }
 
-// ApisixRouteStreamMatch represents the match conditions of stream route.
+// ApisixRouteStreamMatch represents the matching conditions for a stream route.
 type ApisixRouteStreamMatch struct {
-	// IngressPort represents the port listening on the Ingress proxy server.
-	// It should be pre-defined as APISIX doesn't support dynamic listening.
-	IngressPort int32  `json:"ingressPort" yaml:"ingressPort"`
-	Host        string `json:"host,omitempty" yaml:"host,omitempty"`
+	// IngressPort is the port on which the APISIX Ingress proxy server listens.
+	// This must be a statically configured port, as APISIX does not support dynamic port binding.
+	IngressPort int32 `json:"ingressPort" yaml:"ingressPort"`
+	// Host is the destination host address used to match the incoming TCP/UDP traffic.
+	Host string `json:"host,omitempty" yaml:"host,omitempty"`
 }
 
-// ApisixRouteStreamBackend represents a TCP backend (a Kubernetes Service).
+// ApisixRouteStreamBackend represents the backend service for a TCP or UDP stream route.
 type ApisixRouteStreamBackend struct {
-	// The name (short) of the service, note cross namespace is forbidden,
-	// so be sure the ApisixRoute and Service are in the same namespace.
+	// ServiceName is the name of the Kubernetes Service.
+	// Cross-namespace references are not supported—ensure the ApisixRoute
+	// and the Service are in the same namespace.
 	ServiceName string `json:"serviceName" yaml:"serviceName"`
-	// The service port, could be the name or the port number.
+	// ServicePort is the port of the Kubernetes Service.
+	// This can be either the port name or port number.
 	ServicePort intstr.IntOrString `json:"servicePort" yaml:"servicePort"`
-	// The resolve granularity, can be "endpoints" or "service",
-	// when set to "endpoints", the pod ips will be used; other
-	// wise, the service ClusterIP or ExternalIP will be used,
-	// default is endpoints.
+	// ResolveGranularity determines how the backend service is resolved.
+	// Valid values are `endpoints` and `service`. When set to `endpoints`,
+	// individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used.
+	// The default is `endpoints`.
 	ResolveGranularity string `json:"resolveGranularity,omitempty" yaml:"resolveGranularity,omitempty"`
-	// Subset specifies a subset for the target Service. The subset should be pre-defined
-	// in ApisixUpstream about this service.
+	// Subset specifies a named subset of the target Service.
+	// The subset must be pre-defined in the corresponding ApisixUpstream resource.
 	Subset string `json:"subset,omitempty" yaml:"subset,omitempty"`
 }
 
-// ApisixRouteHTTPMatchExpr represents a binary route match expression .
+// ApisixRouteHTTPMatchExpr represents a binary expression used to match requests based on Nginx variables.
 type ApisixRouteHTTPMatchExpr struct {
-	// Subject is the expression subject, it can
-	// be any string composed by literals and nginx
-	// vars.
+	// Subject defines the left-hand side of the expression.
+	// It can be any [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable) or string literal.
 	Subject ApisixRouteHTTPMatchExprSubject `json:"subject" yaml:"subject"`
-	// Op is the operator.
+
+	// Op specifies the operator used in the expression.
+	// Can be `Equal`, `NotEqual`, `GreaterThan`, `GreaterThanEqual`, `LessThan`, `LessThanEqual`, `RegexMatch`,
+	// `RegexNotMatch`, `RegexMatchCaseInsensitive`, `RegexNotMatchCaseInsensitive`, `In`, or `NotIn`.
 	Op string `json:"op" yaml:"op"`
-	// Set is an array type object of the expression.
-	// It should be used when the Op is "in" or "not_in";
+
+	// Set provides a list of acceptable values for the expression.
+	// This should be used when Op is `In` or `NotIn`.
 	// +kubebuilder:validation:Optional
 	Set []string `json:"set" yaml:"set"`
-	// Value is the normal type object for the expression,
-	// it should be used when the Op is not "in" and "not_in".
-	// Set and Value are exclusive so only of them can be set
-	// in the same time.
+
+	// Value defines a single value to compare against the subject.
+	// This should be used when Op is not `In` or `NotIn`.
+	// Set and Value are mutually exclusive—only one should be set at a time.
 	// +kubebuilder:validation:Optional
 	Value *string `json:"value" yaml:"value"`
 }
@@ -335,37 +366,40 @@ func (exprs ApisixRouteHTTPMatchExprs) ToVars() (result adc.Vars, err error) {
 // any plugins.
 type ApisixRoutePluginConfig map[string]apiextensionsv1.JSON
 
-// ApisixRouteAuthenticationKeyAuth is the keyAuth-related
-// configuration in ApisixRouteAuthentication.
+// ApisixRouteAuthenticationKeyAuth defines key authentication configuration in ApisixRouteAuthentication.
 type ApisixRouteAuthenticationKeyAuth struct {
+	// Header specifies the HTTP header name to look for the key authentication token.
 	Header string `json:"header,omitempty" yaml:"header,omitempty"`
 }
 
-// ApisixRouteAuthenticationJwtAuth is the jwt auth related
-// configuration in ApisixRouteAuthentication.
+// ApisixRouteAuthenticationJwtAuth defines JWT authentication configuration in ApisixRouteAuthentication.
 type ApisixRouteAuthenticationJwtAuth struct {
+	// Header specifies the HTTP header name to look for the JWT token.
 	Header string `json:"header,omitempty" yaml:"header,omitempty"`
-	Query  string `json:"query,omitempty" yaml:"query,omitempty"`
+	// Query specifies the URL query parameter name to look for the JWT token.
+	Query string `json:"query,omitempty" yaml:"query,omitempty"`
+	// Cookie specifies the cookie name to look for the JWT token.
 	Cookie string `json:"cookie,omitempty" yaml:"cookie,omitempty"`
 }
 
-// ApisixRouteAuthenticationLDAPAuth is the LDAP auth related
-// configuration in ApisixRouteAuthentication.
+// ApisixRouteAuthenticationLDAPAuth defines LDAP authentication configuration in ApisixRouteAuthentication.
 type ApisixRouteAuthenticationLDAPAuth struct {
-	BaseDN  string `json:"base_dn,omitempty" yaml:"base_dn,omitempty"`
+	// BaseDN is the base distinguished name (DN) for LDAP searches.
+	BaseDN string `json:"base_dn,omitempty" yaml:"base_dn,omitempty"`
+	// LDAPURI is the URI of the LDAP server.
 	LDAPURI string `json:"ldap_uri,omitempty" yaml:"ldap_uri,omitempty"`
-	UseTLS  bool   `json:"use_tls,omitempty" yaml:"use_tls,omitempty"`
-	UID     string `json:"uid,omitempty" yaml:"uid,omitempty"`
+	// UseTLS indicates whether to use TLS for the LDAP connection.
+	UseTLS bool `json:"use_tls,omitempty" yaml:"use_tls,omitempty"`
+	// UID is the user identifier attribute in LDAP.
+	UID string `json:"uid,omitempty" yaml:"uid,omitempty"`
 }
 
-// ApisixRouteHTTPMatchExprSubject describes the route match expression subject.
+// ApisixRouteHTTPMatchExprSubject describes the subject of a route matching expression.
 type ApisixRouteHTTPMatchExprSubject struct {
-	// The subject scope, can be:
-	// ScopeQuery, ScopeHeader, ScopePath
-	// when subject is ScopePath, Name field
-	// will be ignored.
+	// Scope specifies the subject scope and can be `Header`, `Query`, or `Path`.
+	// When Scope is `Path`, Name will be ignored.
 	Scope string `json:"scope" yaml:"scope"`
-	// The name of subject.
+	// Name is the name of the header or query parameter.
 	Name string `json:"name" yaml:"name"`
 }
 
diff --git a/api/v2/apisixtls_types.go b/api/v2/apisixtls_types.go
index 62f24fbb..31c80ff7 100644
--- a/api/v2/apisixtls_types.go
+++ b/api/v2/apisixtls_types.go
@@ -21,18 +21,24 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// ApisixTlsSpec defines the desired state of ApisixTls.
+// ApisixTlsSpec defines configurations for TLS and mutual TLS.
 type ApisixTlsSpec struct {
-	// IngressClassName is the name of an IngressClass cluster resource.
-	// controller implementations use this field to know whether they should be
-	// serving this ApisixTls resource, by a transitive connection
-	// (controller -> IngressClass -> ApisixTls resource).
+	// IngressClassName specifies which IngressClass this resource is associated with.
+	// The APISIX controller only processes this resource if the class matches its own.
 	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
+
+	// Hosts lists the SNI (Server Name Indication) hostnames that this TLS configuration applies to.
+	// Must contain at least one host.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinItems=1
 	Hosts []HostType `json:"hosts" yaml:"hosts,omitempty"`
+
+	// Secret refers to the Kubernetes TLS secret containing the certificate and private key.
+	// This secret must exist in the specified namespace and contain valid TLS data.
 	// +kubebuilder:validation:Required
-	Secret ApisixSecret                 `json:"secret" yaml:"secret"`
+	Secret ApisixSecret `json:"secret" yaml:"secret"`
+
+	// Client defines mutual TLS (mTLS) settings, such as the CA certificate and verification depth.
 	Client *ApisixMutualTlsClientConfig `json:"client,omitempty" yaml:"client,omitempty"`
 }
 
@@ -49,11 +55,12 @@ type ApisixTlsStatus = ApisixStatus
 // +kubebuilder:printcolumn:name="Client CA Secret Name",type=string,JSONPath=`.spec.client.ca.name`
 // +kubebuilder:printcolumn:name="Client CA Secret Namespace",type=string,JSONPath=`.spec.client.ca.namespace`
 
-// ApisixTls is the Schema for the apisixtls API.
+// ApisixTls defines configuration for TLS and mutual TLS (mTLS).
 type ApisixTls struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixTlsSpec defines the TLS configuration.
 	Spec   ApisixTlsSpec   `json:"spec,omitempty"`
 	Status ApisixTlsStatus `json:"status,omitempty"`
 }
@@ -70,21 +77,27 @@ type ApisixTlsList struct {
 // +kubebuilder:validation:Pattern="^\\*?[0-9a-zA-Z-.]+$"
 type HostType string
 
-// ApisixSecret describes the Kubernetes Secret name and namespace.
+// ApisixSecret describes a reference to a Kubernetes Secret, including its name and namespace.
+// This is used to locate secrets such as certificates or credentials for plugins or TLS configuration.
 type ApisixSecret struct {
+	// Name is the name of the Kubernetes Secret.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:Required
 	Name string `json:"name" yaml:"name"`
+	// Namespace is the namespace where the Kubernetes Secret is located.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:Required
 	Namespace string `json:"namespace" yaml:"namespace"`
 }
 
-// ApisixMutualTlsClientConfig describes the mutual TLS CA and verify depth
+// ApisixMutualTlsClientConfig describes the mutual TLS CA and verification settings.
 type ApisixMutualTlsClientConfig struct {
-	CASecret         ApisixSecret `json:"caSecret,omitempty" yaml:"caSecret,omitempty"`
-	Depth            int          `json:"depth,omitempty" yaml:"depth,omitempty"`
-	SkipMTLSUriRegex []string     `json:"skip_mtls_uri_regex,omitempty" yaml:"skip_mtls_uri_regex,omitempty"`
+	// CASecret references the secret containing the CA certificate for client certificate validation.
+	CASecret ApisixSecret `json:"caSecret,omitempty" yaml:"caSecret,omitempty"`
+	// Depth specifies the maximum verification depth for the client certificate chain.
+	Depth int `json:"depth,omitempty" yaml:"depth,omitempty"`
+	// SkipMTLSUriRegex contains RegEx patterns for URIs to skip mutual TLS verification.
+	SkipMTLSUriRegex []string `json:"skip_mtls_uri_regex,omitempty" yaml:"skip_mtls_uri_regex,omitempty"`
 }
 
 func init() {
diff --git a/api/v2/apisixupstream_types.go b/api/v2/apisixupstream_types.go
index 7354c81b..38b41c62 100644
--- a/api/v2/apisixupstream_types.go
+++ b/api/v2/apisixupstream_types.go
@@ -23,22 +23,29 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// ApisixUpstreamSpec describes the specification of ApisixUpstream.
+// ApisixUpstreamSpec describes the desired configuration of an ApisixUpstream resource.
+// It defines how traffic should be routed to backend services, including upstream node
+// definitions and custom configuration.
 type ApisixUpstreamSpec struct {
 	// IngressClassName is the name of an IngressClass cluster resource.
-	// controller implementations use this field to know whether they should be
-	// serving this ApisixUpstream resource, by a transitive connection
-	// (controller -> IngressClass -> ApisixUpstream resource).
+	// Controller implementations use this field to determine whether they
+	// should process this ApisixUpstream resource.
 	// +kubebuilder:validation:Optional
 	IngressClassName string `json:"ingressClassName,omitempty" yaml:"ingressClassName,omitempty"`
-	// ExternalNodes contains external nodes the Upstream should use
-	// If this field is set, the upstream will use these nodes directly without any further resolves
+
+	// ExternalNodes defines a static list of backend nodes located outside the cluster.
+	// When this field is set, the upstream will route traffic directly to these nodes
+	// without DNS resolution or service discovery.
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinItems=1
 	ExternalNodes []ApisixUpstreamExternalNode `json:"externalNodes,omitempty" yaml:"externalNodes,omitempty"`
 
+	// ApisixUpstreamConfig holds the core upstream configuration, such as load balancing,
+	// health checks, retries, and TLS settings. This struct is inlined for simplicity.
 	ApisixUpstreamConfig `json:",inline" yaml:",inline"`
 
+	// PortLevelSettings allows fine-grained upstream configuration for specific ports,
+	// useful when a backend service exposes multiple ports with different behaviors or protocols.
 	PortLevelSettings []PortLevelSettings `json:"portLevelSettings,omitempty" yaml:"portLevelSettings,omitempty"`
 }
 
@@ -49,11 +56,12 @@ type ApisixUpstreamStatus = ApisixStatus
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:shortName=au
 
-// ApisixUpstream is the Schema for the apisixupstreams API.
+// ApisixUpstream defines configuration for upstream services.
 type ApisixUpstream struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// ApisixUpstreamSpec defines the upstream configuration.
 	Spec   ApisixUpstreamSpec   `json:"spec,omitempty"`
 	Status ApisixUpstreamStatus `json:"status,omitempty"`
 }
@@ -67,97 +75,124 @@ type ApisixUpstreamList struct {
 	Items           []ApisixUpstream `json:"items"`
 }
 
-// ApisixUpstreamExternalNode is the external node conf
+// ApisixUpstreamExternalNode defines configuration for an external upstream node.
+// This allows referencing services outside the cluster.
 type ApisixUpstreamExternalNode struct {
-	Name string                     `json:"name,omitempty" yaml:"name"`
+	// Name is the hostname or IP address of the external node.
+	Name string `json:"name,omitempty" yaml:"name"`
+
+	// Type indicates the kind of external node. Can be `Domain`, or `Service`.
 	Type ApisixUpstreamExternalType `json:"type,omitempty" yaml:"type"`
+
+	// Weight defines the load balancing weight of this node.
+	// Higher values increase the share of traffic sent to this node.
 	// +kubebuilder:validation:Optional
 	Weight *int `json:"weight,omitempty" yaml:"weight"`
-	// Port defines the port of the external node
+
+	// Port specifies the port number on which the external node is accepting traffic.
 	// +kubebuilder:validation:Optional
 	Port *int `json:"port,omitempty" yaml:"port"`
 }
 
-// ApisixUpstreamConfig contains rich features on APISIX Upstream, for instance
-// load balancer, health check, etc.
+// ApisixUpstreamConfig defines configuration for upstream services.
 type ApisixUpstreamConfig struct {
-	// LoadBalancer represents the load balancer configuration for Kubernetes Service.
-	// The default strategy is round robin.
+	// LoadBalancer specifies the load balancer configuration for Kubernetes Service.
 	// +kubebuilder:validation:Optional
 	LoadBalancer *LoadBalancer `json:"loadbalancer,omitempty" yaml:"loadbalancer,omitempty"`
-	// The scheme used to talk with the upstream.
-	// Now value can be http, grpc.
+
+	// Scheme is the protocol used to communicate with the upstream.
+	// Default is `http`.
+	// Can be `http`, `https`, `grpc`, or `grpcs`.
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:Enum=http;https;grpc;grpcs;
 	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 defines the number of retry attempts APISIX should make when a failure occurs.
+	// Failures include timeouts, network errors, or 5xx status codes.
 	// +kubebuilder:validation:Optional
 	Retries *int64 `json:"retries,omitempty" yaml:"retries,omitempty"`
 
-	// Timeout settings for the read, send and connect to the upstream.
+	// Timeout specifies the connection, send, and read timeouts for upstream requests.
 	// +kubebuilder:validation:Optional
 	Timeout *UpstreamTimeout `json:"timeout,omitempty" yaml:"timeout,omitempty"`
 
-	// Deprecated: this is no longer support on standalone mode.
-	// The health check configurations for the upstream.
+	// HealthCheck defines the active and passive health check configuration for the upstream.
+	// Deprecated: no longer supported in standalone mode.
 	// +kubebuilder:validation:Optional
 	HealthCheck *HealthCheck `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`
 
-	// Set the client certificate when connecting to TLS upstream.
+	// TLSSecret references a Kubernetes Secret that contains the client certificate and key
+	// for mutual TLS when connecting to the upstream.
 	// +kubebuilder:validation:Optional
 	TLSSecret *ApisixSecret `json:"tlsSecret,omitempty" yaml:"tlsSecret,omitempty"`
 
-	// Subsets groups the service endpoints by their labels. Usually used to differentiate
-	// service versions.
+	// Subsets defines labeled subsets of service endpoints, typically used for
+	// service versioning or canary deployments.
 	// +kubebuilder:validation:Optional
 	Subsets []ApisixUpstreamSubset `json:"subsets,omitempty" yaml:"subsets,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 `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:Optional
 	// +kubebuilder:validation:Enum=pass;node;rewrite;
 	PassHost string `json:"passHost,omitempty" yaml:"passHost,omitempty"`
 
-	// Specifies the host of the Upstream request. This is only valid if
-	// the pass_host is set to rewrite
+	// UpstreamHost sets a custom Host header when passHost is set to `rewrite`.
 	// +kubebuilder:validation:Optional
 	UpstreamHost string `json:"upstreamHost,omitempty" yaml:"upstreamHost,omitempty"`
 
-	// Deprecated: this is no longer support on standalone mode.
-	// Discovery is used to configure service discovery for upstream.
+	// Discovery configures service discovery for the upstream.
+	// Deprecated: no longer supported in standalone mode.
 	// +kubebuilder:validation:Optional
 	Discovery *Discovery `json:"discovery,omitempty" yaml:"discovery,omitempty"`
 }
 
 // PortLevelSettings configures the ApisixUpstreamConfig for each individual port. It inherits
-// configurations from the outer level (the whole Kubernetes Service) and overrides some of
+// configuration from the outer level (the whole Kubernetes Service) and overrides some of
 // them if they are set on the port level.
 type PortLevelSettings struct {
 	ApisixUpstreamConfig `json:",inline" yaml:",inline"`
 
-	// Port is a Kubernetes Service port, it should be already defined.
+	// Port is a Kubernetes Service port.
 	Port int32 `json:"port" yaml:"port"`
 }
 
 // ApisixUpstreamExternalType is the external service type
 type ApisixUpstreamExternalType string
 
-// LoadBalancer describes the load balancing parameters.
+// LoadBalancer defines the load balancing strategy for distributing traffic across upstream nodes.
 type LoadBalancer struct {
+	// Type specifies the load balancing algorithms to route traffic to the backend.
+	// Default is `roundrobin`.
+	// Can be `roundrobin`, `chash`, `ewma`, or `least_conn`.
+	// +kubebuilder:validation:Enum=roundrobin;chash;ewma;least_conn;
+	// +kubebuilder:default=roundrobin
 	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 `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
+	// [APISIX variables](https://apisix.apache.org/docs/apisix/apisix-variable).
 	Key string `json:"key,omitempty" yaml:"key,omitempty"`
 }
 
-// HealthCheck describes the upstream health check parameters.
+// HealthCheck defines the health check configuration for upstream nodes.
+// It includes active checks (proactively probing the nodes) and optional passive checks (monitoring based on traffic).
 type HealthCheck struct {
+	// Active health checks proactively send requests to upstream nodes to determine their availability.
 	// +kubebuilder:validation:Required
 	Active *ActiveHealthCheck `json:"active" yaml:"active"`
+	// Passive health checks evaluate upstream health based on observed traffic, such as timeouts or errors.
 	// +kubebuilder:validation:Optional
 	Passive *PassiveHealthCheck `json:"passive,omitempty" yaml:"passive,omitempty"`
 }
@@ -170,81 +205,105 @@ type ApisixUpstreamSubset struct {
 	Labels map[string]string `json:"labels" yaml:"labels"`
 }
 
-// Discovery defines Service discovery related configuration.
+// Discovery defines the service discovery configuration for dynamically resolving upstream nodes.
+// This is used when APISIX integrates with a service registry such as Nacos, Consul, or Eureka.
 type Discovery struct {
+	// ServiceName is the name of the service to discover.
 	ServiceName string `json:"serviceName" yaml:"serviceName"`
-	Type        string `json:"type" yaml:"type"`
+	// Type is the name of the service discovery provider.
+	Type string `json:"type" yaml:"type"`
+	// Args contains additional configuration parameters required by the discovery provider.
+	// These are passed as key-value pairs.
 	// +kubebuilder:validation:Optional
 	Args map[string]string `json:"args,omitempty" yaml:"args,omitempty"`
 }
 
-// ActiveHealthCheck defines the active kind of upstream health check.
+// ActiveHealthCheck defines the active upstream health check configuration.
 type ActiveHealthCheck struct {
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:Enum=http;https;tcp;
-	Type    string        `json:"type,omitempty" yaml:"type,omitempty"`
+	// Type is the health check type. Can be `http`, `https`, or `tcp`.
+	Type string `json:"type,omitempty" yaml:"type,omitempty"`
+	// Timeout sets health check timeout in seconds.
 	Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
 	// +kubebuilder:validation:Minimum=0
-	Concurrency int    `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
-	Host        string `json:"host,omitempty" yaml:"host,omitempty"`
+	// Concurrency sets the number of targets to be checked at the same time.
+	Concurrency int `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
+	// Host sets the upstream host.
+	Host string `json:"host,omitempty" yaml:"host,omitempty"`
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=65535
-	Port           int32                       `json:"port,omitempty" yaml:"port,omitempty"`
-	HTTPPath       string                      `json:"httpPath,omitempty" yaml:"httpPath,omitempty"`
-	StrictTLS      *bool                       `json:"strictTLS,omitempty" yaml:"strictTLS,omitempty"`
-	RequestHeaders []string                    `json:"requestHeaders,omitempty" yaml:"requestHeaders,omitempty"`
-	Healthy        *ActiveHealthCheckHealthy   `json:"healthy,omitempty" yaml:"healthy,omitempty"`
-	Unhealthy      *ActiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
+	// Port sets the upstream port.
+	Port int32 `json:"port,omitempty" yaml:"port,omitempty"`
+	// HTTPPath sets the HTTP probe request path.
+	HTTPPath string `json:"httpPath,omitempty" yaml:"httpPath,omitempty"`
+	// StrictTLS sets whether to enforce TLS.
+	StrictTLS *bool `json:"strictTLS,omitempty" yaml:"strictTLS,omitempty"`
+	// RequestHeaders sets the request headers.
+	RequestHeaders []string `json:"requestHeaders,omitempty" yaml:"requestHeaders,omitempty"`
+	// Healthy configures the rules that define an upstream node as healthy.
+	Healthy *ActiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+	// Unhealthy configures the rules that define an upstream node as unhealthy.
+	Unhealthy *ActiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
 }
 
-// PassiveHealthCheck defines the conditions to judge whether
-// an upstream node is healthy with the passive manager.
+// PassiveHealthCheck defines the conditions used to determine whether
+// an upstream node is healthy or unhealthy based on passive observations.
+// Passive health checks rely on real traffic responses instead of active probes.
 type PassiveHealthCheck struct {
-	Type      string                       `json:"type,omitempty" yaml:"type,omitempty"`
-	Healthy   *PassiveHealthCheckHealthy   `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+	// Type specifies the type of passive health check.
+	// Can be `http`, `https`, or `tcp`.
+	Type string `json:"type,omitempty" yaml:"type,omitempty"`
+	// Healthy defines the conditions under which an upstream node is considered healthy.
+	Healthy *PassiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+	// Unhealthy defines the conditions under which an upstream node is considered unhealthy.
 	Unhealthy *PassiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
 }
 
-// ActiveHealthCheckHealthy 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.
 type ActiveHealthCheckHealthy struct {
 	PassiveHealthCheckHealthy `json:",inline" yaml:",inline"`
 
+	// Interval defines the time interval for checking targets, in seconds.
 	Interval metav1.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`
 }
 
-// ActiveHealthCheckUnhealthy 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.
 type ActiveHealthCheckUnhealthy struct {
 	PassiveHealthCheckUnhealthy `json:",inline" yaml:",inline"`
 
+	// Interval defines the time interval for checking targets, in seconds.
 	Interval metav1.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`
 }
 
-// PassiveHealthCheckHealthy defines the conditions to judge whether
-// an upstream node is healthy with the passive manner.
+// PassiveHealthCheckHealthy defines the conditions used to passively determine whether an upstream node is healthy.
 type PassiveHealthCheckHealthy struct {
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinItems=1
+	// HTTPCodes define a list of HTTP status codes that are considered healthy.
 	HTTPCodes []int `json:"httpCodes,omitempty" yaml:"httpCodes,omitempty"`
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=254
+	// Successes define the number of successful probes to define a healthy target.
 	Successes int `json:"successes,omitempty" yaml:"successes,omitempty"`
 }
 
-// PassiveHealthCheckUnhealthy 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.
 type PassiveHealthCheckUnhealthy struct {
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MinItems=1
+	// HTTPCodes define a list of HTTP status codes that are considered unhealthy.
 	HTTPCodes []int `json:"httpCodes,omitempty" yaml:"httpCodes,omitempty"`
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=254
+	// HTTPFailures define the number of HTTP failures to define an unhealthy target.
 	HTTPFailures int `json:"httpFailures,omitempty" yaml:"http_failures,omitempty"`
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=254
+	// TCPFailures define the number of TCP failures to define an unhealthy target.
 	TCPFailures int `json:"tcpFailures,omitempty" yaml:"tcpFailures,omitempty"`
-	Timeouts    int `json:"timeout,omitempty" yaml:"timeout,omitempty"`
+	// Timeout sets health check timeout in seconds.
+	Timeouts int `json:"timeout,omitempty" yaml:"timeout,omitempty"`
 }
 
 func init() {
diff --git a/api/v2/shared_types.go b/api/v2/shared_types.go
index 949d1b98..8ea57efa 100644
--- a/api/v2/shared_types.go
+++ b/api/v2/shared_types.go
@@ -68,7 +68,7 @@ const (
 	OpRegexNotMatchCaseInsensitive = "RegexNotMatchCaseInsensitive"
 	// OpIn means the in operator ("in") in nginxVars.
 	OpIn = "In"
-	// OpNotIn means the not in operator ("not_in") in nginxVars.
+	// OpNotIn means the not in operator ("NotIn") in nginxVars.
 	OpNotIn = "NotIn"
 
 	// ScopeQuery means the route match expression subject is in the querystring.
diff --git a/config/crd/bases/apisix.apache.org_apisixconsumers.yaml b/config/crd/bases/apisix.apache.org_apisixconsumers.yaml
index b8ffd734..ed40241b 100644
--- a/config/crd/bases/apisix.apache.org_apisixconsumers.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixconsumers.yaml
@@ -19,7 +19,8 @@ spec:
   - name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixConsumer is the Schema for the apisixconsumers API.
+        description: ApisixConsumer defines configuration of a consumer and their
+          authentication details.
         properties:
           apiVersion:
             description: |-
@@ -39,18 +40,18 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixConsumerSpec defines the desired state of ApisixConsumer.
+            description: ApisixConsumerSpec defines the consumer authentication configuration.
             properties:
               authParameter:
+                description: AuthParameter defines the authentication credentials
+                  and configuration for this consumer.
                 properties:
                   basicAuth:
-                    description: ApisixConsumerBasicAuth defines the configuration
-                      for basic auth.
+                    description: BasicAuth configures the basic authentication details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          the basic authentication credentials.
                         properties:
                           name:
                             default: ""
@@ -64,12 +65,13 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerBasicAuthValue defines the in-place
-                          username and password configuration for basic auth.
+                        description: Value specifies the basic authentication credentials.
                         properties:
                           password:
+                            description: Password is the basic authentication password.
                             type: string
                           username:
+                            description: Username is the basic authentication username.
                             type: string
                         required:
                         - password
@@ -77,13 +79,11 @@ spec:
                         type: object
                     type: object
                   hmacAuth:
-                    description: ApisixConsumerHMACAuth defines the configuration
-                      for the hmac auth.
+                    description: HMACAuth configures the HMAC authentication details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          the HMAC credentials.
                         properties:
                           name:
                             default: ""
@@ -97,30 +97,47 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerHMACAuthValue defines the in-place
-                          configuration for hmac auth.
+                        description: Value specifies HMAC authentication credentials.
                         properties:
                           access_key:
+                            description: AccessKey is the identifier used to look
+                              up the HMAC secret.
                             type: string
                           algorithm:
+                            description: Algorithm specifies the hashing algorithm
+                              (e.g., "hmac-sha256").
                             type: string
                           clock_skew:
+                            description: ClockSkew is the allowed time difference
+                              (in seconds) between client and server clocks.
                             format: int64
                             type: integer
                           encode_uri_params:
+                            description: EncodeURIParams indicates whether URI parameters
+                              are encoded when calculating the signature.
                             type: boolean
                           keep_headers:
+                            description: KeepHeaders determines whether the HMAC signature
+                              headers are preserved after verification.
                             type: boolean
                           max_req_body:
+                            description: MaxReqBody sets the maximum size (in bytes)
+                              of the request body that can be validated.
                             format: int64
                             type: integer
                           secret_key:
+                            description: SecretKey is the HMAC secret used to sign
+                              the request.
                             type: string
                           signed_headers:
+                            description: SignedHeaders lists the headers that must
+                              be included in the signature.
                             items:
                               type: string
                             type: array
                           validate_request_body:
+                            description: ValidateRequestBody enables HMAC validation
+                              of the request body.
                             type: boolean
                         required:
                         - access_key
@@ -128,13 +145,11 @@ spec:
                         type: object
                     type: object
                   jwtAuth:
-                    description: ApisixConsumerJwtAuth defines the configuration for
-                      the jwt auth.
+                    description: JwtAuth configures the JWT authentication details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          JWT authentication credentials.
                         properties:
                           name:
                             default: ""
@@ -148,26 +163,41 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerJwtAuthValue defines the in-place
-                          configuration for jwt auth.
+                        description: Value specifies JWT authentication credentials.
                         properties:
                           algorithm:
+                            description: |-
+                              Algorithm specifies the signing algorithm.
+                              Can be `HS256`, `HS512`, `RS256`, or `ES256`.
                             type: string
                           base64_secret:
+                            description: Base64Secret indicates whether the secret
+                              is base64-encoded.
                             type: boolean
                           exp:
+                            description: Exp is the token expiration period in seconds.
                             format: int64
                             type: integer
                           key:
+                            description: Key is the unique identifier for the JWT
+                              credential.
                             type: string
                           lifetime_grace_period:
+                            description: LifetimeGracePeriod is the allowed clock
+                              skew in seconds for token expiration.
                             format: int64
                             type: integer
                           private_key:
+                            description: PrivateKey is the private key used to sign
+                              the JWT (for asymmetric algorithms).
                             type: string
                           public_key:
+                            description: PublicKey is the public key used to verify
+                              JWT signatures (for asymmetric algorithms).
                             type: string
                           secret:
+                            description: Secret is the shared secret used to sign
+                              the JWT (for symmetric algorithms).
                             type: string
                         required:
                         - key
@@ -175,13 +205,11 @@ spec:
                         type: object
                     type: object
                   keyAuth:
-                    description: ApisixConsumerKeyAuth defines the configuration for
-                      the key auth.
+                    description: KeyAuth configures the key authentication details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          the key authentication credentials.
                         properties:
                           name:
                             default: ""
@@ -195,23 +223,21 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerKeyAuthValue defines the in-place
-                          configuration for basic auth.
+                        description: Value specifies the key authentication credentials.
                         properties:
                           key:
+                            description: Key is the credential used for key authentication.
                             type: string
                         required:
                         - key
                         type: object
                     type: object
                   ldapAuth:
-                    description: ApisixConsumerLDAPAuth defines the configuration
-                      for the ldap auth.
+                    description: LDAPAuth configures the LDAP authentication details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          the LDAP credentials.
                         properties:
                           name:
                             default: ""
@@ -225,10 +251,11 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerLDAPAuthValue defines the in-place
-                          configuration for ldap auth.
+                        description: Value specifies LDAP authentication credentials.
                         properties:
                           user_dn:
+                            description: UserDN is the distinguished name (DN) of
+                              the LDAP user.
                             type: string
                         required:
                         - user_dn
@@ -237,13 +264,12 @@ spec:
                     - secretRef
                     type: object
                   wolfRBAC:
-                    description: ApisixConsumerWolfRBAC defines the configuration
-                      for the wolf-rbac auth.
+                    description: WolfRBAC configures the Wolf RBAC authentication
+                      details.
                     properties:
                       secretRef:
-                        description: |-
-                          LocalObjectReference contains enough information to let you locate the
-                          referenced object inside the same namespace.
+                        description: SecretRef references a Kubernetes Secret containing
+                          the Wolf RBAC token.
                         properties:
                           name:
                             default: ""
@@ -257,15 +283,18 @@ spec:
                         type: object
                         x-kubernetes-map-type: atomic
                       value:
-                        description: ApisixConsumerWolfRBAC defines the in-place server
-                          and appid and header_prefix configuration for wolf-rbac
-                          auth.
+                        description: Value specifies the Wolf RBAC token.
                         properties:
                           appid:
+                            description: Appid is the application identifier used
+                              when communicating with the Wolf RBAC server.
                             type: string
                           header_prefix:
+                            description: HeaderPrefix is the prefix added to request
+                              headers for RBAC enforcement.
                             type: string
                           server:
+                            description: Server is the URL of the Wolf RBAC server.
                             type: string
                         type: object
                     type: object
@@ -273,9 +302,7 @@ spec:
               ingressClassName:
                 description: |-
                   IngressClassName is the name of an IngressClass cluster resource.
-                  controller implementations use this field to know whether they should be
-                  serving this ApisixConsumer resource, by a transitive connection
-                  (controller -> IngressClass -> ApisixConsumer resource).
+                  The controller uses this field to decide whether the resource should be managed.
                 type: string
             required:
             - authParameter
diff --git a/config/crd/bases/apisix.apache.org_apisixglobalrules.yaml b/config/crd/bases/apisix.apache.org_apisixglobalrules.yaml
index 2d7ca2d8..ee6d275e 100644
--- a/config/crd/bases/apisix.apache.org_apisixglobalrules.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixglobalrules.yaml
@@ -19,7 +19,7 @@ spec:
   - name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixGlobalRule is the Schema for the apisixglobalrules API.
+        description: ApisixGlobalRule defines configuration for global plugins.
         properties:
           apiVersion:
             description: |-
@@ -39,15 +39,15 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixGlobalRuleSpec defines the desired state of ApisixGlobalRule.
+            description: ApisixGlobalRuleSpec defines the global plugin configuration.
             properties:
               ingressClassName:
                 description: |-
                   IngressClassName is the name of an IngressClass cluster resource.
-                  The controller uses this field to decide whether the resource should be managed or not.
+                  The controller uses this field to decide whether the resource should be managed.
                 type: string
               plugins:
-                description: Plugins contains a list of ApisixRoutePlugin
+                description: Plugins contain a list of global plugins.
                 items:
                   description: ApisixRoutePlugin represents an APISIX plugin.
                   properties:
diff --git a/config/crd/bases/apisix.apache.org_apisixpluginconfigs.yaml b/config/crd/bases/apisix.apache.org_apisixpluginconfigs.yaml
index 9300f774..acc427f8 100644
--- a/config/crd/bases/apisix.apache.org_apisixpluginconfigs.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixpluginconfigs.yaml
@@ -19,8 +19,8 @@ spec:
   - name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixPluginConfig is the Schema for the apisixpluginconfigs
-          API.
+        description: ApisixPluginConfig defines a reusable set of plugin configuration
+          that can be referenced by routes.
         properties:
           apiVersion:
             description: |-
@@ -40,15 +40,15 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixPluginConfigSpec defines the desired state of ApisixPluginConfigSpec.
+            description: ApisixPluginConfigSpec defines the plugin config configuration.
             properties:
               ingressClassName:
                 description: |-
                   IngressClassName is the name of an IngressClass cluster resource.
-                  The controller uses this field to decide whether the resource should be managed or not.
+                  The controller uses this field to decide whether the resource should be managed.
                 type: string
               plugins:
-                description: Plugins contain a list of ApisixRoutePlugin
+                description: Plugins contain a list of plugins.
                 items:
                   description: ApisixRoutePlugin represents an APISIX plugin.
                   properties:
diff --git a/config/crd/bases/apisix.apache.org_apisixroutes.yaml b/config/crd/bases/apisix.apache.org_apisixroutes.yaml
index 4fcd7744..c1c30d7d 100644
--- a/config/crd/bases/apisix.apache.org_apisixroutes.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixroutes.yaml
@@ -47,7 +47,7 @@ spec:
     name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixRoute is the Schema for the apisixroutes API.
+        description: ApisixRoute is defines configuration for HTTP and stream routes.
         properties:
           apiVersion:
             description: |-
@@ -67,55 +67,67 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixRouteSpec is the spec definition for ApisixRouteSpec.
+            description: ApisixRouteSpec defines HTTP and stream route configuration.
             properties:
               http:
+                description: |-
+                  HTTP defines a list of HTTP route rules.
+                  Each rule specifies conditions to match HTTP requests and how to forward them.
                 items:
-                  description: ApisixRouteHTTP represents a single route in for HTTP
-                    traffic.
+                  description: ApisixRouteHTTP represents a single HTTP route configuration.
                   properties:
                     authentication:
-                      description: |-
-                        ApisixRouteAuthentication is the authentication-related
-                        configuration in ApisixRoute.
+                      description: Authentication holds authentication-related configuration
+                        for this route.
                       properties:
                         enable:
+                          description: Enable toggles authentication on or off.
                           type: boolean
                         jwtAuth:
-                          description: |-
-                            ApisixRouteAuthenticationJwtAuth is the jwt auth related
-                            configuration in ApisixRouteAuthentication.
+                          description: JwtAuth defines configuration for JWT authentication.
                           properties:
                             cookie:
+                              description: Cookie specifies the cookie name to look
+                                for the JWT token.
                               type: string
                             header:
+                              description: Header specifies the HTTP header name to
+                                look for the JWT token.
                               type: string
                             query:
+                              description: Query specifies the URL query parameter
+                                name to look for the JWT token.
                               type: string
                           type: object
                         keyAuth:
-                          description: |-
-                            ApisixRouteAuthenticationKeyAuth is the keyAuth-related
-                            configuration in ApisixRouteAuthentication.
+                          description: KeyAuth defines configuration for key authentication.
                           properties:
                             header:
+                              description: Header specifies the HTTP header name to
+                                look for the key authentication token.
                               type: string
                           type: object
                         ldapAuth:
-                          description: |-
-                            ApisixRouteAuthenticationLDAPAuth is the LDAP auth related
-                            configuration in ApisixRouteAuthentication.
+                          description: LDAPAuth defines configuration for LDAP authentication.
                           properties:
                             base_dn:
+                              description: BaseDN is the base distinguished name (DN)
+                                for LDAP searches.
                               type: string
                             ldap_uri:
+                              description: LDAPURI is the URI of the LDAP server.
                               type: string
                             uid:
+                              description: UID is the user identifier attribute in
+                                LDAP.
                               type: string
                             use_tls:
+                              description: UseTLS indicates whether to use TLS for
+                                the LDAP connection.
                               type: boolean
                           type: object
                         type:
+                          description: Type specifies the authentication type.
                           type: string
                       required:
                       - enable
@@ -123,39 +135,42 @@ spec:
                       type: object
                     backends:
                       description: |-
-                        Backends represents potential backends to proxy after the route
-                        rule matched. When number of backends are more than one, traffic-split
-                        plugin in APISIX will be used to split traffic based on the backend weight.
+                        Backends lists potential backend services to proxy requests to.
+                        If more than one backend is specified, the `traffic-split` plugin is used
+                        to distribute traffic according to backend weights.
                       items:
                         description: ApisixRouteHTTPBackend represents an HTTP backend
-                          (a Kubernetes Service).
+                          (Kubernetes Service).
                         properties:
                           resolveGranularity:
                             description: |-
-                              The resolve granularity, can be "endpoints" or "service",
-                              when set to "endpoints", the pod ips will be used; other
-                              wise, the service ClusterIP or ExternalIP will be used,
-                              default is endpoints.
+                              ResolveGranularity determines how the backend service is resolved.
+                              Valid values are `endpoints` and `service`. When set to `endpoints`,
+                              individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used.
+                              The default is `endpoints`.
                             type: string
                           serviceName:
                             description: |-
-                              The name (short) of the service, note cross namespace is forbidden,
-                              so be sure the ApisixRoute and Service are in the same namespace.
+                              ServiceName is the name of the Kubernetes Service.
+                              Cross-namespace references are not supported—ensure the ApisixRoute
+                              and the Service are in the same namespace.
                             type: string
                           servicePort:
                             anyOf:
                             - type: integer
                             - type: string
-                            description: The service port, could be the name or the
-                              port number.
+                            description: |-
+                              ServicePort is the port of the Kubernetes Service.
+                              This can be either the port name or port number.
                             x-kubernetes-int-or-string: true
                           subset:
                             description: |-
-                              Subset specifies a subset for the target Service. The subset should be pre-defined
-                              in ApisixUpstream about this service.
+                              Subset specifies a named subset of the target Service.
+                              The subset must be pre-defined in the corresponding ApisixUpstream resource.
                             type: string
                           weight:
-                            description: Weight of this backend.
+                            description: Weight specifies the relative traffic weight
+                              for this backend.
                             type: integer
                         required:
                         - serviceName
@@ -163,51 +178,41 @@ spec:
                         type: object
                       type: array
                     match:
-                      description: ApisixRouteHTTPMatch represents the match condition
-                        for hitting this route.
+                      description: Match defines the HTTP request matching criteria.
                       properties:
                         exprs:
-                          description: |-
-                            NginxVars represents generic match predicates,
-                            it uses Nginx variable systems, so any predicate
-                            like headers, querystring and etc can be leveraged
-                            here to match the route.
-                            For instance, it can be:
-                            nginxVars:
-                              - subject: "$remote_addr"
-                                op: in
-                                value:
-                                  - "127.0.0.1"
-                                  - "10.0.5.11"
+                          description: NginxVars defines match conditions based on
+                            Nginx variables.
                           items:
                             description: ApisixRouteHTTPMatchExpr represents a binary
-                              route match expression .
+                              expression used to match requests based on Nginx variables.
                             properties:
                               op:
-                                description: Op is the operator.
+                                description: |-
+                                  Op specifies the operator used in the expression.
+                                  Can be `Equal`, `NotEqual`, `GreaterThan`, `GreaterThanEqual`, `LessThan`, `LessThanEqual`, `RegexMatch`,
+                                  `RegexNotMatch`, `RegexMatchCaseInsensitive`, `RegexNotMatchCaseInsensitive`, `In`, or `NotIn`.
                                 type: string
                               set:
                                 description: |-
-                                  Set is an array type object of the expression.
-                                  It should be used when the Op is "in" or "not_in";
+                                  Set provides a list of acceptable values for the expression.
+                                  This should be used when Op is `In` or `NotIn`.
                                 items:
                                   type: string
                                 type: array
                               subject:
                                 description: |-
-                                  Subject is the expression subject, it can
-                                  be any string composed by literals and nginx
-                                  vars.
+                                  Subject defines the left-hand side of the expression.
+                                  It can be any [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable) or string literal.
                                 properties:
                                   name:
-                                    description: The name of subject.
+                                    description: Name is the name of the header or
+                                      query parameter.
                                     type: string
                                   scope:
                                     description: |-
-                                      The subject scope, can be:
-                                      ScopeQuery, ScopeHeader, ScopePath
-                                      when subject is ScopePath, Name field
-                                      will be ignored.
+                                      Scope specifies the subject scope and can be `Header`, `Query`, or `Path`.
+                                      When Scope is `Path`, Name will be ignored.
                                     type: string
                                 required:
                                 - name
@@ -215,10 +220,9 @@ spec:
                                 type: object
                               value:
                                 description: |-
-                                  Value is the normal type object for the expression,
-                                  it should be used when the Op is not "in" and "not_in".
-                                  Set and Value are exclusive so only of them can be set
-                                  in the same time.
+                                  Value defines a single value to compare against the subject.
+                                  This should be used when Op is not `In` or `NotIn`.
+                                  Set and Value are mutually exclusive—only one should be set at a time.
                                 type: string
                             required:
                             - op
@@ -227,36 +231,36 @@ spec:
                           type: array
                         filter_func:
                           description: |-
-                            Matches based on a user-defined filtering function.
-                            These functions can accept an input parameter `vars`
-                            which can be used to access the Nginx variables.
+                            FilterFunc is a user-defined function for advanced request filtering.
+                            The function can use Nginx variables through the `vars` parameter.
                           type: string
                         hosts:
                           description: |-
-                            HTTP Host predicates, host can be a wildcard domain or
-                            an exact domain. For wildcard domain, only one generic
-                            level is allowed, for instance, "*.foo.com" is valid but
-                            "*.*.foo.com" is not.
+                            Hosts specifies Host header values to match.
+                            Supports exact and wildcard domains.
+                            Only one level of wildcard is allowed (e.g., `*.example.com` is valid,
+                            but `*.*.example.com` is not).
                           items:
                             type: string
                           type: array
                         methods:
-                          description: HTTP request method predicates.
+                          description: Methods specifies the HTTP methods to match.
                           items:
                             type: string
                           type: array
                         paths:
                           description: |-
-                            URI path predicates, at least one path should be
-                            configured, path could be exact or prefix, for prefix path,
-                            append "*" after it, for instance, "/foo*".
+                            Paths is a list of URI path patterns to match.
+                            At least one path must be specified.
+                            Supports exact matches and prefix matches.
+                            For prefix matches, append `*` to the path, such as `/foo*`.
                           items:
                             type: string
                           type: array
                         remoteAddrs:
                           description: |-
-                            Remote address predicates, items can be valid IPv4 address
-                            or IPv6 address or CIDR.
+                            RemoteAddrs is a list of source IP addresses or CIDR ranges to match.
+                            Supports both IPv4 and IPv6 formats.
                           items:
                             type: string
                           type: array
@@ -264,15 +268,20 @@ spec:
                       - paths
                       type: object
                     name:
-                      description: The rule name, cannot be empty.
+                      description: Name is the unique rule name and cannot be empty.
                       type: string
                     plugin_config_name:
+                      description: PluginConfigName specifies the name of the plugin
+                        config to apply.
                       type: string
                     plugin_config_namespace:
-                      description: By default, PluginConfigNamespace will be the same
-                        as the namespace of ApisixRoute
+                      description: |-
+                        PluginConfigNamespace specifies the namespace of the plugin config.
+                        Defaults to the namespace of the ApisixRoute if not set.
                       type: string
                     plugins:
+                      description: Plugins lists additional plugins applied to this
+                        route.
                       items:
                         description: ApisixRoutePlugin represents an APISIX plugin.
                         properties:
@@ -297,97 +306,117 @@ spec:
                       type: array
                     priority:
                       description: |-
-                        Route priority, when multiple routes contains
-                        same URI path (for path matching), route with
-                        higher priority will take effect.
+                        Priority defines the route priority when multiple routes share the same URI path.
+                        Higher values mean higher priority in route matching.
                       type: integer
                     timeout:
-                      description: UpstreamTimeout is settings for the read, send
-                        and connect to the upstream.
+                      description: Timeout specifies upstream timeout settings.
                       properties:
                         connect:
+                          description: Connect timeout for establishing a connection
+                            to the upstream.
                           type: string
                         read:
+                          description: Read timeout for reading data from the upstream.
                           type: string
                         send:
+                          description: Send timeout for sending data to the upstream.
                           type: string
                       type: object
                     upstreams:
-                      description: Upstreams refer to ApisixUpstream CRD
+                      description: Upstreams references ApisixUpstream CRDs.
                       items:
-                        description: ApisixRouteUpstreamReference contains a ApisixUpstream
-                          CRD reference
+                        description: |-
+                          ApisixRouteUpstreamReference references an ApisixUpstream CRD to be used as a backend.
+                          It can be used in traffic-splitting scenarios or to select a specific upstream configuration.
                         properties:
                           name:
+                            description: Name is the name of the ApisixUpstream resource.
                             type: string
                           weight:
+                            description: Weight is the weight assigned to this upstream.
                             type: integer
                         type: object
                       type: array
                     websocket:
+                      description: Websocket enables or disables websocket support
+                        for this route.
                       type: boolean
                   required:
                   - name
                   type: object
                 type: array
               ingressClassName:
+                description: |-
+                  IngressClassName is the name of the IngressClass this route belongs to.
+                  It allows multiple controllers to watch and reconcile different routes.
                 type: string
               stream:
+                description: |-
+                  Stream defines a list of stream route rules.
+                  Each rule specifies conditions to match TCP/UDP traffic and how to forward them.
                 items:
-                  description: ApisixRouteStream is the configuration for level 4
-                    route
+                  description: ApisixRouteStream defines the configuration for a Layer
+                    4 (TCP/UDP) route.
                   properties:
                     backend:
-                      description: ApisixRouteStreamBackend represents a TCP backend
-                        (a Kubernetes Service).
+                      description: Backend specifies the destination service to which
+                        traffic should be forwarded.
                       properties:
                         resolveGranularity:
                           description: |-
-                            The resolve granularity, can be "endpoints" or "service",
-                            when set to "endpoints", the pod ips will be used; other
-                            wise, the service ClusterIP or ExternalIP will be used,
-                            default is endpoints.
+                            ResolveGranularity determines how the backend service is resolved.
+                            Valid values are `endpoints` and `service`. When set to `endpoints`,
+                            individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used.
+                            The default is `endpoints`.
                           type: string
                         serviceName:
                           description: |-
-                            The name (short) of the service, note cross namespace is forbidden,
-                            so be sure the ApisixRoute and Service are in the same namespace.
+                            ServiceName is the name of the Kubernetes Service.
+                            Cross-namespace references are not supported—ensure the ApisixRoute
+                            and the Service are in the same namespace.
                           type: string
                         servicePort:
                           anyOf:
                           - type: integer
                           - type: string
-                          description: The service port, could be the name or the
-                            port number.
+                          description: |-
+                            ServicePort is the port of the Kubernetes Service.
+                            This can be either the port name or port number.
                           x-kubernetes-int-or-string: true
                         subset:
                           description: |-
-                            Subset specifies a subset for the target Service. The subset should be pre-defined
-                            in ApisixUpstream about this service.
+                            Subset specifies a named subset of the target Service.
+                            The subset must be pre-defined in the corresponding ApisixUpstream resource.
                           type: string
                       required:
                       - serviceName
                       - servicePort
                       type: object
                     match:
-                      description: ApisixRouteStreamMatch represents the match conditions
-                        of stream route.
+                      description: Match defines the criteria used to match incoming
+                        TCP or UDP connections.
                       properties:
                         host:
+                          description: Host is the destination host address used to
+                            match the incoming TCP/UDP traffic.
                           type: string
                         ingressPort:
                           description: |-
-                            IngressPort represents the port listening on the Ingress proxy server.
-                            It should be pre-defined as APISIX doesn't support dynamic listening.
+                            IngressPort is the port on which the APISIX Ingress proxy server listens.
+                            This must be a statically configured port, as APISIX does not support dynamic port binding.
                           format: int32
                           type: integer
                       required:
                       - ingressPort
                       type: object
                     name:
-                      description: The rule name cannot be empty.
+                      description: Name is a unique identifier for the route. This
+                        field must not be empty.
                       type: string
                     plugins:
+                      description: Plugins defines a list of plugins to apply to this
+                        route.
                       items:
                         description: ApisixRoutePlugin represents an APISIX plugin.
                         properties:
@@ -411,6 +440,8 @@ spec:
                         type: object
                       type: array
                     protocol:
+                      description: Protocol specifies the L4 protocol to match. Can
+                        be `tcp` or `udp`.
                       type: string
                   required:
                   - backend
diff --git a/config/crd/bases/apisix.apache.org_apisixtlses.yaml b/config/crd/bases/apisix.apache.org_apisixtlses.yaml
index 78926611..65f06eeb 100644
--- a/config/crd/bases/apisix.apache.org_apisixtlses.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixtlses.yaml
@@ -38,7 +38,7 @@ spec:
     name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixTls is the Schema for the apisixtls API.
+        description: ApisixTls defines configuration for TLS and mutual TLS (mTLS).
         properties:
           apiVersion:
             description: |-
@@ -58,20 +58,23 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixTlsSpec defines the desired state of ApisixTls.
+            description: ApisixTlsSpec defines the TLS configuration.
             properties:
               client:
-                description: ApisixMutualTlsClientConfig describes the mutual TLS
-                  CA and verify depth
+                description: Client defines mutual TLS (mTLS) settings, such as the
+                  CA certificate and verification depth.
                 properties:
                   caSecret:
-                    description: ApisixSecret describes the Kubernetes Secret name
-                      and namespace.
+                    description: CASecret references the secret containing the CA
+                      certificate for client certificate validation.
                     properties:
                       name:
+                        description: Name is the name of the Kubernetes Secret.
                         minLength: 1
                         type: string
                       namespace:
+                        description: Namespace is the namespace where the Kubernetes
+                          Secret is located.
                         minLength: 1
                         type: string
                     required:
@@ -79,13 +82,20 @@ spec:
                     - namespace
                     type: object
                   depth:
+                    description: Depth specifies the maximum verification depth for
+                      the client certificate chain.
                     type: integer
                   skip_mtls_uri_regex:
+                    description: SkipMTLSUriRegex contains RegEx patterns for URIs
+                      to skip mutual TLS verification.
                     items:
                       type: string
                     type: array
                 type: object
               hosts:
+                description: |-
+                  Hosts lists the SNI (Server Name Indication) hostnames that this TLS configuration applies to.
+                  Must contain at least one host.
                 items:
                   pattern: ^\*?[0-9a-zA-Z-.]+$
                   type: string
@@ -93,19 +103,21 @@ spec:
                 type: array
               ingressClassName:
                 description: |-
-                  IngressClassName is the name of an IngressClass cluster resource.
-                  controller implementations use this field to know whether they should be
-                  serving this ApisixTls resource, by a transitive connection
-                  (controller -> IngressClass -> ApisixTls resource).
+                  IngressClassName specifies which IngressClass this resource is associated with.
+                  The APISIX controller only processes this resource if the class matches its own.
                 type: string
               secret:
-                description: ApisixSecret describes the Kubernetes Secret name and
-                  namespace.
+                description: |-
+                  Secret refers to the Kubernetes TLS secret containing the certificate and private key.
+                  This secret must exist in the specified namespace and contain valid TLS data.
                 properties:
                   name:
+                    description: Name is the name of the Kubernetes Secret.
                     minLength: 1
                     type: string
                   namespace:
+                    description: Namespace is the namespace where the Kubernetes Secret
+                      is located.
                     minLength: 1
                     type: string
                 required:
diff --git a/config/crd/bases/apisix.apache.org_apisixupstreams.yaml b/config/crd/bases/apisix.apache.org_apisixupstreams.yaml
index 3d6be40e..c07b08e5 100644
--- a/config/crd/bases/apisix.apache.org_apisixupstreams.yaml
+++ b/config/crd/bases/apisix.apache.org_apisixupstreams.yaml
@@ -19,7 +19,7 @@ spec:
   - name: v2
     schema:
       openAPIV3Schema:
-        description: ApisixUpstream is the Schema for the apisixupstreams API.
+        description: ApisixUpstream defines configuration for upstream services.
         properties:
           apiVersion:
             description: |-
@@ -39,20 +39,25 @@ spec:
           metadata:
             type: object
           spec:
-            description: ApisixUpstreamSpec describes the specification of ApisixUpstream.
+            description: ApisixUpstreamSpec defines the upstream configuration.
             properties:
               discovery:
                 description: |-
-                  Deprecated: this is no longer support on standalone mode.
-                  Discovery is used to configure service discovery for upstream.
+                  Discovery configures service discovery for the upstream.
+                  Deprecated: no longer supported in standalone mode.
                 properties:
                   args:
                     additionalProperties:
                       type: string
+                    description: |-
+                      Args contains additional configuration parameters required by the discovery provider.
+                      These are passed as key-value pairs.
                     type: object
                   serviceName:
+                    description: ServiceName is the name of the service to discover.
                     type: string
                   type:
+                    description: Type is the name of the service discovery provider.
                     type: string
                 required:
                 - serviceName
@@ -60,147 +65,186 @@ spec:
                 type: object
               externalNodes:
                 description: |-
-                  ExternalNodes contains external nodes the Upstream should use
-                  If this field is set, the upstream will use these nodes directly without any further resolves
+                  ExternalNodes defines a static list of backend nodes located outside the cluster.
+                  When this field is set, the upstream will route traffic directly to these nodes
+                  without DNS resolution or service discovery.
                 items:
-                  description: ApisixUpstreamExternalNode is the external node conf
+                  description: |-
+                    ApisixUpstreamExternalNode defines configuration for an external upstream node.
+                    This allows referencing services outside the cluster.
                   properties:
                     name:
+                      description: Name is the hostname or IP address of the external
+                        node.
                       type: string
                     port:
-                      description: Port defines the port of the external node
+                      description: Port specifies the port number on which the external
+                        node is accepting traffic.
                       type: integer
                     type:
-                      description: ApisixUpstreamExternalType is the external service
-                        type
+                      description: Type indicates the kind of external node. Can be
+                        `Domain`, or `Service`.
                       type: string
                     weight:
+                      description: |-
+                        Weight defines the load balancing weight of this node.
+                        Higher values increase the share of traffic sent to this node.
                       type: integer
                   type: object
                 minItems: 1
                 type: array
               healthCheck:
                 description: |-
-                  Deprecated: this is no longer support on standalone mode.
-                  The health check configurations for the upstream.
+                  HealthCheck defines the active and passive health check configuration for the upstream.
+                  Deprecated: no longer supported in standalone mode.
                 properties:
                   active:
-                    description: ActiveHealthCheck defines the active kind of upstream
-                      health check.
+                    description: Active health checks proactively send requests to
+                      upstream nodes to determine their availability.
                     properties:
                       concurrency:
+                        description: Concurrency sets the number of targets to be
+                          checked at the same time.
                         minimum: 0
                         type: integer
                       healthy:
-                        description: |-
-                          ActiveHealthCheckHealthy defines the conditions to judge whether
-                          an upstream node is healthy with the active manner.
+                        description: Healthy configures the rules that define an upstream
+                          node as healthy.
                         properties:
                           httpCodes:
+                            description: HTTPCodes define a list of HTTP status codes
+                              that are considered healthy.
                             items:
                               type: integer
                             minItems: 1
                             type: array
                           interval:
+                            description: Interval defines the time interval for checking
+                              targets, in seconds.
                             type: string
                           successes:
+                            description: Successes define the number of successful
+                              probes to define a healthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                         type: object
                       host:
+                        description: Host sets the upstream host.
                         type: string
                       httpPath:
+                        description: HTTPPath sets the HTTP probe request path.
                         type: string
                       port:
+                        description: Port sets the upstream port.
                         format: int32
                         maximum: 65535
                         minimum: 0
                         type: integer
                       requestHeaders:
+                        description: RequestHeaders sets the request headers.
                         items:
                           type: string
                         type: array
                       strictTLS:
+                        description: StrictTLS sets whether to enforce TLS.
                         type: boolean
                       timeout:
-                        description: |-
-                          A Duration represents the elapsed time between two instants
-                          as an int64 nanosecond count. The representation limits the
-                          largest representable duration to approximately 290 years.
+                        description: Timeout sets health check timeout in seconds.
                         format: int64
                         type: integer
                       type:
+                        description: Type is the health check type. Can be `http`,
+                          `https`, or `tcp`.
                         enum:
                         - http
                         - https
                         - tcp
                         type: string
                       unhealthy:
-                        description: |-
-                          ActiveHealthCheckUnhealthy defines the conditions to judge whether
-                          an upstream node is unhealthy with the active manager.
+                        description: Unhealthy configures the rules that define an
+                          upstream node as unhealthy.
                         properties:
                           httpCodes:
+                            description: HTTPCodes define a list of HTTP status codes
+                              that are considered unhealthy.
                             items:
                               type: integer
                             minItems: 1
                             type: array
                           httpFailures:
+                            description: HTTPFailures define the number of HTTP failures
+                              to define an unhealthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                           interval:
+                            description: Interval defines the time interval for checking
+                              targets, in seconds.
                             type: string
                           tcpFailures:
+                            description: TCPFailures define the number of TCP failures
+                              to define an unhealthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                           timeout:
+                            description: Timeout sets health check timeout in seconds.
                             type: integer
                         type: object
                     type: object
                   passive:
-                    description: |-
-                      PassiveHealthCheck defines the conditions to judge whether
-                      an upstream node is healthy with the passive manager.
+                    description: Passive health checks evaluate upstream health based
+                      on observed traffic, such as timeouts or errors.
                     properties:
                       healthy:
-                        description: |-
-                          PassiveHealthCheckHealthy defines the conditions to judge whether
-                          an upstream node is healthy with the passive manner.
+                        description: Healthy defines the conditions under which an
+                          upstream node is considered healthy.
                         properties:
                           httpCodes:
+                            description: HTTPCodes define a list of HTTP status codes
+                              that are considered healthy.
                             items:
                               type: integer
                             minItems: 1
                             type: array
                           successes:
+                            description: Successes define the number of successful
+                              probes to define a healthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                         type: object
                       type:
+                        description: |-
+                          Type specifies the type of passive health check.
+                          Can be `http`, `https`, or `tcp`.
                         type: string
                       unhealthy:
-                        description: |-
-                          PassiveHealthCheckUnhealthy defines the conditions to judge whether
-                          an upstream node is unhealthy with the passive manager.
+                        description: Unhealthy defines the conditions under which
+                          an upstream node is considered unhealthy.
                         properties:
                           httpCodes:
+                            description: HTTPCodes define a list of HTTP status codes
+                              that are considered unhealthy.
                             items:
                               type: integer
                             minItems: 1
                             type: array
                           httpFailures:
+                            description: HTTPFailures define the number of HTTP failures
+                              to define an unhealthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                           tcpFailures:
+                            description: TCPFailures define the number of TCP failures
+                              to define an unhealthy target.
                             maximum: 254
                             minimum: 0
                             type: integer
                           timeout:
+                            description: Timeout sets health check timeout in seconds.
                             type: integer
                         type: object
                     type: object
@@ -210,56 +254,89 @@ spec:
               ingressClassName:
                 description: |-
                   IngressClassName is the name of an IngressClass cluster resource.
-                  controller implementations use this field to know whether they should be
-                  serving this ApisixUpstream resource, by a transitive connection
-                  (controller -> IngressClass -> ApisixUpstream resource).
+                  Controller implementations use this field to determine whether they
+                  should process this ApisixUpstream resource.
                 type: string
               loadbalancer:
-                description: |-
-                  LoadBalancer represents the load balancer configuration for Kubernetes Service.
-                  The default strategy is round robin.
+                description: LoadBalancer specifies the load balancer configuration
+                  for Kubernetes Service.
                 properties:
                   hashOn:
+                    default: vars
                     description: |-
-                      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 `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`.
+                    enum:
+                    - vars
+                    - header
+                    - cookie
+                    - consumer
+                    - vars_combinations
                     type: string
                   key:
-                    description: Key represents the hash key.
+                    description: |-
+                      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
+                      [APISIX variables](https://apisix.apache.org/docs/apisix/apisix-variable).
                     type: string
                   type:
+                    default: roundrobin
+                    description: |-
+                      Type specifies the load balancing algorithms to route traffic to the backend.
+                      Default is `roundrobin`.
+                      Can be `roundrobin`, `chash`, `ewma`, or `least_conn`.
+                    enum:
+                    - roundrobin
+                    - chash
+                    - ewma
+                    - least_conn
                     type: string
                 required:
                 - type
                 type: object
               passHost:
                 description: |-
-                  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 `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
                 enum:
                 - pass
                 - node
                 - rewrite
                 type: string
               portLevelSettings:
+                description: |-
+                  PortLevelSettings allows fine-grained upstream configuration for specific ports,
+                  useful when a backend service exposes multiple ports with different behaviors or protocols.
                 items:
                   description: |-
                     PortLevelSettings configures the ApisixUpstreamConfig for each individual port. It inherits
-                    configurations from the outer level (the whole Kubernetes Service) and overrides some of
+                    configuration from the outer level (the whole Kubernetes Service) and overrides some of
                     them if they are set on the port level.
                   properties:
                     discovery:
                       description: |-
-                        Deprecated: this is no longer support on standalone mode.
-                        Discovery is used to configure service discovery for upstream.
+                        Discovery configures service discovery for the upstream.
+                        Deprecated: no longer supported in standalone mode.
                       properties:
                         args:
                           additionalProperties:
                             type: string
+                          description: |-
+                            Args contains additional configuration parameters required by the discovery provider.
+                            These are passed as key-value pairs.
                           type: object
                         serviceName:
+                          description: ServiceName is the name of the service to discover.
                           type: string
                         type:
+                          description: Type is the name of the service discovery provider.
                           type: string
                       required:
                       - serviceName
@@ -267,126 +344,158 @@ spec:
                       type: object
                     healthCheck:
                       description: |-
-                        Deprecated: this is no longer support on standalone mode.
-                        The health check configurations for the upstream.
+                        HealthCheck defines the active and passive health check configuration for the upstream.
+                        Deprecated: no longer supported in standalone mode.
                       properties:
                         active:
-                          description: ActiveHealthCheck defines the active kind of
-                            upstream health check.
+                          description: Active health checks proactively send requests
+                            to upstream nodes to determine their availability.
                           properties:
                             concurrency:
+                              description: Concurrency sets the number of targets
+                                to be checked at the same time.
                               minimum: 0
                               type: integer
                             healthy:
-                              description: |-
-                                ActiveHealthCheckHealthy defines the conditions to judge whether
-                                an upstream node is healthy with the active manner.
+                              description: Healthy configures the rules that define
+                                an upstream node as healthy.
                               properties:
                                 httpCodes:
+                                  description: HTTPCodes define a list of HTTP status
+                                    codes that are considered healthy.
                                   items:
                                     type: integer
                                   minItems: 1
                                   type: array
                                 interval:
+                                  description: Interval defines the time interval
+                                    for checking targets, in seconds.
                                   type: string
                                 successes:
+                                  description: Successes define the number of successful
+                                    probes to define a healthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                               type: object
                             host:
+                              description: Host sets the upstream host.
                               type: string
                             httpPath:
+                              description: HTTPPath sets the HTTP probe request path.
                               type: string
                             port:
+                              description: Port sets the upstream port.
                               format: int32
                               maximum: 65535
                               minimum: 0
                               type: integer
                             requestHeaders:
+                              description: RequestHeaders sets the request headers.
                               items:
                                 type: string
                               type: array
                             strictTLS:
+                              description: StrictTLS sets whether to enforce TLS.
                               type: boolean
                             timeout:
-                              description: |-
-                                A Duration represents the elapsed time between two instants
-                                as an int64 nanosecond count. The representation limits the
-                                largest representable duration to approximately 290 years.
+                              description: Timeout sets health check timeout in seconds.
                               format: int64
                               type: integer
                             type:
+                              description: Type is the health check type. Can be `http`,
+                                `https`, or `tcp`.
                               enum:
                               - http
                               - https
                               - tcp
                               type: string
                             unhealthy:
-                              description: |-
-                                ActiveHealthCheckUnhealthy defines the conditions to judge whether
-                                an upstream node is unhealthy with the active manager.
+                              description: Unhealthy configures the rules that define
+                                an upstream node as unhealthy.
                               properties:
                                 httpCodes:
+                                  description: HTTPCodes define a list of HTTP status
+                                    codes that are considered unhealthy.
                                   items:
                                     type: integer
                                   minItems: 1
                                   type: array
                                 httpFailures:
+                                  description: HTTPFailures define the number of HTTP
+                                    failures to define an unhealthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                                 interval:
+                                  description: Interval defines the time interval
+                                    for checking targets, in seconds.
                                   type: string
                                 tcpFailures:
+                                  description: TCPFailures define the number of TCP
+                                    failures to define an unhealthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                                 timeout:
+                                  description: Timeout sets health check timeout in
+                                    seconds.
                                   type: integer
                               type: object
                           type: object
                         passive:
-                          description: |-
-                            PassiveHealthCheck defines the conditions to judge whether
-                            an upstream node is healthy with the passive manager.
+                          description: Passive health checks evaluate upstream health
+                            based on observed traffic, such as timeouts or errors.
                           properties:
                             healthy:
-                              description: |-
-                                PassiveHealthCheckHealthy defines the conditions to judge whether
-                                an upstream node is healthy with the passive manner.
+                              description: Healthy defines the conditions under which
+                                an upstream node is considered healthy.
                               properties:
                                 httpCodes:
+                                  description: HTTPCodes define a list of HTTP status
+                                    codes that are considered healthy.
                                   items:
                                     type: integer
                                   minItems: 1
                                   type: array
                                 successes:
+                                  description: Successes define the number of successful
+                                    probes to define a healthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                               type: object
                             type:
+                              description: |-
+                                Type specifies the type of passive health check.
+                                Can be `http`, `https`, or `tcp`.
                               type: string
                             unhealthy:
-                              description: |-
-                                PassiveHealthCheckUnhealthy defines the conditions to judge whether
-                                an upstream node is unhealthy with the passive manager.
+                              description: Unhealthy defines the conditions under
+                                which an upstream node is considered unhealthy.
                               properties:
                                 httpCodes:
+                                  description: HTTPCodes define a list of HTTP status
+                                    codes that are considered unhealthy.
                                   items:
                                     type: integer
                                   minItems: 1
                                   type: array
                                 httpFailures:
+                                  description: HTTPFailures define the number of HTTP
+                                    failures to define an unhealthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                                 tcpFailures:
+                                  description: TCPFailures define the number of TCP
+                                    failures to define an unhealthy target.
                                   maximum: 254
                                   minimum: 0
                                   type: integer
                                 timeout:
+                                  description: Timeout sets health check timeout in
+                                    seconds.
                                   type: integer
                               type: object
                           type: object
@@ -394,47 +503,73 @@ spec:
                       - active
                       type: object
                     loadbalancer:
-                      description: |-
-                        LoadBalancer represents the load balancer configuration for Kubernetes Service.
-                        The default strategy is round robin.
+                      description: LoadBalancer specifies the load balancer configuration
+                        for Kubernetes Service.
                       properties:
                         hashOn:
+                          default: vars
                           description: |-
-                            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 `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`.
+                          enum:
+                          - vars
+                          - header
+                          - cookie
+                          - consumer
+                          - vars_combinations
                           type: string
                         key:
-                          description: Key represents the hash key.
+                          description: |-
+                            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
+                            [APISIX variables](https://apisix.apache.org/docs/apisix/apisix-variable).
                           type: string
                         type:
+                          default: roundrobin
+                          description: |-
+                            Type specifies the load balancing algorithms to route traffic to the backend.
+                            Default is `roundrobin`.
+                            Can be `roundrobin`, `chash`, `ewma`, or `least_conn`.
+                          enum:
+                          - roundrobin
+                          - chash
+                          - ewma
+                          - least_conn
                           type: string
                       required:
                       - type
                       type: object
                     passHost:
                       description: |-
-                        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 `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
                       enum:
                       - pass
                       - node
                       - rewrite
                       type: string
                     port:
-                      description: Port is a Kubernetes Service port, it should be
-                        already defined.
+                      description: Port is a Kubernetes Service port.
                       format: int32
                       type: integer
                     retries:
                       description: |-
-                        How many times that the proxy (Apache APISIX) should do when
-                        errors occur (error, timeout or bad http status codes like 500, 502).
+                        Retries defines the number of retry attempts APISIX should make when a failure occurs.
+                        Failures include timeouts, network errors, or 5xx status codes.
                       format: int64
                       type: integer
                     scheme:
                       description: |-
-                        The scheme used to talk with the upstream.
-                        Now value can be http, grpc.
+                        Scheme is the protocol used to communicate with the upstream.
+                        Default is `http`.
+                        Can be `http`, `https`, `grpc`, or `grpcs`.
                       enum:
                       - http
                       - https
@@ -443,8 +578,8 @@ spec:
                       type: string
                     subsets:
                       description: |-
-                        Subsets groups the service endpoints by their labels. Usually used to differentiate
-                        service versions.
+                        Subsets defines labeled subsets of service endpoints, typically used for
+                        service versioning or canary deployments.
                       items:
                         description: ApisixUpstreamSubset defines a single endpoints
                           group of one Service.
@@ -463,24 +598,32 @@ spec:
                         type: object
                       type: array
                     timeout:
-                      description: Timeout settings for the read, send and connect
-                        to the upstream.
+                      description: Timeout specifies the connection, send, and read
+                        timeouts for upstream requests.
                       properties:
                         connect:
+                          description: Connect timeout for establishing a connection
+                            to the upstream.
                           type: string
                         read:
+                          description: Read timeout for reading data from the upstream.
                           type: string
                         send:
+                          description: Send timeout for sending data to the upstream.
                           type: string
                       type: object
                     tlsSecret:
-                      description: Set the client certificate when connecting to TLS
-                        upstream.
+                      description: |-
+                        TLSSecret references a Kubernetes Secret that contains the client certificate and key
+                        for mutual TLS when connecting to the upstream.
                       properties:
                         name:
+                          description: Name is the name of the Kubernetes Secret.
                           minLength: 1
                           type: string
                         namespace:
+                          description: Namespace is the namespace where the Kubernetes
+                            Secret is located.
                           minLength: 1
                           type: string
                       required:
@@ -488,9 +631,8 @@ spec:
                       - namespace
                       type: object
                     upstreamHost:
-                      description: |-
-                        Specifies the host of the Upstream request. This is only valid if
-                        the pass_host is set to rewrite
+                      description: UpstreamHost sets a custom Host header when passHost
+                        is set to `rewrite`.
                       type: string
                   required:
                   - port
@@ -498,14 +640,15 @@ spec:
                 type: array
               retries:
                 description: |-
-                  How many times that the proxy (Apache APISIX) should do when
-                  errors occur (error, timeout or bad http status codes like 500, 502).
+                  Retries defines the number of retry attempts APISIX should make when a failure occurs.
+                  Failures include timeouts, network errors, or 5xx status codes.
                 format: int64
                 type: integer
               scheme:
                 description: |-
-                  The scheme used to talk with the upstream.
-                  Now value can be http, grpc.
+                  Scheme is the protocol used to communicate with the upstream.
+                  Default is `http`.
+                  Can be `http`, `https`, `grpc`, or `grpcs`.
                 enum:
                 - http
                 - https
@@ -514,8 +657,8 @@ spec:
                 type: string
               subsets:
                 description: |-
-                  Subsets groups the service endpoints by their labels. Usually used to differentiate
-                  service versions.
+                  Subsets defines labeled subsets of service endpoints, typically used for
+                  service versioning or canary deployments.
                 items:
                   description: ApisixUpstreamSubset defines a single endpoints group
                     of one Service.
@@ -534,23 +677,32 @@ spec:
                   type: object
                 type: array
               timeout:
-                description: Timeout settings for the read, send and connect to the
-                  upstream.
+                description: Timeout specifies the connection, send, and read timeouts
+                  for upstream requests.
                 properties:
                   connect:
+                    description: Connect timeout for establishing a connection to
+                      the upstream.
                     type: string
                   read:
+                    description: Read timeout for reading data from the upstream.
                     type: string
                   send:
+                    description: Send timeout for sending data to the upstream.
                     type: string
                 type: object
               tlsSecret:
-                description: Set the client certificate when connecting to TLS upstream.
+                description: |-
+                  TLSSecret references a Kubernetes Secret that contains the client certificate and key
+                  for mutual TLS when connecting to the upstream.
                 properties:
                   name:
+                    description: Name is the name of the Kubernetes Secret.
                     minLength: 1
                     type: string
                   namespace:
+                    description: Namespace is the namespace where the Kubernetes Secret
+                      is located.
                     minLength: 1
                     type: string
                 required:
@@ -558,9 +710,8 @@ spec:
                 - namespace
                 type: object
               upstreamHost:
-                description: |-
-                  Specifies the host of the Upstream request. This is only valid if
-                  the pass_host is set to rewrite
+                description: UpstreamHost sets a custom Host header when passHost
+                  is set to `rewrite`.
                 type: string
             type: object
           status:
diff --git a/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml b/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml
index beff7f2b..ed2cad68 100644
--- a/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml
+++ b/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml
@@ -17,6 +17,8 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
+        description: BackendTrafficPolicy defines configuration for traffic handling
+          policies applied to backend services.
         properties:
           apiVersion:
             description: |-
@@ -48,9 +50,9 @@ spec:
                   hashOn:
                     default: vars
                     description: |-
-                      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`.
                     enum:
                     - vars
                     - header
@@ -60,7 +62,7 @@ spec:
                     type: string
                   key:
                     description: |-
-                      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
@@ -69,9 +71,9 @@ spec:
                   type:
                     default: roundrobin
                     description: |-
-                      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`.
                     enum:
                     - roundrobin
                     - chash
@@ -88,8 +90,10 @@ spec:
                 description: |-
                   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`
                 enum:
                 - pass
                 - node
@@ -105,7 +109,7 @@ spec:
                 description: |-
                   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`.
                 enum:
                 - http
                 - https
diff --git a/config/crd/bases/apisix.apache.org_consumers.yaml b/config/crd/bases/apisix.apache.org_consumers.yaml
index 67a9b4a3..187bc113 100644
--- a/config/crd/bases/apisix.apache.org_consumers.yaml
+++ b/config/crd/bases/apisix.apache.org_consumers.yaml
@@ -17,6 +17,7 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
+        description: Consumer defines configuration for a consumer.
         properties:
           apiVersion:
             description: |-
@@ -37,7 +38,7 @@ spec:
             type: object
           spec:
             description: |-
-              ConsumerSpec defines the configuration for a consumer, including consumer name,
+              ConsumerSpec defines configuration for a consumer, including consumer name,
               authentication credentials, and plugin settings.
             properties:
               credentials:
@@ -66,7 +67,7 @@ spec:
                     type:
                       description: |-
                         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`.
                       enum:
                       - jwt-auth
                       - basic-auth
diff --git a/config/crd/bases/apisix.apache.org_gatewayproxies.yaml b/config/crd/bases/apisix.apache.org_gatewayproxies.yaml
index cd5f42c0..cd2d1a96 100644
--- a/config/crd/bases/apisix.apache.org_gatewayproxies.yaml
+++ b/config/crd/bases/apisix.apache.org_gatewayproxies.yaml
@@ -17,7 +17,8 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: GatewayProxy is the Schema for the gatewayproxies API.
+        description: GatewayProxy defines configuration for the gateway proxy instances
+          used to route traffic to services.
         properties:
           apiVersion:
             description: |-
@@ -38,19 +39,19 @@ spec:
             type: object
           spec:
             description: |-
-              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.
             properties:
               pluginMetadata:
                 additionalProperties:
                   x-kubernetes-preserve-unknown-fields: true
-                description: PluginMetadata configures common configurations shared
+                description: PluginMetadata configures common configuration shared
                   by all plugin instances of the same name.
                 type: object
               plugins:
                 description: Plugins configure global plugins.
                 items:
-                  description: GatewayProxyPlugin contains plugin configurations.
+                  description: GatewayProxyPlugin contains plugin configuration.
                   properties:
                     config:
                       description: Config defines the plugin's configuration details.
@@ -71,7 +72,7 @@ spec:
                       plane provider.
                     properties:
                       auth:
-                        description: Auth specifies the authentication configurations.
+                        description: Auth specifies the authentication configuration.
                         properties:
                           adminKey:
                             description: AdminKey specifies the admin key authentication
@@ -122,8 +123,10 @@ spec:
                       service:
                         properties:
                           name:
+                            description: Name is the name of the provider.
                             type: string
                           port:
+                            description: Port is the port of the provider.
                             format: int32
                             maximum: 65535
                             minimum: 1
diff --git a/config/crd/bases/apisix.apache.org_httproutepolicies.yaml b/config/crd/bases/apisix.apache.org_httproutepolicies.yaml
index 974a44fb..ea4fa0d4 100644
--- a/config/crd/bases/apisix.apache.org_httproutepolicies.yaml
+++ b/config/crd/bases/apisix.apache.org_httproutepolicies.yaml
@@ -17,7 +17,7 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: HTTPRoutePolicy is the Schema for the httproutepolicies API.
+        description: HTTPRoutePolicy defines configuration of traffic policies.
         properties:
           apiVersion:
             description: |-
@@ -38,12 +38,13 @@ spec:
             type: object
           spec:
             description: |-
-              HTTPRoutePolicySpec defines the desired state and configuration of a HTTPRoutePolicy,
+              HTTPRoutePolicySpec defines configuration of a HTTPRoutePolicy,
               including route priority and request matching conditions.
             properties:
               priority:
-                description: Priority sets the priority for route. A higher value
-                  sets a higher priority in route matching.
+                description: |-
+                  Priority sets the priority for route. when multiple routes have the same URI path,
+                  a higher value sets a higher priority in route matching.
                 format: int64
                 type: integer
               targetRefs:
diff --git a/config/crd/bases/apisix.apache.org_pluginconfigs.yaml b/config/crd/bases/apisix.apache.org_pluginconfigs.yaml
index b9d529ed..0891f5e8 100644
--- a/config/crd/bases/apisix.apache.org_pluginconfigs.yaml
+++ b/config/crd/bases/apisix.apache.org_pluginconfigs.yaml
@@ -17,7 +17,7 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: PluginConfig is the Schema for the PluginConfigs API.
+        description: PluginConfig defines plugin configuration.
         properties:
           apiVersion:
             description: |-
@@ -39,10 +39,10 @@ spec:
           spec:
             description: |-
               PluginConfigSpec defines the desired state of a PluginConfig,
-              in which plugins and their configurations are specified.
+              in which plugins and their configuration are specified.
             properties:
               plugins:
-                description: Plugins are an array of plugins and their configurations
+                description: Plugins are an array of plugins and their configuration
                   to be applied.
                 items:
                   properties:
diff --git a/docs/assets/template/gv_details.tpl b/docs/assets/template/gv_details.tpl
index 611ca1c9..eae500cf 100644
--- a/docs/assets/template/gv_details.tpl
+++ b/docs/assets/template/gv_details.tpl
@@ -39,7 +39,7 @@
 
 ### Types
 
-In this section you will find types that the CRDs rely on.
+This section describes the types used by the CRDs.
 
 {{- /* Display Types that are not exported Kinds */ -}}
 {{- range $typ := $gv.SortedTypes -}}
diff --git a/docs/assets/template/gv_list.tpl b/docs/assets/template/gv_list.tpl
index d723151a..974599d0 100644
--- a/docs/assets/template/gv_list.tpl
+++ b/docs/assets/template/gv_list.tpl
@@ -22,11 +22,11 @@
 
 ---
 title: Custom Resource Definitions API Reference
-slug: /reference/apisix-ingress-controller/crd-reference
+slug: /reference/apisix-ingress-controller/api-reference
 description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller.
 ---
 
-This document provides the API resource description the APISIX Ingress Controller custom resource definitions (CRDs).
+This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs).
 
 ## Packages
 {{- range $groupVersions }}
diff --git a/docs/en/latest/api-reference.md b/docs/en/latest/api-reference.md
deleted file mode 100644
index e66c0ba3..00000000
--- a/docs/en/latest/api-reference.md
+++ /dev/null
@@ -1,1589 +0,0 @@
----
-title: Custom Resource Definitions API Reference
-slug: /reference/apisix-ingress-controller/crd-reference
-description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller.
----
-
-This document provides the API resource description the APISIX Ingress Controller custom resource definitions (CRDs).
-
-## Packages
-- [apisix.apache.org/v1alpha1](#apisixapacheorgv1alpha1)
-- [apisix.apache.org/v2](#apisixapacheorgv2)
-
-
-## apisix.apache.org/v1alpha1
-
-Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group
-
-- [BackendTrafficPolicy](#backendtrafficpolicy)
-- [Consumer](#consumer)
-- [GatewayProxy](#gatewayproxy)
-- [HTTPRoutePolicy](#httproutepolicy)
-- [PluginConfig](#pluginconfig)
-### BackendTrafficPolicy
-
-
-
-
-<!-- BackendTrafficPolicy resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
-| `kind` _string_ | `BackendTrafficPolicy`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | BackendTrafficPolicySpec defines traffic handling policies applied to backend services, such as load balancing strategy, connection settings, and failover behavior. |
-
-
-
-### Consumer
-
-
-
-
-<!-- Consumer resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
-| `kind` _string_ | `Consumer`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ConsumerSpec](#consumerspec)_ | ConsumerSpec defines the configuration for a consumer, including consumer name, authentication credentials, and plugin settings. |
-
-
-
-### GatewayProxy
-
-
-GatewayProxy is the Schema for the gatewayproxies API.
-
-<!-- GatewayProxy resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
-| `kind` _string_ | `GatewayProxy`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[GatewayProxySpec](#gatewayproxyspec)_ | GatewayProxySpec defines the desired state and configuration of a GatewayProxy, including networking settings, global plugins, and plugin metadata. |
-
-
-
-### HTTPRoutePolicy
-
-
-HTTPRoutePolicy is the Schema for the httproutepolicies API.
-
-<!-- HTTPRoutePolicy resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
-| `kind` _string_ | `HTTPRoutePolicy`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[HTTPRoutePolicySpec](#httproutepolicyspec)_ | HTTPRoutePolicySpec defines the desired state and configuration of a HTTPRoutePolicy, including route priority and request matching conditions. |
-
-
-
-### PluginConfig
-
-
-PluginConfig is the Schema for the PluginConfigs API.
-
-<!-- PluginConfig resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
-| `kind` _string_ | `PluginConfig`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[PluginConfigSpec](#pluginconfigspec)_ | PluginConfigSpec defines the desired state of a PluginConfig, in which plugins and their configurations are specified. |
-
-
-
-### Types
-
-In this section you will find types that the CRDs rely on.
-#### AdminKeyAuth
-
-
-AdminKeyAuth defines the admin key authentication configuration.
-
-
-
-| Field | Description |
-| --- | --- |
-| `value` _string_ | Value sets the admin key value explicitly (not recommended for production). |
-| `valueFrom` _[AdminKeyValueFrom](#adminkeyvaluefrom)_ | ValueFrom specifies the source of the admin key. |
-
-
-_Appears in:_
-- [ControlPlaneAuth](#controlplaneauth)
-
-#### AdminKeyValueFrom
-
-
-AdminKeyValueFrom defines the source of the admin key.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | SecretKeyRef references a key in a Secret. |
-
-
-_Appears in:_
-- [AdminKeyAuth](#adminkeyauth)
-
-#### AuthType
-_Base type:_ `string`
-
-AuthType defines the type of authentication.
-
-
-
-
-
-_Appears in:_
-- [ControlPlaneAuth](#controlplaneauth)
-
-#### BackendPolicyTargetReferenceWithSectionName
-_Base type:_ `LocalPolicyTargetReferenceWithSectionName`
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `group` _[Group](#group)_ | Group is the group of the target resource. |
-| `kind` _[Kind](#kind)_ | Kind is kind of the target resource. |
-| `name` _[ObjectName](#objectname)_ | Name is the name of the target resource. |
-| `sectionName` _[SectionName](#sectionname)_ | SectionName is the name of a section within the target resource. When unspecified, this targetRef targets the entire resource. In the following resources, SectionName is interpreted as the following:<br /><br /> • Gateway: Listener name<br /> • HTTPRoute: HTTPRouteRule name<br /> • Service: Port name<br /><br /> If a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implement [...]
-
-
-_Appears in:_
-- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
-
-#### BackendTrafficPolicySpec
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `targetRefs` _[BackendPolicyTargetReferenceWithSectionName](#backendpolicytargetreferencewithsectionname) array_ | TargetRef identifies an API object to apply policy to. Currently, Backends (i.e. Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. |
-| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. |
-| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be one of `http`, `https`, `grpc`, or `grpcs`. |
-| `retries` _integer_ | Retries specify the number of times the gateway should retry sending requests when errors such as timeouts or 502 errors occur. |
-| `timeout` _[Timeout](#timeout)_ | Timeout sets the read, send, and connect timeouts to the upstream. |
-| `passHost` _string_ | 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`. |
-| `upstreamHost` _[Hostname](#hostname)_ | UpstreamHost specifies the host of the Upstream request. Used only if passHost is set to `rewrite`. |
-
-
-_Appears in:_
-- [BackendTrafficPolicy](#backendtrafficpolicy)
-
-#### ConsumerSpec
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `gatewayRef` _[GatewayRef](#gatewayref)_ | GatewayRef specifies the gateway details. |
-| `credentials` _[Credential](#credential) array_ | Credentials specifies the credential details of a consumer. |
-| `plugins` _[Plugin](#plugin) array_ | Plugins define the plugins associated with a consumer. |
-
-
-_Appears in:_
-- [Consumer](#consumer)
-
-
-
-#### ControlPlaneAuth
-
-
-ControlPlaneAuth defines the authentication configuration for control plane.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _[AuthType](#authtype)_ | Type specifies the type of authentication. Can only be `AdminKey`. |
-| `adminKey` _[AdminKeyAuth](#adminkeyauth)_ | AdminKey specifies the admin key authentication configuration. |
-
-
-_Appears in:_
-- [ControlPlaneProvider](#controlplaneprovider)
-
-#### ControlPlaneProvider
-
-
-ControlPlaneProvider defines the configuration for control plane provider.
-
-
-
-| Field | Description |
-| --- | --- |
-| `endpoints` _string array_ | Endpoints specifies the list of control plane endpoints. |
-| `service` _[ProviderService](#providerservice)_ |  |
-| `tlsVerify` _boolean_ | TlsVerify specifies whether to verify the TLS certificate of the control plane. |
-| `auth` _[ControlPlaneAuth](#controlplaneauth)_ | Auth specifies the authentication configurations. |
-
-
-_Appears in:_
-- [GatewayProxyProvider](#gatewayproxyprovider)
-
-#### Credential
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _string_ | Type specifies the type of authentication to configure credentials for. Can be one of `jwt-auth`, `basic-auth`, `key-auth`, or `hmac-auth`. |
-| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config specifies the credential details for authentication. |
-| `secretRef` _[SecretReference](#secretreference)_ | SecretRef references to the Secret that contains the credentials. |
-| `name` _string_ | Name is the name of the credential. |
-
-
-_Appears in:_
-- [ConsumerSpec](#consumerspec)
-
-#### GatewayProxyPlugin
-
-
-GatewayProxyPlugin contains plugin configurations.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of the plugin. |
-| `enabled` _boolean_ | Enabled defines whether the plugin is enabled. |
-| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config defines the plugin's configuration details. |
-
-
-_Appears in:_
-- [GatewayProxySpec](#gatewayproxyspec)
-
-#### GatewayProxyProvider
-
-
-GatewayProxyProvider defines the provider configuration for GatewayProxy.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _[ProviderType](#providertype)_ | Type specifies the type of provider. Can only be `ControlPlane`. |
-| `controlPlane` _[ControlPlaneProvider](#controlplaneprovider)_ | ControlPlane specifies the configuration for control plane provider. |
-
-
-_Appears in:_
-- [GatewayProxySpec](#gatewayproxyspec)
-
-#### GatewayProxySpec
-
-
-GatewayProxySpec defines the desired state of GatewayProxy.
-
-
-
-| Field | Description |
-| --- | --- |
-| `publishService` _string_ | PublishService specifies the LoadBalancer-type Service whose external address the controller uses to update the status of Ingress resources. |
-| `statusAddress` _string array_ | StatusAddress specifies the external IP addresses that the controller uses to populate the status field of GatewayProxy or Ingress resources for developers to access. |
-| `provider` _[GatewayProxyProvider](#gatewayproxyprovider)_ | Provider configures the provider details. |
-| `plugins` _[GatewayProxyPlugin](#gatewayproxyplugin) array_ | Plugins configure global plugins. |
-| `pluginMetadata` _object (keys:string, values:[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io))_ | PluginMetadata configures common configurations shared by all plugin instances of the same name. |
-
-
-_Appears in:_
-- [GatewayProxy](#gatewayproxy)
-
-#### GatewayRef
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of the gateway. |
-| `kind` _string_ | Kind is the type of Kubernetes object. Default is `Gateway`. |
-| `group` _string_ | Group is the API group the resource belongs to. Default is `gateway.networking.k8s.io`. |
-| `namespace` _string_ | Namespace is namespace of the resource. |
-
-
-_Appears in:_
-- [ConsumerSpec](#consumerspec)
-
-#### HTTPRoutePolicySpec
-
-
-HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy.
-
-
-
-| Field | Description |
-| --- | --- |
-| `targetRefs` _LocalPolicyTargetReferenceWithSectionName array_ | TargetRef identifies an API object (i.e. HTTPRoute, Ingress) to apply HTTPRoutePolicy to. |
-| `priority` _integer_ | Priority sets the priority for route. A higher value sets a higher priority in route matching. |
-| `vars` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io) array_ | Vars sets the request matching conditions. |
-
-
-_Appears in:_
-- [HTTPRoutePolicy](#httproutepolicy)
-
-#### Hostname
-_Base type:_ `string`
-
-
-
-
-
-
-
-_Appears in:_
-- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
-
-#### LoadBalancer
-
-
-LoadBalancer describes the load balancing parameters.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _string_ | Type specifies the load balancing algorithms. Default is `roundrobin`. Can be one of `roundrobin`, `chash`, `ewma`, or `least_conn`. |
-| `hashOn` _string_ | 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`. |
-| `key` _string_ | 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 [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/). |
-
-
-_Appears in:_
-- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
-
-#### Plugin
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of the plugin. |
-| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config is plugin configuration details. |
-
-
-_Appears in:_
-- [ConsumerSpec](#consumerspec)
-- [PluginConfigSpec](#pluginconfigspec)
-
-#### PluginConfigSpec
-
-
-PluginConfigSpec defines the desired state of PluginConfig.
-
-
-
-| Field | Description |
-| --- | --- |
-| `plugins` _[Plugin](#plugin) array_ | Plugins are an array of plugins and their configurations to be applied. |
-
-
-_Appears in:_
-- [PluginConfig](#pluginconfig)
-
-
-
-#### ProviderService
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ |  |
-| `port` _integer_ |  |
-
-
-_Appears in:_
-- [ControlPlaneProvider](#controlplaneprovider)
-
-#### ProviderType
-_Base type:_ `string`
-
-ProviderType defines the type of provider.
-
-
-
-
-
-_Appears in:_
-- [GatewayProxyProvider](#gatewayproxyprovider)
-
-#### SecretKeySelector
-
-
-SecretKeySelector defines a reference to a specific key within a Secret.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of the secret. |
-| `key` _string_ | Key is the key in the secret to retrieve the secret from. |
-
-
-_Appears in:_
-- [AdminKeyValueFrom](#adminkeyvaluefrom)
-
-#### SecretReference
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of the secret. |
-| `namespace` _string_ | Namespace is the namespace of the secret. |
-
-
-_Appears in:_
-- [Credential](#credential)
-
-#### Status
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#condition-v1-meta) array_ |  |
-
-
-_Appears in:_
-- [ConsumerStatus](#consumerstatus)
-
-#### Timeout
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `connect` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Connection timeout. Default is `60s`. |
-| `send` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Send timeout. Default is `60s`. |
-| `read` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Read timeout. Default is `60s`. |
-
-
-_Appears in:_
-- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
-
-
-## apisix.apache.org/v2
-
-Package v2 contains API Schema definitions for the apisix.apache.org v2 API group.
-
-- [ApisixConsumer](#apisixconsumer)
-- [ApisixGlobalRule](#apisixglobalrule)
-- [ApisixPluginConfig](#apisixpluginconfig)
-- [ApisixRoute](#apisixroute)
-- [ApisixTls](#apisixtls)
-- [ApisixUpstream](#apisixupstream)
-### ApisixConsumer
-
-
-ApisixConsumer is the Schema for the apisixconsumers API.
-
-<!-- ApisixConsumer resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixConsumer`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixConsumerSpec](#apisixconsumerspec)_ |  |
-
-
-
-### ApisixGlobalRule
-
-
-ApisixGlobalRule is the Schema for the apisixglobalrules API.
-
-<!-- ApisixGlobalRule resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixGlobalRule`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixGlobalRuleSpec](#apisixglobalrulespec)_ |  |
-
-
-
-### ApisixPluginConfig
-
-
-ApisixPluginConfig is the Schema for the apisixpluginconfigs API.
-
-<!-- ApisixPluginConfig resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixPluginConfig`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixPluginConfigSpec](#apisixpluginconfigspec)_ |  |
-
-
-
-### ApisixRoute
-
-
-ApisixRoute is the Schema for the apisixroutes API.
-
-<!-- ApisixRoute resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixRoute`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixRouteSpec](#apisixroutespec)_ |  |
-
-
-
-### ApisixTls
-
-
-ApisixTls is the Schema for the apisixtls API.
-
-<!-- ApisixTls resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixTls`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixTlsSpec](#apisixtlsspec)_ |  |
-
-
-
-### ApisixUpstream
-
-
-ApisixUpstream is the Schema for the apisixupstreams API.
-
-<!-- ApisixUpstream resource -->
-
-| Field | Description |
-| --- | --- |
-| `apiVersion` _string_ | `apisix.apache.org/v2`
-| `kind` _string_ | `ApisixUpstream`
-| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
-| `spec` _[ApisixUpstreamSpec](#apisixupstreamspec)_ |  |
-
-
-
-### Types
-
-In this section you will find types that the CRDs rely on.
-#### ActiveHealthCheck
-
-
-ActiveHealthCheck defines the active kind of upstream health check.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _string_ |  |
-| `timeout` _[Duration](#duration)_ |  |
-| `concurrency` _integer_ |  |
-| `host` _string_ |  |
-| `port` _integer_ |  |
-| `httpPath` _string_ |  |
-| `strictTLS` _boolean_ |  |
-| `requestHeaders` _string array_ |  |
-| `healthy` _[ActiveHealthCheckHealthy](#activehealthcheckhealthy)_ |  |
-| `unhealthy` _[ActiveHealthCheckUnhealthy](#activehealthcheckunhealthy)_ |  |
-
-
-_Appears in:_
-- [HealthCheck](#healthcheck)
-
-#### ActiveHealthCheckHealthy
-
-
-ActiveHealthCheckHealthy defines the conditions to judge whether
-an upstream node is healthy with the active manner.
-
-
-
-| Field | Description |
-| --- | --- |
-| `httpCodes` _integer array_ |  |
-| `successes` _integer_ |  |
-| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ |  |
-
-
-_Appears in:_
-- [ActiveHealthCheck](#activehealthcheck)
-
-#### ActiveHealthCheckUnhealthy
-
-
-ActiveHealthCheckUnhealthy defines the conditions to judge whether
-an upstream node is unhealthy with the active manager.
-
-
-
-| Field | Description |
-| --- | --- |
-| `httpCodes` _integer array_ |  |
-| `httpFailures` _integer_ |  |
-| `tcpFailures` _integer_ |  |
-| `timeout` _integer_ |  |
-| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ |  |
-
-
-_Appears in:_
-- [ActiveHealthCheck](#activehealthcheck)
-
-#### ApisixConsumerAuthParameter
-
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `basicAuth` _[ApisixConsumerBasicAuth](#apisixconsumerbasicauth)_ |  |
-| `keyAuth` _[ApisixConsumerKeyAuth](#apisixconsumerkeyauth)_ |  |
-| `wolfRBAC` _[ApisixConsumerWolfRBAC](#apisixconsumerwolfrbac)_ |  |
-| `jwtAuth` _[ApisixConsumerJwtAuth](#apisixconsumerjwtauth)_ |  |
-| `hmacAuth` _[ApisixConsumerHMACAuth](#apisixconsumerhmacauth)_ |  |
-| `ldapAuth` _[ApisixConsumerLDAPAuth](#apisixconsumerldapauth)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerSpec](#apisixconsumerspec)
-
-#### ApisixConsumerBasicAuth
-
-
-ApisixConsumerBasicAuth defines the configuration for basic auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerBasicAuthValue](#apisixconsumerbasicauthvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerBasicAuthValue
-
-
-ApisixConsumerBasicAuthValue defines the in-place username and password configuration for basic auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `username` _string_ |  |
-| `password` _string_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerBasicAuth](#apisixconsumerbasicauth)
-
-#### ApisixConsumerHMACAuth
-
-
-ApisixConsumerHMACAuth defines the configuration for the hmac auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerHMACAuthValue](#apisixconsumerhmacauthvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerHMACAuthValue
-
-
-ApisixConsumerHMACAuthValue defines the in-place configuration for hmac auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `access_key` _string_ |  |
-| `secret_key` _string_ |  |
-| `algorithm` _string_ |  |
-| `clock_skew` _integer_ |  |
-| `signed_headers` _string array_ |  |
-| `keep_headers` _boolean_ |  |
-| `encode_uri_params` _boolean_ |  |
-| `validate_request_body` _boolean_ |  |
-| `max_req_body` _integer_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerHMACAuth](#apisixconsumerhmacauth)
-
-#### ApisixConsumerJwtAuth
-
-
-ApisixConsumerJwtAuth defines the configuration for the jwt auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerJwtAuthValue](#apisixconsumerjwtauthvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerJwtAuthValue
-
-
-ApisixConsumerJwtAuthValue defines the in-place configuration for jwt auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `key` _string_ |  |
-| `secret` _string_ |  |
-| `public_key` _string_ |  |
-| `private_key` _string_ |  |
-| `algorithm` _string_ |  |
-| `exp` _integer_ |  |
-| `base64_secret` _boolean_ |  |
-| `lifetime_grace_period` _integer_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerJwtAuth](#apisixconsumerjwtauth)
-
-#### ApisixConsumerKeyAuth
-
-
-ApisixConsumerKeyAuth defines the configuration for the key auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerKeyAuthValue](#apisixconsumerkeyauthvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerKeyAuthValue
-
-
-ApisixConsumerKeyAuthValue defines the in-place configuration for basic auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `key` _string_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerKeyAuth](#apisixconsumerkeyauth)
-
-#### ApisixConsumerLDAPAuth
-
-
-ApisixConsumerLDAPAuth defines the configuration for the ldap auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerLDAPAuthValue](#apisixconsumerldapauthvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerLDAPAuthValue
-
-
-ApisixConsumerLDAPAuthValue defines the in-place configuration for ldap auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `user_dn` _string_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerLDAPAuth](#apisixconsumerldapauth)
-
-#### ApisixConsumerSpec
-
-
-ApisixConsumerSpec defines the desired state of ApisixConsumer.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. controller implementations use this field to know whether they should be serving this ApisixConsumer resource, by a transitive connection (controller -> IngressClass -> ApisixConsumer resource). |
-| `authParameter` _[ApisixConsumerAuthParameter](#apisixconsumerauthparameter)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumer](#apisixconsumer)
-
-#### ApisixConsumerWolfRBAC
-
-
-ApisixConsumerWolfRBAC defines the configuration for the wolf-rbac auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ |  |
-| `value` _[ApisixConsumerWolfRBACValue](#apisixconsumerwolfrbacvalue)_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
-
-#### ApisixConsumerWolfRBACValue
-
-
-ApisixConsumerWolfRBAC defines the in-place server and appid and header_prefix configuration for wolf-rbac auth.
-
-
-
-| Field | Description |
-| --- | --- |
-| `server` _string_ |  |
-| `appid` _string_ |  |
-| `header_prefix` _string_ |  |
-
-
-_Appears in:_
-- [ApisixConsumerWolfRBAC](#apisixconsumerwolfrbac)
-
-#### ApisixGlobalRuleSpec
-
-
-ApisixGlobalRuleSpec defines the desired state of ApisixGlobalRule.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. The controller uses this field to decide whether the resource should be managed or not. |
-| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins contains a list of ApisixRoutePlugin |
-
-
-_Appears in:_
-- [ApisixGlobalRule](#apisixglobalrule)
-
-#### ApisixMutualTlsClientConfig
-
-
-ApisixMutualTlsClientConfig describes the mutual TLS CA and verify depth
-
-
-
-| Field | Description |
-| --- | --- |
-| `caSecret` _[ApisixSecret](#apisixsecret)_ |  |
-| `depth` _integer_ |  |
-| `skip_mtls_uri_regex` _string array_ |  |
-
-
-_Appears in:_
-- [ApisixTlsSpec](#apisixtlsspec)
-
-#### ApisixPluginConfigSpec
-
-
-ApisixPluginConfigSpec defines the desired state of ApisixPluginConfigSpec.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. The controller uses this field to decide whether the resource should be managed or not. |
-| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins contain a list of ApisixRoutePlugin |
-
-
-_Appears in:_
-- [ApisixPluginConfig](#apisixpluginconfig)
-
-#### ApisixRouteAuthentication
-
-
-ApisixRouteAuthentication is the authentication-related
-configuration in ApisixRoute.
-
-
-
-| Field | Description |
-| --- | --- |
-| `enable` _boolean_ |  |
-| `type` _string_ |  |
-| `keyAuth` _[ApisixRouteAuthenticationKeyAuth](#apisixrouteauthenticationkeyauth)_ |  |
-| `jwtAuth` _[ApisixRouteAuthenticationJwtAuth](#apisixrouteauthenticationjwtauth)_ |  |
-| `ldapAuth` _[ApisixRouteAuthenticationLDAPAuth](#apisixrouteauthenticationldapauth)_ |  |
-
-
-_Appears in:_
-- [ApisixRouteHTTP](#apisixroutehttp)
-
-#### ApisixRouteAuthenticationJwtAuth
-
-
-ApisixRouteAuthenticationJwtAuth is the jwt auth related
-configuration in ApisixRouteAuthentication.
-
-
-
-| Field | Description |
-| --- | --- |
-| `header` _string_ |  |
-| `query` _string_ |  |
-| `cookie` _string_ |  |
-
-
-_Appears in:_
-- [ApisixRouteAuthentication](#apisixrouteauthentication)
-
-#### ApisixRouteAuthenticationKeyAuth
-
-
-ApisixRouteAuthenticationKeyAuth is the keyAuth-related
-configuration in ApisixRouteAuthentication.
-
-
-
-| Field | Description |
-| --- | --- |
-| `header` _string_ |  |
-
-
-_Appears in:_
-- [ApisixRouteAuthentication](#apisixrouteauthentication)
-
-#### ApisixRouteAuthenticationLDAPAuth
-
-
-ApisixRouteAuthenticationLDAPAuth is the LDAP auth related
-configuration in ApisixRouteAuthentication.
-
-
-
-| Field | Description |
-| --- | --- |
-| `base_dn` _string_ |  |
-| `ldap_uri` _string_ |  |
-| `use_tls` _boolean_ |  |
-| `uid` _string_ |  |
-
-
-_Appears in:_
-- [ApisixRouteAuthentication](#apisixrouteauthentication)
-
-#### ApisixRouteHTTP
-
-
-ApisixRouteHTTP represents a single route in for HTTP traffic.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | The rule name, cannot be empty. |
-| `priority` _integer_ | Route priority, when multiple routes contains same URI path (for path matching), route with higher priority will take effect. |
-| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ |  |
-| `match` _[ApisixRouteHTTPMatch](#apisixroutehttpmatch)_ |  |
-| `backends` _[ApisixRouteHTTPBackend](#apisixroutehttpbackend) array_ | Backends represents potential backends to proxy after the route rule matched. When number of backends are more than one, traffic-split plugin in APISIX will be used to split traffic based on the backend weight. |
-| `upstreams` _[ApisixRouteUpstreamReference](#apisixrouteupstreamreference) array_ | Upstreams refer to ApisixUpstream CRD |
-| `websocket` _boolean_ |  |
-| `plugin_config_name` _string_ |  |
-| `plugin_config_namespace` _string_ | By default, PluginConfigNamespace will be the same as the namespace of ApisixRoute |
-| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ |  |
-| `authentication` _[ApisixRouteAuthentication](#apisixrouteauthentication)_ |  |
-
-
-_Appears in:_
-- [ApisixRouteSpec](#apisixroutespec)
-
-#### ApisixRouteHTTPBackend
-
-
-ApisixRouteHTTPBackend represents an HTTP backend (a Kubernetes Service).
-
-
-
-| Field | Description |
-| --- | --- |
-| `serviceName` _string_ | The name (short) of the service, note cross namespace is forbidden, so be sure the ApisixRoute and Service are in the same namespace. |
-| `servicePort` _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#intorstring-intstr-util)_ | The service port, could be the name or the port number. |
-| `resolveGranularity` _string_ | The resolve granularity, can be "endpoints" or "service", when set to "endpoints", the pod ips will be used; other wise, the service ClusterIP or ExternalIP will be used, default is endpoints. |
-| `weight` _integer_ | Weight of this backend. |
-| `subset` _string_ | Subset specifies a subset for the target Service. The subset should be pre-defined in ApisixUpstream about this service. |
-
-
-_Appears in:_
-- [ApisixRouteHTTP](#apisixroutehttp)
-
-#### ApisixRouteHTTPMatch
-
-
-ApisixRouteHTTPMatch represents the match condition for hitting this route.
-
-
-
-| Field | Description |
-| --- | --- |
-| `paths` _string array_ | URI path predicates, at least one path should be configured, path could be exact or prefix, for prefix path, append "*" after it, for instance, "/foo*". |
-| `methods` _string array_ | HTTP request method predicates. |
-| `hosts` _string array_ | HTTP Host predicates, host can be a wildcard domain or an exact domain. For wildcard domain, only one generic level is allowed, for instance, "*.foo.com" is valid but "*.*.foo.com" is not. |
-| `remoteAddrs` _string array_ | Remote address predicates, items can be valid IPv4 address or IPv6 address or CIDR. |
-| `exprs` _[ApisixRouteHTTPMatchExprs](#apisixroutehttpmatchexprs)_ | NginxVars represents generic match predicates, it uses Nginx variable systems, so any predicate like headers, querystring and etc can be leveraged here to match the route. For instance, it can be: nginxVars:   - subject: "$remote_addr"     op: in     value:       - "127.0.0.1"       - "10.0.5.11" |
-| `filter_func` _string_ | Matches based on a user-defined filtering function. These functions can accept an input parameter `vars` which can be used to access the Nginx variables. |
-
-
-_Appears in:_
-- [ApisixRouteHTTP](#apisixroutehttp)
-
-#### ApisixRouteHTTPMatchExpr
-
-
-ApisixRouteHTTPMatchExpr represents a binary route match expression .
-
-
-
-| Field | Description |
-| --- | --- |
-| `subject` _[ApisixRouteHTTPMatchExprSubject](#apisixroutehttpmatchexprsubject)_ | Subject is the expression subject, it can be any string composed by literals and nginx vars. |
-| `op` _string_ | Op is the operator. |
-| `set` _string array_ | Set is an array type object of the expression. It should be used when the Op is "in" or "not_in"; |
-| `value` _string_ | Value is the normal type object for the expression, it should be used when the Op is not "in" and "not_in". Set and Value are exclusive so only of them can be set in the same time. |
-
-
-_Appears in:_
-- [ApisixRouteHTTPMatchExprs](#apisixroutehttpmatchexprs)
-
-#### ApisixRouteHTTPMatchExprSubject
-
-
-ApisixRouteHTTPMatchExprSubject describes the route match expression subject.
-
-
-
-| Field | Description |
-| --- | --- |
-| `scope` _string_ | The subject scope, can be: ScopeQuery, ScopeHeader, ScopePath when subject is ScopePath, Name field will be ignored. |
-| `name` _string_ | The name of subject. |
-
-
-_Appears in:_
-- [ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)
-
-#### ApisixRouteHTTPMatchExprs
-_Base type:_ `[ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)`
-
-
-
-
-
-| Field | Description |
-| --- | --- |
-| `subject` _[ApisixRouteHTTPMatchExprSubject](#apisixroutehttpmatchexprsubject)_ | Subject is the expression subject, it can be any string composed by literals and nginx vars. |
-| `op` _string_ | Op is the operator. |
-| `set` _string array_ | Set is an array type object of the expression. It should be used when the Op is "in" or "not_in"; |
-| `value` _string_ | Value is the normal type object for the expression, it should be used when the Op is not "in" and "not_in". Set and Value are exclusive so only of them can be set in the same time. |
-
-
-_Appears in:_
-- [ApisixRouteHTTPMatch](#apisixroutehttpmatch)
-
-#### ApisixRoutePlugin
-
-
-ApisixRoutePlugin represents an APISIX plugin.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | The plugin name. |
-| `enable` _boolean_ | Whether this plugin is in use, default is true. |
-| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Plugin configuration. |
-| `secretRef` _string_ | Plugin configuration secretRef. |
-
-
-_Appears in:_
-- [ApisixGlobalRuleSpec](#apisixglobalrulespec)
-- [ApisixPluginConfigSpec](#apisixpluginconfigspec)
-- [ApisixRouteHTTP](#apisixroutehttp)
-- [ApisixRouteStream](#apisixroutestream)
-
-
-
-#### ApisixRouteSpec
-
-
-ApisixRouteSpec is the spec definition for ApisixRouteSpec.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ |  |
-| `http` _[ApisixRouteHTTP](#apisixroutehttp) array_ |  |
-| `stream` _[ApisixRouteStream](#apisixroutestream) array_ |  |
-
-
-_Appears in:_
-- [ApisixRoute](#apisixroute)
-
-#### ApisixRouteStream
-
-
-ApisixRouteStream is the configuration for level 4 route
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | The rule name cannot be empty. |
-| `protocol` _string_ |  |
-| `match` _[ApisixRouteStreamMatch](#apisixroutestreammatch)_ |  |
-| `backend` _[ApisixRouteStreamBackend](#apisixroutestreambackend)_ |  |
-| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ |  |
-
-
-_Appears in:_
-- [ApisixRouteSpec](#apisixroutespec)
-
-#### ApisixRouteStreamBackend
-
-
-ApisixRouteStreamBackend represents a TCP backend (a Kubernetes Service).
-
-
-
-| Field | Description |
-| --- | --- |
-| `serviceName` _string_ | The name (short) of the service, note cross namespace is forbidden, so be sure the ApisixRoute and Service are in the same namespace. |
-| `servicePort` _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#intorstring-intstr-util)_ | The service port, could be the name or the port number. |
-| `resolveGranularity` _string_ | The resolve granularity, can be "endpoints" or "service", when set to "endpoints", the pod ips will be used; other wise, the service ClusterIP or ExternalIP will be used, default is endpoints. |
-| `subset` _string_ | Subset specifies a subset for the target Service. The subset should be pre-defined in ApisixUpstream about this service. |
-
-
-_Appears in:_
-- [ApisixRouteStream](#apisixroutestream)
-
-#### ApisixRouteStreamMatch
-
-
-ApisixRouteStreamMatch represents the match conditions of stream route.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressPort` _integer_ | IngressPort represents the port listening on the Ingress proxy server. It should be pre-defined as APISIX doesn't support dynamic listening. |
-| `host` _string_ |  |
-
-
-_Appears in:_
-- [ApisixRouteStream](#apisixroutestream)
-
-#### ApisixRouteUpstreamReference
-
-
-ApisixRouteUpstreamReference contains a ApisixUpstream CRD reference
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ |  |
-| `weight` _integer_ |  |
-
-
-_Appears in:_
-- [ApisixRouteHTTP](#apisixroutehttp)
-
-#### ApisixSecret
-
-
-ApisixSecret describes the Kubernetes Secret name and namespace.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ |  |
-| `namespace` _string_ |  |
-
-
-_Appears in:_
-- [ApisixMutualTlsClientConfig](#apisixmutualtlsclientconfig)
-- [ApisixTlsSpec](#apisixtlsspec)
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-#### ApisixTlsSpec
-
-
-ApisixTlsSpec defines the desired state of ApisixTls.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. controller implementations use this field to know whether they should be serving this ApisixTls resource, by a transitive connection (controller -> IngressClass -> ApisixTls resource). |
-| `hosts` _[HostType](#hosttype) array_ |  |
-| `secret` _[ApisixSecret](#apisixsecret)_ |  |
-| `client` _[ApisixMutualTlsClientConfig](#apisixmutualtlsclientconfig)_ |  |
-
-
-_Appears in:_
-- [ApisixTls](#apisixtls)
-
-#### ApisixUpstreamConfig
-
-
-ApisixUpstreamConfig contains rich features on APISIX Upstream, for instance
-load balancer, health check, etc.
-
-
-
-| Field | Description |
-| --- | --- |
-| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. |
-| `scheme` _string_ | The scheme used to talk with the upstream. Now value can be http, grpc. |
-| `retries` _integer_ | How many times that the proxy (Apache APISIX) should do when errors occur (error, timeout or bad http status codes like 500, 502). |
-| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout settings for the read, send and connect to the upstream. |
-| `healthCheck` _[HealthCheck](#healthcheck)_ | Deprecated: this is no longer support on standalone mode. The health check configurations for the upstream. |
-| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | Set the client certificate when connecting to TLS upstream. |
-| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets groups the service endpoints by their labels. Usually used to differentiate service versions. |
-| `passHost` _string_ | Configures the host when the request is forwarded to the upstream. Can be one of pass, node or rewrite. |
-| `upstreamHost` _string_ | Specifies the host of the Upstream request. This is only valid if the pass_host is set to rewrite |
-| `discovery` _[Discovery](#discovery)_ | Deprecated: this is no longer support on standalone mode. Discovery is used to configure service discovery for upstream. |
-
-
-_Appears in:_
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-#### ApisixUpstreamExternalNode
-
-
-ApisixUpstreamExternalNode is the external node conf
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ |  |
-| `type` _[ApisixUpstreamExternalType](#apisixupstreamexternaltype)_ |  |
-| `weight` _integer_ |  |
-| `port` _integer_ | Port defines the port of the external node |
-
-
-_Appears in:_
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-
-#### ApisixUpstreamExternalType
-_Base type:_ `string`
-
-ApisixUpstreamExternalType is the external service type
-
-
-
-
-
-_Appears in:_
-- [ApisixUpstreamExternalNode](#apisixupstreamexternalnode)
-
-#### ApisixUpstreamSpec
-
-
-ApisixUpstreamSpec describes the specification of ApisixUpstream.
-
-
-
-| Field | Description |
-| --- | --- |
-| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. controller implementations use this field to know whether they should be serving this ApisixUpstream resource, by a transitive connection (controller -> IngressClass -> ApisixUpstream resource). |
-| `externalNodes` _[ApisixUpstreamExternalNode](#apisixupstreamexternalnode) array_ | ExternalNodes contains external nodes the Upstream should use If this field is set, the upstream will use these nodes directly without any further resolves |
-| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. |
-| `scheme` _string_ | The scheme used to talk with the upstream. Now value can be http, grpc. |
-| `retries` _integer_ | How many times that the proxy (Apache APISIX) should do when errors occur (error, timeout or bad http status codes like 500, 502). |
-| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout settings for the read, send and connect to the upstream. |
-| `healthCheck` _[HealthCheck](#healthcheck)_ | Deprecated: this is no longer support on standalone mode. The health check configurations for the upstream. |
-| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | Set the client certificate when connecting to TLS upstream. |
-| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets groups the service endpoints by their labels. Usually used to differentiate service versions. |
-| `passHost` _string_ | Configures the host when the request is forwarded to the upstream. Can be one of pass, node or rewrite. |
-| `upstreamHost` _string_ | Specifies the host of the Upstream request. This is only valid if the pass_host is set to rewrite |
-| `discovery` _[Discovery](#discovery)_ | Deprecated: this is no longer support on standalone mode. Discovery is used to configure service discovery for upstream. |
-| `portLevelSettings` _[PortLevelSettings](#portlevelsettings) array_ |  |
-
-
-_Appears in:_
-- [ApisixUpstream](#apisixupstream)
-
-#### ApisixUpstreamSubset
-
-
-ApisixUpstreamSubset defines a single endpoints group of one Service.
-
-
-
-| Field | Description |
-| --- | --- |
-| `name` _string_ | Name is the name of subset. |
-| `labels` _object (keys:string, values:string)_ | Labels is the label set of this subset. |
-
-
-_Appears in:_
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-#### Discovery
-
-
-Discovery defines Service discovery related configuration.
-
-
-
-| Field | Description |
-| --- | --- |
-| `serviceName` _string_ |  |
-| `type` _string_ |  |
-| `args` _object (keys:string, values:string)_ |  |
-
-
-_Appears in:_
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-#### HealthCheck
-
-
-HealthCheck describes the upstream health check parameters.
-
-
-
-| Field | Description |
-| --- | --- |
-| `active` _[ActiveHealthCheck](#activehealthcheck)_ |  |
-| `passive` _[PassiveHealthCheck](#passivehealthcheck)_ |  |
-
-
-_Appears in:_
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-#### HostType
-_Base type:_ `string`
-
-
-
-
-
-
-
-_Appears in:_
-- [ApisixTlsSpec](#apisixtlsspec)
-
-#### LoadBalancer
-
-
-LoadBalancer describes the load balancing parameters.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _string_ |  |
-| `hashOn` _string_ | The HashOn and Key fields are required when Type is "chash". HashOn represents the key fetching scope. |
-| `key` _string_ | Key represents the hash key. |
-
-
-_Appears in:_
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
-#### PassiveHealthCheck
-
-
-PassiveHealthCheck defines the conditions to judge whether
-an upstream node is healthy with the passive manager.
-
-
-
-| Field | Description |
-| --- | --- |
-| `type` _string_ |  |
-| `healthy` _[PassiveHealthCheckHealthy](#passivehealthcheckhealthy)_ |  |
-| `unhealthy` _[PassiveHealthCheckUnhealthy](#passivehealthcheckunhealthy)_ |  |
-
-
-_Appears in:_
-- [HealthCheck](#healthcheck)
-
-#### PassiveHealthCheckHealthy
-
-
-PassiveHealthCheckHealthy defines the conditions to judge whether
-an upstream node is healthy with the passive manner.
-
-
-
-| Field | Description |
-| --- | --- |
-| `httpCodes` _integer array_ |  |
-| `successes` _integer_ |  |
-
-
-_Appears in:_
-- [ActiveHealthCheckHealthy](#activehealthcheckhealthy)
-- [PassiveHealthCheck](#passivehealthcheck)
-
-#### PassiveHealthCheckUnhealthy
-
-
-PassiveHealthCheckUnhealthy defines the conditions to judge whether
-an upstream node is unhealthy with the passive manager.
-
-
-
-| Field | Description |
-| --- | --- |
-| `httpCodes` _integer array_ |  |
-| `httpFailures` _integer_ |  |
-| `tcpFailures` _integer_ |  |
-| `timeout` _integer_ |  |
-
-
-_Appears in:_
-- [ActiveHealthCheckUnhealthy](#activehealthcheckunhealthy)
-- [PassiveHealthCheck](#passivehealthcheck)
-
-#### PortLevelSettings
-
-
-PortLevelSettings configures the ApisixUpstreamConfig for each individual port. It inherits
-configurations from the outer level (the whole Kubernetes Service) and overrides some of
-them if they are set on the port level.
-
-
-
-| Field | Description |
-| --- | --- |
-| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. |
-| `scheme` _string_ | The scheme used to talk with the upstream. Now value can be http, grpc. |
-| `retries` _integer_ | How many times that the proxy (Apache APISIX) should do when errors occur (error, timeout or bad http status codes like 500, 502). |
-| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout settings for the read, send and connect to the upstream. |
-| `healthCheck` _[HealthCheck](#healthcheck)_ | Deprecated: this is no longer support on standalone mode. The health check configurations for the upstream. |
-| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | Set the client certificate when connecting to TLS upstream. |
-| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets groups the service endpoints by their labels. Usually used to differentiate service versions. |
-| `passHost` _string_ | Configures the host when the request is forwarded to the upstream. Can be one of pass, node or rewrite. |
-| `upstreamHost` _string_ | Specifies the host of the Upstream request. This is only valid if the pass_host is set to rewrite |
-| `discovery` _[Discovery](#discovery)_ | Deprecated: this is no longer support on standalone mode. Discovery is used to configure service discovery for upstream. |
-| `port` _integer_ | Port is a Kubernetes Service port, it should be already defined. |
-
-
-_Appears in:_
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-
-
-
-
-
-
-
-#### UpstreamTimeout
-
-
-UpstreamTimeout is settings for the read, send and connect to the upstream.
-
-
-
-| Field | Description |
-| --- | --- |
-| `connect` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ |  |
-| `send` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ |  |
-| `read` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ |  |
-
-
-_Appears in:_
-- [ApisixRouteHTTP](#apisixroutehttp)
-- [ApisixUpstreamConfig](#apisixupstreamconfig)
-- [ApisixUpstreamSpec](#apisixupstreamspec)
-- [PortLevelSettings](#portlevelsettings)
-
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 5094cb52..c7c5e92f 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -3,7 +3,18 @@
     "sidebar": [
         {
             "type": "doc",
-            "id": "getting-started"
+            "id": "overview"
+        },
+        {
+            "type": "category",
+            "label": "Getting Started",
+            "items": [
+                "get-apisix-ingress-controller",
+                "configure-routes",
+                "load-balancing",
+                "key-authentication",
+                "rate-limiting"
+            ]
         },
         {
             "type": "category",
@@ -23,8 +34,12 @@
             "id": "developer-guide"
         },
         {
-            "type": "doc",
-            "id": "api-reference"
+            "type": "category",
+            "label": "Reference",
+            "items": [
+                "reference/api-reference",
+                "reference/example"
+            ]
         },
         {
             "type": "doc",
diff --git a/docs/en/latest/getting-started/configure-routes.md b/docs/en/latest/getting-started/configure-routes.md
new file mode 100644
index 00000000..e248e981
--- /dev/null
+++ b/docs/en/latest/getting-started/configure-routes.md
@@ -0,0 +1,198 @@
+---
+title: Configure Routes
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Learn how to create routes in APISIX using APISIX Ingress controller to forward client to upstream services.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Apache APISIX provides flexible gateway management capabilities based on routes, in which routing paths and target upstreams are defined.
+
+This tutorial guides you through creating a Route using the APISIX Ingress Controller and verifying its behavior. You’ll configure a Route to a sample Upstream pointing to an httpbin service, then send a request to observe how APISIX proxies the traffic.
+
+## Prerequisites
+
+1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md).
+
+## Set Up a Sample Upstream
+
+Install the httpbin example application on the cluster to test the configuration:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml
+```
+
+## Configure a Route
+
+In this section, you will create a Route that forwards client requests to the httpbin example application, an HTTP request and response service.
+
+You can use either Gateway API, Ingress, or APISIX CRD resources to configure the route.
+
+:::important
+
+If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: apisix
+spec:
+  controllerName: apisix.apache.org/apisix-ingress-controller
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: apisix
+spec:
+  gatewayClassName: apisix
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+  infrastructure:
+    parametersRef:
+      group: apisix.apache.org
+      kind: GatewayProxy
+      name: apisix-config
+```
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+
+:::
+
+Create a Kubernetes manifest file for a Route that proxy requests to httpbin:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'Ingress', value: 'ingress-rs'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: getting-started-ip
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches:
+    - path:
+        type: Exact
+        value: /ip
+    backendRefs:
+    - name: httpbin
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="ingress-rs">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: getting-started-ip
+spec:
+  ingressClassName: apisix
+  rules:
+    - http:
+        paths:
+          - backend:
+              service:
+                name: httpbin
+                port:
+                  number: 80
+            path: /ip
+            pathType: Exact
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: getting-started-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: getting-started-ip
+      match:
+        paths:
+          - /ip
+      backends:
+        - serviceName: httpbin
+          servicePort: 80
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configurations to your cluster:
+
+```shell
+kubectl apply -f httpbin-route.yaml
+```
+
+## Verify
+
+Expose the service port to your local machine by port forwarding:
+
+```shell
+kubectl port-forward svc/apisix-gateway 9080:80 &
+```
+
+Send a request to the Route:
+
+```shell
+curl "http://127.0.0.1:9080/ip"
+```
+
+You should see a response similar to the following:
+
+```json
+{
+  "origin": "127.0.0.1"
+}
+```
diff --git a/docs/en/latest/getting-started/get-apisix-ingress-controller.md b/docs/en/latest/getting-started/get-apisix-ingress-controller.md
new file mode 100644
index 00000000..fd977d1a
--- /dev/null
+++ b/docs/en/latest/getting-started/get-apisix-ingress-controller.md
@@ -0,0 +1,135 @@
+---
+title: Get APISIX and APISIX Ingress Controller
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Learn how to quickly install and set up Apache APISIX Ingres Controller.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+APISIX Ingress Controller is a [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy.
+
+APISIX Ingress Controller can be configured using the native Kubernetes Ingress or Gateway API, as well as with APISIX’s own declarative and easy-to-use custom resources. The controller translates these resources into APISIX configuration.
+
+This tutorial series walks you through how to quickly get started with APISIX on a [kind](https://kind.sigs.k8s.io) Kubernetes cluster and use the APISIX Ingress Controller to manage resources.
+
+## Prerequisites
+
+* Install [Docker](https://docs.docker.com/get-docker/) as a dependency of [kind](https://kind.sigs.k8s.io).
+* Install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to start a local Kubernetes cluster, or use any existing Kubernetes cluster (version 1.26+).
+* Install [Helm](https://helm.sh/docs/intro/install/) (version 3.8+).
+* Install [kubectl](https://kubernetes.io/docs/tasks/tools/) to run commands against Kubernetes clusters.
+
+## Create a Cluster and Configure Namespace
+
+In this section, you will be creating a kind cluster and configuring the namespace. Skip to [the next section](#install-apisix-and-apisix-ingress-controller-standalone-api-driven-mode) if you already have an existing cluster and a corresponding namspace.
+
+Ensure you have Docker running and start a kind cluster:
+
+```shell
+kind create cluster
+```
+
+Create a new namespace `ingress-apisix`:
+
+```shell
+kubectl create namespace ingress-apisix
+```
+
+Set the namespace to `ingress-apisix` to avoid specifying it explicitly in each subsequent command:
+
+```shell
+kubectl config set-context --current --namespace=ingress-apisix
+```
+
+## Install APISIX and APISIX Ingress Controller (Standalone API-driven mode)
+
+Install the Gateway API CRDs, [APISIX Standalone API-driven mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), and APISIX Ingress Controller:
+
+```bash
+helm repo add apisix https://charts.apiseven.com
+helm repo update
+
+helm install apisix \
+  --namespace ingress-apisix \
+  --create-namespace \
+  --set apisix.deployment.role=traditional \
+  --set apisix.deployment.role_traditional.config_provider=yaml \
+  --set etcd.enabled=false \
+  --set ingress-controller.enabled=true \
+  --set ingress-controller.config.provider.type=apisix-standalone \
+  --set ingress-controller.apisix.adminService.namespace=ingress-apisix \
+  --set ingress-controller.gatewayProxy.createDefault=true \
+  apisix/apisix
+```
+
+More details on the installation can be found in the [Installation Guide](../install.md).
+
+## Verify Installation
+
+Check the statuses of resources in the current namespace:
+
+```shell
+kubectl get all
+```
+
+You should wait for all pods to be running before proceeding:
+
+```text
+NAME                                             READY   STATUS    RESTARTS   AGE
+pod/apisix-7c5fb8d546-gtfqn                      1/1     Running   0          113s
+pod/apisix-ingress-controller-56c46fd54f-f8fxt   1/1     Running   0          113s
+
+NAME                             TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
+service/apisix-admin             ClusterIP   10.96.174.119   <none>        9180/TCP       113s
+service/apisix-gateway           NodePort    10.96.231.33    <none>        80:31321/TCP   113s
+service/apisix-metrics-service   ClusterIP   10.96.77.248    <none>        8443/TCP       113s
+
+NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
+deployment.apps/apisix                      1/1     1            1           113s
+deployment.apps/apisix-ingress-controller   1/1     1            1           113s
+
+NAME                                                   DESIRED   CURRENT   READY   AGE
+replicaset.apps/apisix-7c5fb8d546                      1         1         1       113s
+replicaset.apps/apisix-ingress-controller-56c46fd54f   1         1         1       113s
+```
+
+To verify the installed APISIX version, map port `80` of the `apisix-gateway` service to port `8080` on the local machine:
+
+```shell
+kubectl port-forward svc/apisix-gateway 9080:80 &
+```
+
+Send a request to the gateway:
+
+```shell
+curl -sI "http://127.0.0.1:9080" | grep Server
+```
+
+If everything is ok, you should see the APISIX version:
+
+```text
+Server: APISIX/x.x.x
+```
diff --git a/docs/en/latest/getting-started/key-authentication.md b/docs/en/latest/getting-started/key-authentication.md
new file mode 100644
index 00000000..0c7e38e8
--- /dev/null
+++ b/docs/en/latest/getting-started/key-authentication.md
@@ -0,0 +1,250 @@
+---
+title: Key Authentication
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Explore how to configure key authentication in APISIX using APISIX Ingress Controller, which implement access control to your APIs.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+APISIX has a flexible plugin extension system and a number of existing plugins for user authentication and authorization.
+
+In this tutorial, you will create a Consumer, configure its key authentication Credential, and enable key authentication on a route, using APISIX Ingress Controller.
+
+## Prerequisite
+
+1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md).
+
+## Configure Key Authentication
+
+For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org). If you would like to proxy requests to services on Kubernetes, please modify accordingly.
+
+:::important
+
+If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: apisix
+spec:
+  controllerName: apisix.apache.org/apisix-ingress-controller
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: apisix
+spec:
+  gatewayClassName: apisix
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+  infrastructure:
+    parametersRef:
+      group: apisix.apache.org
+      kind: GatewayProxy
+      name: apisix-config
+```
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+
+:::
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+Create a Kubernetes manifest file to configure a consumer:
+
+```yaml title="consumer.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+  name: tom
+spec:
+  gatewayRef:
+    name: apisix
+  credentials:
+    - type: key-auth
+      name: primary-key
+      config:
+        key: secret-key
+```
+
+Create a Kubernetes manifest file to configure a route and enable key authentication:
+
+```yaml title="httpbin-route.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin-external-domain
+spec:
+  type: ExternalName
+  externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+  name: auth-plugin-config
+spec:
+  plugins:
+    - name: key-auth
+      config:
+        _meta:
+          disable: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: getting-started-ip
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches: 
+    - path:
+        type: Exact
+        value: /ip
+    filters:
+    - type: ExtensionRef
+      extensionRef:
+        group: apisix.apache.org
+        kind: PluginConfig
+        name: auth-plugin-config
+    backendRefs:
+    - name: httpbin-external-domain
+      port: 80
+```
+
+Apply the configurations to your cluster:
+
+```shell
+kubectl apply -f consumer.yaml -f httpbin-route.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Kubernetes manifest file to configure a consumer:
+
+```yaml title="consumer.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+  name: tom
+spec:
+  ingressClassName: apisix
+  authParameter:
+    keyAuth:
+      value:
+        key: secret-key
+```
+
+Create a Kubernetes manifest file to configure a route and enable key authentication:
+
+```yaml title="httpbin-route.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin-external-domain
+spec:
+  externalNodes:
+  - type: Domain
+    name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: getting-started-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: getting-started-ip
+      match:
+        paths:
+          - /ip
+      upstreams:
+      - name: httpbin-external-domain
+      authentication:
+        enable: true
+        type: keyAuth
+```
+
+Apply the configurations to your cluster:
+
+```shell
+kubectl apply -f consumer.yaml -f httpbin-route.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+## Verify
+
+Expose the service port to your local machine by port forwarding:
+
+```shell
+kubectl port-forward svc/apisix-gateway 9080:80 &
+```
+
+Send a request without the `apikey` header.
+
+```shell
+curl -i "http://127.0.0.1:9080/ip"
+```
+
+You should receive an an `HTTP/1.1 401 Unauthorized` response.
+
+Send a request with a wrong key in the `apikey` header.
+
+```shell
+curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key'
+```
+
+Since the key is incorrect, you should receive an `HTTP/1.1 401 Unauthorized` response.
+
+Send a request with the correct key in the `apikey` header.
+
+```shell
+curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key'
+```
+
+You should receive an `HTTP/1.1 200 OK` response.
diff --git a/docs/en/latest/getting-started/load-balancing.md b/docs/en/latest/getting-started/load-balancing.md
new file mode 100644
index 00000000..ee6d2f04
--- /dev/null
+++ b/docs/en/latest/getting-started/load-balancing.md
@@ -0,0 +1,177 @@
+---
+title: Load Balancing
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Learn how to implement load balancing in APISIX using APISIX Ingress Controller, distributing clients requests across multiple upstream nodes.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Load balancing is a technique used to distribute network request loads. It is a key consideration in designing systems that need to handle a large volume of traffic, allowing for improved system performance, scalability, and reliability.
+
+In this tutorial, you will create a route using APISIX Ingress Controller with two upstream services and uses the round-robin load balancing algorithm to load balance requests.
+
+## Prerequisite
+
+1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md).
+
+## Configure Load Balancing
+
+For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org) and [mock.api7.ai](https://mock.api7.ai). If you would like to proxy requests to services on Kubernetes, please modify accordingly.
+
+:::important
+
+If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: apisix
+spec:
+  controllerName: apisix.apache.org/apisix-ingress-controller
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: apisix
+spec:
+  gatewayClassName: apisix
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+  infrastructure:
+    parametersRef:
+      group: apisix.apache.org
+      kind: GatewayProxy
+      name: apisix-config
+```
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+
+:::
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+APISIX Ingress controller installed with the current helm chart version (`apisix-2.11.2`) has a bug in load balancing, which is actively being fixed.
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Create a Kubernetes manifest file for a route that proxy requests to two upstream services for load balancing:
+
+```yaml title="lb-route.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin-external-domain
+spec:
+  scheme: https
+  passHost: node
+  externalNodes:
+  - type: Domain
+    name: httpbin.org
+    weight: 1
+    port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: mockapi7-external-domain
+spec:
+  scheme: https
+  passHost: node
+  externalNodes:
+  - type: Domain
+    name: mock.api7.ai
+    weight: 1
+    port: 443
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: lb-route
+spec:
+  ingressClassName: apisix
+  http:
+    - name: lb-route
+      match:
+        paths:
+          - /headers
+      upstreams:
+      - name: httpbin-external-domain
+      - name: mockapi7-external-domain
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f lb-route.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+## Verify
+
+Expose the service port to your local machine by port forwarding:
+
+```shell
+kubectl port-forward svc/apisix-gateway 9080:80 &
+```
+
+Generate 50 consecutive requests to the route to see the load-balancing effect:
+
+```shell
+resp=$(seq 50 | xargs -I{} curl "http://127.0.0.1:9080/headers" -sL) && \
+  count_httpbin=$(echo "$resp" | grep "httpbin.org" | wc -l) && \
+  count_mockapi7=$(echo "$resp" | grep "mock.api7.ai" | wc -l) && \
+  echo httpbin.org: $count_httpbin, mock.api7.ai: $count_mockapi7
+```
+
+The command keeps count of the number of requests that was handled by the two services respectively. The output shows that requests were distributed over to the two services:
+
+```text
+httpbin.org: 23, mock.api7.ai: 27
+```
+
+The distribution of requests across services should be close to 1:1 but might not always result in a perfect 1:1 ratio. The slight deviation is due to APISIX operates with multiple workers.
diff --git a/docs/en/latest/getting-started/rate-limiting.md b/docs/en/latest/getting-started/rate-limiting.md
new file mode 100644
index 00000000..82a5f272
--- /dev/null
+++ b/docs/en/latest/getting-started/rate-limiting.md
@@ -0,0 +1,206 @@
+---
+title: Rate Limiting
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Implement rate limiting in APISIX using APISIX Ingress Controller to control traffic flow, protect your APIs from misuse, and ensure fair usage by setting request limits.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Rate limiting is one of the commonly used techniques to protect and manage APIs. For example, you can configure your API endpoints to allow for a set number of requests within a given period of time. This ensures fair usage of the upstream services and safeguards the APIs from potential cyber attacks like DDoS (Distributed Denial of Service) or excessive requests from web crawlers.
+
+In this tutorial, you will enable the `limit-count` plugin to set a rate limiting constraint on the incoming traffic, using APISIX Ingress Controller.
+
+## Prerequisite
+
+1. Complete [Get APISIX and APISIX Ingress Controller](./get-apisix-ingress-controller.md).
+
+## Configure Rate Limiting
+
+For demonstration purpose, you will be creating a route to the [publicly hosted httpbin services](https://httpbin.org) and [mock.api7.ai](https://mock.api7.ai). If you would like to proxy requests to services on Kubernetes, please modify accordingly.
+
+:::important
+
+If you are using Gateway API, you should first configure the GatewayClass and Gateway resources:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: apisix
+spec:
+  controllerName: apisix.apache.org/apisix-ingress-controller
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: apisix
+spec:
+  gatewayClassName: apisix
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+  infrastructure:
+    parametersRef:
+      group: apisix.apache.org
+      kind: GatewayProxy
+      name: apisix-config
+```
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+
+:::
+
+Create a Kubernetes manifest file for a route and enable `limit-count`:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin-external-domain
+spec:
+  type: ExternalName
+  externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+  name: limit-count-plugin-config
+spec:
+  plugins:
+    - name: limit-count
+      config:
+        count: 2
+        time_window: 10
+        rejected_code: 429
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: getting-started-ip
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches: 
+    - path:
+        type: Exact
+        value: /ip
+    filters:
+    - type: ExtensionRef
+      extensionRef:
+        group: apisix.apache.org
+        kind: PluginConfig
+        name: limit-count-plugin-config
+    backendRefs:
+    - name: httpbin-external-domain
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin-external-domain
+spec:
+  externalNodes:
+  - type: Domain
+    name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: getting-started-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: getting-started-ip
+      match:
+        paths:
+          - /ip
+      upstreams:
+      - name: httpbin-external-domain
+      plugins:
+      - name: limit-count
+        enable: true
+        config:
+          count: 2
+          time_window: 10
+          rejected_code: 429
+```
+
+</TabItem>
+
+</Tabs>
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f httpbin-route.yaml
+```
+
+## Verify
+
+Expose the service port to your local machine by port forwarding:
+
+```shell
+kubectl port-forward svc/apisix-gateway 9080:80 &
+```
+
+Generate 50 simultaneous requeststo the route:
+
+```shell
+resp=$(seq 50 | xargs -I{} curl "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200": $count_200, "429": $count_429
+```
+
+The results are as expected: out of the 50 requests, 2 requests were sent successfully (status code `200`) while the others were rejected (status code `429`).
+
+```text
+"200": 2, "429": 48
+```
diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/overview.md
similarity index 52%
rename from docs/en/latest/getting-started.md
rename to docs/en/latest/overview.md
index fc8d0213..954ebb7a 100644
--- a/docs/en/latest/getting-started.md
+++ b/docs/en/latest/overview.md
@@ -1,11 +1,12 @@
 ---
-title: Getting started
+title: Overview
 keywords:
   - APISIX ingress
   - Apache APISIX
   - Kubernetes ingress
-description: Guide to get started with Apache APISIX ingress controller.
+description: Overview of the APISIX Ingress Controller, its features, APISIX compatibility, and how to contribute to the project.
 ---
+
 <!--
 #
 # Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,135 +26,11 @@ description: Guide to get started with Apache APISIX ingress controller.
 #
 -->
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 APISIX Ingress Controller is a [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy.
 
 APISIX Ingress Controller can be configured using the native Kubernetes Ingress or Gateway API, as well as with APISIX’s own declarative and easy-to-use custom resources. The controller translates these resources into APISIX configuration.
 
-## Quick Start
-
-Get started with APISIX Ingress Controller in a few simple steps.
-
-### Prerequisites
-
-Before installing APISIX Ingress Controller, ensure you have:
-
-1. A working Kubernetes cluster (version 1.26+)
-2. [Helm](https://helm.sh/) (version 3.8+) installed
-
-### Install APISIX and APISIX Ingress Controller (Standalone API-driven mode)
-
-Install the Gateway API CRDs, [APISIX Standalone API-driven mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), and APISIX Ingress Controller using the following commands:
-
-```bash
-helm repo add apisix https://charts.apiseven.com
-helm repo add bitnami https://charts.bitnami.com/bitnami
-helm repo update
-
-helm install apisix \
-  --namespace ingress-apisix \
-  --create-namespace \
-  --set apisix.deployment.role=traditional \
-  --set apisix.deployment.role_traditional.config_provider=yaml \
-  --set etcd.enabled=false \
-  --set ingress-controller.enabled=true \
-  --set ingress-controller.config.provider.type=apisix-standalone \
-  --set ingress-controller.apisix.adminService.namespace=ingress-apisix \
-  --set ingress-controller.gatewayProxy.createDefault=true \
-  apisix/apisix
-```
-
-### Set Up a Sample Upstream
-
-Install the httpbin example application to test the configuration:
-
-```bash
-kubectl apply -f https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml
-```
-
-### Configure a Route
-
-Install an ApisixRoute or Ingress resource to route traffic to httpbin:
-
-> The examples below show how these differ. Both the examples configure a Route in APISIX that routes to an httpbin service as the Upstream.
-
-<Tabs
-groupId="resources"
-defaultValue="apisix"
-values={[
-{label: 'APISIX Ingress CRD', value: 'apisix'},
-{label: 'Kubernetes Ingress API', value: 'ingress'},
-]}>
-
-<TabItem value="apisix">
-
-```yaml title="httpbin-route.yaml"
-apiVersion: apisix.apache.org/v2
-kind: ApisixRoute
-metadata:
-  name: httpbin-route
-spec:
-  ingressClassName: apisix
-  http:
-    - name: route-1
-      match:
-        hosts:
-          - local.httpbin.org
-        paths:
-          - /*
-      backends:
-        - serviceName: httpbin
-          servicePort: 80
-```
-
-</TabItem>
-
-<TabItem value="ingress">
-
-```yaml title="httpbin-route.yaml"
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: httpbin-route
-spec:
-  ingressClassName: apisix
-  rules:
-    - host: local.httpbin.org
-      http:
-        paths:
-          - backend:
-              service:
-                name: httpbin
-                port:
-                  number: 80
-            path: /
-            pathType: Prefix
-```
-
-</TabItem>
-</Tabs>
-
-:::note
-
-More details on the installation can be found in the [Installation guide](./install.md).
-
-:::
-
-### Verify Route Configuration
-
-Let's verify the configuration. In order to access APISIX locally, we can use `kubectl port-forward` command to forward traffic from the specified port at your local machine to the specified port on the specified service.
-
-```bash
-kubectl port-forward -n ingress-apisix svc/apisix-gateway 9080:80
-```
-
-Run curl command in a APISIX pod to see if the routing configuration works.
-
-```bash
-curl http://127.0.0.1:9080/headers -H 'Host: local.httpbin.org'
-```
+See the [Getting Started tutorials](./getting-started/get-apisix-ingress-controller.md) to set up and start using the APISIX Ingress Controller.
 
 ## Features
 
diff --git a/docs/en/latest/reference/api-reference.md b/docs/en/latest/reference/api-reference.md
new file mode 100644
index 00000000..4ff8c06d
--- /dev/null
+++ b/docs/en/latest/reference/api-reference.md
@@ -0,0 +1,1589 @@
+---
+title: Custom Resource Definitions API Reference
+slug: /reference/apisix-ingress-controller/api-reference
+description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller.
+---
+
+This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs).
+
+## Packages
+- [apisix.apache.org/v1alpha1](#apisixapacheorgv1alpha1)
+- [apisix.apache.org/v2](#apisixapacheorgv2)
+
+
+## apisix.apache.org/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group.
+
+- [BackendTrafficPolicy](#backendtrafficpolicy)
+- [Consumer](#consumer)
+- [GatewayProxy](#gatewayproxy)
+- [HTTPRoutePolicy](#httproutepolicy)
+- [PluginConfig](#pluginconfig)
+### BackendTrafficPolicy
+
+
+BackendTrafficPolicy defines configuration for traffic handling policies applied to backend services.
+
+<!-- BackendTrafficPolicy resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
+| `kind` _string_ | `BackendTrafficPolicy`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | BackendTrafficPolicySpec defines traffic handling policies applied to backend services, such as load balancing strategy, connection settings, and failover behavior. |
+
+
+
+### Consumer
+
+
+Consumer defines configuration for a consumer.
+
+<!-- Consumer resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
+| `kind` _string_ | `Consumer`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ConsumerSpec](#consumerspec)_ | ConsumerSpec defines configuration for a consumer, including consumer name, authentication credentials, and plugin settings. |
+
+
+
+### GatewayProxy
+
+
+GatewayProxy defines configuration for the gateway proxy instances used to route traffic to services.
+
+<!-- GatewayProxy resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
+| `kind` _string_ | `GatewayProxy`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[GatewayProxySpec](#gatewayproxyspec)_ | GatewayProxySpec defines configuration of gateway proxy instances, including networking settings, global plugins, and plugin metadata. |
+
+
+
+### HTTPRoutePolicy
+
+
+HTTPRoutePolicy defines configuration of traffic policies.
+
+<!-- HTTPRoutePolicy resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
+| `kind` _string_ | `HTTPRoutePolicy`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[HTTPRoutePolicySpec](#httproutepolicyspec)_ | HTTPRoutePolicySpec defines configuration of a HTTPRoutePolicy, including route priority and request matching conditions. |
+
+
+
+### PluginConfig
+
+
+PluginConfig defines plugin configuration.
+
+<!-- PluginConfig resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v1alpha1`
+| `kind` _string_ | `PluginConfig`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[PluginConfigSpec](#pluginconfigspec)_ | PluginConfigSpec defines the desired state of a PluginConfig, in which plugins and their configuration are specified. |
+
+
+
+### Types
+
+This section describes the types used by the CRDs.
+#### AdminKeyAuth
+
+
+AdminKeyAuth defines the admin key authentication configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `value` _string_ | Value sets the admin key value explicitly (not recommended for production). |
+| `valueFrom` _[AdminKeyValueFrom](#adminkeyvaluefrom)_ | ValueFrom specifies the source of the admin key. |
+
+
+_Appears in:_
+- [ControlPlaneAuth](#controlplaneauth)
+
+#### AdminKeyValueFrom
+
+
+AdminKeyValueFrom defines the source of the admin key.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | SecretKeyRef references a key in a Secret. |
+
+
+_Appears in:_
+- [AdminKeyAuth](#adminkeyauth)
+
+#### AuthType
+_Base type:_ `string`
+
+AuthType defines the type of authentication.
+
+
+
+
+
+_Appears in:_
+- [ControlPlaneAuth](#controlplaneauth)
+
+#### BackendPolicyTargetReferenceWithSectionName
+_Base type:_ `LocalPolicyTargetReferenceWithSectionName`
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `group` _[Group](#group)_ | Group is the group of the target resource. |
+| `kind` _[Kind](#kind)_ | Kind is kind of the target resource. |
+| `name` _[ObjectName](#objectname)_ | Name is the name of the target resource. |
+| `sectionName` _[SectionName](#sectionname)_ | SectionName is the name of a section within the target resource. When unspecified, this targetRef targets the entire resource. In the following resources, SectionName is interpreted as the following:<br /><br /> • Gateway: Listener name<br /> • HTTPRoute: HTTPRouteRule name<br /> • Service: Port name<br /><br /> If a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implement [...]
+
+
+_Appears in:_
+- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
+
+#### BackendTrafficPolicySpec
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `targetRefs` _[BackendPolicyTargetReferenceWithSectionName](#backendpolicytargetreferencewithsectionname) array_ | TargetRef identifies an API object to apply policy to. Currently, Backends (i.e. Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. |
+| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. |
+| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
+| `retries` _integer_ | Retries specify the number of times the gateway should retry sending requests when errors such as timeouts or 502 errors occur. |
+| `timeout` _[Timeout](#timeout)_ | Timeout sets the read, send, and connect timeouts to the upstream. |
+| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via `upstreamHost` |
+| `upstreamHost` _[Hostname](#hostname)_ | UpstreamHost specifies the host of the Upstream request. Used only if passHost is set to `rewrite`. |
+
+
+_Appears in:_
+- [BackendTrafficPolicy](#backendtrafficpolicy)
+
+#### ConsumerSpec
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `gatewayRef` _[GatewayRef](#gatewayref)_ | GatewayRef specifies the gateway details. |
+| `credentials` _[Credential](#credential) array_ | Credentials specifies the credential details of a consumer. |
+| `plugins` _[Plugin](#plugin) array_ | Plugins define the plugins associated with a consumer. |
+
+
+_Appears in:_
+- [Consumer](#consumer)
+
+
+
+#### ControlPlaneAuth
+
+
+ControlPlaneAuth defines the authentication configuration for control plane.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _[AuthType](#authtype)_ | Type specifies the type of authentication. Can only be `AdminKey`. |
+| `adminKey` _[AdminKeyAuth](#adminkeyauth)_ | AdminKey specifies the admin key authentication configuration. |
+
+
+_Appears in:_
+- [ControlPlaneProvider](#controlplaneprovider)
+
+#### ControlPlaneProvider
+
+
+ControlPlaneProvider defines configuration for control plane provider.
+
+
+
+| Field | Description |
+| --- | --- |
+| `endpoints` _string array_ | Endpoints specifies the list of control plane endpoints. |
+| `service` _[ProviderService](#providerservice)_ |  |
+| `tlsVerify` _boolean_ | TlsVerify specifies whether to verify the TLS certificate of the control plane. |
+| `auth` _[ControlPlaneAuth](#controlplaneauth)_ | Auth specifies the authentication configuration. |
+
+
+_Appears in:_
+- [GatewayProxyProvider](#gatewayproxyprovider)
+
+#### Credential
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _string_ | Type specifies the type of authentication to configure credentials for. Can be `jwt-auth`, `basic-auth`, `key-auth`, or `hmac-auth`. |
+| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config specifies the credential details for authentication. |
+| `secretRef` _[SecretReference](#secretreference)_ | SecretRef references to the Secret that contains the credentials. |
+| `name` _string_ | Name is the name of the credential. |
+
+
+_Appears in:_
+- [ConsumerSpec](#consumerspec)
+
+#### GatewayProxyPlugin
+
+
+GatewayProxyPlugin contains plugin configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the plugin. |
+| `enabled` _boolean_ | Enabled defines whether the plugin is enabled. |
+| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config defines the plugin's configuration details. |
+
+
+_Appears in:_
+- [GatewayProxySpec](#gatewayproxyspec)
+
+#### GatewayProxyProvider
+
+
+GatewayProxyProvider defines the provider configuration for GatewayProxy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _[ProviderType](#providertype)_ | Type specifies the type of provider. Can only be `ControlPlane`. |
+| `controlPlane` _[ControlPlaneProvider](#controlplaneprovider)_ | ControlPlane specifies the configuration for control plane provider. |
+
+
+_Appears in:_
+- [GatewayProxySpec](#gatewayproxyspec)
+
+#### GatewayProxySpec
+
+
+GatewayProxySpec defines the desired state of GatewayProxy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `publishService` _string_ | PublishService specifies the LoadBalancer-type Service whose external address the controller uses to update the status of Ingress resources. |
+| `statusAddress` _string array_ | StatusAddress specifies the external IP addresses that the controller uses to populate the status field of GatewayProxy or Ingress resources for developers to access. |
+| `provider` _[GatewayProxyProvider](#gatewayproxyprovider)_ | Provider configures the provider details. |
+| `plugins` _[GatewayProxyPlugin](#gatewayproxyplugin) array_ | Plugins configure global plugins. |
+| `pluginMetadata` _object (keys:string, values:[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io))_ | PluginMetadata configures common configuration shared by all plugin instances of the same name. |
+
+
+_Appears in:_
+- [GatewayProxy](#gatewayproxy)
+
+#### GatewayRef
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the gateway. |
+| `kind` _string_ | Kind is the type of Kubernetes object. Default is `Gateway`. |
+| `group` _string_ | Group is the API group the resource belongs to. Default is `gateway.networking.k8s.io`. |
+| `namespace` _string_ | Namespace is namespace of the resource. |
+
+
+_Appears in:_
+- [ConsumerSpec](#consumerspec)
+
+#### HTTPRoutePolicySpec
+
+
+HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `targetRefs` _LocalPolicyTargetReferenceWithSectionName array_ | TargetRef identifies an API object (i.e. HTTPRoute, Ingress) to apply HTTPRoutePolicy to. |
+| `priority` _integer_ | Priority sets the priority for route. when multiple routes have the same URI path, a higher value sets a higher priority in route matching. |
+| `vars` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io) array_ | Vars sets the request matching conditions. |
+
+
+_Appears in:_
+- [HTTPRoutePolicy](#httproutepolicy)
+
+#### Hostname
+_Base type:_ `string`
+
+
+
+
+
+
+
+_Appears in:_
+- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
+
+#### LoadBalancer
+
+
+LoadBalancer describes the load balancing parameters.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _string_ | Type specifies the load balancing algorithms to route traffic to the backend. Default is `roundrobin`. Can be `roundrobin`, `chash`, `ewma`, or `least_conn`. |
+| `hashOn` _string_ | HashOn specified the type of field used for hashing, required when type is `chash`. Default is `vars`. Can be `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`. |
+| `key` _string_ | 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 [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/). |
+
+
+_Appears in:_
+- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
+
+#### Plugin
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the plugin. |
+| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config is plugin configuration details. |
+
+
+_Appears in:_
+- [ConsumerSpec](#consumerspec)
+- [PluginConfigSpec](#pluginconfigspec)
+
+#### PluginConfigSpec
+
+
+PluginConfigSpec defines the desired state of PluginConfig.
+
+
+
+| Field | Description |
+| --- | --- |
+| `plugins` _[Plugin](#plugin) array_ | Plugins are an array of plugins and their configuration to be applied. |
+
+
+_Appears in:_
+- [PluginConfig](#pluginconfig)
+
+
+
+#### ProviderService
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the provider. |
+| `port` _integer_ | Port is the port of the provider. |
+
+
+_Appears in:_
+- [ControlPlaneProvider](#controlplaneprovider)
+
+#### ProviderType
+_Base type:_ `string`
+
+ProviderType defines the type of provider.
+
+
+
+
+
+_Appears in:_
+- [GatewayProxyProvider](#gatewayproxyprovider)
+
+#### SecretKeySelector
+
+
+SecretKeySelector defines a reference to a specific key within a Secret.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the secret. |
+| `key` _string_ | Key is the key in the secret to retrieve the secret from. |
+
+
+_Appears in:_
+- [AdminKeyValueFrom](#adminkeyvaluefrom)
+
+#### SecretReference
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the secret. |
+| `namespace` _string_ | Namespace is the namespace of the secret. |
+
+
+_Appears in:_
+- [Credential](#credential)
+
+#### Status
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#condition-v1-meta) array_ |  |
+
+
+_Appears in:_
+- [ConsumerStatus](#consumerstatus)
+
+#### Timeout
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `connect` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Connection timeout. Default is `60s`. |
+| `send` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Send timeout. Default is `60s`. |
+| `read` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Read timeout. Default is `60s`. |
+
+
+_Appears in:_
+- [BackendTrafficPolicySpec](#backendtrafficpolicyspec)
+
+
+## apisix.apache.org/v2
+
+Package v2 contains API Schema definitions for the apisix.apache.org v2 API group.
+
+- [ApisixConsumer](#apisixconsumer)
+- [ApisixGlobalRule](#apisixglobalrule)
+- [ApisixPluginConfig](#apisixpluginconfig)
+- [ApisixRoute](#apisixroute)
+- [ApisixTls](#apisixtls)
+- [ApisixUpstream](#apisixupstream)
+### ApisixConsumer
+
+
+ApisixConsumer defines configuration of a consumer and their authentication details.
+
+<!-- ApisixConsumer resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixConsumer`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixConsumerSpec](#apisixconsumerspec)_ | ApisixConsumerSpec defines the consumer authentication configuration. |
+
+
+
+### ApisixGlobalRule
+
+
+ApisixGlobalRule defines configuration for global plugins.
+
+<!-- ApisixGlobalRule resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixGlobalRule`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixGlobalRuleSpec](#apisixglobalrulespec)_ | ApisixGlobalRuleSpec defines the global plugin configuration. |
+
+
+
+### ApisixPluginConfig
+
+
+ApisixPluginConfig defines a reusable set of plugin configuration that can be referenced by routes.
+
+<!-- ApisixPluginConfig resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixPluginConfig`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixPluginConfigSpec](#apisixpluginconfigspec)_ | ApisixPluginConfigSpec defines the plugin config configuration. |
+
+
+
+### ApisixRoute
+
+
+ApisixRoute is defines configuration for HTTP and stream routes.
+
+<!-- ApisixRoute resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixRoute`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixRouteSpec](#apisixroutespec)_ | ApisixRouteSpec defines HTTP and stream route configuration. |
+
+
+
+### ApisixTls
+
+
+ApisixTls defines configuration for TLS and mutual TLS (mTLS).
+
+<!-- ApisixTls resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixTls`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixTlsSpec](#apisixtlsspec)_ | ApisixTlsSpec defines the TLS configuration. |
+
+
+
+### ApisixUpstream
+
+
+ApisixUpstream defines configuration for upstream services.
+
+<!-- ApisixUpstream resource -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `apisix.apache.org/v2`
+| `kind` _string_ | `ApisixUpstream`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. |
+| `spec` _[ApisixUpstreamSpec](#apisixupstreamspec)_ | ApisixUpstreamSpec defines the upstream configuration. |
+
+
+
+### Types
+
+This section describes the types used by the CRDs.
+#### ActiveHealthCheck
+
+
+ActiveHealthCheck defines the active upstream health check configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _string_ | Type is the health check type. Can be `http`, `https`, or `tcp`. |
+| `timeout` _[Duration](#duration)_ | Timeout sets health check timeout in seconds. |
+| `concurrency` _integer_ | Concurrency sets the number of targets to be checked at the same time. |
+| `host` _string_ | Host sets the upstream host. |
+| `port` _integer_ | Port sets the upstream port. |
+| `httpPath` _string_ | HTTPPath sets the HTTP probe request path. |
+| `strictTLS` _boolean_ | StrictTLS sets whether to enforce TLS. |
+| `requestHeaders` _string array_ | RequestHeaders sets the request headers. |
+| `healthy` _[ActiveHealthCheckHealthy](#activehealthcheckhealthy)_ | Healthy configures the rules that define an upstream node as healthy. |
+| `unhealthy` _[ActiveHealthCheckUnhealthy](#activehealthcheckunhealthy)_ | Unhealthy configures the rules that define an upstream node as unhealthy. |
+
+
+_Appears in:_
+- [HealthCheck](#healthcheck)
+
+#### ActiveHealthCheckHealthy
+
+
+UpstreamActiveHealthCheckHealthy defines the conditions used to actively determine whether an upstream node is healthy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered healthy. |
+| `successes` _integer_ | Successes define the number of successful probes to define a healthy target. |
+| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Interval defines the time interval for checking targets, in seconds. |
+
+
+_Appears in:_
+- [ActiveHealthCheck](#activehealthcheck)
+
+#### ActiveHealthCheckUnhealthy
+
+
+UpstreamActiveHealthCheckHealthy defines the conditions used to actively determine whether an upstream node is unhealthy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered unhealthy. |
+| `httpFailures` _integer_ | HTTPFailures define the number of HTTP failures to define an unhealthy target. |
+| `tcpFailures` _integer_ | TCPFailures define the number of TCP failures to define an unhealthy target. |
+| `timeout` _integer_ | Timeout sets health check timeout in seconds. |
+| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Interval defines the time interval for checking targets, in seconds. |
+
+
+_Appears in:_
+- [ActiveHealthCheck](#activehealthcheck)
+
+#### ApisixConsumerAuthParameter
+
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `basicAuth` _[ApisixConsumerBasicAuth](#apisixconsumerbasicauth)_ | BasicAuth configures the basic authentication details. |
+| `keyAuth` _[ApisixConsumerKeyAuth](#apisixconsumerkeyauth)_ | KeyAuth configures the key authentication details. |
+| `wolfRBAC` _[ApisixConsumerWolfRBAC](#apisixconsumerwolfrbac)_ | WolfRBAC configures the Wolf RBAC authentication details. |
+| `jwtAuth` _[ApisixConsumerJwtAuth](#apisixconsumerjwtauth)_ | JwtAuth configures the JWT authentication details. |
+| `hmacAuth` _[ApisixConsumerHMACAuth](#apisixconsumerhmacauth)_ | HMACAuth configures the HMAC authentication details. |
+| `ldapAuth` _[ApisixConsumerLDAPAuth](#apisixconsumerldapauth)_ | LDAPAuth configures the LDAP authentication details. |
+
+
+_Appears in:_
+- [ApisixConsumerSpec](#apisixconsumerspec)
+
+#### ApisixConsumerBasicAuth
+
+
+ApisixConsumerBasicAuth defines configuration for basic authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing the basic authentication credentials. |
+| `value` _[ApisixConsumerBasicAuthValue](#apisixconsumerbasicauthvalue)_ | Value specifies the basic authentication credentials. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerBasicAuthValue
+
+
+ApisixConsumerBasicAuthValue defines the username and password configuration for basic authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `username` _string_ | Username is the basic authentication username. |
+| `password` _string_ | Password is the basic authentication password. |
+
+
+_Appears in:_
+- [ApisixConsumerBasicAuth](#apisixconsumerbasicauth)
+
+#### ApisixConsumerHMACAuth
+
+
+ApisixConsumerHMACAuth defines configuration for the HMAC authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing the HMAC credentials. |
+| `value` _[ApisixConsumerHMACAuthValue](#apisixconsumerhmacauthvalue)_ | Value specifies HMAC authentication credentials. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerHMACAuthValue
+
+
+ApisixConsumerHMACAuthValue defines configuration for HMAC authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `access_key` _string_ | AccessKey is the identifier used to look up the HMAC secret. |
+| `secret_key` _string_ | SecretKey is the HMAC secret used to sign the request. |
+| `algorithm` _string_ | Algorithm specifies the hashing algorithm (e.g., "hmac-sha256"). |
+| `clock_skew` _integer_ | ClockSkew is the allowed time difference (in seconds) between client and server clocks. |
+| `signed_headers` _string array_ | SignedHeaders lists the headers that must be included in the signature. |
+| `keep_headers` _boolean_ | KeepHeaders determines whether the HMAC signature headers are preserved after verification. |
+| `encode_uri_params` _boolean_ | EncodeURIParams indicates whether URI parameters are encoded when calculating the signature. |
+| `validate_request_body` _boolean_ | ValidateRequestBody enables HMAC validation of the request body. |
+| `max_req_body` _integer_ | MaxReqBody sets the maximum size (in bytes) of the request body that can be validated. |
+
+
+_Appears in:_
+- [ApisixConsumerHMACAuth](#apisixconsumerhmacauth)
+
+#### ApisixConsumerJwtAuth
+
+
+ApisixConsumerJwtAuth defines configuration for JWT authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing JWT authentication credentials. |
+| `value` _[ApisixConsumerJwtAuthValue](#apisixconsumerjwtauthvalue)_ | Value specifies JWT authentication credentials. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerJwtAuthValue
+
+
+ApisixConsumerJwtAuthValue defines configuration for JWT authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `key` _string_ | Key is the unique identifier for the JWT credential. |
+| `secret` _string_ | Secret is the shared secret used to sign the JWT (for symmetric algorithms). |
+| `public_key` _string_ | PublicKey is the public key used to verify JWT signatures (for asymmetric algorithms). |
+| `private_key` _string_ | PrivateKey is the private key used to sign the JWT (for asymmetric algorithms). |
+| `algorithm` _string_ | Algorithm specifies the signing algorithm. Can be `HS256`, `HS512`, `RS256`, or `ES256`. |
+| `exp` _integer_ | Exp is the token expiration period in seconds. |
+| `base64_secret` _boolean_ | Base64Secret indicates whether the secret is base64-encoded. |
+| `lifetime_grace_period` _integer_ | LifetimeGracePeriod is the allowed clock skew in seconds for token expiration. |
+
+
+_Appears in:_
+- [ApisixConsumerJwtAuth](#apisixconsumerjwtauth)
+
+#### ApisixConsumerKeyAuth
+
+
+ApisixConsumerKeyAuth defines configuration for the key auth.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing the key authentication credentials. |
+| `value` _[ApisixConsumerKeyAuthValue](#apisixconsumerkeyauthvalue)_ | Value specifies the key authentication credentials. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerKeyAuthValue
+
+
+ApisixConsumerKeyAuthValue defines configuration for key authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `key` _string_ | Key is the credential used for key authentication. |
+
+
+_Appears in:_
+- [ApisixConsumerKeyAuth](#apisixconsumerkeyauth)
+
+#### ApisixConsumerLDAPAuth
+
+
+ApisixConsumerLDAPAuth defines configuration for the LDAP authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing the LDAP credentials. |
+| `value` _[ApisixConsumerLDAPAuthValue](#apisixconsumerldapauthvalue)_ | Value specifies LDAP authentication credentials. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerLDAPAuthValue
+
+
+ApisixConsumerLDAPAuthValue defines configuration for LDAP authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `user_dn` _string_ | UserDN is the distinguished name (DN) of the LDAP user. |
+
+
+_Appears in:_
+- [ApisixConsumerLDAPAuth](#apisixconsumerldapauth)
+
+#### ApisixConsumerSpec
+
+
+ApisixConsumerSpec defines the desired state of ApisixConsumer.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. The controller uses this field to decide whether the resource should be managed. |
+| `authParameter` _[ApisixConsumerAuthParameter](#apisixconsumerauthparameter)_ | AuthParameter defines the authentication credentials and configuration for this consumer. |
+
+
+_Appears in:_
+- [ApisixConsumer](#apisixconsumer)
+
+#### ApisixConsumerWolfRBAC
+
+
+ApisixConsumerWolfRBAC defines configuration for the Wolf RBAC authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `secretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#localobjectreference-v1-core)_ | SecretRef references a Kubernetes Secret containing the Wolf RBAC token. |
+| `value` _[ApisixConsumerWolfRBACValue](#apisixconsumerwolfrbacvalue)_ | Value specifies the Wolf RBAC token. |
+
+
+_Appears in:_
+- [ApisixConsumerAuthParameter](#apisixconsumerauthparameter)
+
+#### ApisixConsumerWolfRBACValue
+
+
+ApisixConsumerWolfRBACValue defines configuration for Wolf RBAC authentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `server` _string_ | Server is the URL of the Wolf RBAC server. |
+| `appid` _string_ | Appid is the application identifier used when communicating with the Wolf RBAC server. |
+| `header_prefix` _string_ | HeaderPrefix is the prefix added to request headers for RBAC enforcement. |
+
+
+_Appears in:_
+- [ApisixConsumerWolfRBAC](#apisixconsumerwolfrbac)
+
+#### ApisixGlobalRuleSpec
+
+
+ApisixGlobalRuleSpec defines configuration for global plugins.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. The controller uses this field to decide whether the resource should be managed. |
+| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins contain a list of global plugins. |
+
+
+_Appears in:_
+- [ApisixGlobalRule](#apisixglobalrule)
+
+#### ApisixMutualTlsClientConfig
+
+
+ApisixMutualTlsClientConfig describes the mutual TLS CA and verification settings.
+
+
+
+| Field | Description |
+| --- | --- |
+| `caSecret` _[ApisixSecret](#apisixsecret)_ | CASecret references the secret containing the CA certificate for client certificate validation. |
+| `depth` _integer_ | Depth specifies the maximum verification depth for the client certificate chain. |
+| `skip_mtls_uri_regex` _string array_ | SkipMTLSUriRegex contains RegEx patterns for URIs to skip mutual TLS verification. |
+
+
+_Appears in:_
+- [ApisixTlsSpec](#apisixtlsspec)
+
+#### ApisixPluginConfigSpec
+
+
+ApisixPluginConfigSpec defines the desired state of ApisixPluginConfigSpec.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. The controller uses this field to decide whether the resource should be managed. |
+| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins contain a list of plugins. |
+
+
+_Appears in:_
+- [ApisixPluginConfig](#apisixpluginconfig)
+
+#### ApisixRouteAuthentication
+
+
+ApisixRouteAuthentication represents authentication-related configuration in ApisixRoute.
+
+
+
+| Field | Description |
+| --- | --- |
+| `enable` _boolean_ | Enable toggles authentication on or off. |
+| `type` _string_ | Type specifies the authentication type. |
+| `keyAuth` _[ApisixRouteAuthenticationKeyAuth](#apisixrouteauthenticationkeyauth)_ | KeyAuth defines configuration for key authentication. |
+| `jwtAuth` _[ApisixRouteAuthenticationJwtAuth](#apisixrouteauthenticationjwtauth)_ | JwtAuth defines configuration for JWT authentication. |
+| `ldapAuth` _[ApisixRouteAuthenticationLDAPAuth](#apisixrouteauthenticationldapauth)_ | LDAPAuth defines configuration for LDAP authentication. |
+
+
+_Appears in:_
+- [ApisixRouteHTTP](#apisixroutehttp)
+
+#### ApisixRouteAuthenticationJwtAuth
+
+
+ApisixRouteAuthenticationJwtAuth defines JWT authentication configuration in ApisixRouteAuthentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `header` _string_ | Header specifies the HTTP header name to look for the JWT token. |
+| `query` _string_ | Query specifies the URL query parameter name to look for the JWT token. |
+| `cookie` _string_ | Cookie specifies the cookie name to look for the JWT token. |
+
+
+_Appears in:_
+- [ApisixRouteAuthentication](#apisixrouteauthentication)
+
+#### ApisixRouteAuthenticationKeyAuth
+
+
+ApisixRouteAuthenticationKeyAuth defines key authentication configuration in ApisixRouteAuthentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `header` _string_ | Header specifies the HTTP header name to look for the key authentication token. |
+
+
+_Appears in:_
+- [ApisixRouteAuthentication](#apisixrouteauthentication)
+
+#### ApisixRouteAuthenticationLDAPAuth
+
+
+ApisixRouteAuthenticationLDAPAuth defines LDAP authentication configuration in ApisixRouteAuthentication.
+
+
+
+| Field | Description |
+| --- | --- |
+| `base_dn` _string_ | BaseDN is the base distinguished name (DN) for LDAP searches. |
+| `ldap_uri` _string_ | LDAPURI is the URI of the LDAP server. |
+| `use_tls` _boolean_ | UseTLS indicates whether to use TLS for the LDAP connection. |
+| `uid` _string_ | UID is the user identifier attribute in LDAP. |
+
+
+_Appears in:_
+- [ApisixRouteAuthentication](#apisixrouteauthentication)
+
+#### ApisixRouteHTTP
+
+
+ApisixRouteHTTP represents a single HTTP route configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the unique rule name and cannot be empty. |
+| `priority` _integer_ | Priority defines the route priority when multiple routes share the same URI path. Higher values mean higher priority in route matching. |
+| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies upstream timeout settings. |
+| `match` _[ApisixRouteHTTPMatch](#apisixroutehttpmatch)_ | Match defines the HTTP request matching criteria. |
+| `backends` _[ApisixRouteHTTPBackend](#apisixroutehttpbackend) array_ | Backends lists potential backend services to proxy requests to. If more than one backend is specified, the `traffic-split` plugin is used to distribute traffic according to backend weights. |
+| `upstreams` _[ApisixRouteUpstreamReference](#apisixrouteupstreamreference) array_ | Upstreams references ApisixUpstream CRDs. |
+| `websocket` _boolean_ | Websocket enables or disables websocket support for this route. |
+| `plugin_config_name` _string_ | PluginConfigName specifies the name of the plugin config to apply. |
+| `plugin_config_namespace` _string_ | PluginConfigNamespace specifies the namespace of the plugin config. Defaults to the namespace of the ApisixRoute if not set. |
+| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins lists additional plugins applied to this route. |
+| `authentication` _[ApisixRouteAuthentication](#apisixrouteauthentication)_ | Authentication holds authentication-related configuration for this route. |
+
+
+_Appears in:_
+- [ApisixRouteSpec](#apisixroutespec)
+
+#### ApisixRouteHTTPBackend
+
+
+ApisixRouteHTTPBackend represents an HTTP backend (Kubernetes Service).
+
+
+
+| Field | Description |
+| --- | --- |
+| `serviceName` _string_ | ServiceName is the name of the Kubernetes Service. Cross-namespace references are not supported—ensure the ApisixRoute and the Service are in the same namespace. |
+| `servicePort` _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#intorstring-intstr-util)_ | ServicePort is the port of the Kubernetes Service. This can be either the port name or port number. |
+| `resolveGranularity` _string_ | ResolveGranularity determines how the backend service is resolved. Valid values are `endpoints` and `service`. When set to `endpoints`, individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used. The default is `endpoints`. |
+| `weight` _integer_ | Weight specifies the relative traffic weight for this backend. |
+| `subset` _string_ | Subset specifies a named subset of the target Service. The subset must be pre-defined in the corresponding ApisixUpstream resource. |
+
+
+_Appears in:_
+- [ApisixRouteHTTP](#apisixroutehttp)
+
+#### ApisixRouteHTTPMatch
+
+
+ApisixRouteHTTPMatch defines the conditions used to match incoming HTTP requests.
+
+
+
+| Field | Description |
+| --- | --- |
+| `paths` _string array_ | Paths is a list of URI path patterns to match. At least one path must be specified. Supports exact matches and prefix matches. For prefix matches, append `*` to the path, such as `/foo*`. |
+| `methods` _string array_ | Methods specifies the HTTP methods to match. |
+| `hosts` _string array_ | Hosts specifies Host header values to match. Supports exact and wildcard domains. Only one level of wildcard is allowed (e.g., `*.example.com` is valid, but `*.*.example.com` is not). |
+| `remoteAddrs` _string array_ | RemoteAddrs is a list of source IP addresses or CIDR ranges to match. Supports both IPv4 and IPv6 formats. |
+| `exprs` _[ApisixRouteHTTPMatchExprs](#apisixroutehttpmatchexprs)_ | NginxVars defines match conditions based on Nginx variables. |
+| `filter_func` _string_ | FilterFunc is a user-defined function for advanced request filtering. The function can use Nginx variables through the `vars` parameter. |
+
+
+_Appears in:_
+- [ApisixRouteHTTP](#apisixroutehttp)
+
+#### ApisixRouteHTTPMatchExpr
+
+
+ApisixRouteHTTPMatchExpr represents a binary expression used to match requests based on Nginx variables.
+
+
+
+| Field | Description |
+| --- | --- |
+| `subject` _[ApisixRouteHTTPMatchExprSubject](#apisixroutehttpmatchexprsubject)_ | Subject defines the left-hand side of the expression. It can be any [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable) or string literal. |
+| `op` _string_ | Op specifies the operator used in the expression. Can be `Equal`, `NotEqual`, `GreaterThan`, `GreaterThanEqual`, `LessThan`, `LessThanEqual`, `RegexMatch`, `RegexNotMatch`, `RegexMatchCaseInsensitive`, `RegexNotMatchCaseInsensitive`, `In`, or `NotIn`. |
+| `set` _string array_ | Set provides a list of acceptable values for the expression. This should be used when Op is `In` or `NotIn`. |
+| `value` _string_ | Value defines a single value to compare against the subject. This should be used when Op is not `In` or `NotIn`. Set and Value are mutually exclusive—only one should be set at a time. |
+
+
+_Appears in:_
+- [ApisixRouteHTTPMatchExprs](#apisixroutehttpmatchexprs)
+
+#### ApisixRouteHTTPMatchExprSubject
+
+
+ApisixRouteHTTPMatchExprSubject describes the subject of a route matching expression.
+
+
+
+| Field | Description |
+| --- | --- |
+| `scope` _string_ | Scope specifies the subject scope and can be `Header`, `Query`, or `Path`. When Scope is `Path`, Name will be ignored. |
+| `name` _string_ | Name is the name of the header or query parameter. |
+
+
+_Appears in:_
+- [ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)
+
+#### ApisixRouteHTTPMatchExprs
+_Base type:_ `[ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)`
+
+
+
+
+
+| Field | Description |
+| --- | --- |
+| `subject` _[ApisixRouteHTTPMatchExprSubject](#apisixroutehttpmatchexprsubject)_ | Subject defines the left-hand side of the expression. It can be any [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable) or string literal. |
+| `op` _string_ | Op specifies the operator used in the expression. Can be `Equal`, `NotEqual`, `GreaterThan`, `GreaterThanEqual`, `LessThan`, `LessThanEqual`, `RegexMatch`, `RegexNotMatch`, `RegexMatchCaseInsensitive`, `RegexNotMatchCaseInsensitive`, `In`, or `NotIn`. |
+| `set` _string array_ | Set provides a list of acceptable values for the expression. This should be used when Op is `In` or `NotIn`. |
+| `value` _string_ | Value defines a single value to compare against the subject. This should be used when Op is not `In` or `NotIn`. Set and Value are mutually exclusive—only one should be set at a time. |
+
+
+_Appears in:_
+- [ApisixRouteHTTPMatch](#apisixroutehttpmatch)
+
+#### ApisixRoutePlugin
+
+
+ApisixRoutePlugin represents an APISIX plugin.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | The plugin name. |
+| `enable` _boolean_ | Whether this plugin is in use, default is true. |
+| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Plugin configuration. |
+| `secretRef` _string_ | Plugin configuration secretRef. |
+
+
+_Appears in:_
+- [ApisixGlobalRuleSpec](#apisixglobalrulespec)
+- [ApisixPluginConfigSpec](#apisixpluginconfigspec)
+- [ApisixRouteHTTP](#apisixroutehttp)
+- [ApisixRouteStream](#apisixroutestream)
+
+
+
+#### ApisixRouteSpec
+
+
+ApisixRouteSpec is the spec definition for ApisixRoute.
+It defines routing rules for both HTTP and stream traffic.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName is the name of the IngressClass this route belongs to. It allows multiple controllers to watch and reconcile different routes. |
+| `http` _[ApisixRouteHTTP](#apisixroutehttp) array_ | HTTP defines a list of HTTP route rules. Each rule specifies conditions to match HTTP requests and how to forward them. |
+| `stream` _[ApisixRouteStream](#apisixroutestream) array_ | Stream defines a list of stream route rules. Each rule specifies conditions to match TCP/UDP traffic and how to forward them. |
+
+
+_Appears in:_
+- [ApisixRoute](#apisixroute)
+
+#### ApisixRouteStream
+
+
+ApisixRouteStream defines the configuration for a Layer 4 (TCP/UDP) route.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is a unique identifier for the route. This field must not be empty. |
+| `protocol` _string_ | Protocol specifies the L4 protocol to match. Can be `tcp` or `udp`. |
+| `match` _[ApisixRouteStreamMatch](#apisixroutestreammatch)_ | Match defines the criteria used to match incoming TCP or UDP connections. |
+| `backend` _[ApisixRouteStreamBackend](#apisixroutestreambackend)_ | Backend specifies the destination service to which traffic should be forwarded. |
+| `plugins` _[ApisixRoutePlugin](#apisixrouteplugin) array_ | Plugins defines a list of plugins to apply to this route. |
+
+
+_Appears in:_
+- [ApisixRouteSpec](#apisixroutespec)
+
+#### ApisixRouteStreamBackend
+
+
+ApisixRouteStreamBackend represents the backend service for a TCP or UDP stream route.
+
+
+
+| Field | Description |
+| --- | --- |
+| `serviceName` _string_ | ServiceName is the name of the Kubernetes Service. Cross-namespace references are not supported—ensure the ApisixRoute and the Service are in the same namespace. |
+| `servicePort` _[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#intorstring-intstr-util)_ | ServicePort is the port of the Kubernetes Service. This can be either the port name or port number. |
+| `resolveGranularity` _string_ | ResolveGranularity determines how the backend service is resolved. Valid values are `endpoints` and `service`. When set to `endpoints`, individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used. The default is `endpoints`. |
+| `subset` _string_ | Subset specifies a named subset of the target Service. The subset must be pre-defined in the corresponding ApisixUpstream resource. |
+
+
+_Appears in:_
+- [ApisixRouteStream](#apisixroutestream)
+
+#### ApisixRouteStreamMatch
+
+
+ApisixRouteStreamMatch represents the matching conditions for a stream route.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressPort` _integer_ | IngressPort is the port on which the APISIX Ingress proxy server listens. This must be a statically configured port, as APISIX does not support dynamic port binding. |
+| `host` _string_ | Host is the destination host address used to match the incoming TCP/UDP traffic. |
+
+
+_Appears in:_
+- [ApisixRouteStream](#apisixroutestream)
+
+#### ApisixRouteUpstreamReference
+
+
+ApisixRouteUpstreamReference references an ApisixUpstream CRD to be used as a backend.
+It can be used in traffic-splitting scenarios or to select a specific upstream configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the ApisixUpstream resource. |
+| `weight` _integer_ | Weight is the weight assigned to this upstream. |
+
+
+_Appears in:_
+- [ApisixRouteHTTP](#apisixroutehttp)
+
+#### ApisixSecret
+
+
+ApisixSecret describes a reference to a Kubernetes Secret, including its name and namespace.
+This is used to locate secrets such as certificates or credentials for plugins or TLS configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the Kubernetes Secret. |
+| `namespace` _string_ | Namespace is the namespace where the Kubernetes Secret is located. |
+
+
+_Appears in:_
+- [ApisixMutualTlsClientConfig](#apisixmutualtlsclientconfig)
+- [ApisixTlsSpec](#apisixtlsspec)
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#### ApisixTlsSpec
+
+
+ApisixTlsSpec defines configurations for TLS and mutual TLS.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName specifies which IngressClass this resource is associated with. The APISIX controller only processes this resource if the class matches its own. |
+| `hosts` _[HostType](#hosttype) array_ | Hosts lists the SNI (Server Name Indication) hostnames that this TLS configuration applies to. Must contain at least one host. |
+| `secret` _[ApisixSecret](#apisixsecret)_ | Secret refers to the Kubernetes TLS secret containing the certificate and private key. This secret must exist in the specified namespace and contain valid TLS data. |
+| `client` _[ApisixMutualTlsClientConfig](#apisixmutualtlsclientconfig)_ | Client defines mutual TLS (mTLS) settings, such as the CA certificate and verification depth. |
+
+
+_Appears in:_
+- [ApisixTls](#apisixtls)
+
+#### ApisixUpstreamConfig
+
+
+ApisixUpstreamConfig defines configuration for upstream services.
+
+
+
+| Field | Description |
+| --- | --- |
+| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer specifies the load balancer configuration for Kubernetes Service. |
+| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
+| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
+| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
+| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
+| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
+| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
+| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
+| `upstreamHost` _string_ | UpstreamHost sets a custom Host header when passHost is set to `rewrite`. |
+| `discovery` _[Discovery](#discovery)_ | Discovery configures service discovery for the upstream. Deprecated: no longer supported in standalone mode. |
+
+
+_Appears in:_
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+#### ApisixUpstreamExternalNode
+
+
+ApisixUpstreamExternalNode defines configuration for an external upstream node.
+This allows referencing services outside the cluster.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the hostname or IP address of the external node. |
+| `type` _[ApisixUpstreamExternalType](#apisixupstreamexternaltype)_ | Type indicates the kind of external node. Can be `Domain`, or `Service`. |
+| `weight` _integer_ | Weight defines the load balancing weight of this node. Higher values increase the share of traffic sent to this node. |
+| `port` _integer_ | Port specifies the port number on which the external node is accepting traffic. |
+
+
+_Appears in:_
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+
+#### ApisixUpstreamExternalType
+_Base type:_ `string`
+
+ApisixUpstreamExternalType is the external service type
+
+
+
+
+
+_Appears in:_
+- [ApisixUpstreamExternalNode](#apisixupstreamexternalnode)
+
+#### ApisixUpstreamSpec
+
+
+ApisixUpstreamSpec describes the desired configuration of an ApisixUpstream resource.
+It defines how traffic should be routed to backend services, including upstream node
+definitions and custom configuration.
+
+
+
+| Field | Description |
+| --- | --- |
+| `ingressClassName` _string_ | IngressClassName is the name of an IngressClass cluster resource. Controller implementations use this field to determine whether they should process this ApisixUpstream resource. |
+| `externalNodes` _[ApisixUpstreamExternalNode](#apisixupstreamexternalnode) array_ | ExternalNodes defines a static list of backend nodes located outside the cluster. When this field is set, the upstream will route traffic directly to these nodes without DNS resolution or service discovery. |
+| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer specifies the load balancer configuration for Kubernetes Service. |
+| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
+| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
+| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
+| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
+| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
+| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
+| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
+| `upstreamHost` _string_ | UpstreamHost sets a custom Host header when passHost is set to `rewrite`. |
+| `discovery` _[Discovery](#discovery)_ | Discovery configures service discovery for the upstream. Deprecated: no longer supported in standalone mode. |
+| `portLevelSettings` _[PortLevelSettings](#portlevelsettings) array_ | PortLevelSettings allows fine-grained upstream configuration for specific ports, useful when a backend service exposes multiple ports with different behaviors or protocols. |
+
+
+_Appears in:_
+- [ApisixUpstream](#apisixupstream)
+
+#### ApisixUpstreamSubset
+
+
+ApisixUpstreamSubset defines a single endpoints group of one Service.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of subset. |
+| `labels` _object (keys:string, values:string)_ | Labels is the label set of this subset. |
+
+
+_Appears in:_
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+#### Discovery
+
+
+Discovery defines the service discovery configuration for dynamically resolving upstream nodes.
+This is used when APISIX integrates with a service registry such as Nacos, Consul, or Eureka.
+
+
+
+| Field | Description |
+| --- | --- |
+| `serviceName` _string_ | ServiceName is the name of the service to discover. |
+| `type` _string_ | Type is the name of the service discovery provider. |
+| `args` _object (keys:string, values:string)_ | Args contains additional configuration parameters required by the discovery provider. These are passed as key-value pairs. |
+
+
+_Appears in:_
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+#### HealthCheck
+
+
+HealthCheck defines the health check configuration for upstream nodes.
+It includes active checks (proactively probing the nodes) and optional passive checks (monitoring based on traffic).
+
+
+
+| Field | Description |
+| --- | --- |
+| `active` _[ActiveHealthCheck](#activehealthcheck)_ | Active health checks proactively send requests to upstream nodes to determine their availability. |
+| `passive` _[PassiveHealthCheck](#passivehealthcheck)_ | Passive health checks evaluate upstream health based on observed traffic, such as timeouts or errors. |
+
+
+_Appears in:_
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+#### HostType
+_Base type:_ `string`
+
+
+
+
+
+
+
+_Appears in:_
+- [ApisixTlsSpec](#apisixtlsspec)
+
+#### LoadBalancer
+
+
+LoadBalancer defines the load balancing strategy for distributing traffic across upstream nodes.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _string_ | Type specifies the load balancing algorithms to route traffic to the backend. Default is `roundrobin`. Can be `roundrobin`, `chash`, `ewma`, or `least_conn`. |
+| `hashOn` _string_ | HashOn specified the type of field used for hashing, required when type is `chash`. Default is `vars`. Can be `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`. |
+| `key` _string_ | 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 [APISIX variables](https://apisix.apache.org/docs/apisix/apisix-variable). |
+
+
+_Appears in:_
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
+#### PassiveHealthCheck
+
+
+PassiveHealthCheck defines the conditions used to determine whether
+an upstream node is healthy or unhealthy based on passive observations.
+Passive health checks rely on real traffic responses instead of active probes.
+
+
+
+| Field | Description |
+| --- | --- |
+| `type` _string_ | Type specifies the type of passive health check. Can be `http`, `https`, or `tcp`. |
+| `healthy` _[PassiveHealthCheckHealthy](#passivehealthcheckhealthy)_ | Healthy defines the conditions under which an upstream node is considered healthy. |
+| `unhealthy` _[PassiveHealthCheckUnhealthy](#passivehealthcheckunhealthy)_ | Unhealthy defines the conditions under which an upstream node is considered unhealthy. |
+
+
+_Appears in:_
+- [HealthCheck](#healthcheck)
+
+#### PassiveHealthCheckHealthy
+
+
+PassiveHealthCheckHealthy defines the conditions used to passively determine whether an upstream node is healthy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered healthy. |
+| `successes` _integer_ | Successes define the number of successful probes to define a healthy target. |
+
+
+_Appears in:_
+- [ActiveHealthCheckHealthy](#activehealthcheckhealthy)
+- [PassiveHealthCheck](#passivehealthcheck)
+
+#### PassiveHealthCheckUnhealthy
+
+
+UpstreamPassiveHealthCheckUnhealthy defines the conditions used to passively determine whether an upstream node is unhealthy.
+
+
+
+| Field | Description |
+| --- | --- |
+| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered unhealthy. |
+| `httpFailures` _integer_ | HTTPFailures define the number of HTTP failures to define an unhealthy target. |
+| `tcpFailures` _integer_ | TCPFailures define the number of TCP failures to define an unhealthy target. |
+| `timeout` _integer_ | Timeout sets health check timeout in seconds. |
+
+
+_Appears in:_
+- [ActiveHealthCheckUnhealthy](#activehealthcheckunhealthy)
+- [PassiveHealthCheck](#passivehealthcheck)
+
+#### PortLevelSettings
+
+
+PortLevelSettings configures the ApisixUpstreamConfig for each individual port. It inherits
+configuration from the outer level (the whole Kubernetes Service) and overrides some of
+them if they are set on the port level.
+
+
+
+| Field | Description |
+| --- | --- |
+| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer specifies the load balancer configuration for Kubernetes Service. |
+| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
+| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
+| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
+| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
+| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
+| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
+| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
+| `upstreamHost` _string_ | UpstreamHost sets a custom Host header when passHost is set to `rewrite`. |
+| `discovery` _[Discovery](#discovery)_ | Discovery configures service discovery for the upstream. Deprecated: no longer supported in standalone mode. |
+| `port` _integer_ | Port is a Kubernetes Service port. |
+
+
+_Appears in:_
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+
+
+
+
+
+
+
+#### UpstreamTimeout
+
+
+UpstreamTimeout defines timeout settings for connecting, sending, and reading from the upstream.
+
+
+
+| Field | Description |
+| --- | --- |
+| `connect` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Connect timeout for establishing a connection to the upstream. |
+| `send` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Send timeout for sending data to the upstream. |
+| `read` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Read timeout for reading data from the upstream. |
+
+
+_Appears in:_
+- [ApisixRouteHTTP](#apisixroutehttp)
+- [ApisixUpstreamConfig](#apisixupstreamconfig)
+- [ApisixUpstreamSpec](#apisixupstreamspec)
+- [PortLevelSettings](#portlevelsettings)
+
diff --git a/docs/en/latest/reference/example.md b/docs/en/latest/reference/example.md
new file mode 100644
index 00000000..c3231f4f
--- /dev/null
+++ b/docs/en/latest/reference/example.md
@@ -0,0 +1,1024 @@
+---
+title: Configuration Examples
+slug: /reference/apisix-ingress-controller/examples
+description: Explore a variety of APISIX Ingress Controller configuration examples to help you customize settings to suit your environment effectively.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+APISIX Ingress Controller supports both Ingress resources and Gateway API for traffic management in Kubernetes. In addition to these standard Kubernetes APIs, the APISIX Ingress Controller also supports a set of [CRDs (Custom Resource Definitions)](./api-reference.md) designed specifically for APISIX-native functionality.
+
+This document provides examples of common configurations covering how and when to use these resources. You should adjust custom values such as namespaces, route URIs, and credentials to match your environment.
+
+## Configure CP Endpoint and Admin Key
+
+To update the Control Plane endpoint and admin key for connectivity between APISIX Ingress Controller and Control Plane at runtime:
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+  namespace: apisix-ingress
+spec:
+  provider:
+    type: ControlPlane
+    controlPlane:
+      endpoints:
+      - http://127.0.0.1:9180
+      auth:
+        type: AdminKey
+        adminKey:
+          value: replace-with-your-admin-key
+```
+
+## Define Controller and Gateway
+
+To specify the controller responsible for handling resources before applying further configurations:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'Ingress', value: 'ingress'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: apisix
+spec:
+  controllerName: "apisix.apache.org/apisix-ingress-controller"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: apisix
+spec:
+  gatewayClassName: apisix
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80
+  infrastructure:
+    parametersRef:
+      group: apisix.apache.org
+      kind: GatewayProxy
+      name: apisix-config
+```
+
+</TabItem>
+
+<TabItem value="ingress">
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: apisix-ingress
+    scope: Namespace
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: apisix-ingress
+    scope: Namespace
+```
+
+</TabItem>
+
+</Tabs>
+
+## Route to K8s Services
+
+To create a route that proxies requests to a service on K8s:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'Ingress', value: 'ingress'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: httpbin
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches:
+    - path:
+        type: Exact
+        value: /ip
+    backendRefs:
+    - name: httpbin
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="ingress">
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  rules:
+  - http:
+      paths:
+      - path: /ip
+        pathType: Exact
+        backend:
+          service:
+            name: httpbin
+            port:
+              number: 80
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  http:
+  - name: httpbin
+    match:
+      paths:
+      - /ip
+    backends:
+    - serviceName: httpbin
+      servicePort: 80
+```
+
+</TabItem>
+
+</Tabs>
+
+## Route to External Services
+
+To create a route that proxies requests to a service publicly hosted:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'Ingress', value: 'ingress'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin-external-domain
+spec:
+  type: ExternalName
+  externalName: httpbin.org
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: get-ip
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches:
+    - path:
+        type: Exact
+        value: /ip
+    backendRefs:
+    - name: httpbin-external-domain
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="ingress">
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin-external-domain
+spec:
+  type: ExternalName
+  externalName: httpbin.org
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: get-ip
+spec:
+  rules:
+  - http:
+      paths:
+      - path: /ip
+        pathType: Exact
+        backend:
+          service:
+            name: httpbin-external-domain
+            port:
+              number: 80
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin-external-domain
+spec:
+  externalNodes:
+  - type: Domain
+    name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: get-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: get-ip
+      match:
+        paths:
+          - /ip
+      upstreams:
+      - name: httpbin-external-domain
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Weighted Services
+
+To create a route that proxies traffic to upstream services by weight:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: httpbin
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches:
+    - path:
+        type: Exact
+        value: /ip
+    backendRefs:
+    - name: httpbin-1
+      port: 80
+      weight: 3
+    - name: httpbin-2
+      port: 80
+      weight: 7
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  http:
+  - name: httpbin
+    match:
+      paths:
+      - /ip
+    backends:
+    - serviceName: httpbin-1
+      servicePort: 80
+      weight: 3
+    - serviceName: httpbin-2
+      servicePort: 80
+      weight: 7
+```
+
+</TabItem>
+
+</Tabs>
+
+This configuration is not supported by the Ingress resource.
+
+## Configure Upstream
+
+To configure upstream related configurations, including load balancing algorithm, how the host header is passed to upstream, service timeout, and more:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: httpbin
+spec:
+  targetRefs:
+  - name: httpbin
+    kind: Service
+    group: ""
+  timeout:
+    send: 10s
+    read: 10s
+    connect: 10s
+  scheme: http
+  retries: 10
+  loadbalancer:
+    type: roundrobin
+  passHost: rewrite
+  upstreamHost: httpbin.example.com
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  timeout:
+    send: 10s
+    read: 10s
+    connect: 10s
+  scheme: http
+  retries: 10
+  loadbalancer:
+    type: roundrobin
+  passHost: rewrite
+  upstreamHost: httpbin.example.com
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Consumer and Credentials
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+To create a consumer and configure the authentication credentials directly on the consumer:
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+  name: alice
+spec:
+  gatewayRef:
+    name: apisix
+  credentials:
+    - type: key-auth
+      name: primary-key
+      config:
+        key: alice-primary-key
+```
+
+You can also use the secret CRD, where the credential should be base64 encoded:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: key-auth-primary
+data:
+  key: YWxpY2UtcHJpbWFyeS1rZXk=
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+  name: alice
+spec:
+  gatewayRef:
+    name: apisix
+  credentials:
+    - type: key-auth
+      name: key-auth-primary
+      secretRef:
+        name: key-auth-primary
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+To create a consumer and configure the authentication credentials directly on the consumer:
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+  name: alice
+spec:
+  ingressClassName: apisix
+  authParameter:
+    keyAuth:
+      value:
+        key: alice-primary-key
+```
+
+You can also use the secret CRD, where the credential should be base64 encoded:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: key-auth-primary
+data:
+  key: YWxpY2UtcHJpbWFyeS1rZXk=
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+  name: alice
+spec:
+  ingressClassName: apisix
+  authParameter:
+    keyAuth:
+      secretRef:
+        name: key-auth-primary
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Plugin on Consumer
+
+To configure plugin(s) on a consumer, such as a rate limiting plugin:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+  name: alice
+spec:
+  gatewayRef:
+    name: apisix
+  credentials:
+    - type: key-auth
+      name: alice-key
+      config:
+        key: alice-key
+  plugins:
+    - name: limit-count
+      config:
+        count: 3
+        time_window: 60
+        key: remote_addr
+        key_type: var
+        policy: local
+        rejected_code: 429
+        rejected_msg: Too many requests
+        show_limit_quota_header: true
+        allow_degradation: false
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+ApisixConsumer currently does not support configuring plugins on consumers.
+
+</TabItem>
+
+</Tabs>
+
+## Configure Route Priority and Matching Conditions
+
+To configure route priority and request matching conditions on a targeted route:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: HTTPRoutePolicy
+metadata:
+  name: http-route-policy
+spec:
+  targetRefs:
+  - group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: httpbin
+  priority: 10
+  vars:
+  - - http_x_test_name
+    - ==
+    - new_name
+  - - arg_test
+    - ==
+    - test_name
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  http:
+  - name: httpbin
+    match:
+      paths:
+      - /*
+      exprs:
+      - subject:
+          scope: Header
+          name: X-Test-Name
+        op: Equal
+        value: new_name
+      - subject:
+          scope: Query
+          name: test
+        op: Equal
+        value: test_name
+    backends:
+    - serviceName: httpbin
+      servicePort: 80
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Plugin on a Route
+
+To configure plugins on a route:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+  name: auth-plugin-config
+spec:
+  plugins:
+    - name: key-auth
+      config:
+        _meta:
+          disable: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: get-ip
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches: 
+    - path:
+        type: Exact
+        value: /ip
+    filters:
+    - type: ExtensionRef
+      extensionRef:
+        group: apisix.apache.org
+        kind: PluginConfig
+        name: auth-plugin-config
+    backendRefs:
+    - name: httpbin
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+To enable `basic-auth`, `key-auth`, `wolf-rbac`, `jwt-auth`, `ldap-auth`, or `hmac-auth`:
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: get-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: get-ip
+      match:
+        paths:
+          - /ip
+    authentication:
+      enable: true
+      type: keyAuth
+    backends:
+    - serviceName: httpbin
+      servicePort: 80
+```
+
+To enable other plugins:
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: get-ip
+spec:
+  ingressClassName: apisix
+  http:
+    - name: get-ip
+      match:
+        paths:
+          - /ip
+      plugins:
+      - name: limit-count
+        enable: true
+        config:
+          count: 2
+          time_window: 10
+          rejected_code: 429
+    backends:
+    - serviceName: httpbin
+      servicePort: 80
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Global Plugin
+
+To configure a global plugin:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+spec:
+  plugins:
+  - name: clickhouse-logger
+    config:
+      endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123
+      user: quickstart-user
+      password: quickstart-pass
+      logtable: test
+      database: quickstart_db
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixGlobalRule
+metadata:
+  name: apisix-global-rule-logging
+spec:
+  ingressClassName: apisix
+  plugins:
+  - name: clickhouse-logger
+    enable: true
+    config:
+      endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123
+      user: quickstart-user
+      password: quickstart-pass
+      logtable: test
+      database: quickstart_db
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Plugin Metadata
+
+To configure plugin metadata:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+spec:
+  pluginMetadata:
+    opentelemetry: {
+      "trace_id_source": "x-request-id",
+      "resource": {
+        "service.name": "APISIX"
+      },
+      "collector": {
+        "address": "simplest-collector:4318",
+        "request_timeout": 3,
+        "request_headers": {
+          "Authorization": "token"
+        }
+      },
+      "batch_span_processor": {
+        "drop_on_queue_full": false,
+        "max_queue_size": 1024,
+        "batch_timeout": 2,
+        "inactive_timeout": 1,
+        "max_export_batch_size": 16
+      },
+      "set_ngx_var": true
+    }
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Not currently supported.
+
+</TabItem>
+
+</Tabs>
+
+## Configure Plugin Config
+
+To create a plugin config and reference it in a route:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway">
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+  name: example-plugin-config
+spec:
+  plugins:
+  - name: response-rewrite
+    enable: true
+    config:
+      headers:
+        X-Plugin-Config: "example-response-rewrite"
+        X-Plugin-Test: "enabled"
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: httpbin
+spec:
+  parentRefs:
+  - name: apisix
+  rules:
+  - matches: 
+    - path:
+        type: Exact
+        value: /ip
+    filters:
+    - type: ExtensionRef
+      extensionRef:
+        group: apisix.apache.org
+        kind: PluginConfig
+        name: example-plugin-config
+    backendRefs:
+    - name: httpbin
+      port: 80
+```
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixPluginConfig
+metadata:
+  name: example-plugin-config
+spec:
+  ingressClassName: apisix
+  plugins:
+  - name: response-rewrite
+    enable: true
+    config:
+      headers:
+        X-Plugin-Config: "example-response-rewrite"
+        X-Plugin-Test: "enabled"
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpbin
+spec:
+  ingressClassName: apisix
+  http:
+  - name: get-ip
+    match:
+      paths:
+      - /ip
+    backends:
+    - serviceName: httpbin
+      servicePort: 80
+    plugin_config_name: example-plugin-config
+```
+
+</TabItem>
+
+</Tabs>
+
+## Configure Gateway Access Information
+
+These configurations allow Ingress Controller users to access the gateway.
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway"
+values={[
+{label: 'Gateway API', value: 'gateway'},
+{label: 'Ingress', value: 'ingress'},
+{label: 'APISIX CRD', value: 'apisix-crd'},
+]}>
+
+<TabItem value="gateway">
+
+To configure the `statusAddress`:
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+spec:
+  statusAddress:
+    - 10.24.87.13
+```
+
+</TabItem>
+
+<TabItem value="ingress">
+
+If you are using Ingress resources, you can configure either `statusAddress` or `publishService`.
+
+To configure the `statusAddress`:
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+spec:
+  statusAddress:
+    - 10.24.87.13
+```
+
+To configure the `publishService`:
+
+```yaml
+apiVersion: apisix.apache.org/v1alpha1
+kind: GatewayProxy
+metadata:
+  name: apisix-config
+spec:
+  publishService: apisix-ee-3-gateway-gateway
+```
+
+When using `publishService`, make sure your gateway Service is of `LoadBalancer` type the address can be populated. The controller will use the endpoint of this Service to update the status information of the Ingress resource. The format can be either `namespace/svc-name` or simply `svc-name` if the default namespace is correctly set.
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Not supported.
+
+</TabItem>
+
+</Tabs>