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.

Attribute	Type	Description
http	array	HTTP Route rules.
http[].name	string (required)	Route rule name.
http[].priority	integer	Route priority. Used to determined which Route to use when multiple routes contain the same URI. Large number means higher priority.
http[].timeout	object	Timeouts for connecting, sending, and receiving messages between Ingress and the service. This will overwrite the value configured in ApisixUpstream resource.
http[].timeout.connect	string	Connect timeout in the form "72h3m0.5s".
http[].timeout.send	string	Send timeout in the form "72h3m0.5s".
http[].timeout.read	string	Read timeout in the form "72h3m0.5s".
http[].match	object	Conditions to match a request with the Route.
http[].match.paths	array	List of URIs to match the Route with. The Route will be used if any one of the URIs is matched.
http[].match.hosts	array	List of hosts to match the Route with. The Route will be used if any one of the hosts is matched.
http[].match.methods	array	List 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.remoteAddrs	array	List 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.exprs	array	List of expressions to match the Route with. The Route will be used if any one of the expression is matched.
http[].match.exprs[].subject	object	Subject for the expression.
http[].match.exprs[].subject.scope	string	Scope of the subject. Can be one of Header, Query, Cookie, or Path.
http[].match.exprs[].subject.name	string	Subject name. Can be empty when the scope is Path.
http[].match.exprs[].op	string	Operator for the expression. See Expression operators for more details.
http[].match.exprs[].value	string	Value to compare the subject with. Can use either this or http[].match.exprs[].set.
http[].match.exprs[].set	array	Set to compare the subject with. Only used when the operator is In or NotIn. Can use either this or http[].match.exprs[].value.
http[].websocket	boolean	When set to true enables websocket proxy.
http[].plugin_config_name	string	Existing Plugin Config name to use in the Route.
http[].plugin_config_namespace	string	Namespace in which to look for plugin_config_name Route.
http[].backends	object	List of backend services. If there are more than one, a weight based traffic split policy would be applied.
http[].backends[].serviceName	string	Name of the backend service. The service and the ApisixRoute resource should be created in the same namespace.
http[].backends[].servicePort	integer or string	Port number or the name defined in the service object of the backend.
http[].backends[].resolveGranularity	string	See Service resolution granularity for details.
http[].backends[].weight	int	Weight with which to split traffic to the backend. Defaults to 100 and is ignored when there is only one backend.
http[].backends[].subset	string	Subset for the target service. Should be pre-defined in the ApisixUpstream resource.
http[].plugins	array	APISIX Plugins to be executed if the Route is matched.
http[].plugins[].name	string	Name of the Plugin. See Plugin hub for a list of available Plugins.
http[].plugins[].enable	boolean	When set to true, the Plugin is enabled on the Route.
http[].plugins[].config	object	Configuration of the Plugin. Should have the same fields as in APISIX docs.
http[].authentication	object	List of APISIX authentication Plugins.
http[].authentication.enable	boolean	When set to true, the authentication Plugin is enabled on the Route.
http[].authentication.type	string	Type of authentication. Set to one of basicAuth or keyAuth.
http[].authentication.keyAuth	object	Unique key for a Consumer.
http[].authentication.keyAuth.header	string	Header to get the key from.
http[].upstreams	array	List of ApisixUpstream resources.
http[].upstreams[].name	string	Name of the ApisixUpstream resource.
http[].upstreams[].weight	integer	Weight with which to split traffic to the upstream.
stream	array	Stream route rules. Contains TCP or UDP rules.
stream[].protocol	string (required)	The protocol of rule. Support TCP or UDP
stream[].name	string (required)	Name of the rule.
stream[].match	object (required)	Conditions to match the request with the Route.
stream[].match.ingressPort	integer (required)	Listening port in the Ingress proxy server. This port should be defined in the APISIX configuration.
stream[].backend	object	Backend service (deprecated). Use http[].backends instead.
stream[].backend.serviceName	string	Name of the backend service (depricated). The service and the ApisixRoute resource should be created in the same namespace.
stream[].backend.servicePort	integer or string	Port number or the name defined in the service object of the backend (deprecated).
stream[].backend.resolveGranularity	string	See Service resolution granularity for details (depricated).
stream[].backend.subset	string	Subset for the target service (depricated). Should be pre-defined in the ApisixUpstream resource.

Expression operators

The following operators can be used in match expressions:

Operator	Description
Equal	Result of the subject should be equal to the value.
NotEqual	Result of the subject should not be equal to the value.
GreaterThan	Result of the subject should be a number and must be larger than the value.
LessThan	Result of the subject should be a number and must be less than the value.
In	Result of the subject should be a part of the set.
NotIn	Result of the subject should be a part of the set.
RegexMatch	Result of the subject should match the PCRE regex pattern of the value.
RegexNotMatch	Result of the subject should not match the PCRE regex pattern of the value.
RegexMatchCaseInsensitive	Similar to RegexMatch but case insensitive.
RegexNotMatchCaseInsensitive	Similar 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):

Granularity	Description
endpoint	Upstream nodes are pods' IP adresses.
service	Upstream nodes are service cluster IP. Load balancing is implemented by kube-proxy.