From 41efd44933bb1ac54e2a68d93ba1cffb1ac34895 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Tue, 18 Oct 2022 11:17:56 +0530 Subject: [PATCH 1/5] docs: update ApisixRoute docs Signed-off-by: Navendu Pottekkat --- docs/en/latest/concepts/apisix_route.md | 116 +++++++++++------------- 1 file changed, 53 insertions(+), 63 deletions(-) diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md index a7ecd238fc..174cf4963e 100644 --- a/docs/en/latest/concepts/apisix_route.md +++ b/docs/en/latest/concepts/apisix_route.md @@ -1,5 +1,10 @@ --- title: ApisixRoute +keywords: + - APISIX ingress + - Apache APISIX + - ApisixRoute +description: Guide to using ApisixRoute custom Kubernetes resource. --- -`ApisixRoute` is a CRD resource which focus on how to route traffic to -expected backend, it exposes many features supported by Apache APISIX. -Compared to [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/), -functions are implemented in a more native way, with stronger semantics. +`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](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. -Path based route rules ----------------------- -URI path are always used to split traffic, for instance, requests with host `foo.com` and -`/foo` prefix should be routed to service `foo` while requests which path is `/bar` -should be routed to service `bar`, in the manner of `ApisixRoute`, the configuration -should be: +See [reference](/docs/ingress-controller/next/references/apisix_route_v2/) 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. ```yaml apiVersion: apisix.apache.org/v2 @@ -46,31 +47,30 @@ spec: hosts: - foo.com paths: - - "/foo*" + - "/foo/*" backends: - serviceName: foo servicePort: 80 - name: bar match: paths: - - "/bar" + - "/bar/*" backends: - serviceName: bar servicePort: 80 ``` -There are two path types can be used, `prefix` and `exact`, default is `exact`, -while if `prefix` is desired, just append a `*`, for instance, `/id/*` matches -all paths with the prefix of `/id/`. +:::info IMPORTANT + +Paths are matched exactly by default. To match a prefix, use `*`. For example `/id/*` will match all paths with the `/id/` prefix. + +::: -Advanced route features ------------------------ +## Advanced routing -Path based route are most common, but if it's not enough, try -other route features in `ApisixRoute` such as `methods`, `exprs`. +`ApisixRoute` resource can also be used to configure advanced routing through `methods` and `exprs`. -The `methods` splits traffic according to the HTTP method, the following configurations routes requests -with `GET` method to `foo` service (a Kubernetes Service). +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. ```yaml apiVersion: apisix.apache.org/v2 @@ -90,8 +90,11 @@ spec: servicePort: 80 ``` -The `exprs` allows user to configure match conditions with arbitrary predicates in HTTP, such as queries, HTTP headers, Cookie. -It's composed by several expressions, which in turn composed by subject, operator and value/set. +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: ```yaml apiVersion: apisix.apache.org/v2 @@ -115,17 +118,9 @@ spec: servicePort: 80 ``` -The above configuration configures an extra route match condition, which asks the -query `id` must be equal to `2143`. - -Service Resolution Granularity ------------------------------- +## Service resolution granularity -By default a referenced Service will be watched, so -it's newest endpoints list can be updated to Apache APISIX. -apisix-ingress-controller provides another mechanism that just use -the `ClusterIP` of this service, if that's what you want, just set -the `resolveGranularity` to `service` (default is `endpoint`). +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`): ```yaml apiVersion: apisix.apache.org/v2 @@ -146,13 +141,11 @@ spec: resolveGranularity: service ``` -Weight Based Traffic Split --------------------------- +## Weight-based traffic split -There can more than one backend specified in one route rule, -when multiple backends co-exist there, the traffic split based on weights -will be applied (which actually uses the [traffic-split](http://apisix.apache.org/docs/apisix/plugins/traffic-split/) plugin in Apache APISIX). -You can specify weight for each backend, the default weight is `100`. +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](http://apisix.apache.org/docs/apisix/plugins/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: ```yaml apiVersion: apisix.apache.org/v2 @@ -182,15 +175,11 @@ spec: weight: 50 ``` -The above `ApisixRoute` has one route rule, which contains two backends `foo` and `bar`, the weight ratio is `100:50`, -which means `2/3` requests (with `GET` method and `User-Agent` matching regex pattern `.*Chrome.*`) will be sent to service `foo` and `1/3` requests -will be proxied to service `bar`. +## Plugins -Plugins -------- +APISIX's [70+ Plugins](/docs/apisix/plugins/batch-requests/) can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation. -Apache APISIX provides more than 70 [plugins](https://github.com/apache/apisix/tree/master/docs/en/latest/plugins), which can be used -in `ApisixRoute`. All configuration items are named same to the one in APISIX. +The example below configures [cors](/docs/apisix/plugins/cors/) Plugin for the route: ```yaml apiVersion: apisix.apache.org/v2 @@ -213,14 +202,9 @@ spec: enable: true ``` -The above configuration enables [Cors](https://github.com/apache/apisix/blob/master/docs/en/latest/plugins/cors.md) plugin for requests -which host is `local.httpbin.org`. - -Websocket Proxy ---------------- +## Websocket proxy -[Websocket](https://en.wikipedia.org/wiki/WebSocket#:~:text=WebSocket%20is%20a%20computer%20communications,WebSocket%20is%20distinct%20from%20HTTP.) service can be proxied -by creating a route with specifying the `websocket` field. +You can route requests to [WebSocket](https://en.wikipedia.org/wiki/WebSocket#:~:text=WebSocket%20is%20a%20computer%20communications,WebSocket%20is%20distinct%20from%20HTTP.) services by setting the `websocket` attribute to `true` as shown below: ```yaml apiVersion: apisix.apache.org/v2 @@ -241,10 +225,11 @@ spec: websocket: true ``` -TCP Route ---------- +## TCP route + +You can configure APISIX Ingress to route traffic to TCP servers. -apisix-ingress-controller supports the port-based tcp route. +The example below configures APISIX Ingress to route traffic from port `9100` to the service `tcp-server`: ```yaml apiVersion: apisix.apache.org/v2 @@ -262,14 +247,17 @@ spec: servicePort: 8080 ``` -The above yaml configuration guides TCP traffic entered to the Ingress proxy server (i.e. [APISIX](https://apisix.apache.org)) port `9100` should be routed to the backend service `tcp-server`. +:::note -Note since APISIX doesn't support dynamic listening, so here the `9100` port should be pre-defined in APISIX [configuration](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L101). +The `ingressPort` (`9100` here) should be pre-defined in the [APISIX configuration](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L101). -UDP Route ---------- +::: -apisix-ingress-controller supports the port-based udp route. +## 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`: ```yaml apiVersion: apisix.apache.org/v2 @@ -287,6 +275,8 @@ spec: servicePort: 53 ``` -The above yaml configuration guides UDP traffic entered to the Ingress proxy server (i.e. [APISIX](https://apisix.apache.org)) port `9200` should be routed to the backend service `udp-server`. +:::note + +The `ingressPort` (`9200` here) should be pre-defined in the [APISIX configuration](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L105). -Note since APISIX doesn't support dynamic listening, so here the `9200` port should be pre-defined in APISIX [configuration](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L105). +::: From fb3c48000f7626e596a1b523930cd1534c758569 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Tue, 18 Oct 2022 11:29:03 +0530 Subject: [PATCH 2/5] fix lint errors Signed-off-by: Navendu Pottekkat --- docs/en/latest/concepts/apisix_route.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md index 174cf4963e..c52f679297 100644 --- a/docs/en/latest/concepts/apisix_route.md +++ b/docs/en/latest/concepts/apisix_route.md @@ -28,7 +28,6 @@ description: Guide to using ApisixRoute custom Kubernetes resource. `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](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. - See [reference](/docs/ingress-controller/next/references/apisix_route_v2/) for the full API documentation. ## Path-based routing @@ -204,7 +203,7 @@ spec: ## Websocket proxy -You can route requests to [WebSocket](https://en.wikipedia.org/wiki/WebSocket#:~:text=WebSocket%20is%20a%20computer%20communications,WebSocket%20is%20distinct%20from%20HTTP.) services by setting the `websocket` attribute to `true` as shown below: +You can route requests to [WebSocket](https://en.wikipedia.org/wiki/WebSocket#:~:text=WebSocket%20is%20a%20computer%20communications,WebSocket%20is%20distinct%20from%20HTTP.) services by setting the `websocket` attribute to `true` as shown below: ```yaml apiVersion: apisix.apache.org/v2 From 11246f93fa1c130cb33f454b72d39155946635c2 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Tue, 18 Oct 2022 11:31:27 +0530 Subject: [PATCH 3/5] fix broken links Signed-off-by: Navendu Pottekkat --- docs/en/latest/concepts/apisix_route.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md index c52f679297..248a1d260b 100644 --- a/docs/en/latest/concepts/apisix_route.md +++ b/docs/en/latest/concepts/apisix_route.md @@ -28,7 +28,7 @@ description: Guide to using ApisixRoute custom Kubernetes resource. `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](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. -See [reference](/docs/ingress-controller/next/references/apisix_route_v2/) for the full API documentation. +See [reference](https://apisix.apache.org/docs/ingress-controller/references/apisix_route_v2/) for the full API documentation. ## Path-based routing @@ -176,9 +176,9 @@ spec: ## Plugins -APISIX's [70+ Plugins](/docs/apisix/plugins/batch-requests/) can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation. +APISIX's [70+ Plugins](https://apisix.apache.org/docs/apisix/plugins/batch-requests/) can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation. -The example below configures [cors](/docs/apisix/plugins/cors/) Plugin for the route: +The example below configures [cors](https://apisix.apache.org/docs/apisix/plugins/cors/) Plugin for the route: ```yaml apiVersion: apisix.apache.org/v2 From ad77512ee68103a63c7a9410e274275052cd0023 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Tue, 18 Oct 2022 13:48:53 +0530 Subject: [PATCH 4/5] apply suggestions from the review Signed-off-by: Navendu Pottekkat --- docs/en/latest/concepts/apisix_route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md index 248a1d260b..582d7e762e 100644 --- a/docs/en/latest/concepts/apisix_route.md +++ b/docs/en/latest/concepts/apisix_route.md @@ -176,7 +176,7 @@ spec: ## Plugins -APISIX's [70+ Plugins](https://apisix.apache.org/docs/apisix/plugins/batch-requests/) can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation. +APISIX's [80+ Plugins](https://apisix.apache.org/docs/apisix/plugins/batch-requests/) can be used with APISIX Ingress. These Plugins have the same name as in the APISIX documentation. The example below configures [cors](https://apisix.apache.org/docs/apisix/plugins/cors/) Plugin for the route: From 57c265046e7463f86c791ff8e0d4e4ec86d0171a Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Wed, 19 Oct 2022 11:46:43 +0530 Subject: [PATCH 5/5] remove trailing / to fix lint error? Signed-off-by: Navendu Pottekkat --- docs/en/latest/concepts/apisix_route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/concepts/apisix_route.md b/docs/en/latest/concepts/apisix_route.md index 582d7e762e..c04860b222 100644 --- a/docs/en/latest/concepts/apisix_route.md +++ b/docs/en/latest/concepts/apisix_route.md @@ -28,7 +28,7 @@ description: Guide to using ApisixRoute custom Kubernetes resource. `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](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. -See [reference](https://apisix.apache.org/docs/ingress-controller/references/apisix_route_v2/) for the full API documentation. +See [reference](https://apisix.apache.org/docs/ingress-controller/references/apisix_route_v2) for the full API documentation. ## Path-based routing