Skip to main content
Version: 1.8.0

ApisixRoute/v2

See concepts to learn more about how to use the ApisixRoute resource.

Spec#

See the definition on GitHub.

The table below describes each of the attributes in the spec. The fields apiVersion, kind, and metadata are similar to other Kubernetes resources and are excluded below.

AttributeTypeDescription
httparrayHTTP Route rules.
http[].namestring (required)Route rule name.
http[].priorityintegerRoute priority. Used to determined which Route to use when multiple routes contain the same URI. Large number means higher priority.
http[].timeoutobjectTimeouts for connecting, sending, and receiving messages between Ingress and the service. This will overwrite the value configured in ApisixUpstream resource.
http[].timeout.connectstringConnect timeout in the form "72h3m0.5s".
http[].timeout.sendstringSend timeout in the form "72h3m0.5s".
http[].timeout.readstringRead timeout in the form "72h3m0.5s".
http[].matchobjectConditions to match a request with the Route.
http[].match.pathsarrayList of URIs to match the Route with. The Route will be used if any one of the URIs is matched.
http[].match.hostsarrayList of hosts to match the Route with. The Route will be used if any one of the hosts is matched.
http[].match.methodsarrayList of HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE) to match the Route with. The Route will be used if any one of the methods is matched.
http[].match.remoteAddrsarrayList of IP addresses (CIDR format) to match the Route with. The Route will be used if any one of the IP address is matched.
http[].match.exprsarrayList of expressions to match the Route with. The Route will be used if any one of the expression is matched.
http[].match.exprs[].subjectobjectSubject for the expression.
http[].match.exprs[].subject.scopestringScope of the subject. Can be one of Header, Query, Cookie, or Path.
http[].match.exprs[].subject.namestringSubject name. Can be empty when the scope is Path.
http[].match.exprs[].opstringOperator for the expression. See Expression operators for more details.
http[].match.exprs[].valuestringValue to compare the subject with. Can use either this or http[].match.exprs[].set.
http[].match.exprs[].setarraySet to compare the subject with. Only used when the operator is In or NotIn. Can use either this or http[].match.exprs[].value.
http[].websocketbooleanWhen set to true enables websocket proxy.
http[].plugin_config_namestringExisting Plugin Config name to use in the Route.
http[].backendsobjectList of backend services. If there are more than one, a weight based traffic split policy would be applied.
http[].backends[].serviceNamestringName of the backend service. The service and the ApisixRoute resource should be created in the same namespace.
http[].backends[].servicePortinteger or stringPort number or the name defined in the service object of the backend.
http[].backends[].resolveGranularitystringSee Service resolution granularity for details.
http[].backends[].weightintWeight with which to split traffic to the backend. Defaults to 100 and is ignored when there is only one backend.
http[].backends[].subsetstringSubset for the target service. Should be pre-defined in the ApisixUpstream resource.
http[].pluginsarrayAPISIX Plugins to be executed if the Route is matched.
http[].plugins[].namestringName of the Plugin. See Plugin hub for a list of available Plugins.
http[].plugins[].enablebooleanWhen set to true, the Plugin is enabled on the Route.
http[].plugins[].configobjectConfiguration of the Plugin. Should have the same fields as in APISIX docs.
http[].authenticationobjectList of APISIX authentication Plugins.
http[].authentication.enablebooleanWhen set to true, the authentication Plugin is enabled on the Route.
http[].authentication.typestringType of authentication. Set to one of basicAuth or keyAuth.
http[].authentication.keyAuthobjectUnique key for a Consumer.
http[].authentication.keyAuth.headerstringHeader to get the key from.
streamarrayStream route rules. Contains TCP or UDP rules.
stream[].protocolstring (required)The protocol of rule. Support TCP or UDP
stream[].namestring (required)Name of the rule.
stream[].matchobject (required)Conditions to match the request with the Route.
stream[].match.ingressPortinteger (required)Listening port in the Ingress proxy server. This port should be defined in the APISIX configuration.
stream[].backendobjectBackend service (deprecated). Use http[].backends instead.
stream[].backend.serviceNamestringName of the backend service (depricated). The service and the ApisixRoute resource should be created in the same namespace.
stream[].backend.servicePortinteger or stringPort number or the name defined in the service object of the backend (deprecated).
stream[].backend.resolveGranularitystringSee Service resolution granularity for details (depricated).
stream[].backend.subsetstringSubset for the target service (depricated). Should be pre-defined in the ApisixUpstream resource.

Expression operators#

The following operators can be used in match expressions:

OperatorDescription
EqualResult of the subject should be equal to the value.
NotEqualResult of the subject should not be equal to the value.
GreaterThanResult of the subject should be a number and must be larger than the value.
LessThanResult of the subject should be a number and must be less than the value.
InResult of the subject should be a part of the set.
NotInResult of the subject should be a part of the set.
RegexMatchResult of the subject should match the PCRE regex pattern of the value.
RegexNotMatchResult of the subject should not match the PCRE regex pattern of the value.
RegexMatchCaseInsensitiveSimilar to RegexMatch but case insensitive.
RegexNotMatchCaseInsensitiveSimilar to RegexNotMatch but case insensitive.

Service resolution granularity#

By default, the service referenced will be watched to update its endpoint list in APISIX. To just use the ClusterIP of the service, you can set the resolveGranularity attribute to service (defaults to endpoint):

GranularityDescription
endpointUpstream nodes are pods' IP adresses.
serviceUpstream nodes are service cluster IP. Load balancing is implemented by kube-proxy.