| title | Custom Resource Definitions API Reference |
|---|---|
| slug | /reference/apisix-ingress-controller/api-reference |
| description | Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the APISIX Ingress Controller. |
This document provides the API resource description for the APISIX Ingress Controller custom resource definitions (CRDs).
Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group.
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 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 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 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 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. |
This section describes the types used by the CRDs.
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:
AdminKeyValueFrom defines the source of the admin key.
| Field | Description |
|---|---|
secretKeyRef SecretKeySelector |
SecretKeyRef references a key in a Secret. |
Appears in:
Base type: string
AuthType defines the type of authentication.
Appears in:
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:
| 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:
| 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:
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 defines configuration for control plane provider.
| Field | Description |
|---|---|
mode string |
Mode specifies the mode of control plane provider. Can be apisix or apisix-standalone. |
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:
| 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:
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:
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 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:
| 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:
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:
Base type: string
Appears in:
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 built-in variables. |
Appears in:
| Field | Description |
|---|---|
name string |
Name is the name of the plugin. |
config JSON |
Config is plugin configuration details. |
Appears in:
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:
| Field | Description |
|---|---|
name string |
Name is the name of the provider. |
port integer |
Port is the port of the provider. |
Appears in:
Base type: string
ProviderType defines the type of provider.
Appears in:
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:
| Field | Description |
|---|---|
name string |
Name is the name of the secret. |
namespace string |
Namespace is the namespace of the secret. |
Appears in:
| Field | Description |
|---|---|
conditions Condition array |
Appears in:
| 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:
Package v2 contains API Schema definitions for the apisix.apache.org v2 API group.
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 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 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 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 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 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. |
This section describes the types used by the CRDs.
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:
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:
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 the number of timeouts to define an unhealthy target. |
interval Duration |
Interval defines the time interval for checking targets, in seconds. |
Appears in:
| 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:
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:
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:
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:
ApisixConsumerHMACAuthValue defines configuration for HMAC authentication.
| Field | Description |
|---|---|
key_id string |
KeyID is the identifier used to look up the HMAC secret. |
secret_key string |
SecretKey is the HMAC secret used to sign the request. |
access_key string |
AccessKey is the identifier used to look up the HMAC secret. Deprecated from consumer configuration |
algorithm string |
Algorithm specifies the hashing algorithm (e.g., "hmac-sha256"). Deprecated from consumer configuration |
clock_skew integer |
ClockSkew is the allowed time difference (in seconds) between client and server clocks. Deprecated from consumer configuration |
signed_headers string array |
SignedHeaders lists the headers that must be included in the signature. Deprecated from consumer configuration |
keep_headers boolean |
KeepHeaders determines whether the HMAC signature headers are preserved after verification. Deprecated from consumer configuration |
encode_uri_params boolean |
EncodeURIParams indicates whether URI parameters are encoded when calculating the signature. Deprecated from consumer configuration |
validate_request_body boolean |
ValidateRequestBody enables HMAC validation of the request body. Deprecated from consumer configuration |
max_req_body integer |
MaxReqBody sets the maximum size (in bytes) of the request body that can be validated. Deprecated from consumer configuration |
Appears in:
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:
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, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512, or EdDSA. Currently APISIX only supports HS256, HS512, RS256, and ES256. API7 Enterprise supports all algorithms. |
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:
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:
ApisixConsumerKeyAuthValue defines configuration for key authentication.
| Field | Description |
|---|---|
key string |
Key is the credential used for key authentication. |
Appears in:
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:
ApisixConsumerLDAPAuthValue defines configuration for LDAP authentication.
| Field | Description |
|---|---|
user_dn string |
UserDN is the distinguished name (DN) of the LDAP user. |
Appears in:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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. This field is supported in APISIX but not in API7 Enterprise. |
Appears in:
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 built-in 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:
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:
Base type: [ApisixRouteHTTPMatchExpr](#apisixroutehttpmatchexpr)
| Field | Description |
|---|---|
subject ApisixRouteHTTPMatchExprSubject |
Subject defines the left-hand side of the expression. It can be any built-in 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:
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:
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:
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:
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 endpoint and service. When set to endpoint, individual pod IPs will be used; otherwise, the Service's ClusterIP or ExternalIP is used. The default is endpoint. |
subset string |
Subset specifies a named subset of the target Service. The subset must be pre-defined in the corresponding ApisixUpstream resource. |
Appears in:
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:
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:
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:
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:
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. |
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. |
Appears in:
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:
Base type: string
ApisixUpstreamExternalType is the external service type
Appears in:
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. These can be external hosts outside the cluster or cluster-internal Services specified by their DNS name. 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. |
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. |
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:
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:
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:
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:
Base type: string
Appears in:
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 built-in variables. |
Appears in:
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:
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:
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 the number of timeouts to define an unhealthy target. |
Appears in:
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. |
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. |
port integer |
Port is a Kubernetes Service port. |
Appears in:
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: