docs: add usage/design/install/contribute/FAQ docs & modify README (a…

…pache#48) * feat: add usage and design docs * doc: add link of usage in README * fix: rm .DS_Store and add .gitignore * doc: change background opacity * doc: change the order of example, make CRDs first * doc: make FAQ in a separate file * change: Supplement in docs * doc: modify readme * doc: make todo more specific * doc: modify position of compare with other ingress * doc: remove namespace cloud in doc, use default instead * doc: change docs/develop.md to english * doc: remove compare with other ingress controller * doc: modify desc * doc: add EOL * doc: modify desc * doc: add architecture image * fix: rm .DS_Store * doc: add git ignore * doc: add hyperlink for todos * doc: remove Architecture section and make the image in introduction
junnplus · Dec 8, 2020 · f0c86d6 · f0c86d6
1 parent 23672ce
commit f0c86d6
Show file tree

Hide file tree

Showing 23 changed files with 572 additions and 229 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,4 @@
 *.out
 
 .idea
+.DS_Store
diff --git a/README.md b/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.
+
+The technical architecture of `apisix-ingress-controller`:
+
+<img src="./docs/images/module-0.png" alt="Architecture" width="600" height="313" />
 
 ## Features
 
@@ -13,147 +19,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.
+
+## Modules
+
+<img src="./docs/images/module-1.png" alt="module" width="600" height="313" />
+
+### 1. `Ingress types` Submodule
+
+- Define 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` Submodule
+
+- 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` submodule
+
+- Contain main application logic.
+
+- Sync the k8s cluster states to Apache APISIX, based on Apisix-types object.
+
+### 4.`Ingress-controller` Submodule
+
+- Driver process for ingress controller, watches k8s apiserver.
+
+- Match and covert Apisix-ingress-types to Apisix-types before handing the control over to the above module `seven`.
+
+Get more [implementation details](./docs/design.md).
 
 ## Get started
 
-### 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.
-
-3. Configmap: Contains the necessary configuration for `ingress controller`.
-
-### CRDs installation
-
-Install CRDs in Kubernetes
-
-```shell
-kubectl apply -f - <<EOF
-apiVersion: apiextensions.k8s.io/v1beta1
-kind: CustomResourceDefinition
-metadata:
-  name: apisixroutes.apisix.apache.org
-spec:
-  group: apisix.apache.org
-  versions:
-    - name: v1
-      served: true
-      storage: true
-  scope: Namespaced
-  names:
-    plural: apisixroutes
-    singular: apisixroute
-    kind: ApisixRoute
-    shortNames:
-    - ar
-
----
-apiVersion: apiextensions.k8s.io/v1beta1
-kind: CustomResourceDefinition
-metadata:
-  name: apisixservices.apisix.apache.org
-spec:
-  group: apisix.apache.org
-  versions:
-    - name: v1
-      served: true
-      storage: true
-  scope: Namespaced
-  names:
-    plural: apisixservices
-    singular: apisixservice
-    kind: ApisixService
-    shortNames:
-    - as
-
----
-apiVersion: apiextensions.k8s.io/v1beta1
-kind: CustomResourceDefinition
-metadata:
-  name: apisixupstreams.apisix.apache.org
-spec:
-  group: apisix.apache.org
-  versions:
-    - name: v1
-      served: true
-      storage: true
-  scope: Namespaced
-  names:
-    plural: apisixupstreams
-    singular: apisixupstream
-    kind: ApisixUpstream
-    shortNames:
-    - au
-
-EOF
-```
-
-### RBAC configuration
-
-* Create ServiceAccount
-
-```shell
-kubectl apply -f samples/deploy/rbac/service_account.yaml
-```
-
-* Create ClusterRole
-
-```shell
-kubectl apply -f samples/deploy/rbac/apisix_view_clusterrole.yaml
-```
-
-* Create ClusterRoleBinding
-
-```shell
-kubectl apply -f samples/deploy/rbac/apisix_view_clusterrolebinding.yaml
-```
-
-### Configmap for ingress controller
-
-Pay attention to the `namespace` and `APISIX address` in configmap.
-
-```shell
-kubectl apply -f samples/deploy/configmap/cloud.yaml
-```
-
-### Deploy ingress controller
-
-[How to build image from master branch?](# Master branch builds)
-
-```shell
-kubectl apply -f samples/deploy/deployment/ingress-controller.yaml
-```
-
-### Helm
-
-// todo
-
-## Document
+* [How to install](./docs/install.md)
+
+## Todos
+
+* Support `ApisixSSL` CRD and the logic. [#52](https://github.com/apache/apisix-ingress-controller/issues/52)
+* Support retry when synchronization. [#59](https://github.com/apache/apisix-ingress-controller/issues/59)
+* Add a complete demo. [#9](https://github.com/apache/apisix-ingress-controller/issues/9)
+* Use terratest for testing with Kubernetes. [#51](https://github.com/apache/apisix-ingress-controller/issues/51)
+* More todos will display in [issues](https://github.com/apache/apisix-ingress-controller/issues)
 
+## Documents
+
+* [Usage](./docs/usage.md)
 * [SDK doc](./docs/develop.md)
 * [Design introduction](./docs/design.md)
 
-## Master branch builds
+## FAQ
+
+* [FAQ](./docs/FAQ.md)
+
+## User stories
+
+- [aispeech: Why we create a new k8s ingress controller?(Chinese)](https://mp.weixin.qq.com/s/bmm2ibk2V7-XYneLo9XAPQ)
+- [Tencent Cloud: Why choose Apache APISIX to implement the k8s ingress controller?(Chinese)](https://www.upyun.com/opentalk/448.html)
 
-```shell
-docker build -t apache/ingress-controller:v0.1.0 .
-```
+## Contributing
 
-## Seeking help
+We welcome all kinds of contributions from the open-source community, individuals and partners.
+
+* [Contributing Guide](./docs/contribute.md)
+
+## Community
 
 - Mailing List: Mail to dev-subscribe@apisix.apache.org, follow the reply to subscribe the mailing list.
-- QQ Group - 578997126, 552030619
-- [Slack Workspace](http://s.apache.org/slack-invite) - join `#apisix` on our Slack to meet the team and ask questions
+- QQ Group - 578997126
 - ![Twitter Follow](https://img.shields.io/twitter/follow/ApacheAPISIX?style=social) - follow and interact with us using hashtag `#ApacheAPISIX`
-- [bilibili video](https://space.bilibili.com/551921247)
+- [Bilibili video](https://space.bilibili.com/551921247)
 
 ## License
 
-[Apache License 2.0](https://github.com/api7/ingress-controller/blob/master/LICENSE)
-
+[Apache License 2.0](https://github.com/apache/apisix-ingress-controller/blob/master/LICENSE)
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -0,0 +1,15 @@
+# FAQ
+
+1. How to bind Service and Upstream?
+
+All resource objects are uniquely determined by the namespace / name / port combination Id. If the combined Id is the same, the `service` and `upstream` will be considered as a binding relationship.
+
+2. When modifying a CRD, how do other binding objects perceive it?
+
+This is a cascading update problem, see for details [apisix-ingress-controller Design ideas](./design.md)
+
+3. Can I mix CRDs and admin api to define routing rules?
+
+No, currently we are implementing one-way synchronization, that is, CRDs file -> Apache AIPSIX. If the configuration is modified separately through admin api, it will not be synchronized to CRDs in Kubernetes.
+
+This is because CRDs are generally declared in the file system, and Apply to enter Kubernetes etcd, we follow the definition of CRDs and synchronize to Apache Apisix Data Plane, but the reverse will make the situation more complicated.
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -0,0 +1,30 @@
+# Contributing to apisix-ingress-controller
+
+Firstly, thanks for your interest in contributing! I hope that this will be a
+pleasant first experience for you, and that you will return to continue
+contributing.
+
+## How to contribute
+
+Most of the contributions that we receive are code contributions, but you can
+also contribute to the documentation or simply report solid bugs
+for us to fix.
+
+ For new contributors, please take a look at issues with a tag called [Good first issue](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [Help wanted](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+
+## How to report a bug
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/apache/apisix-ingress-controller/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/apache/apisix-ingress-controller/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+
+## How to add a new feature or change an existing one
+
+Before making any significant changes, please [open an issue](https://github.com/apache/apisix-ingress-controller/issues). Discussing your proposed changes ahead of time will make the contribution process smooth for everyone.
+
+Once we've discussed your changes and you've got your code ready, make sure that tests are passing and open your pull request. Your PR is most likely to be accepted if it:
+
+* Update the README.md with details of changes to the interface.
+* Includes tests for new functionality.
+* References the original issue in the description, e.g. "Resolves #123".
+* Has a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
diff --git a/docs/deploy.md b/docs/deploy.md
@@ -107,7 +107,6 @@ apiVersion: apisix.apache.org/v1
 kind: ApisixRoute
 metadata:
   name: httpserver-route
-  namespace: cloud
 spec:
   rules:
   - host: test.apisix.apache.org

diff --git a/docs/design.md b/docs/design.md
@@ -2,9 +2,9 @@
 
 Apache APISIX ingress for Kubernetes.
 
-## Design
+## Modules
 
-![Architecture](../images/module.png)
+![Architecture](./images/module-1.png)
 
 ### 1.Ingress-types
 
@@ -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
 
-![Sequence Diagram](../images/flow.png)
+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
+
+![flow](./images/flow.png)
+
+### 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:
+
+![strut-compare](./images/struct-compare.png)
+
+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.
+
+![hierarchical](./images/hierarchical.png)
+
+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.
+
+![diff-flow](./images/diff-flow.png)
+
+### 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 backend 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](https://github.com/apache/apisix/blob/master/doc/plugins/ip-restriction.md) plugin.
+
+There will be more annotation implementations in the future to facilitate the definition of some common configurations, such as CORS.
+
+If you have some annotation needs, welcome to [issue](https://github.com/apache/apisix-ingress-controller/issues) to discuss, let’s discuss how to implement it.