title: ApisixRoute keywords:
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.
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
:::info IMPORTANT
Paths are matched exactly by default. To match a prefix, use *
. For example /id/*
will match all paths with the /id/
prefix.
:::
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
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
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
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.
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
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
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.
:::
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.
:::