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