Skip to main content
Version: Next

ApisixRoute

ApisixRoute is a Kubernetes CRD object that provides a spec to route traffic to services with APISIX. It is much more capable and easy to use compared to the default Kubernetes Ingress resource.

See reference for the full API documentation.

Path-based routing#

The example below shows how you can configure Ingress to route traffic to two backend services. Requests with host foo.com and /foo prefix are routed to the foo service and requests with the /bar prefix are routed to the bar service.

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: foo-bar-route
spec:
http:
- name: foo
match:
hosts:
- foo.com
paths:
- "/foo/*"
backends:
- serviceName: foo
servicePort: 80
- name: bar
match:
paths:
- "/bar/*"
backends:
- serviceName: bar
servicePort: 80
IMPORTANT

Paths are matched exactly by default. To match a prefix, use *. For example /id/* will match all paths with the /id/ prefix.

Advanced routing#

ApisixRoute resource can also be used to configure advanced routing through methods and exprs.

The methods attribute can be used to route traffic based on the HTTP method as shown in the example below. This will route all requests with the GET method to the foo service.

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: method-route
spec:
http:
- name: method
match:
paths:
- /
methods:
- GET
backends:
- serviceName: foo
servicePort: 80

The exprs attribute is used to configure conditions to match HTTP queries, headers, and cookies.

It can be composed of several expressions and each of them in-turn is composed of a subject, operator, and a value/set.

The configuration below will route all requests with a query parameter id with the value 2143 to the foo service:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: method-route
spec:
http:
- name: method
match:
paths:
- /
exprs:
- subject:
scope: Query
name: id
op: Equal
value: "2143"
backends:
- serviceName: foo
servicePort: 80

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

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: method-route
spec:
http:
- name: method
match:
paths:
- /*
methods:
- GET
backends:
- serviceName: foo
servicePort: 80
resolveGranularity: service

Weight-based traffic split#

You can configure more than one backend services in a route rule and set weights to route traffic between them. This uses the traffic-split Plugin internally. The default weight is 100.

The example below shows routing traffic between two services with a weight ratio 100:50. This means that 2/3 of the requests (with GET method and User-Agent header matching the regex pattern .*Chrome.*) will be routed to the foo service and 1/3 of the requests will be routed to the bar service:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: method-route
spec:
http:
- name: method
match:
paths:
- /*
methods:
- GET
exprs:
- subject:
scope: Header
name: User-Agent
op: RegexMatch
value: ".*Chrome.*"
backends:
- serviceName: foo
servicePort: 80
weight: 100
- serviceName: bar
servicePort: 81
weight: 50

Plugins#

APISIX's 80+ Plugins can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation.

note

If the Plugin is not enabled in APISIX by default, you can enable it by adding it to the plugins attribute in your values.yaml file while installing APISIX and Ingress controller via Helm. Alternatively, you can directly modify your APISIX configuration file (conf/config.yaml) to enable/disable Plugins.

The example below configures limit-count Plugin for the route:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: httpbin-route
spec:
http:
- name: rule1
match:
hosts:
- httpbin.org
paths:
- /ip
backends:
- serviceName: %s
servicePort: %d
weight: 10
plugins:
- name: limit-count
enable: true
config:
rejected_code: 503
count: 2
time_window: 3
key: remote_addr

You can also use the ApisixPluginConfig CRD to extract and reuse commonly used Plugins and bind them directly to a Route.

Config with secretRef#

Plugins are supported to be configured from kubernetes secret with secretRef.

The priority is plugins.secretRef > plugins.config. That is, the duplicated key in plugins.config are replaced by plugins.secretRef.

Example below configures echo plugin. The final values of before_body, body and after_body are "This is the replaced preface", "my custom body" and "This is the epilogue", respectively.

apiVersion: v1
kind: Secret
metadata:
name: echo
data:
# content is "This is the replaced preface"
before_body: IlRoaXMgaXMgdGhlIHJlcGxhY2VkIHByZWZhY2Ui
# content is "my custom body"
body: Im15IGN1c3RvbSBib2R5Ig==
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: httpbin-route
spec:
http:
- name: rule1
match:
hosts:
- httpbin.org
paths:
- /ip
backends:
- serviceName: %s
servicePort: %d
weight: 10
plugins:
- name: echo
enable: true
config:
before_body: "This is the preface"
after_body: "This is the epilogue"
headers:
X-Foo: v1
X-Foo2: v2
secretRef: echo

Config with secretRef where the secret data contains path to a specific key that needs to be overridden in plugin config#

You can also configure specific fields in the plugin configuration that are deeply nested by passing the path to that field. The path is dot-separated keys that lead to that field. The below example overrides the X-Foo header field in the plugin configuration from v1 to v2.

apiVersion: v1
kind: Secret
metadata:
#content is "v2"
name: echo
data:
headers.X-Foo: djI=
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: httpbin-route
spec:
http:
- name: rule1
match:
hosts:
- httpbin.org
paths:
- /ip
backends:
- serviceName: %s
servicePort: %d
weight: 10
plugins:
- name: echo
enable: true
config:
before_body: "This is the preface"
after_body: "This is the epilogue"
headers:
X-Foo: v1
secretRef: echo

Websocket proxy#

You can route requests to WebSocket services by setting the websocket attribute to true as shown below:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: ws-route
spec:
http:
- name: websocket
match:
hosts:
- ws.foo.org
paths:
- /*
backends:
- serviceName: websocket-server
servicePort: 8080
websocket: true

TCP route#

You can configure APISIX Ingress to route traffic to TCP servers.

The example below configures APISIX Ingress to route traffic from port 9100 to the service tcp-server:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: tcp-route
spec:
stream:
- name: tcp-route-rule1
protocol: TCP
match:
ingressPort: 9100
backend:
serviceName: tcp-server
servicePort: 8080
note

The ingressPort (9100 here) should be pre-defined in the APISIX configuration.

UDP route#

You can configure APISIX Ingress to route traffic to UDP servers.

The example below configures APISIX Ingress to route traffic from port 9200 to the service udp-server:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: udp-route
spec:
stream:
- name: udp-route-rule1
protocol: UDP
match:
ingressPort: 9200
backend:
serviceName: udp-server
servicePort: 53
note

The ingressPort (9200 here) should be pre-defined in the APISIX configuration.