diff --git a/api/v1alpha1/backendtrafficpolicy_types.go b/api/v1alpha1/backendtrafficpolicy_types.go index 9e2f1d756..fed45a8ff 100644 --- a/api/v1alpha1/backendtrafficpolicy_types.go +++ b/api/v1alpha1/backendtrafficpolicy_types.go @@ -10,6 +10,8 @@ type BackendTrafficPolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // BackendTrafficPolicySpec defines traffic handling policies applied to backend services, + // such as load balancing strategy, connection settings, and failover behavior. Spec BackendTrafficPolicySpec `json:"spec,omitempty"` Status PolicyStatus `json:"status,omitempty"` } @@ -25,57 +27,71 @@ type BackendTrafficPolicySpec struct { // LoadBalancer represents the load balancer configuration for Kubernetes Service. // The default strategy is round robin. LoadBalancer *LoadBalancer `json:"loadbalancer,omitempty" yaml:"loadbalancer,omitempty"` - // The scheme used to talk with the upstream. - // + // Scheme is the protocol used to communicate with the upstream. + // Default is `http`. + // Can be one of `http`, `https`, `grpc`, or `grpcs`. // +kubebuilder:validation:Enum=http;https;grpc;grpcs; // +kubebuilder:default=http Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"` - // How many times that the proxy (Apache APISIX) should do when - // errors occur (error, timeout or bad http status codes like 500, 502). + // Retries specify the number of times the gateway should retry sending + // requests when errors such as timeouts or 502 errors occur. // +optional Retries *int `json:"retries,omitempty" yaml:"retries,omitempty"` - // Timeout settings for the read, send and connect to the upstream. + // Timeout sets the read, send, and connect timeouts to the upstream. Timeout *Timeout `json:"timeout,omitempty" yaml:"timeout,omitempty"` - // Configures the host when the request is forwarded to the upstream. - // Can be one of pass, node or rewrite. + // PassHost configures how the host header should be determined when a + // request is forwarded to the upstream. + // Default is `pass`. + // Can be one of `pass`, `node` or `rewrite`. // // +kubebuilder:validation:Enum=pass;node;rewrite; // +kubebuilder:default=pass PassHost string `json:"passHost,omitempty" yaml:"passHost,omitempty"` - // Specifies the host of the Upstream request. This is only valid if - // the passHost is set to rewrite + // UpstreamHost specifies the host of the Upstream request. Used only if + // passHost is set to `rewrite`. Host Hostname `json:"upstreamHost,omitempty" yaml:"upstreamHost,omitempty"` } // LoadBalancer describes the load balancing parameters. // +kubebuilder:validation:XValidation:rule="!(has(self.key) && self.type != 'chash')" type LoadBalancer struct { + // Type specifies the load balancing algorithms. + // Default is `roundrobin`. + // Can be one of `roundrobin`, `chash`, `ewma`, or `least_conn`. // +kubebuilder:validation:Enum=roundrobin;chash;ewma;least_conn; // +kubebuilder:default=roundrobin // +kubebuilder:validation:Required Type string `json:"type" yaml:"type"` - // The HashOn and Key fields are required when Type is "chash". - // HashOn represents the key fetching scope. + // HashOn specified the type of field used for hashing, required when Type is `chash`. + // Default is `vars`. + // Can be one of `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`. // +kubebuilder:validation:Enum=vars;header;cookie;consumer;vars_combinations; // +kubebuilder:default=vars HashOn string `json:"hashOn,omitempty" yaml:"hashOn,omitempty"` - // Key represents the hash key. + // Key is used with HashOn, generally required when Type is `chash`. + // When HashOn is `header` or `cookie`, specifies the name of the header or cookie. + // When HashOn is `consumer`, key is not required, as the consumer name is used automatically. + // When HashOn is `vars` or `vars_combinations`, key refers to one or a combination of + // [built-in variables](/enterprise/reference/built-in-variables). Key string `json:"key,omitempty" yaml:"key,omitempty"` } type Timeout struct { + // Connection timeout. Default is `60s`. // +kubebuilder:default="60s" // +kubebuilder:validation:Pattern=`^[0-9]+s$` // +kubebuilder:validation:Type=string Connect metav1.Duration `json:"connect,omitempty" yaml:"connect,omitempty"` + // Send timeout. Default is `60s`. // +kubebuilder:default="60s" // +kubebuilder:validation:Pattern=`^[0-9]+s$` // +kubebuilder:validation:Type=string Send metav1.Duration `json:"send,omitempty" yaml:"send,omitempty"` + // Read timeout. Default is `60s`. // +kubebuilder:default="60s" // +kubebuilder:validation:Pattern=`^[0-9]+s$` // +kubebuilder:validation:Type=string diff --git a/api/v1alpha1/consumer_types.go b/api/v1alpha1/consumer_types.go index e0cda80d7..d6762c3e0 100644 --- a/api/v1alpha1/consumer_types.go +++ b/api/v1alpha1/consumer_types.go @@ -11,38 +11,54 @@ type Consumer struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // ConsumerSpec defines the configuration for a consumer, including consumer name, + // authentication credentials, and plugin settings. Spec ConsumerSpec `json:"spec,omitempty"` Status Status `json:"status,omitempty"` } type ConsumerSpec struct { + // GatewayRef specifies the gateway details. GatewayRef GatewayRef `json:"gatewayRef,omitempty"` + // Credentials specifies the credential details of a consumer. Credentials []Credential `json:"credentials,omitempty"` + // Plugins define the plugins associated with a consumer. Plugins []Plugin `json:"plugins,omitempty"` } type GatewayRef struct { + // Name is the name of the gateway. // +kubebuilder:validation:Required // +kubebuilder:validation:MinLength=1 Name string `json:"name"` + // Kind is the type of Kubernetes object. Default is `Gateway`. // +kubebuilder:default=Gateway Kind *string `json:"kind,omitempty"` + // Group is the API group the resource belongs to. Default is `gateway.networking.k8s.io`. // +kubebuilder:default=gateway.networking.k8s.io Group *string `json:"group,omitempty"` + // Namespace is namespace of the resource. Namespace *string `json:"namespace,omitempty"` } type Credential struct { // +kubebuilder:validation:Required // +kubebuilder:validation:Enum=jwt-auth;basic-auth;key-auth;hmac-auth; + // Type specifies the type of authentication to configure credentials for. + // Can be one of `jwt-auth`, `basic-auth`, `key-auth`, or `hmac-auth`. Type string `json:"type"` + // Config specifies the credential details for authentication. Config apiextensionsv1.JSON `json:"config,omitempty"` + // SecretRef references to the Secret that contains the credentials. SecretRef *SecretReference `json:"secretRef,omitempty"` + // Name is the name of the credential. Name string `json:"name,omitempty"` } type SecretReference struct { + // Name is the name of the secret. Name string `json:"name"` + // Namespace is the namespace of the secret. Namespace *string `json:"namespace,omitempty"` } diff --git a/api/v1alpha1/gatewayproxy_types.go b/api/v1alpha1/gatewayproxy_types.go index 45f534af6..db552bf98 100644 --- a/api/v1alpha1/gatewayproxy_types.go +++ b/api/v1alpha1/gatewayproxy_types.go @@ -24,124 +24,138 @@ import ( // EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN! // NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized. -// GatewayProxySpec defines the desired state of GatewayProxy +// GatewayProxySpec defines the desired state of GatewayProxy. type GatewayProxySpec struct { // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster // Important: Run "make" to regenerate code after modifying this file + // PublishService specifies the LoadBalancer-type Service whose external address the controller uses to + // update the status of Ingress resources. PublishService string `json:"publishService,omitempty"` + // StatusAddress specifies the external IP addresses that the controller uses to populate the status field + // of GatewayProxy or Ingress resources for developers to access. StatusAddress []string `json:"statusAddress,omitempty"` + // Provider configures the provider details. Provider *GatewayProxyProvider `json:"provider,omitempty"` + // Plugins configure global plugins. Plugins []GatewayProxyPlugin `json:"plugins,omitempty"` + // PluginMetadata configures common configurations shared by all plugin instances of the same name. PluginMetadata map[string]apiextensionsv1.JSON `json:"pluginMetadata,omitempty"` } -// ProviderType defines the type of provider +// ProviderType defines the type of provider. // +kubebuilder:validation:Enum=ControlPlane type ProviderType string const ( - // ProviderTypeControlPlane represents the control plane provider type + // ProviderTypeControlPlane represents the control plane provider type. ProviderTypeControlPlane ProviderType = "ControlPlane" ) -// GatewayProxyProvider defines the provider configuration for GatewayProxy +// GatewayProxyProvider defines the provider configuration for GatewayProxy. // +kubebuilder:validation:XValidation:rule="self.type == 'ControlPlane' ? has(self.controlPlane) : true",message="controlPlane must be specified when type is ControlPlane" type GatewayProxyProvider struct { - // Type specifies the type of provider + // Type specifies the type of provider. Can only be `ControlPlane`. // +kubebuilder:validation:Required Type ProviderType `json:"type"` - // ControlPlane specifies the configuration for control plane provider + // ControlPlane specifies the configuration for control plane provider. // +optional ControlPlane *ControlPlaneProvider `json:"controlPlane,omitempty"` } -// AuthType defines the type of authentication +// AuthType defines the type of authentication. // +kubebuilder:validation:Enum=AdminKey type AuthType string const ( - // AuthTypeAdminKey represents the admin key authentication type + // AuthTypeAdminKey represents the admin key authentication type. AuthTypeAdminKey AuthType = "AdminKey" ) -// SecretKeySelector defines a reference to a specific key within a Secret +// SecretKeySelector defines a reference to a specific key within a Secret. type SecretKeySelector struct { - // Name is the name of the secret + // Name is the name of the secret. // +kubebuilder:validation:Required Name string `json:"name"` - // Key is the key in the secret + // Key is the key in the secret to retrieve the secret from. // +kubebuilder:validation:Required Key string `json:"key"` } -// AdminKeyAuth defines the admin key authentication configuration +// AdminKeyAuth defines the admin key authentication configuration. type AdminKeyAuth struct { - // Value specifies the admin key value directly (not recommended for production) + // Value sets the admin key value explicitly (not recommended for production). // +optional Value string `json:"value,omitempty"` - // ValueFrom specifies the source of the admin key + // ValueFrom specifies the source of the admin key. // +optional ValueFrom *AdminKeyValueFrom `json:"valueFrom,omitempty"` } -// AdminKeyValueFrom defines the source of the admin key +// AdminKeyValueFrom defines the source of the admin key. type AdminKeyValueFrom struct { - // SecretKeyRef references a key in a Secret + // SecretKeyRef references a key in a Secret. // +optional SecretKeyRef *SecretKeySelector `json:"secretKeyRef,omitempty"` } -// ControlPlaneAuth defines the authentication configuration for control plane +// ControlPlaneAuth defines the authentication configuration for control plane. type ControlPlaneAuth struct { - // Type specifies the type of authentication + // Type specifies the type of authentication. + // Can only be `AdminKey`. // +kubebuilder:validation:Required Type AuthType `json:"type"` - // AdminKey specifies the admin key authentication configuration + // AdminKey specifies the admin key authentication configuration. // +optional AdminKey *AdminKeyAuth `json:"adminKey,omitempty"` } -// ControlPlaneProvider defines the configuration for control plane provider +// ControlPlaneProvider defines the configuration for control plane provider. type ControlPlaneProvider struct { - // Endpoints specifies the list of control plane endpoints + // Endpoints specifies the list of control plane endpoints. // +kubebuilder:validation:Required // +kubebuilder:validation:MinItems=1 Endpoints []string `json:"endpoints"` - // TlsVerify specifies whether to verify the TLS certificate of the control plane + // TlsVerify specifies whether to verify the TLS certificate of the control plane. // +optional TlsVerify *bool `json:"tlsVerify,omitempty"` - // Auth specifies the authentication configuration + // Auth specifies the authentication configurations. // +kubebuilder:validation:Required Auth ControlPlaneAuth `json:"auth"` } // +kubebuilder:object:root=true -// GatewayProxy is the Schema for the gatewayproxies API +// GatewayProxy is the Schema for the gatewayproxies API. type GatewayProxy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // GatewayProxySpec defines the desired state and configuration of a GatewayProxy, + // including networking settings, global plugins, and plugin metadata. Spec GatewayProxySpec `json:"spec,omitempty"` } // +kubebuilder:object:root=true -// GatewayProxyList contains a list of GatewayProxy +// GatewayProxyList contains a list of GatewayProxy. type GatewayProxyList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` Items []GatewayProxy `json:"items"` } +// GatewayProxyPlugin contains plugin configurations. type GatewayProxyPlugin struct { + // Name is the name of the plugin. Name string `json:"name,omitempty"` + // Enabled defines whether the plugin is enabled. Enabled bool `json:"enabled,omitempty"` + // Config defines the plugin's configuration details. Config apiextensionsv1.JSON `json:"config,omitempty"` } diff --git a/api/v1alpha1/httproutepolicy_types.go b/api/v1alpha1/httproutepolicy_types.go index e307b4f31..7e4907a4d 100644 --- a/api/v1alpha1/httproutepolicy_types.go +++ b/api/v1alpha1/httproutepolicy_types.go @@ -24,14 +24,13 @@ import ( // HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy. type HTTPRoutePolicySpec struct { - // TargetRef identifies an API object (enum: HTTPRoute, Ingress) to apply HTTPRoutePolicy to. - // - // target references. + // TargetRef identifies an API object (i.e. HTTPRoute, Ingress) to apply HTTPRoutePolicy to. // +kubebuilder:validation:MinItems=1 // +kubebuilder:validation:MaxItems=16 TargetRefs []gatewayv1alpha2.LocalPolicyTargetReferenceWithSectionName `json:"targetRefs"` - + // Priority sets the priority for route. A higher value sets a higher priority in route matching. Priority *int64 `json:"priority,omitempty" yaml:"priority,omitempty"` + // Vars sets the request matching conditions. Vars []apiextensionsv1.JSON `json:"vars,omitempty" yaml:"vars,omitempty"` } @@ -43,6 +42,8 @@ type HTTPRoutePolicy struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // HTTPRoutePolicySpec defines the desired state and configuration of a HTTPRoutePolicy, + // including route priority and request matching conditions. Spec HTTPRoutePolicySpec `json:"spec,omitempty"` Status PolicyStatus `json:"status,omitempty"` } diff --git a/api/v1alpha1/pluginconfig_types.go b/api/v1alpha1/pluginconfig_types.go index b62730b04..62b1b6e22 100644 --- a/api/v1alpha1/pluginconfig_types.go +++ b/api/v1alpha1/pluginconfig_types.go @@ -10,22 +10,25 @@ import ( // +kubebuilder:object:root=true -// PluginConfig is the Schema for the PluginConfigs API +// PluginConfig is the Schema for the PluginConfigs API. type PluginConfig struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // PluginConfigSpec defines the desired state of a PluginConfig, + // in which plugins and their configurations are specified. Spec PluginConfigSpec `json:"spec,omitempty"` } -// PluginConfigSpec defines the desired state of PluginConfig +// PluginConfigSpec defines the desired state of PluginConfig. type PluginConfigSpec struct { + // Plugins are an array of plugins and their configurations to be applied. Plugins []Plugin `json:"plugins"` } // +kubebuilder:object:root=true -// PluginConfigList contains a list of PluginConfig +// PluginConfigList contains a list of PluginConfig. type PluginConfigList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` @@ -33,9 +36,9 @@ type PluginConfigList struct { } type Plugin struct { - // The plugin name. + // Name is the name of the plugin. Name string `json:"name" yaml:"name"` - // Plugin configuration. + // Config is plugin configuration details. Config apiextensionsv1.JSON `json:"config,omitempty" yaml:"config,omitempty"` } diff --git a/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml b/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml index 7462ac3fd..2f664a553 100644 --- a/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml +++ b/config/crd/bases/apisix.apache.org_backendtrafficpolicies.yaml @@ -36,6 +36,9 @@ spec: metadata: type: object spec: + description: |- + BackendTrafficPolicySpec defines traffic handling policies applied to backend services, + such as load balancing strategy, connection settings, and failover behavior. properties: loadbalancer: description: |- @@ -45,8 +48,9 @@ spec: 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 one of `vars`, `header`, `cookie`, `consumer`, or `vars_combinations`. enum: - vars - header @@ -55,10 +59,19 @@ spec: - 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 + [built-in variables](/enterprise/reference/built-in-variables). type: string type: default: roundrobin + description: |- + Type specifies the load balancing algorithms. + Default is `roundrobin`. + Can be one of `roundrobin`, `chash`, `ewma`, or `least_conn`. enum: - roundrobin - chash @@ -73,8 +86,10 @@ spec: passHost: default: pass 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 one of `pass`, `node` or `rewrite`. enum: - pass - node @@ -82,12 +97,15 @@ spec: type: string 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 specify the number of times the gateway should retry sending + requests when errors such as timeouts or 502 errors occur. type: integer scheme: default: http - description: The scheme used to talk with the upstream. + description: |- + Scheme is the protocol used to communicate with the upstream. + Default is `http`. + Can be one of `http`, `https`, `grpc`, or `grpcs`. enum: - http - https @@ -159,26 +177,29 @@ spec: minItems: 1 type: array timeout: - description: Timeout settings for the read, send and connect to the - upstream. + description: Timeout sets the read, send, and connect timeouts to + the upstream. properties: connect: default: 60s + description: Connection timeout. Default is `60s`. pattern: ^[0-9]+s$ type: string read: default: 60s + description: Read timeout. Default is `60s`. pattern: ^[0-9]+s$ type: string send: default: 60s + description: Send timeout. Default is `60s`. pattern: ^[0-9]+s$ type: string type: object upstreamHost: description: |- - Specifies the host of the Upstream request. This is only valid if - the passHost is set to rewrite + UpstreamHost specifies the host of the Upstream request. Used only if + passHost is set to `rewrite`. maxLength: 253 minLength: 1 pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ diff --git a/config/crd/bases/apisix.apache.org_consumers.yaml b/config/crd/bases/apisix.apache.org_consumers.yaml index 6520d191e..65432feaa 100644 --- a/config/crd/bases/apisix.apache.org_consumers.yaml +++ b/config/crd/bases/apisix.apache.org_consumers.yaml @@ -36,24 +36,37 @@ spec: metadata: type: object spec: + description: |- + ConsumerSpec defines the configuration for a consumer, including consumer name, + authentication credentials, and plugin settings. properties: credentials: + description: Credentials specifies the credential details of a consumer. items: properties: config: + description: Config specifies the credential details for authentication. x-kubernetes-preserve-unknown-fields: true name: + description: Name is the name of the credential. type: string secretRef: + description: SecretRef references to the Secret that contains + the credentials. properties: name: + description: Name is the name of the secret. type: string namespace: + description: Namespace is the namespace of the secret. type: string required: - name type: object 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`. enum: - jwt-auth - basic-auth @@ -65,29 +78,37 @@ spec: type: object type: array gatewayRef: + description: GatewayRef specifies the gateway details. properties: group: default: gateway.networking.k8s.io + description: Group is the API group the resource belongs to. Default + is `gateway.networking.k8s.io`. type: string kind: default: Gateway + description: Kind is the type of Kubernetes object. Default is + `Gateway`. type: string name: + description: Name is the name of the gateway. minLength: 1 type: string namespace: + description: Namespace is namespace of the resource. type: string required: - name type: object plugins: + description: Plugins define the plugins associated with a consumer. items: properties: config: - description: Plugin configuration. + description: Config is plugin configuration details. x-kubernetes-preserve-unknown-fields: true name: - description: The plugin name. + description: Name is the name of the plugin. type: string required: - name diff --git a/config/crd/bases/apisix.apache.org_gatewayproxies.yaml b/config/crd/bases/apisix.apache.org_gatewayproxies.yaml index 2149a7e3e..cc65d486e 100644 --- a/config/crd/bases/apisix.apache.org_gatewayproxies.yaml +++ b/config/crd/bases/apisix.apache.org_gatewayproxies.yaml @@ -17,7 +17,7 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: GatewayProxy is the Schema for the gatewayproxies API + description: GatewayProxy is the Schema for the gatewayproxies API. properties: apiVersion: description: |- @@ -37,55 +37,64 @@ spec: metadata: type: object spec: - description: GatewayProxySpec defines the desired state of GatewayProxy + description: |- + GatewayProxySpec defines the desired state and configuration of a GatewayProxy, + including networking settings, global plugins, and plugin metadata. properties: pluginMetadata: additionalProperties: x-kubernetes-preserve-unknown-fields: true + description: PluginMetadata configures common configurations shared + by all plugin instances of the same name. type: object plugins: + description: Plugins configure global plugins. items: + description: GatewayProxyPlugin contains plugin configurations. properties: config: + description: Config defines the plugin's configuration details. x-kubernetes-preserve-unknown-fields: true enabled: + description: Enabled defines whether the plugin is enabled. type: boolean name: + description: Name is the name of the plugin. type: string type: object type: array provider: - description: GatewayProxyProvider defines the provider configuration - for GatewayProxy + description: Provider configures the provider details. properties: controlPlane: description: ControlPlane specifies the configuration for control - plane provider + plane provider. properties: auth: - description: Auth specifies the authentication configuration + description: Auth specifies the authentication configurations. properties: adminKey: description: AdminKey specifies the admin key authentication - configuration + configuration. properties: value: - description: Value specifies the admin key value directly - (not recommended for production) + description: Value sets the admin key value explicitly + (not recommended for production). type: string valueFrom: description: ValueFrom specifies the source of the - admin key + admin key. properties: secretKeyRef: description: SecretKeyRef references a key in - a Secret + a Secret. properties: key: description: Key is the key in the secret + to retrieve the secret from. type: string name: - description: Name is the name of the secret + description: Name is the name of the secret. type: string required: - key @@ -94,7 +103,9 @@ spec: type: object type: object type: - description: Type specifies the type of authentication + description: |- + Type specifies the type of authentication. + Can only be `AdminKey`. enum: - AdminKey type: string @@ -103,21 +114,22 @@ spec: type: object endpoints: description: Endpoints specifies the list of control plane - endpoints + endpoints. items: type: string minItems: 1 type: array tlsVerify: description: TlsVerify specifies whether to verify the TLS - certificate of the control plane + certificate of the control plane. type: boolean required: - auth - endpoints type: object type: - description: Type specifies the type of provider + description: Type specifies the type of provider. Can only be + `ControlPlane`. enum: - ControlPlane type: string @@ -129,8 +141,14 @@ spec: rule: 'self.type == ''ControlPlane'' ? has(self.controlPlane) : true' publishService: + description: |- + PublishService specifies the LoadBalancer-type Service whose external address the controller uses to + update the status of Ingress resources. type: string statusAddress: + description: |- + StatusAddress specifies the external IP addresses that the controller uses to populate the status field + of GatewayProxy or Ingress resources for developers to access. items: type: string type: array diff --git a/config/crd/bases/apisix.apache.org_httproutepolicies.yaml b/config/crd/bases/apisix.apache.org_httproutepolicies.yaml index 0f66ac054..737526ecd 100644 --- a/config/crd/bases/apisix.apache.org_httproutepolicies.yaml +++ b/config/crd/bases/apisix.apache.org_httproutepolicies.yaml @@ -37,17 +37,18 @@ spec: metadata: type: object spec: - description: HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy. + description: |- + HTTPRoutePolicySpec defines the desired state and 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. format: int64 type: integer targetRefs: - description: |- - TargetRef identifies an API object (enum: HTTPRoute, Ingress) to apply HTTPRoutePolicy to. - - - target references. + description: TargetRef identifies an API object (i.e. HTTPRoute, Ingress) + to apply HTTPRoutePolicy to. items: description: |- LocalPolicyTargetReferenceWithSectionName identifies an API object to apply a @@ -105,6 +106,7 @@ spec: minItems: 1 type: array vars: + description: Vars sets the request matching conditions. items: x-kubernetes-preserve-unknown-fields: true type: array diff --git a/config/crd/bases/apisix.apache.org_pluginconfigs.yaml b/config/crd/bases/apisix.apache.org_pluginconfigs.yaml index 3b0ddfaeb..6998a8114 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 is the Schema for the PluginConfigs API. properties: apiVersion: description: |- @@ -37,16 +37,20 @@ spec: metadata: type: object spec: - description: PluginConfigSpec defines the desired state of PluginConfig + description: |- + PluginConfigSpec defines the desired state of a PluginConfig, + in which plugins and their configurations are specified. properties: plugins: + description: Plugins are an array of plugins and their configurations + to be applied. items: properties: config: - description: Plugin configuration. + description: Config is plugin configuration details. x-kubernetes-preserve-unknown-fields: true name: - description: The plugin name. + description: Name is the name of the plugin. type: string required: - name diff --git a/docs/crd/api.md b/docs/crd/api.md index f42684721..dc6c6a925 100644 --- a/docs/crd/api.md +++ b/docs/crd/api.md @@ -31,7 +31,7 @@ Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alp | `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)_ | | +| `spec` _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | BackendTrafficPolicySpec defines traffic handling policies applied to backend services, such as load balancing strategy, connection settings, and failover behavior. | @@ -47,14 +47,14 @@ Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alp | `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)_ | | +| `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 is the Schema for the gatewayproxies API. @@ -63,7 +63,7 @@ GatewayProxy is the Schema for the gatewayproxies API | `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)_ | | +| `spec` _[GatewayProxySpec](#gatewayproxyspec)_ | GatewayProxySpec defines the desired state and configuration of a GatewayProxy, including networking settings, global plugins, and plugin metadata. | @@ -79,14 +79,14 @@ HTTPRoutePolicy is the Schema for the httproutepolicies API. | `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)_ | | +| `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 is the Schema for the PluginConfigs API. @@ -95,7 +95,7 @@ PluginConfig is the Schema for the PluginConfigs API | `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)_ | | +| `spec` _[PluginConfigSpec](#pluginconfigspec)_ | PluginConfigSpec defines the desired state of a PluginConfig, in which plugins and their configurations are specified. | @@ -105,14 +105,14 @@ In this section you will find types that the CRDs rely on. #### AdminKeyAuth -AdminKeyAuth defines the admin key authentication configuration +AdminKeyAuth defines the admin key authentication configuration. | Field | Description | | --- | --- | -| `value` _string_ | Value specifies the admin key value directly (not recommended for production) | -| `valueFrom` _[AdminKeyValueFrom](#adminkeyvaluefrom)_ | ValueFrom specifies the source of the admin key | +| `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:_ @@ -121,13 +121,13 @@ _Appears in:_ #### AdminKeyValueFrom -AdminKeyValueFrom defines the source of the admin key +AdminKeyValueFrom defines the source of the admin key. | Field | Description | | --- | --- | -| `secretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | SecretKeyRef references a key in a Secret | +| `secretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | SecretKeyRef references a key in a Secret. | _Appears in:_ @@ -136,7 +136,7 @@ _Appears in:_ #### AuthType _Base type:_ `string` -AuthType defines the type of authentication +AuthType defines the type of authentication. @@ -174,11 +174,11 @@ _Appears in:_ | --- | --- | | `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_ | The scheme used to talk with the upstream. | -| `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` _[Timeout](#timeout)_ | Timeout settings for the read, send and connect to the upstream. | -| `passHost` _string_ | Configures the host when the request is forwarded to the upstream. Can be one of pass, node or rewrite. | -| `upstreamHost` _[Hostname](#hostname)_ | Specifies the host of the Upstream request. This is only valid if the passHost is set to rewrite | +| `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:_ @@ -193,9 +193,9 @@ _Appears in:_ | Field | Description | | --- | --- | -| `gatewayRef` _[GatewayRef](#gatewayref)_ | | -| `credentials` _[Credential](#credential) array_ | | -| `plugins` _[Plugin](#plugin) array_ | | +| `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:_ @@ -204,14 +204,14 @@ _Appears in:_ #### ControlPlaneAuth -ControlPlaneAuth defines the authentication configuration for control plane +ControlPlaneAuth defines the authentication configuration for control plane. | Field | Description | | --- | --- | -| `type` _[AuthType](#authtype)_ | Type specifies the type of authentication | -| `adminKey` _[AdminKeyAuth](#adminkeyauth)_ | AdminKey specifies the admin key authentication configuration | +| `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:_ @@ -220,15 +220,15 @@ _Appears in:_ #### ControlPlaneProvider -ControlPlaneProvider defines the configuration for control plane provider +ControlPlaneProvider defines the configuration for control plane provider. | Field | Description | | --- | --- | -| `endpoints` _string array_ | Endpoints specifies the list of control plane endpoints | -| `tlsVerify` _boolean_ | TlsVerify specifies whether to verify the TLS certificate of the control plane | -| `auth` _[ControlPlaneAuth](#controlplaneauth)_ | Auth specifies the authentication configuration | +| `endpoints` _string array_ | Endpoints specifies the list of control plane endpoints. | +| `tlsVerify` _boolean_ | TlsVerify specifies whether to verify the TLS certificate of the control plane. | +| `auth` _[ControlPlaneAuth](#controlplaneauth)_ | Auth specifies the authentication configurations. | _Appears in:_ @@ -243,10 +243,10 @@ _Appears in:_ | Field | Description | | --- | --- | -| `type` _string_ | | -| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | | -| `secretRef` _[SecretReference](#secretreference)_ | | -| `name` _string_ | | +| `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:_ @@ -255,15 +255,15 @@ _Appears in:_ #### GatewayProxyPlugin - +GatewayProxyPlugin contains plugin configurations. | Field | Description | | --- | --- | -| `name` _string_ | | -| `enabled` _boolean_ | | -| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | | +| `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:_ @@ -272,14 +272,14 @@ _Appears in:_ #### GatewayProxyProvider -GatewayProxyProvider defines the provider configuration for GatewayProxy +GatewayProxyProvider defines the provider configuration for GatewayProxy. | Field | Description | | --- | --- | -| `type` _[ProviderType](#providertype)_ | Type specifies the type of provider | -| `controlPlane` _[ControlPlaneProvider](#controlplaneprovider)_ | ControlPlane specifies the configuration for control plane provider | +| `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:_ @@ -288,17 +288,17 @@ _Appears in:_ #### GatewayProxySpec -GatewayProxySpec defines the desired state of GatewayProxy +GatewayProxySpec defines the desired state of GatewayProxy. | Field | Description | | --- | --- | -| `publishService` _string_ | | -| `statusAddress` _string array_ | | -| `provider` _[GatewayProxyProvider](#gatewayproxyprovider)_ | | -| `plugins` _[GatewayProxyPlugin](#gatewayproxyplugin) array_ | | -| `pluginMetadata` _object (keys:string, values:[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io))_ | | +| `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:_ @@ -313,10 +313,10 @@ _Appears in:_ | Field | Description | | --- | --- | -| `name` _string_ | | -| `kind` _string_ | | -| `group` _string_ | | -| `namespace` _string_ | | +| `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:_ @@ -331,9 +331,9 @@ HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy. | Field | Description | | --- | --- | -| `targetRefs` _LocalPolicyTargetReferenceWithSectionName array_ | TargetRef identifies an API object (enum: HTTPRoute, Ingress) to apply HTTPRoutePolicy to.

target references. | -| `priority` _integer_ | | -| `vars` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io) array_ | | +| `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:_ @@ -360,9 +360,9 @@ 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. | +| `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 [built-in variables](/enterprise/reference/built-in-variables). | _Appears in:_ @@ -377,8 +377,8 @@ _Appears in:_ | Field | Description | | --- | --- | -| `name` _string_ | The plugin name. | -| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Plugin configuration. | +| `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:_ @@ -388,13 +388,13 @@ _Appears in:_ #### PluginConfigSpec -PluginConfigSpec defines the desired state of PluginConfig +PluginConfigSpec defines the desired state of PluginConfig. | Field | Description | | --- | --- | -| `plugins` _[Plugin](#plugin) array_ | | +| `plugins` _[Plugin](#plugin) array_ | Plugins are an array of plugins and their configurations to be applied. | _Appears in:_ @@ -405,7 +405,7 @@ _Appears in:_ #### ProviderType _Base type:_ `string` -ProviderType defines the type of provider +ProviderType defines the type of provider. @@ -417,14 +417,14 @@ _Appears in:_ #### SecretKeySelector -SecretKeySelector defines a reference to a specific key within a Secret +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 | +| `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:_ @@ -439,8 +439,8 @@ _Appears in:_ | Field | Description | | --- | --- | -| `name` _string_ | | -| `namespace` _string_ | | +| `name` _string_ | Name is the name of the secret. | +| `namespace` _string_ | Namespace is the namespace of the secret. | _Appears in:_ @@ -457,9 +457,9 @@ _Appears in:_ | 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)_ | | +| `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:_