[apisix-control-plane] branch master updated: doc: enrich readme (#27)

[we...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wenming pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-control-plane.git


The following commit(s) were added to refs/heads/master by this push:
     new 7ec9452  doc: enrich readme (#27)
7ec9452 is described below

commit 7ec94524b64f2351d03eb009b4bc666a88835de0
Author: kv <gx...@163.com>
AuthorDate: Thu Oct 15 10:33:09 2020 +0800

    doc: enrich readme (#27)
---
 README.md           |  63 ++++++++++++++++++++++++++++++++++++++++++----------
 doc/images/flow.png | Bin 0 -> 131408 bytes
 2 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 694b9f2..9dde855 100644
--- a/README.md
+++ b/README.md
@@ -17,18 +17,57 @@
 #
 -->
 
-# apisix-control-plane
+# APISIX-CONTROL-PLANE
 
-## what is apisix-control-plane?
-apisix-control-plane provide APISIX with a `yml` configuration capability,
-We can use `yml` to define the proxy behavior of APISIX
+## What is apisix-control-plane
 
-## Why do you want to do this?
-1. In order to facilitate the integration of k8s, use `yml` to define APISIX;
-2. For easier synchronization across clusters;
-3. Can be better adapted to multiple platforms (k8s, vm);
+apisix-control-plane is an implementation of providing a control plane for DPs (Data Plane) like Apache APISIX or other gateways. with a `yaml` configuration capability, We can use `yaml` to define the behavior of any DP.
+
+## Why do we need to implement a control-plane
+
+For now, we have a default implementation for Apache APISIX.
+
+As we knows, Apache APISIX is a high-performance gateway. When using APISIX we need to inform APISIX of some proxy rules, and distribute these rules to APISIX modules. We can call it contol-plane, similar to pilot in istio. Of course, the distribution configuration is only the most basic function of the control plane.
+
+We know that APISIX already has Admin API, so why do we need to implement a control-plane?
+
+First of all, Apache APISIX Admin API is a way to define a single object, such as a single object such as route / service / upstream / consumer, although it is also possible to completely define a route through a huge route object, and the upstream object is embedded in the route , But any minor changes will trigger the reconstruction of the route. Rebuilding the route is definitely not a good idea and reduce performance.
+
+In fact, leaving aside the Admin API, what we need is a description method that can completely define the rules while maintaining the legibility of the Admin API. Therefore, we have [discussion here](https://github.com/apache/apisix-control-plane/blob/master/doc/yaml_struct.md), and we have implemented a version of the basic functions according to this data structure , I hope everyone puts forward their views. We can also submit a PR to modify this [document](doc/yaml_struct.md).
+
+Secondly, Apache APISIX Admin API uses id associations to strongly bind objects to express the relationship between objects. For example, the route object uses `service_id` and `upstream_id` to bind the relationship with service and upstream respectively.
+
+This kind of representation, like the well-known relational database, is easier to understand and reduces redundant configurations. But it also brings some other problems. For example, rely on verification. When we want to bind an `upstream_id` to a route, we must first create the upstream, and then bind the generated `upstream_id` to the route. This process corresponds to two Admin APIs, and there is no transaction management.
+
+We hope that the emergence of control-plane can solve the above two problems.
+1. Use yaml declarative definition method to define complete rules.
+2. Block DP implementation details, describe object relationships in a unified way.
+
+Of course, with control-plane we can do more.
+
+For example, based on gitops configuration version management, it is also more convenient to use yaml to define APISIX in k8s.
+
+Realize the prototype of cross-cluster synchronization configuration through the control panel. In the future, we can also enrich the functions of the control plane and simplify management under the cluster mode of multi-platform hybrid deployment (k8s/vm). We can also shield specific implementations of APISIX and provide configuration functions for more types of gateways.
+
+## Feature support
+
+1. Support the declarative definition of yaml.
+2. Use the memory database to synchronize the gateway status.
+3. Diff capabilities based on memory objects.
+4. Sync / update the APISIX configuration.
+5. Support incremental synchronization.
+6. Support transaction processing.
+
+We created [apache/apisix-control-plane](https://github.com/apache/apisix-control-plane) to provide the basic implementation of the above features.
+
+We also plan to support the following features
+
+1. Support multiple DP configuration.
+2. Support pull/push two synchronization strategies.
+3. Support multi-DP hybrid cluster.
+4. Support migration between DPs.
+
+![](doc/images/flow.png)
+
+Everyone is welcome to participate in discussions and contributions.
 
-## DISCUSS
-Here are some examples of `yml` and we can add comments here.
-https://github.com/apache/apisix-control-plane/issues/3
-We can also submit a PR to modify this [document](doc/yaml_struct.md).
diff --git a/doc/images/flow.png b/doc/images/flow.png
new file mode 100644
index 0000000..5073cb6
Binary files /dev/null and b/doc/images/flow.png differ