[GitHub] [apisix-ingress-controller] nic-chen commented on a change in pull request #48: docs: add usage and design docs

[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.
+
+![scene](./images/scene.png)
+
+## 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.
+
+![first](./images/first.png)
+
+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
 
-![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 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