You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apisix.apache.org by GitBox <gi...@apache.org> on 2020/12/05 14:02:36 UTC
[GitHub] [apisix-ingress-controller] membphis commented on a change in pull request #48: docs: add usage and design docs
membphis commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536774081
##########
File path: docs/design.md
##########
@@ -36,6 +36,89 @@ Apache APISIX ingress for Kubernetes.
- match and covert Apisix-ingress-types to Apisix-types before handing the control over to the above module seven;
-## Sequence Diagram
+## CRD design
-
+Currently `apisix-ingress-controller` CRDs consist of 3 parts: ApisixRoute/ApisixService/ApisixUpstream. The design follows the following ideas.
+
+1. The most important part of the gateway is the routing part, which is used to define the distribution rules of the gateway traffics.
+2. In order to facilitate understanding and configuration, the design structure of `ApisixRoute` is basically similar to Kubernetes Ingress.
+3. In the design of annotation, the structure of Kubernetes Ingress is used for reference, but the internal implementation is based on the plug-in of Apache APISIX.
+4. Both `ApisixRoute` and `ApisixService` can be bound to plug-ins, which is consistent with Apache APISIX.
+5. In the simplest case, you only need to define `ApisixRoute`, and the Ingress controller will automatically add `ApisixService` and `ApisixUpstream`.
+6. `ApisixService`, like Apache APISIX service, is a grouping of routes, which can simplify the configuration complexity of the same plug-in.
+7. `ApisixUpstream` can define some details on Apache APISIX upstream, such as load balancing/health check, etc.
+
+## Monitoring CRDs
+
+`apisix-ingress-controller` is responsible for interacting with the Kubernetes Apiserver, applying for accessible resource permissions (RBAC), monitoring changes, and implementing object conversion within the Ingress controller, comparing the changes, and then synchronizing to Apache APISIX.
+
+### Timing diagram
+
+
+
+### Conversion structure
+
+`apisix-ingress-controller` provides external configuration methods for CRDs. It is aimed at operators such as daily operation and maintenance, who often need to process a large number of routes in batches, hoping to handle all related services in the same configuration file, and at the same time have convenient and understandable management capabilities. Apache APISIX is designed from the perspective of the gateway, and all routes are independent. This leads to obvious differences in the data structure between the two. One focuses on batch definition, while the other is discrete implementation.
+
+Taking into account the usage habits of different groups of people, the data structure of CRDs draws on the data structure of Kubernetes Ingress, and is basically the same in shape.
+
+A simple comparison is as follows, they have different definitions:
+
+
Review comment:
Remove the background color to make it easier to read.
##########
File path: docs/design.md
##########
@@ -36,6 +36,89 @@ Apache APISIX ingress for Kubernetes.
- match and covert Apisix-ingress-types to Apisix-types before handing the control over to the above module seven;
-## Sequence Diagram
+## CRD design
-
+Currently `apisix-ingress-controller` CRDs consist of 3 parts: ApisixRoute/ApisixService/ApisixUpstream. The design follows the following ideas.
+
+1. The most important part of the gateway is the routing part, which is used to define the distribution rules of the gateway traffics.
+2. In order to facilitate understanding and configuration, the design structure of `ApisixRoute` is basically similar to Kubernetes Ingress.
+3. In the design of annotation, the structure of Kubernetes Ingress is used for reference, but the internal implementation is based on the plug-in of Apache APISIX.
+4. Both `ApisixRoute` and `ApisixService` can be bound to plug-ins, which is consistent with Apache APISIX.
+5. In the simplest case, you only need to define `ApisixRoute`, and the Ingress controller will automatically add `ApisixService` and `ApisixUpstream`.
+6. `ApisixService`, like Apache APISIX service, is a grouping of routes, which can simplify the configuration complexity of the same plug-in.
+7. `ApisixUpstream` can define some details on Apache APISIX upstream, such as load balancing/health check, etc.
+
+## Monitoring CRDs
+
+`apisix-ingress-controller` is responsible for interacting with the Kubernetes Apiserver, applying for accessible resource permissions (RBAC), monitoring changes, and implementing object conversion within the Ingress controller, comparing the changes, and then synchronizing to Apache APISIX.
+
+### Timing diagram
+
+
Review comment:
different style, we can update it later
##########
File path: docs/usage.md
##########
@@ -0,0 +1,175 @@
+# Usage of Ingress controller
+
+In this article, we will use ingress controller CRDs (CustomResourceDefinition) to define routing rules against the admin api of Apache APISIX.
+
+## Scenes
+
+Configure a simple routing rule through the ingress controller CRDs. After synchronizing to the gateway, the data traffic is accessed to the back-end service through Apache APISIX. Then, we gradually add or remove plug-ins to the routing to achieve functional expansion.
+
+As shown below.
+
+
+
+## A simple example
+
+Define the simplest route to direct traffic to the back-end service, the back-end service is named `httpserver`.
+
+When using admin api, we define as below.
+
+```shell
+# 1. Define upstream: foo-upstream id=1
+curl -XPUT http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -d '
+{
+ "nodes": {
+ "10.244.143.48:8080": 100,
+ "10.244.102.43:8080": 100,
+ "10.244.102.63:8080": 100
+ },
+ "desc": "foo-upstream",
+ "type": "roundrobin"
+}
+'
+# 2. Define service: foo-service, id=2, binding upstream: foo-upstream
+curl -XPUT http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -d '
+{
+ "desc": "foo-service",
+ "upstream_id": 1
+}
+'
+
+# 3. Define route: foo-route， id=3， binding service: foo-service
+
+curl -XPUT http://127.0.0.1:9080/apisix/admin/routes/3 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -d '
+{
+ "desc": "foo-route",
+ "uri": "/hello*",
+ "host": "test.apisix.apache.org",
+ "service_id": "2"
+}'
+```
+
+Now we change to the definition of CRDs as follows.
+
+1. Define Upstream with `ApisixUpstream`
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: foo
+ namespace: cloud
+spec:
+ ports:
+ - port: 8080
+ loadbalancer:
+ type: chash
+ hashOn: header
+ key: hello
+```
+
+2. Define Service with `ApisixService`
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixService
+metadata:
+ name: foo
+ namespace: cloud
+spec:
+ upstream: foo
+ port: 8080
+```
+
+3. Define Route with `ApisixRoute`
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixRoute
+metadata:
+ name: foo-route
+ namespace: cloud
+spec:
+ rules:
+ - host: test.apisix.apache.org
+ http:
+ paths:
+ - backend:
+ serviceName: foo
+ servicePort: 8080
+ path: /hello*
+```
+
+Tips: When defining ApisixUpstream, there is no need to define a specific pod ip list, the ingress controller will do service discovery based on namespace/name/port composite index.
+
+As shown below.
+
+
+
+## Add a plugin
+
+Next, take the `proxy-rewrite` plugin as an example.
+
+Add plug-ins through admin api to achieve the purpose of rewriting upstream uri.
+
+e.g. test.apisix.apache.org/hello -> test-rewrite.apisix.apache.org/copy/hello
+
+With admin api
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "desc": "foo-service",
+ "upstream_id": "1",
+ "plugins": {
+ "proxy-rewrite": {
+ "regex_uri": ["^/(.*)", "/copy/$1"],
+ "scheme": "http",
+ "host": "test-rewrite.apisix.apache.org"
+ }
+ }
+}'
+```
+
+With CRDs, use `ApisixService` as example.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixService
+metadata:
+ name: foo
+ namespace: cloud
+spec:
+ upstream: foo
+ port: 8080
+ plugins:
+ - enable: true
+ name: proxy-rewrite
+ config:
+ regex_uri:
+ - '^/(.*)'
+ - '/copy/$1'
+ scheme: http
+ host: test-rewrite.apisix.apache.org
+```
+
+It can be found that the way of defining plugins is almost the same, except that the format is changed from `json` to `yaml`.
+
+By defining the plug-in in CRDs, you can disable the plug-in by setting `enable: false` without deleting it. Keep the original configuration for easy opening next time.
+
+Tips: ApisixRoute and ApisixService both support plugins definition.
+
+## FAQ
Review comment:
We'd better put `FAQ` to a single file, what do you think? @gxthrj
##########
File path: docs/usage.md
##########
@@ -0,0 +1,175 @@
+# Usage of Ingress controller
+
+In this article, we will use ingress controller CRDs (CustomResourceDefinition) to define routing rules against the admin api of Apache APISIX.
+
+## Scenes
+
+Configure a simple routing rule through the ingress controller CRDs. After synchronizing to the gateway, the data traffic is accessed to the back-end service through Apache APISIX. Then, we gradually add or remove plug-ins to the routing to achieve functional expansion.
+
+As shown below.
+
+
+
+## A simple example
+
+Define the simplest route to direct traffic to the back-end service, the back-end service is named `httpserver`.
Review comment:
We want the reader to learn CRD, they do not need to know how it works.
The examples of `Admin API` are not important, I think we can remove them.
##########
File path: docs/usage.md
##########
@@ -0,0 +1,175 @@
+# Usage of Ingress controller
+
+In this article, we will use ingress controller CRDs (CustomResourceDefinition) to define routing rules against the admin api of Apache APISIX.
+
+## Scenes
+
+Configure a simple routing rule through the ingress controller CRDs. After synchronizing to the gateway, the data traffic is accessed to the back-end service through Apache APISIX. Then, we gradually add or remove plug-ins to the routing to achieve functional expansion.
+
+As shown below.
+
+
+
+## A simple example
+
+Define the simplest route to direct traffic to the back-end service, the back-end service is named `httpserver`.
Review comment:
I think we should show the example of `CRDs` first
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org