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 07:16:55 UTC
[GitHub] [apisix-ingress-controller] gxthrj opened a new pull request #48: docs: add usage and design docs
gxthrj opened a new pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-740419091
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739303041
> any related issue?
There is no issue related.
The doc should be impove as always.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis edited a comment on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
membphis edited a comment on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739495903
> > any related issue?
>
> There is no issue related.
> The doc should be impove as always.
I do not think so.
eg: We can close issue https://github.com/apache/apisix-ingress-controller/issues/46 after we merged this PR.
https://github.com/apache/apisix-ingress-controller/pull/48/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R153
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739253704
`docs/.DS_Store` please delete similar file
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538055578
##########
File path: docs/design.md
##########
@@ -36,6 +36,88 @@ 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 route 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:
+
+
+
+They are a many-to-many relationship.Therefore, `apisix-ingress-controller` has to do some conversion of CRDs to adapt to different gateways.
+
+### Cascade update
+
+At present, we have defined multiple CRDs, and these CRDs are responsible for the definition of their respective fields. `ApisixRoute`/ `ApisixService` / `ApisixUpstream` correspond to objects such as `route`/ `service` / `upstream` in Apache APISIX. As the strong binding relationship between APISIX objects, when modifying and deleting batch data structures such as CRDs, you have to consider the impact of cascading between objects.
+
+So, in `apisix-ingress-controller`, a broadcast notification mechanism is designed through `channel`, that is, the definition of any object must be notified to other objects related to it and trigger the corresponding behavior.
+
+
+
+In a typical scenario, there is a many-to-many relationship between `ApisixRoute` and `ApisixService`, and a one-to-one relationship between `ApisixService` and `ApisixUpstream`.
+
+* When the `ApisixService` changes, it needs to be notified upwards to the `ApisixRoute`, and also needs to be notified downwards to the corresponding `ApisixUpstream`.
+* When one of the `http-route` in `ApisixRoute` changes, the relevant `ApisixService` and `ApisixUpstream` need to be notified.
+
+This is particularly prominent in `modify` and `delete`.
+
+**We can initiate discussions in this area and propose a more reasonable design plan**
+
+### Diff rules
+
+The `seven` module internally saves memory data structures, which is currently very similar to the Apache Apisix resource object. When the Kubernetes resource object is newly changed, `seven` will compare the memory objects and update incrementally according to the result of the comparison.
+
+The current comparison rule is based on the grouping of `route` / `service` / `upstream` resource objects, compare them separately, and make corresponding broadcast notifications after finding the differences.
+
+
+
+### Service Discovery
+
+According to the `namespace` `name` `port` defined in the `ApisixUpstream` resource object, `apisix-ingress-controller` will register the `endpoints` node information in the `running` state to the nodes in Apache APISIX Upstream. And according to Kubernetes Endpoint status is synchronized in real time.
+
+Based on service discovery, Apache APISIX Ingress can directly access back-end Pod nodes. Bypassing Kubernetes Service, it is possible to implement customized load balancing strategies.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536807705
##########
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 agree to changed the order of example, making CRDs first.
But I think `Admin API` is useful here to facilitate understanding.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536808507
##########
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:
I agree, make FAQ in a separate file, with a link in README.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538055367
##########
File path: docs/FAQ.md
##########
@@ -0,0 +1,15 @@
+# FAQ
+
+1. How to bind between Service and Upstream?
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536807787
##########
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:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739495903
> > any related issue?
>
> There is no issue related.
> The doc should be impove as always.
I do not think so.
eg: We can close issue https://github.com/apache/apisix-ingress-controller/issues/46 after we merged this PR.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] tokers commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
tokers commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r537985950
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
Review comment:
What about:
Dynamically update the configuration without reloading.
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
Review comment:
typo: upport -> support.
##########
File path: docs/design.md
##########
@@ -36,6 +36,88 @@ 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 route 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:
+
+
+
+They are a many-to-many relationship.Therefore, `apisix-ingress-controller` has to do some conversion of CRDs to adapt to different gateways.
+
+### Cascade update
+
+At present, we have defined multiple CRDs, and these CRDs are responsible for the definition of their respective fields. `ApisixRoute`/ `ApisixService` / `ApisixUpstream` correspond to objects such as `route`/ `service` / `upstream` in Apache APISIX. As the strong binding relationship between APISIX objects, when modifying and deleting batch data structures such as CRDs, you have to consider the impact of cascading between objects.
+
+So, in `apisix-ingress-controller`, a broadcast notification mechanism is designed through `channel`, that is, the definition of any object must be notified to other objects related to it and trigger the corresponding behavior.
+
+
+
+In a typical scenario, there is a many-to-many relationship between `ApisixRoute` and `ApisixService`, and a one-to-one relationship between `ApisixService` and `ApisixUpstream`.
+
+* When the `ApisixService` changes, it needs to be notified upwards to the `ApisixRoute`, and also needs to be notified downwards to the corresponding `ApisixUpstream`.
+* When one of the `http-route` in `ApisixRoute` changes, the relevant `ApisixService` and `ApisixUpstream` need to be notified.
+
+This is particularly prominent in `modify` and `delete`.
+
+**We can initiate discussions in this area and propose a more reasonable design plan**
+
+### Diff rules
+
+The `seven` module internally saves memory data structures, which is currently very similar to the Apache Apisix resource object. When the Kubernetes resource object is newly changed, `seven` will compare the memory objects and update incrementally according to the result of the comparison.
+
+The current comparison rule is based on the grouping of `route` / `service` / `upstream` resource objects, compare them separately, and make corresponding broadcast notifications after finding the differences.
+
+
+
+### Service Discovery
+
+According to the `namespace` `name` `port` defined in the `ApisixUpstream` resource object, `apisix-ingress-controller` will register the `endpoints` node information in the `running` state to the nodes in Apache APISIX Upstream. And according to Kubernetes Endpoint status is synchronized in real time.
+
+Based on service discovery, Apache APISIX Ingress can directly access back-end Pod nodes. Bypassing Kubernetes Service, it is possible to implement customized load balancing strategies.
+
+### Annotation implementation
+
+Unlike the implementation of Kubernetes Nginx Ingress, the implementation of Annotation by `apisix-ingress-controller` is based on the plug-in mechanism of Apache APISIX.
+
+For example, the settings of the black and white list can be configured through the `k8s.apisix.apache.org/whitelist-source-range` annotation in the `ApisixRoute` resource object.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixRoute
+metadata:
+ annotations:
+ k8s.apisix.apache.org/whitelist-source-range: 1.2.3.4,2.2.0.0/16
+ name: httpserver-route
+spec:
+ ...
+```
+
+The black and white list here is implemented by the `ip-restriction` plugin.
Review comment:
We should give the hyperlink for `ip-restriction`.
##########
File path: docs/design.md
##########
@@ -36,6 +36,88 @@ 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 route 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:
+
+
+
+They are a many-to-many relationship.Therefore, `apisix-ingress-controller` has to do some conversion of CRDs to adapt to different gateways.
+
+### Cascade update
+
+At present, we have defined multiple CRDs, and these CRDs are responsible for the definition of their respective fields. `ApisixRoute`/ `ApisixService` / `ApisixUpstream` correspond to objects such as `route`/ `service` / `upstream` in Apache APISIX. As the strong binding relationship between APISIX objects, when modifying and deleting batch data structures such as CRDs, you have to consider the impact of cascading between objects.
+
+So, in `apisix-ingress-controller`, a broadcast notification mechanism is designed through `channel`, that is, the definition of any object must be notified to other objects related to it and trigger the corresponding behavior.
+
+
+
+In a typical scenario, there is a many-to-many relationship between `ApisixRoute` and `ApisixService`, and a one-to-one relationship between `ApisixService` and `ApisixUpstream`.
+
+* When the `ApisixService` changes, it needs to be notified upwards to the `ApisixRoute`, and also needs to be notified downwards to the corresponding `ApisixUpstream`.
+* When one of the `http-route` in `ApisixRoute` changes, the relevant `ApisixService` and `ApisixUpstream` need to be notified.
+
+This is particularly prominent in `modify` and `delete`.
+
+**We can initiate discussions in this area and propose a more reasonable design plan**
+
+### Diff rules
+
+The `seven` module internally saves memory data structures, which is currently very similar to the Apache Apisix resource object. When the Kubernetes resource object is newly changed, `seven` will compare the memory objects and update incrementally according to the result of the comparison.
+
+The current comparison rule is based on the grouping of `route` / `service` / `upstream` resource objects, compare them separately, and make corresponding broadcast notifications after finding the differences.
+
+
+
+### Service Discovery
+
+According to the `namespace` `name` `port` defined in the `ApisixUpstream` resource object, `apisix-ingress-controller` will register the `endpoints` node information in the `running` state to the nodes in Apache APISIX Upstream. And according to Kubernetes Endpoint status is synchronized in real time.
+
+Based on service discovery, Apache APISIX Ingress can directly access back-end Pod nodes. Bypassing Kubernetes Service, it is possible to implement customized load balancing strategies.
Review comment:
`back-end` => `backend`.
##########
File path: README.md
##########
@@ -13,147 +22,84 @@ Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), l
* Support load balancing based on pod (upstream nodes).
* Plug-in extension supports hot configuration and immediate effect.
* Ingress controller itself as a plugable hot-reload component.
+* Multi-cluster configuration distribution.
+
+## Architecture
+
+
+
+### 1.Ingress types
Review comment:
What about using resources instead of types?
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
+* Flexible extension capabilities based on plugins.
Review comment:
What about:
Flexible extension capabilities based on rich plugins in Apache APISIX.
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
+* Flexible extension capabilities based on plugins.
+* Convenient traffic split.
+* Multi-cluster configuration distribution.
+
+`apisix-ingress-controller` belongs to Apache APISIX control plane. Currently it serves for Kubernetes clusters. In the future, we plan to separate the submodule to adapt to more deployment modes, such as virtual machine clusters.
Review comment:
What about:
`apisix-ingress-controller` is an Apache APISIX control plane component.
##########
File path: README.md
##########
@@ -13,147 +22,84 @@ Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), l
* Support load balancing based on pod (upstream nodes).
* Plug-in extension supports hot configuration and immediate effect.
* Ingress controller itself as a plugable hot-reload component.
+* Multi-cluster configuration distribution.
+
+## Architecture
+
+
+
+### 1.Ingress types
+
+- defines the CRD(CustomResourceDefinition) needed by Apache APISIX
+
+- currently supports ApisixRoute/ApisixService/ApisixUpstream，and other service and route level plugins.
+
+- can be packaged as a stand-alone binary, keep in sync with the ingress definition.
+
+- [CRD design](https://github.com/api7/ingress-controller/issues/3)
+
+### 2. APISIX types
+
+- define interface objects to match concepts from Apache APISIX like route, service, upstream, and plugin.
+
+- can be a packaged as a stand-alone binary, need to match with compatible Apache APISIX version.
+
+- add new types to this module to support new features.
+
+### 3.Seven
Review comment:
The title is confusing.
##########
File path: docs/FAQ.md
##########
@@ -0,0 +1,15 @@
+# FAQ
+
+1. How to bind between Service and Upstream?
Review comment:
the word `between` is redundant.
##########
File path: docs/develop.md
##########
@@ -162,22 +168,22 @@ spec:
host: internalalpha.talkinggenie.com
enable_websocket: true
```
-config中定义需要按照 插件```proxy-rewrite```的schema定义；
-如果插件的schema是一个数组，需要用将config字段修改为config_set；
+The definition in config needs to follow the schema definition of the plugin `proxy-rewrite`.
Review comment:
We also needs the hyperlink for `proxy-rewrite`.
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
Review comment:
What about:
All configurations in `apisix-ingress-controller` are defined with Kubernetes CRDs (Custom Resource Definitions).
##########
File path: docs/install.md
##########
@@ -0,0 +1,129 @@
+# Installation
+
+## Dependencies
+
+* Kubernetes
+* [Deploy Apache APISIX in k8s](https://github.com/apache/apisix/blob/master/kubernetes/README.md)
+
+To install `ingress controller` in k8s, need to care about 3 parts:
+
+1. CRDs: They are the data structure of Apache APISIX in Kubernetes, used to define route, service, upstream, plugins, etc.
+
+2. RBAC: This is a function of Kubernetes, granting `ingress controller` resource access permissions.
Review comment:
Give the RBAC doc is better.
##########
File path: docs/install.md
##########
@@ -0,0 +1,129 @@
+# Installation
+
+## Dependencies
+
+* Kubernetes
+* [Deploy Apache APISIX in k8s](https://github.com/apache/apisix/blob/master/kubernetes/README.md)
+
+To install `ingress controller` in k8s, need to care about 3 parts:
+
+1. CRDs: They are the data structure of Apache APISIX in Kubernetes, used to define route, service, upstream, plugins, etc.
Review comment:
What about:
1. CRDs: the definitions of Apache APISIX configurations in Kubernetes
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538052942
##########
File path: README.md
##########
@@ -13,147 +22,84 @@ Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), l
* Support load balancing based on pod (upstream nodes).
* Plug-in extension supports hot configuration and immediate effect.
* Ingress controller itself as a plugable hot-reload component.
+* Multi-cluster configuration distribution.
+
+## Architecture
+
+
+
+### 1.Ingress types
+
+- defines the CRD(CustomResourceDefinition) needed by Apache APISIX
+
+- currently supports ApisixRoute/ApisixService/ApisixUpstream，and other service and route level plugins.
+
+- can be packaged as a stand-alone binary, keep in sync with the ingress definition.
+
+- [CRD design](https://github.com/api7/ingress-controller/issues/3)
+
+### 2. APISIX types
+
+- define interface objects to match concepts from Apache APISIX like route, service, upstream, and plugin.
+
+- can be a packaged as a stand-alone binary, need to match with compatible Apache APISIX version.
+
+- add new types to this module to support new features.
+
+### 3.Seven
Review comment:
How about changing to `The `Seven` submodule`
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538056451
##########
File path: docs/develop.md
##########
@@ -162,22 +168,22 @@ spec:
host: internalalpha.talkinggenie.com
enable_websocket: true
```
-config中定义需要按照 插件```proxy-rewrite```的schema定义；
-如果插件的schema是一个数组，需要用将config字段修改为config_set；
+The definition in config needs to follow the schema definition of the plugin `proxy-rewrite`.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739258659
> `docs/.DS_Store` please delete similar file
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538061913
##########
File path: docs/install.md
##########
@@ -0,0 +1,129 @@
+# Installation
+
+## Dependencies
+
+* Kubernetes
+* [Deploy Apache APISIX in k8s](https://github.com/apache/apisix/blob/master/kubernetes/README.md)
+
+To install `ingress controller` in k8s, need to care about 3 parts:
+
+1. CRDs: They are the data structure of Apache APISIX in Kubernetes, used to define route, service, upstream, plugins, etc.
+
+2. RBAC: This is a function of Kubernetes, granting `ingress controller` resource access permissions.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r537008568
##########
File path: docs/usage.md
##########
@@ -0,0 +1,159 @@
+# 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`.
+
+As shown below.
+
+
+
+Now we define with 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.
+
+List the way to define the above rules using `Admin API` to facilitate comparison and understanding.
+
+```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
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538055175
##########
File path: README.md
##########
@@ -13,147 +22,84 @@ Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), l
* Support load balancing based on pod (upstream nodes).
* Plug-in extension supports hot configuration and immediate effect.
* Ingress controller itself as a plugable hot-reload component.
+* Multi-cluster configuration distribution.
+
+## Architecture
+
+
+
+### 1.Ingress types
Review comment:
`ingress-types` is the name of [submodule](https://github.com/api7/ingress-types) in the ./docs/images/module-1.png.
And explained below the title are defined resources.
How about adds `submodule` after the titles.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739257634
any related issue?
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
membphis commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r537028089
##########
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:
got it
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538050460
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
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
[GitHub] [apisix-ingress-controller] nic-chen commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
nic-chen commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536992268
##########
File path: docs/usage.md
##########
@@ -0,0 +1,159 @@
+# 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`.
+
+As shown below.
+
+
+
+Now we define with 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.
+
+List the way to define the above rules using `Admin API` to facilitate comparison and understanding.
+
+```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
Review comment:
These IPs should be explained. When I first saw them, I didn't understand the relationship with the above example.
##########
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.
Review comment:
In this context route may be better than routing here？
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
membphis commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538120328
##########
File path: README.md
##########
@@ -2,7 +2,13 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+All configurations in `apisix-ingress-controller` are defined with Kubernetes CRDs (Custom Resource Definitions). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), Support service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+`apisix-ingress-controller` is an Apache APISIX control plane component. Currently it serves for Kubernetes clusters. In the future, we plan to separate the submodule to adapt to more deployment modes, such as virtual machine clusters.
+
+## Architecture
Review comment:
we need a better name here
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536803451
##########
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:
Done, I change the opacity of backgrounds, with little diff color for easy to distinguish.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538051398
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
+* Flexible extension capabilities based on plugins.
Review comment:
Done, Remove the section of compare with other ingress controller
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536793262
##########
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:
> `docs/.DS_Store` please delete similar file
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538134259
##########
File path: README.md
##########
@@ -2,7 +2,13 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+All configurations in `apisix-ingress-controller` are defined with Kubernetes CRDs (Custom Resource Definitions). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), Support service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+`apisix-ingress-controller` is an Apache APISIX control plane component. Currently it serves for Kubernetes clusters. In the future, we plan to separate the submodule to adapt to more deployment modes, such as virtual machine clusters.
+
+## Architecture
Review comment:
Done, I remove the `Architecture` section
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-740420284
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538056827
##########
File path: docs/install.md
##########
@@ -0,0 +1,129 @@
+# Installation
+
+## Dependencies
+
+* Kubernetes
+* [Deploy Apache APISIX in k8s](https://github.com/apache/apisix/blob/master/kubernetes/README.md)
+
+To install `ingress controller` in k8s, need to care about 3 parts:
+
+1. CRDs: They are the data structure of Apache APISIX in Kubernetes, used to define route, service, upstream, plugins, etc.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj merged pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj merged pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538103398
##########
File path: samples/deploy/rbac/apisix_view_clusterrolebinding.yaml
##########
@@ -8,5 +8,4 @@ roleRef:
name: apisix-view-clusterrole
subjects:
- kind: ServiceAccount
- name: apisix-view-serviceaccount
- namespace: cloud
\ No newline at end of file
+ name: apisix-view-serviceaccount
Review comment:
done
##########
File path: samples/deploy/rbac/service_account.yaml
##########
@@ -2,4 +2,4 @@ apiVersion: v1
kind: ServiceAccount
metadata:
name: apisix-view-serviceaccount
- namespace: cloud
\ No newline at end of file
+
Review comment:
done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538056103
##########
File path: docs/design.md
##########
@@ -36,6 +36,88 @@ 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 route 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:
+
+
+
+They are a many-to-many relationship.Therefore, `apisix-ingress-controller` has to do some conversion of CRDs to adapt to different gateways.
+
+### Cascade update
+
+At present, we have defined multiple CRDs, and these CRDs are responsible for the definition of their respective fields. `ApisixRoute`/ `ApisixService` / `ApisixUpstream` correspond to objects such as `route`/ `service` / `upstream` in Apache APISIX. As the strong binding relationship between APISIX objects, when modifying and deleting batch data structures such as CRDs, you have to consider the impact of cascading between objects.
+
+So, in `apisix-ingress-controller`, a broadcast notification mechanism is designed through `channel`, that is, the definition of any object must be notified to other objects related to it and trigger the corresponding behavior.
+
+
+
+In a typical scenario, there is a many-to-many relationship between `ApisixRoute` and `ApisixService`, and a one-to-one relationship between `ApisixService` and `ApisixUpstream`.
+
+* When the `ApisixService` changes, it needs to be notified upwards to the `ApisixRoute`, and also needs to be notified downwards to the corresponding `ApisixUpstream`.
+* When one of the `http-route` in `ApisixRoute` changes, the relevant `ApisixService` and `ApisixUpstream` need to be notified.
+
+This is particularly prominent in `modify` and `delete`.
+
+**We can initiate discussions in this area and propose a more reasonable design plan**
+
+### Diff rules
+
+The `seven` module internally saves memory data structures, which is currently very similar to the Apache Apisix resource object. When the Kubernetes resource object is newly changed, `seven` will compare the memory objects and update incrementally according to the result of the comparison.
+
+The current comparison rule is based on the grouping of `route` / `service` / `upstream` resource objects, compare them separately, and make corresponding broadcast notifications after finding the differences.
+
+
+
+### Service Discovery
+
+According to the `namespace` `name` `port` defined in the `ApisixUpstream` resource object, `apisix-ingress-controller` will register the `endpoints` node information in the `running` state to the nodes in Apache APISIX Upstream. And according to Kubernetes Endpoint status is synchronized in real time.
+
+Based on service discovery, Apache APISIX Ingress can directly access back-end Pod nodes. Bypassing Kubernetes Service, it is possible to implement customized load balancing strategies.
+
+### Annotation implementation
+
+Unlike the implementation of Kubernetes Nginx Ingress, the implementation of Annotation by `apisix-ingress-controller` is based on the plug-in mechanism of Apache APISIX.
+
+For example, the settings of the black and white list can be configured through the `k8s.apisix.apache.org/whitelist-source-range` annotation in the `ApisixRoute` resource object.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixRoute
+metadata:
+ annotations:
+ k8s.apisix.apache.org/whitelist-source-range: 1.2.3.4,2.2.0.0/16
+ name: httpserver-route
+spec:
+ ...
+```
+
+The black and white list here is implemented by the `ip-restriction` plugin.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r536809741
##########
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:
OK, update it in future
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
membphis commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r537982915
##########
File path: samples/deploy/rbac/apisix_view_clusterrolebinding.yaml
##########
@@ -8,5 +8,4 @@ roleRef:
name: apisix-view-clusterrole
subjects:
- kind: ServiceAccount
- name: apisix-view-serviceaccount
- namespace: cloud
\ No newline at end of file
+ name: apisix-view-serviceaccount
Review comment:
need a blank line at the end of file
##########
File path: samples/deploy/rbac/service_account.yaml
##########
@@ -2,4 +2,4 @@ apiVersion: v1
kind: ServiceAccount
metadata:
name: apisix-view-serviceaccount
- namespace: cloud
\ No newline at end of file
+
Review comment:
ditto
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538048793
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
Review comment:
Remove the compare with other ingress controller
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage and design docs
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r537008205
##########
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.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538050918
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
+* Flexible extension capabilities based on plugins.
+* Convenient traffic split.
+* Multi-cluster configuration distribution.
+
+`apisix-ingress-controller` belongs to Apache APISIX control plane. Currently it serves for Kubernetes clusters. In the future, we plan to separate the submodule to adapt to more deployment modes, such as virtual machine clusters.
Review comment:
Done
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] membphis commented on pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
membphis commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-740468544
@moonming take a look when you have time
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on a change in pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on a change in pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#discussion_r538048793
##########
File path: README.md
##########
@@ -2,7 +2,16 @@
Use Apache APISIX for Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
-Configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), load balancing and more in Apache APISIX for Kubernetes Services, support service registration discovery mechanism for upstreams. All using Custom Resource Definitions (CRDs).
+In `apisix-ingress-controller`, all using Custom Resource Definitions (CRDs). Such as configure [plugins](https://github.com/apache/apisix/tree/master/doc/plugins), upport service registration discovery mechanism for upstreams, load balancing and more in Apache APISIX.
+
+Compared with other ingress controllers, `apisix-ingress-controller` have solved several obvious problems.
+
+* Dynamically update the configuration, no need to reload.
Review comment:
Done, Remove the section of compare with other ingress controller.
----------------------------------------------------------------
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
[GitHub] [apisix-ingress-controller] gxthrj commented on pull request #48: docs: add usage/design/install/contribute/FAQ docs & modify README
Posted by GitBox <gi...@apache.org>.
gxthrj commented on pull request #48:
URL: https://github.com/apache/apisix-ingress-controller/pull/48#issuecomment-739507249
> Please put the architecture diagram on the homepage without highlighting the installation steps. The homepage contains: what is this project, how we implement it, what features it has, the smallest example, todo list，how to join and contribute
Done
----------------------------------------------------------------
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