Docs (#296)

* docs: update roadmap Signed-off-by: genghaotao <genghaotao@beyondcent.com> * docs: fix typo Signed-off-by: genghaotao <genghaotao@beyondcent.com> * docs: update user-guide Signed-off-by: genghaotao <genghaotao@beyondcent.com> * docs: update README Signed-off-by: genghaotao <genghaotao@beyondcent.com>
FabEdge · Mar 21, 2022 · 0303407 · 0303407
1 parent af54eda
commit 0303407
Show file tree

Hide file tree

Showing 5 changed files with 50 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -8,29 +8,39 @@
 
 English | [中文](README_zh.md)
 
-FabEdge is a secure edge networking solution based on Kubernetes. It enables cloud-edge, edge-edge collaboration and solves the problems including complex  configuration management, network isolation, lack of topology-aware routing, etc. 
 
-FabEdge is able to manage the network of not only the edge nodes, but also the edge clusters. 
+FabEdge is a secure container networking solution based on Kubernetes, focusing on edge computing. It enables cloud-edge, edge-edge collaboration and solves the problems including complex configuration management, network isolation, unaware of the underlying topology, etc. It supports weak network, such as 4/5G, WiFi, etc. The main use cases are IoT, IoV, smart city, etc.
+
+FabEdge supports the major edge computing frameworks ,like KubeEdge/SuperEdge/OpenYurt.
+
+FabEdge not only supports edge nodes (remote nodes joined to the cluster via an edge computing framework such as KubeEdge), but also edge clusters (standalone K8S clusters).
+
+FabEdge is a sandbox project of the Cloud Native Computing Foundation (CNCF).
 
-FabEdge supports weak transport network, such as 4/5G, WiFi, etc. It is suitable for scenarios such as IoT (Internet of Things),  IoV (Internet of Vehicles), etc.
 
 ## Features
 * **Kubernetes Native**: Compatible with Kubernetes, transparent to applications.  
-* **Automatic Address Management**：Management of the subnets allocation and IP address assignment for edge containers.  
-* **Cloud-Edge/Edge-Edge Collaboration**: Secure tunnels between cloud-edge, edge-edge nodes for synergy.  
-* **Edge Node Community Control**:  Use CRD of “community” to control which edge nodes can communicate with each others.  
-* **Topology-aware service**: Improve service latency by giving higher priority to local endpoints, while still able to access endpoints in remote cloud.  
 
-## Advantages
-* **Standard**: fully compatible with Kubernetes, support any cluster, any application, plug and play.  
-* **Secure**: all communication over secure IPSec tunnels with certificate based authentication.  
-* **Easy to use**: designed using operator pattern, minimized ongoing operation effort.  
+* **Automatic Configuration Management**: the addresses, certificates, endpoints, tunnels, etc. are automatically managed.
+
+* **Cloud-Edge/Edge-Edge Collaboration**: Secure tunnels between cloud-edge, edge-edge nodes for synergy.
+
+
+* **Topology-aware Service Discovery**: reduces service access latency, by using the nearest available service endpoint.
+
+
+## Advantages:
+
+- **Standard**: suitable for any protocol, any application.
+- **Secure**: Uses mature and stable IPSec technology, and a secure certificate-based authentication system.
+- **Easy to use**: Adopts the `Operator` pattern to automatically manage addresses, nodes, certificates, etc., minimizing human intervention.
+
 
 ## How it works
 <img src="docs/images/FabEdge-Arch.png" alt="fabedge-arch" />
 
 * The cloud can be any Kubernetes cluster with supported CNI network plug-in, including Calico, Flannel, etc.
-* FabEdge builds a layer 3 data plane with tunnels in additional to the control plan managed by KubeEdge, SuperEdge, OpenYurt，etc.
+* FabEdge builds a layer-3 data plane with tunnels in additional to the control plan managed by KubeEdge, SuperEdge, OpenYurt，etc.
 * Fabedge consists of **Operators, Connector, Agent, Cloud-Agent**.
 * Operator monitors k8s resources such as node, service, and endpoint in the cloud, and creates a configmap for each edge node, which contains the  configuration information such as the subnet, tunnel, and load balancing rules. The operator is also responsible to manage the life cycle of agent pod for each edge node.  
 * Connector is responsible to terminate the tunnels from edge nodes, and forward traffic between the cloud and the edge. It relies on the cloud CNI plug-in to forward traffic to other non-connector nodes in the cloud.
@@ -40,17 +50,12 @@ FabEdge supports weak transport network, such as 4/5G, WiFi, etc. It is suitable
     - Manage the tunnels of this node
     - Manage the load balancing rules of this node  
 
-## Compatibility
-
-|             | KubeEdge 1.8.0 | SuperEdge  0.5.0 | OpenYurt 0.5.0 |
-| ----------- | -------------- | ---------------- | -------------- |
-| FabEdge 0.3 | ✓              | ✓                | ✓              |
+* Fab-DNS runs in all the clusters, to provide the topology-aware service discovery capability by intercepting the DNS queries.    
 
-> It means the versions we have verified and it does not mean the others do not work. Since FabEdge does not tightly coupled with any edge-computing frameworks  it is very likely that the other version works.
 
-## FabEdge vs Calico/Flannel 
+## FabEdge vs. Calico/Flannel/etc
 
-Fabedge is different from generic Kubernetes network plug-ins such as Calico/Flannel. As in the above architecture diagram, Calico/Flannel is used in the cloud for communication between cloud nodes. Fabedge is a complement to it for the edge-cloud, edge-edge communication. 
+Fabedge is not to replace the traditional Kubernetes network plugins such as Calico/Flannel. As in the above architecture diagram, Calico/Flannel is used within the cloud for communication between cloud nodes, while Fabedge is a complement to it for the edge-cloud, edge-edge communication. 
 
 ## Guides
 See  [the docs](docs/).

diff --git a/README_zh.md b/README_zh.md
@@ -36,7 +36,7 @@ FabEdge是托管在CNCF下的沙箱项目。
 * Operator运行在云端任意的节点，通过监听节点，服务等K8S资源，为每个Agent维护一个ConfigMap，包括了本Agent需要的路由信息，比如子网，端点，负载均衡规则等，同时为每个Agent维护一个Secret，包括CA证书，节点证书等。Operator也负责Agent自身的管理，包括创建，更新，删除等。
 * Connector运行在云端选定的节点，负责管理从边缘节点发起的隧道，在边缘节点和云端集群之间转发流量。从Connector节点到云端其它非Connector节点的流量转发仍然依靠云端CNI。
 * Cloud-Agent运行在集群中所有非边缘，非Connector的节点，它负责管理本节点到远端的路由。  
-* Agent运行在每个边缘节点上， 它使用自己的ConfigMap和Secret的信息，发起到云端Connector和其它边缘节点的隧道，负责本节点的路由，负责均衡，iptables规则的管理。
+* Agent运行在每个边缘节点上， 它使用自己的ConfigMap和Secret的信息，发起到云端Connector和其它边缘节点的隧道，负责本节点的路由，负载均衡，iptables规则的管理。
 * Fab-DNS运行在所有FabEdge的集群里，它通过截获DNS请求，提供拓扑感知的跨集群服务发现能力。
 
 ## FabEdge和传统CNI的区别 

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -11,11 +11,18 @@
 
 ## Q4 2021
 
-- Support auto-discovery of Edge Tunnel Endpoints
 - Support Edge Cluster
-- Support Direct Routing in Community
+- Support topology-aware service discovery
 
 ## H1 2022
 
-- Suport Canal/Weave/Cillium/etc.
 - Support IPV6
+- cli tool to facilitate fabedge configuation
+
+## others
+
+- Support auto-discovery of edge tunnel endpoints
+- Add monitoring capability 
+- Connector HA solution
+- Support more tunnel methods 
+- Suport Canal/Weave/Cillium/etc.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -100,3 +100,10 @@ In public cloud, the virtual machine has only private address, which prevents fr
 kubectl annotate node edge1 "fabedge.io/node-public-addresses=60.247.88.194"
 ```
 
+## Create GlobalService
+
+GlobalService is used to export a local/standard k8s service (ClusterIP or Headless) for other clusters to access it. And it provides the topology-aware service discovery capability.
+
+1. create a service, e.g. namespace: default, name: web
+2. Label it with : `fabedge.io/global-service: true`  
+3. It can be accessed by the domain name: `web.defaut.svc.global`
diff --git a/docs/user-guide_zh.md b/docs/user-guide_zh.md
@@ -53,6 +53,7 @@ spec:
    kind: Cluster
    metadata:
      name: beijing
+
    ```
 
 2. 查看token
@@ -93,7 +94,6 @@ spec:
    ```
 
 
-
 ## 为边缘节点指定公网地址
 
 对于公有云的场景，云主机一般只配置了私有地址，导致FabEdge无法建立边缘到边缘的隧道。这种情况下可以为云主机申请一个公网地址，加入节点的注解，FabEdge将自动使用这个公网地址建立隧道，而不是私有地址。
@@ -103,3 +103,9 @@ spec:
 kubectl annotate node edge1 "fabedge.io/node-public-addresses=60.247.88.194"
 ```
 
+## 创建全局服务
+全局服务把本集群的一个普通的Service （Headless 或 ClusetrIP），暴露给其它集群访问，并且提供基于拓扑的服务发现能力。  
+
+1. 创建一个k8s的服务， 比如，命名空间是default， service的名字是web   
+2. 为web服务添加标签：`fabedge.io/global-service: true`  
+3. 所有集群可以通过域名：`web.default.svc.global`,  就近访问到web的服务。