Version: Next

Custom Resource Definitions API Reference

This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs).

Packages#

apisix.apache.org/v1alpha1
apisix.apache.org/v2

apisix.apache.org/v1alpha1#

Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group.

BackendTrafficPolicy
Consumer
GatewayProxy
HTTPRoutePolicy
PluginConfig

BackendTrafficPolicy#

BackendTrafficPolicy defines configuration for traffic handling policies applied to backend services.

Field	Description
`apiVersion` string	`apisix.apache.org/v1alpha1`
`kind` string	`BackendTrafficPolicy`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` 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.

Field	Description
`apiVersion` string	`apisix.apache.org/v1alpha1`
`kind` string	`Consumer`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` 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.

Field	Description
`apiVersion` string	`apisix.apache.org/v1alpha1`
`kind` string	`GatewayProxy`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` GatewayProxySpec	GatewayProxySpec defines configuration of gateway proxy instances, including networking settings, global plugins, and plugin metadata.

HTTPRoutePolicy#

HTTPRoutePolicy defines configuration of traffic policies.

Field	Description
`apiVersion` string	`apisix.apache.org/v1alpha1`
`kind` string	`HTTPRoutePolicy`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` HTTPRoutePolicySpec	HTTPRoutePolicySpec defines configuration of a HTTPRoutePolicy, including route priority and request matching conditions.

PluginConfig#

PluginConfig defines plugin configuration.

Field	Description
`apiVersion` string	`apisix.apache.org/v1alpha1`
`kind` string	`PluginConfig`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` 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	ValueFrom specifies the source of the admin key.

Appears in:

ControlPlaneAuth

AdminKeyValueFrom#

AdminKeyValueFrom defines the source of the admin key.

Field	Description
`secretKeyRef` SecretKeySelector	SecretKeyRef references a key in a Secret.

Appears in:

AdminKeyAuth

AuthType#

Base type: string

AuthType defines the type of authentication.

Appears in:

ControlPlaneAuth

BackendPolicyTargetReferenceWithSectionName#

Base type: LocalPolicyTargetReferenceWithSectionName

Field	Description
`group` Group	Group is the group of the target resource.
`kind` Kind	Kind is kind of the target resource.
`name` ObjectName	Name is the name of the target resource.
`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: • Gateway: Listener name • HTTPRoute: HTTPRouteRule name • Service: Port name If a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implementation should record a `ResolvedRefs` or similar Condition in the Policy's status.

Appears in:

BackendTrafficPolicySpec

BackendTrafficPolicySpec#

Field	Description
`targetRefs` 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 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 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`: • `pass`: preserve the original Host header • `node`: use the upstream node’s host • `rewrite`: set to a custom host via `upstreamHost`
`upstreamHost` Hostname	UpstreamHost specifies the host of the Upstream request. Used only if passHost is set to `rewrite`.

Appears in:

BackendTrafficPolicy

ConsumerSpec#

Field	Description
`gatewayRef` GatewayRef	GatewayRef specifies the gateway details.
`credentials` Credential array	Credentials specifies the credential details of a consumer.
`plugins` Plugin array	Plugins define the plugins associated with a consumer.

Appears in:

Consumer

ControlPlaneAuth#

ControlPlaneAuth defines the authentication configuration for control plane.

Field	Description
`type` AuthType	Type specifies the type of authentication. Can only be `AdminKey`.
`adminKey` AdminKeyAuth	AdminKey specifies the admin key authentication configuration.

Appears in:

ControlPlaneProvider

ControlPlaneProvider#

ControlPlaneProvider defines configuration for control plane provider.

Field	Description
`endpoints` string array	Endpoints specifies the list of control plane endpoints.
`service` ProviderService
`tlsVerify` boolean	TlsVerify specifies whether to verify the TLS certificate of the control plane.
`auth` ControlPlaneAuth	Auth specifies the authentication configuration.

Appears in:

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	Config specifies the credential details for authentication.
`secretRef` SecretReference	SecretRef references to the Secret that contains the credentials.
`name` string	Name is the name of the credential.

Appears in:

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	Config defines the plugin's configuration details.

Appears in:

GatewayProxySpec

GatewayProxyProvider#

GatewayProxyProvider defines the provider configuration for GatewayProxy.

Field	Description
`type` ProviderType	Type specifies the type of provider. Can only be `ControlPlane`.
`controlPlane` ControlPlaneProvider	ControlPlane specifies the configuration for control plane provider.

Appears in:

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	Provider configures the provider details.
`plugins` GatewayProxyPlugin array	Plugins configure global plugins.
`pluginMetadata` object (keys:string, values:JSON)	PluginMetadata configures common configuration shared by all plugin instances of the same name.

Appears in:

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

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 array	Vars sets the request matching conditions.

Appears in:

HTTPRoutePolicy

Hostname#

Base type: string

Appears in:

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.

Appears in:

BackendTrafficPolicySpec

Plugin#

Field	Description
`name` string	Name is the name of the plugin.
`config` JSON	Config is plugin configuration details.

Appears in:

ConsumerSpec
PluginConfigSpec

PluginConfigSpec#

PluginConfigSpec defines the desired state of PluginConfig.

Field	Description
`plugins` Plugin array	Plugins are an array of plugins and their configuration to be applied.

Appears in:

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

ProviderType#

Base type: string

ProviderType defines the type of provider.

Appears in:

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

SecretReference#

Field	Description
`name` string	Name is the name of the secret.
`namespace` string	Namespace is the namespace of the secret.

Appears in:

Credential

Status#

Field	Description
`conditions` Condition array

Appears in:

ConsumerStatus

Timeout#

Field	Description
`connect` Duration	Connection timeout. Default is `60s`.
`send` Duration	Send timeout. Default is `60s`.
`read` Duration	Read timeout. Default is `60s`.

Appears in:

BackendTrafficPolicySpec

apisix.apache.org/v2#

Package v2 contains API Schema definitions for the apisix.apache.org v2 API group.

ApisixConsumer
ApisixGlobalRule
ApisixPluginConfig
ApisixRoute
ApisixTls
ApisixUpstream

ApisixConsumer#

ApisixConsumer defines configuration of a consumer and their authentication details.

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixConsumer`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` ApisixConsumerSpec	ApisixConsumerSpec defines the consumer authentication configuration.

ApisixGlobalRule#

ApisixGlobalRule defines configuration for global plugins.

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixGlobalRule`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` ApisixGlobalRuleSpec	ApisixGlobalRuleSpec defines the global plugin configuration.

ApisixPluginConfig#

ApisixPluginConfig defines a reusable set of plugin configuration that can be referenced by routes.

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixPluginConfig`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` ApisixPluginConfigSpec	ApisixPluginConfigSpec defines the plugin config configuration.

ApisixRoute#

ApisixRoute is defines configuration for HTTP and stream routes.

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixRoute`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` ApisixRouteSpec	ApisixRouteSpec defines HTTP and stream route configuration.

ApisixTls#

ApisixTls defines configuration for TLS and mutual TLS (mTLS).

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixTls`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` ApisixTlsSpec	ApisixTlsSpec defines the TLS configuration.

ApisixUpstream#

ApisixUpstream defines configuration for upstream services.

Field	Description
`apiVersion` string	`apisix.apache.org/v2`
`kind` string	`ApisixUpstream`
`metadata` ObjectMeta	Please refer to the Kubernetes API documentation for details on the `metadata` field.
`spec` 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	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	Healthy configures the rules that define an upstream node as healthy.
`unhealthy` ActiveHealthCheckUnhealthy	Unhealthy configures the rules that define an upstream node as unhealthy.

Appears in:

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	Interval defines the time interval for checking targets, in seconds.

Appears in:

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	Interval defines the time interval for checking targets, in seconds.

Appears in:

ActiveHealthCheck

ApisixConsumerAuthParameter#

Field	Description
`basicAuth` ApisixConsumerBasicAuth	BasicAuth configures the basic authentication details.
`keyAuth` ApisixConsumerKeyAuth	KeyAuth configures the key authentication details.
`wolfRBAC` ApisixConsumerWolfRBAC	WolfRBAC configures the Wolf RBAC authentication details.
`jwtAuth` ApisixConsumerJwtAuth	JwtAuth configures the JWT authentication details.
`hmacAuth` ApisixConsumerHMACAuth	HMACAuth configures the HMAC authentication details.
`ldapAuth` ApisixConsumerLDAPAuth	LDAPAuth configures the LDAP authentication details.

Appears in:

ApisixConsumerSpec

ApisixConsumerBasicAuth#

ApisixConsumerBasicAuth defines configuration for basic authentication.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the basic authentication credentials.
`value` ApisixConsumerBasicAuthValue	Value specifies the basic authentication credentials.

Appears in:

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

ApisixConsumerHMACAuth#

ApisixConsumerHMACAuth defines configuration for the HMAC authentication.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the HMAC credentials.
`value` ApisixConsumerHMACAuthValue	Value specifies HMAC authentication credentials.

Appears in:

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

ApisixConsumerJwtAuth#

ApisixConsumerJwtAuth defines configuration for JWT authentication.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing JWT authentication credentials.
`value` ApisixConsumerJwtAuthValue	Value specifies JWT authentication credentials.

Appears in:

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

ApisixConsumerKeyAuth#

ApisixConsumerKeyAuth defines configuration for the key auth.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the key authentication credentials.
`value` ApisixConsumerKeyAuthValue	Value specifies the key authentication credentials.

Appears in:

ApisixConsumerAuthParameter

ApisixConsumerKeyAuthValue#

ApisixConsumerKeyAuthValue defines configuration for key authentication.

Field	Description
`key` string	Key is the credential used for key authentication.

Appears in:

ApisixConsumerKeyAuth

ApisixConsumerLDAPAuth#

ApisixConsumerLDAPAuth defines configuration for the LDAP authentication.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the LDAP credentials.
`value` ApisixConsumerLDAPAuthValue	Value specifies LDAP authentication credentials.

Appears in:

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

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	AuthParameter defines the authentication credentials and configuration for this consumer.

Appears in:

ApisixConsumer

ApisixConsumerWolfRBAC#

ApisixConsumerWolfRBAC defines configuration for the Wolf RBAC authentication.

Field	Description
`secretRef` LocalObjectReference	SecretRef references a Kubernetes Secret containing the Wolf RBAC token.
`value` ApisixConsumerWolfRBACValue	Value specifies the Wolf RBAC token.

Appears in:

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

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 array	Plugins contain a list of global plugins.

Appears in:

ApisixGlobalRule

ApisixMutualTlsClientConfig#

ApisixMutualTlsClientConfig describes the mutual TLS CA and verification settings.

Field	Description
`caSecret` 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

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 array	Plugins contain a list of plugins.

Appears in:

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	KeyAuth defines configuration for key authentication.
`jwtAuth` ApisixRouteAuthenticationJwtAuth	JwtAuth defines configuration for JWT authentication.
`ldapAuth` ApisixRouteAuthenticationLDAPAuth	LDAPAuth defines configuration for LDAP authentication.

Appears in:

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

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

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

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	Timeout specifies upstream timeout settings.
`match` ApisixRouteHTTPMatch	Match defines the HTTP request matching criteria.
`backends` 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 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 array	Plugins lists additional plugins applied to this route.
`authentication` ApisixRouteAuthentication	Authentication holds authentication-related configuration for this route.

Appears in:

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	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

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	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

ApisixRouteHTTPMatchExpr#

ApisixRouteHTTPMatchExpr represents a binary expression used to match requests based on Nginx variables.

Field	Description
`subject` ApisixRouteHTTPMatchExprSubject	Subject defines the left-hand side of the expression. It can be any 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

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

ApisixRouteHTTPMatchExprs#

Base type: [ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)

Field	Description
`subject` ApisixRouteHTTPMatchExprSubject	Subject defines the left-hand side of the expression. It can be any 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

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	Plugin configuration.
`secretRef` string	Plugin configuration secretRef.

Appears in:

ApisixGlobalRuleSpec
ApisixPluginConfigSpec
ApisixRouteHTTP
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 array	HTTP defines a list of HTTP route rules. Each rule specifies conditions to match HTTP requests and how to forward them.
`stream` 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

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	Match defines the criteria used to match incoming TCP or UDP connections.
`backend` ApisixRouteStreamBackend	Backend specifies the destination service to which traffic should be forwarded.
`plugins` ApisixRoutePlugin array	Plugins defines a list of plugins to apply to this route.

Appears in:

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	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

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

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

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
ApisixTlsSpec
ApisixUpstreamConfig
ApisixUpstreamSpec
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 array	Hosts lists the SNI (Server Name Indication) hostnames that this TLS configuration applies to. Must contain at least one host.
`secret` 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	Client defines mutual TLS (mTLS) settings, such as the CA certificate and verification depth.

Appears in:

ApisixTls

ApisixUpstreamConfig#

ApisixUpstreamConfig defines configuration for upstream services.

Field	Description
`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	Timeout specifies the connection, send, and read timeouts for upstream requests.
`healthCheck` HealthCheck	HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode.
`tlsSecret` ApisixSecret	TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream.
`subsets` 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`: • `pass`: preserve the original Host header • `node`: use the upstream node’s host • `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 configures service discovery for the upstream. Deprecated: no longer supported in standalone mode.

Appears in:

ApisixUpstreamSpec
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	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

ApisixUpstreamExternalType#

Base type: string

ApisixUpstreamExternalType is the external service type

Appears in:

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 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 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	Timeout specifies the connection, send, and read timeouts for upstream requests.
`healthCheck` HealthCheck	HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode.
`tlsSecret` ApisixSecret	TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream.
`subsets` 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`: • `pass`: preserve the original Host header • `node`: use the upstream node’s host • `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 configures service discovery for the upstream. Deprecated: no longer supported in standalone mode.
`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

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
ApisixUpstreamSpec
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
ApisixUpstreamSpec
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	Active health checks proactively send requests to upstream nodes to determine their availability.
`passive` PassiveHealthCheck	Passive health checks evaluate upstream health based on observed traffic, such as timeouts or errors.

Appears in:

ApisixUpstreamConfig
ApisixUpstreamSpec
PortLevelSettings

HostType#

Base type: string

Appears in:

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.

Appears in:

ApisixUpstreamConfig
ApisixUpstreamSpec
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	Healthy defines the conditions under which an upstream node is considered healthy.
`unhealthy` PassiveHealthCheckUnhealthy	Unhealthy defines the conditions under which an upstream node is considered unhealthy.

Appears in:

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
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
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 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	Timeout specifies the connection, send, and read timeouts for upstream requests.
`healthCheck` HealthCheck	HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode.
`tlsSecret` ApisixSecret	TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream.
`subsets` 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`: • `pass`: preserve the original Host header • `node`: use the upstream node’s host • `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 configures service discovery for the upstream. Deprecated: no longer supported in standalone mode.
`port` integer	Port is a Kubernetes Service port.

Appears in:

ApisixUpstreamSpec

UpstreamTimeout#

UpstreamTimeout defines timeout settings for connecting, sending, and reading from the upstream.

Field	Description
`connect` Duration	Connect timeout for establishing a connection to the upstream.
`send` Duration	Send timeout for sending data to the upstream.
`read` Duration	Read timeout for reading data from the upstream.

Appears in:

ApisixRouteHTTP
ApisixUpstreamConfig
ApisixUpstreamSpec
PortLevelSettings