[incubator-shenyu-nginx] branch main updated: doc: add nacos example (#17)

[im...@apache.org]

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

impactcn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-shenyu-nginx.git


The following commit(s) were added to refs/heads/main by this push:
     new e87d0a1  doc: add nacos example (#17)
e87d0a1 is described below

commit e87d0a18917c84ee8bdd5eaf74ed547ee7f4ce00
Author: Luke.Z <10...@users.noreply.github.com>
AuthorDate: Sun Jul 3 23:24:09 2022 +0800

    doc: add nacos example (#17)
    
    * add nacos example
    
    * Update README.md
---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 9329ab9..6e98937 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,15 @@
-incubator-shenyu-nginx
+Apache ShenYu Nginx Module(Experimental)
 ---
 
-ShenYu(Incubator) is High-Performance Java API Gateway. 
+This module provided SDK to watch available ShenYu instance list as upstream nodes by Service Register Center for OpenResty.
+1. [ETCD](#greeting-etcd) (Supported)
+2. [Nacos](#greeting-nacos) (Supported)
+3. Zookeeper (TODO)
+4. Consul (TODO)
 
-ShenYu Nginx is an Nginx Upstream module for ShenYu instances discovery. The module will discover ShenYu instances to be upstream server of Nginx throght watching register, such as Etcd(supported), Apache Zookeeper(Todo), Nacos(Todo), and others.
+In the cluster mode, Apache ShenYu supports the deployment of multiple ShenYu instances, which may have new instances joining or leaving at any time.
+Hence, Apache ShenYu introduces Service Discovery modules to help client to detect the available instances. 
+Currently, Apache ShenYu Bootstrap already supports Apache Zookeeper, Nacos, Etcd, and consul. Client or LoadBalancer can get the available ShenYu instances by those Service register center. 
 
 ## Getting Started
 
@@ -13,7 +19,7 @@ ShenYu Nginx is an Nginx Upstream module for ShenYu instances discovery. The mod
 
 ### Build from source
 
-The first, clone the source from Github.
+The first, clone the source from GitHub.
 ```shell
 git clone https://github.com/apache/incubator-shenyu-nginx
 ```
@@ -24,7 +30,13 @@ cd incubator-shenyu-nginx
 luarocks make rockspec/shenyu-nginx-main-0.rockspec
 ```
 
-Modify the Nginx configure, create and initialize the ShenYu Register to connect to targed register center.  Here is an example for Etcd.
+### Greeting ETCD
+
+Modify the Nginx configure, create and initialize the ShenYu Register to connect to the target register center. 
+The module will fetch the all of ShenYu instances which are registered to Etcd in the same cluster.
+It works like Etcd client to watch(based on long polling) ShenYu instance lists. 
+
+Here is an example for Etcd.
 ```
 init_worker_by_lua_block {
     local register = require("shenyu.register.etcd")
@@ -36,9 +48,9 @@ init_worker_by_lua_block {
 ```
 
 1. `balancer_type` specify the balancer. It has supported `chash` and `round robin`.
-2. `etcd_base_url` specify the Etcd server.
+2. `etcd_base_url` specify the Etcd server.(Currently, authentication is not supported.)
 
-Modify the `upstream` to enable to update upstream servers dynamically. This case will synchorinze the ShenYu instance list with register center. 
+Add an `upstream block` for ShenYu and enable to update upstream servers dynamically. This case will synchronize the ShenYu instance list with register center. 
 And then pick one up for handling the request.
 ```
 upstream shenyu {
@@ -55,7 +67,47 @@ Finally, restart OpenResty.
 openresty -s reload
 ```
 
-Here provides a completed [example](https://github.com/apache/incubator-shenyu-nginx/blob/main/example/nginx.conf).
+Here is a completed [example](https://github.com/apache/incubator-shenyu-nginx/blob/main/example/etcd/nginx.conf) working with ETCD.
+
+### Greeting Nacos
+
+Modify the Nginx configure, create and initialize the ShenYu Register to connect to target register center.  Here is an example for Nacos.
+```
+init_worker_by_lua_block {
+    local register = require("shenyu.register.nacos")
+    register.init({
+        shenyu_storage = ngx.shared.shenyu_storage,
+        balancer_type = "chash",
+        nacos_base_url = "http://127.0.0.1:8848",
+        username = "nacos",
+        password = "naocs",
+    })
+}
+```
+
+1. `balancer_type` specify the balancer. It has supported `chash` and `round robin`.
+2. `nacos_base_url` specify the Nacos server address.
+3. `username` specify the username to log in Nacos. (it is only required when Nacos auth enable)
+4. `password` specify the password to log in Nacos.
+
+Modify the `upstream` to enable to update upstream servers dynamically. This case will synchronize the ShenYu instance list with register center. 
+And then pick one up for handling the request.
+```
+upstream shenyu {
+    server 0.0.0.1; -- bad 
+    
+    balancer_by_lua_block {
+        require("shenyu.register.nacos").pick_and_set_peer()
+    }
+}
+```
+
+Finally, restart OpenResty.
+```shell
+openresty -s reload
+```
+
+Here is a completed [example](https://github.com/apache/incubator-shenyu-nginx/blob/main/example/nacos/nginx.conf) working with Nacos.
 
 ## Contributor and Support