You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/09/21 00:48:32 UTC

[apisix] branch master updated: docs: refactor kubernetes discovery (#7944)

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

sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git


The following commit(s) were added to refs/heads/master by this push:
     new 2d533a875 docs: refactor kubernetes discovery (#7944)
2d533a875 is described below

commit 2d533a875d736da0ddf9a1de06eeba03c648178f
Author: zhixiongdu <ro...@libssl.com>
AuthorDate: Wed Sep 21 08:48:22 2022 +0800

    docs: refactor kubernetes discovery (#7944)
    
    * docs: refactor kubernetes discovery
    
    * Update docs/zh/latest/discovery/kubernetes.md
    
    Co-authored-by: Sylvia <39...@users.noreply.github.com>
---
 conf/config-default.yaml               |  43 +++++++-
 docs/en/latest/discovery/kubernetes.md | 196 +++++++++++++++++++++++++++++----
 docs/zh/latest/discovery/kubernetes.md | 192 +++++++++++++++++++++++++++++---
 3 files changed, 392 insertions(+), 39 deletions(-)

diff --git a/conf/config-default.yaml b/conf/config-default.yaml
index 9c70d8ee0..80c8a3466 100755
--- a/conf/config-default.yaml
+++ b/conf/config-default.yaml
@@ -238,7 +238,6 @@ nginx_config:                     # config for render the template to generate n
       introspection: 10m
       access-tokens: 1m
       ext-plugin: 1m
-      kubernetes: 1m
       tars: 1m
 
 # HashiCorp Vault storage backend for sensitive data retrieval. The config shows an example of what APISIX expects if you
@@ -303,6 +302,10 @@ nginx_config:                     # config for render the template to generate n
 #       path: "logs/consul_kv.dump"
 #       expire: 2592000            # unit sec, here is 30 day
 #  kubernetes:
+#    ### kubernetes service discovery both support single-cluster and multi-cluster mode
+#    ### applicable to the case where the service is distributed in a single or multiple kubernetes clusters.
+#
+#    ### single-cluster mode ###
 #    service:
 #      schema: https                     #apiserver schema, options [http, https], default https
 #      host: ${KUBERNETES_SERVICE_HOST}  #apiserver host, options [ipv4, ipv6, domain, environment variable], default ${KUBERNETES_SERVICE_HOST}
@@ -332,6 +335,44 @@ nginx_config:                     # config for render the template to generate n
 #    # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
 #    label_selector: |-
 #      first="a",second="b"
+#    # reserved lua shared memory size,1m memory can store about 1000 pieces of endpoint
+#    shared_size: 1m #default 1m
+#    ### single-cluster mode ###
+#
+#    ### multi-cluster mode ###
+#  - id: release  # a custom name refer to the cluster, pattern ^[a-z0-9]{1,8}
+#    service:
+#      schema: https                     #apiserver schema, options [http, https], default https
+#      host: ${KUBERNETES_SERVICE_HOST}  #apiserver host, options [ipv4, ipv6, domain, environment variable]
+#      port: ${KUBERNETES_SERVICE_PORT}  #apiserver port, options [port number, environment variable]
+#    client:
+#      # serviceaccount token or path of serviceaccount token_file
+#      token_file: ${KUBERNETES_CLIENT_TOKEN_FILE}
+#      # token: |-
+#       # eyJhbGciOiJSUzI1NiIsImtpZCI6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEif
+#       # 6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEifeyJhbGciOiJSUzI1NiIsImtpZCI
+#    # kubernetes discovery plugin support use namespace_selector
+#    # you can use one of [equal, not_equal, match, not_match] filter namespace
+#    namespace_selector:
+#      # only save endpoints with namespace equal default
+#      equal: default
+#      # only save endpoints with namespace not equal default
+#      #not_equal: default
+#      # only save endpoints with namespace match one of [default, ^my-[a-z]+$]
+#      #match:
+#      #- default
+#      #- ^my-[a-z]+$
+#      # only save endpoints with namespace not match one of [default, ^my-[a-z]+$ ]
+#      #not_match:
+#      #- default
+#      #- ^my-[a-z]+$
+#    # kubernetes discovery plugin support use label_selector
+#    # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
+#    label_selector: |-
+#      first="a",second="b"
+#    # reserved lua shared memory size,1m memory can store about 1000 pieces of endpoint
+#    shared_size: 1m #default 1m
+#    ### multi-cluster mode ###
 
 graphql:
   max_size: 1048576               # the maximum size limitation of graphql in bytes, default 1MiB
diff --git a/docs/en/latest/discovery/kubernetes.md b/docs/en/latest/discovery/kubernetes.md
index eb931ba35..d95cdcceb 100644
--- a/docs/en/latest/discovery/kubernetes.md
+++ b/docs/en/latest/discovery/kubernetes.md
@@ -24,12 +24,17 @@ title: Kubernetes
 ## Summary
 
 The [_Kubernetes_](https://kubernetes.io/) service discovery [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) real-time changes of [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service/) resources,
-then store theirs value into ngx.shared.kubernetes \
-Discovery also provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md)
+then store theirs value into ngx.shared.DICT \
+Discovery also provides a node query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md)
 
-## Configuration
+## How To Use
 
-A detailed configuration for the kubernetes service discovery is as follows:
+Kubernetes service discovery both support single-cluster and multi-cluster mode, \
+applicable to the case where the service is distributed in a single or multiple Kubernetes clusters.
+
+### Single-Cluster Mode Configuration
+
+A detailed configuration for single-cluster mode Kubernetes service discovery is as follows:
 
 ```yaml
 discovery:
@@ -54,7 +59,7 @@ discovery:
 
     default_weight: 50 # weight assigned to each discovered endpoint. default 50, minimum 0
 
-    # kubernetes discovery plugin support use namespace_selector
+    # kubernetes discovery support namespace_selector
     # you can use one of [equal, not_equal, match, not_match] filter namespace
     namespace_selector:
       # only save endpoints with namespace equal default
@@ -73,21 +78,23 @@ discovery:
        #- default
        #- ^my-[a-z]+$
 
-    # kubernetes discovery plugin support use label_selector
+    # kubernetes discovery support label_selector
     # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
     label_selector: |-
       first="a",second="b"
+
+    # reserved lua shared memory size,1m memory can store about 1000 pieces of endpoint
+    shared_size: 1m #default 1m
 ```
 
-If the kubernetes service discovery runs inside a pod, you can use minimal configuration:
+If the Kubernetes service discovery runs inside a pod, you can use minimal configuration:
 
 ```yaml
 discovery:
   kubernetes: { }
 ```
 
-If the kubernetes service discovery runs outside a pod, you need to create or select a specified [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/),
-then get its token value, and use following configuration:
+If the Kubernetes service discovery runs outside a pod, you need to create or select a specified [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), then get its token value, and use following configuration:
 
 ```yaml
 discovery:
@@ -101,25 +108,25 @@ discovery:
       #token_file: # enter file path here
 ```
 
-## Interface
+### Single-Cluster Mode Query Interface
 
-the kubernetes service discovery provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md)
+The Kubernetes service discovery provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md).
 
 **function:** \
  nodes(service_name)
 
 **description:** \
-  nodes() function attempts to look up the ngx.shared.kubernetes for nodes corresponding to service_name, \
+  nodes() function attempts to look up the ngx.shared.DICT for nodes corresponding to service_name, \
   service_name should match pattern: _[namespace]/[name]:[portName]_
 
-  + namespace: The namespace where the kubernetes endpoints is located
+  + namespace: The namespace where the Kubernetes endpoints is located
 
-  + name: The name of the kubernetes endpoints
+  + name: The name of the Kubernetes endpoints
 
-  + portName: The portName of the kubernetes endpoints, if there is no portName, use targetPort, port instead
+  + portName: The ports.name value in the Kubernetes endpoints, if there is no ports.name, use targetPort, port instead
 
 **return value:** \
-  if the kubernetes endpoints value is as follows:
+  if the Kubernetes endpoints value is as follows:
 
   ```yaml
   apiVersion: v1
@@ -133,9 +140,122 @@ the kubernetes service discovery provides a query interface in accordance with t
         - ip: "10.5.10.110"
       ports:
         - port: 3306
+          name: port
   ```
 
-  a nodes("default/plat-dev:3306") call will get follow result:
+  a nodes("default/plat-dev:port") call will get follow result:
+
+  ```
+   {
+       {
+           host="10.5.10.109",
+           port= 3306,
+           weight= 50,
+       },
+       {
+           host="10.5.10.110",
+           port= 3306,
+           weight= 50,
+       },
+   }
+  ```
+
+### Multi-Cluster Mode Configuration
+
+A detailed configuration for multi-cluster mode Kubernetes service discovery is as follows:
+
+```yaml
+discovery:
+  kubernetes:
+  - id: release  # a custom name refer to the cluster, pattern ^[a-z0-9]{1,8}
+    service:
+      # apiserver schema, options [http, https]
+      schema: https #default https
+
+      # apiserver host, options [ipv4, ipv6, domain, environment variable]
+      host: "1.cluster.com"
+
+      # apiserver port, options [port number, environment variable]
+      port: "6443"
+
+    client:
+      # serviceaccount token or token_file
+      token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+
+      #token: |-
+       # eyJhbGciOiJSUzI1NiIsImtpZCI6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEif
+       # 6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEifeyJhbGciOiJSUzI1NiIsImtpZCI
+
+    default_weight: 50 # weight assigned to each discovered endpoint. default 50, minimum 0
+
+    # kubernetes discovery support namespace_selector
+    # you can use one of [equal, not_equal, match, not_match] filter namespace
+    namespace_selector:
+      # only save endpoints with namespace equal default
+      equal: default
+
+      # only save endpoints with namespace not equal default
+      #not_equal: default
+
+      # only save endpoints with namespace match one of [default, ^my-[a-z]+$]
+      #match:
+       #- default
+       #- ^my-[a-z]+$
+
+      # only save endpoints with namespace not match one of [default, ^my-[a-z]+$]
+      #not_match:
+       #- default
+       #- ^my-[a-z]+$
+
+    # kubernetes discovery support label_selector
+    # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
+    label_selector: |-
+      first="a",second="b"
+
+    # reserved lua shared memory size,1m memory can store about 1000 pieces of endpoint
+    shared_size: 1m #default 1m
+```
+
+Multi-Kubernetes service discovery does not fill default values for service and client fields, you need to fill them according to the cluster configuration.
+
+### Multi-Cluster Mode Query Interface
+
+The Kubernetes service discovery provides a query interface in accordance with the [_APISIX Discovery Specification_](https://github.com/apache/apisix/blob/master/docs/en/latest/discovery.md).
+
+**function:** \
+nodes(service_name)
+
+**description:** \
+nodes() function attempts to look up the ngx.shared.DICT for nodes corresponding to service_name, \
+service_name should match pattern: _[id]/[namespace]/[name]:[portName]_
+
++ id: value defined in service discovery configuration
+
++ namespace: The namespace where the Kubernetes endpoints is located
+
++ name: The name of the Kubernetes endpoints
+
++ portName: The ports.name value in the Kubernetes endpoints, if there is no ports.name, use targetPort, port instead
+
+**return value:** \
+if the Kubernetes endpoints value is as follows:
+
+  ```yaml
+  apiVersion: v1
+  kind: Endpoints
+  metadata:
+    name: plat-dev
+    namespace: default
+  subsets:
+    - addresses:
+        - ip: "10.5.10.109"
+        - ip: "10.5.10.110"
+      ports:
+        - port: 3306
+          name: port
+  ```
+
+a nodes("release/default/plat-dev:port") call will get follow result:
 
   ```
    {
@@ -167,13 +287,49 @@ the kubernetes service discovery provides a query interface in accordance with t
 ---
 
 > Q: APISIX inherits Nginx's multiple process model, does it mean that each nginx worker process will [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) kubernetes endpoints resources \
-> A: The kubernetes service discovery only uses privileged processes to [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) kubernetes endpoints resources, then store theirs value \
-> into ngx.shared.kubernetes, worker processes get results by querying ngx.shared.kubernetes
+> A: The Kubernetes service discovery only uses privileged processes to [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/) Kubernetes endpoints resources, then store theirs value \
+> into ngx.shared.DICT, worker processes get results by querying ngx.shared.DICT
 
 ---
 
+> Q: What permissions do [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) require \
+> A: ServiceAccount requires the permissions of cluster-level [ get, list, watch ] endpoints resources, the declarative definition is as follows:
+>
+>```yaml
+>kind: ServiceAccount
+>apiVersion: v1
+>metadata:
+> name: apisix-test
+> namespace: default
+>---
+>
+>kind: ClusterRole
+>apiVersion: rbac.authorization.k8s.io/v1
+>metadata:
+> name: apisix-test
+>rules:
+>- apiGroups: [ "" ]
+>  resources: [ endpoints ]
+>  verbs: [ get,list,watch ]
+>---
+>
+>apiVersion: rbac.authorization.k8s.io/v1
+>kind: ClusterRoleBinding
+>metadata:
+> name: apisix-test
+>roleRef:
+> apiGroup: rbac.authorization.k8s.io
+> kind: ClusterRole
+> name: apisix-test
+>subjects:
+> - kind: ServiceAccount
+>   name: apisix-test
+>   namespace: default
+>```
+
+---
 > Q: How to get [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) token value \
-> A: Assume your [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) located in namespace apisix and name is kubernetes-discovery, you can use the following steps to get token value
+> A: Assume your [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) located in namespace apisix and name is Kubernetes-discovery, you can use the following steps to get token value
 >
 > 1. Get secret name: \
 > you can execute the following command, the output of the first column is the secret name we want
diff --git a/docs/zh/latest/discovery/kubernetes.md b/docs/zh/latest/discovery/kubernetes.md
index 6e0f449f2..e1bc22122 100644
--- a/docs/zh/latest/discovery/kubernetes.md
+++ b/docs/zh/latest/discovery/kubernetes.md
@@ -23,13 +23,17 @@ title: Kubernetes
 
 ## 基于 Kubernetes 的服务发现
 
-Kubernetes 服务发现模块以 [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts) 方式监听 [_Kubernetes_](https://kubernetes.io) 集群 [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service) 资源的实时变化,
-并将其值存储到 ngx.shared.kubernetes 中 \
-模块同时遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供了节点查询接口
+Kubernetes 服务发现以 [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts) 方式监听 [_Kubernetes_](https://kubernetes.io) 集群 [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service) 资源的实时变化,并将其值存储到 ngx.shared.DICT 中。
 
-## Kubernetes 服务发现模块的配置
+同时遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供了节点查询接口。
 
-Kubernetes 服务发现模块的完整配置如下:
+## Kubernetes 服务发现的使用
+
+目前 Kubernetes 服务发现支持单集群和多集群模式,分别适用于待发现的服务分布在单个或多个 Kubernetes 的场景。
+
+### 单集群模式 Kubernetes 服务发现的配置格式
+
+单集群模式 Kubernetes 服务发现的完整配置如下:
 
 ```yaml
 discovery:
@@ -54,7 +58,7 @@ discovery:
 
     default_weight: 50 # weight assigned to each discovered endpoint. default 50, minimum 0
 
-    # kubernetes discovery plugin support use namespace_selector
+    # kubernetes discovery support namespace_selector
     # you can use one of [equal, not_equal, match, not_match] filter namespace
     namespace_selector:
       # only save endpoints with namespace equal default
@@ -73,20 +77,23 @@ discovery:
        #- default
        #- ^my-[a-z]+$
 
-    # kubernetes discovery plugin support use label_selector
+    # kubernetes discovery support label_selector
     # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
     label_selector: |-
       first="a",second="b"
+
+    # reserved lua shared memory size, 1m memory can store about 1000 pieces of endpoint
+    shared_size: 1m #default 1m
 ```
 
-如果 Kubernetes 服务发现模块运行在 Pod 内,你可以使用最简配置:
+如果 Kubernetes 服务发现运行在 Pod 内,你可以使用如下最简配置:
 
 ```yaml
 discovery:
   kubernetes: { }
 ```
 
-如果 Kubernetes 服务发现模块运行在 Pod 外,你需要新建或选取指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), 获取其 Token 值,然后使用如下配置:
+如果 Kubernetes 服务发现运行在 Pod 外,你需要新建或选取指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), 获取其 Token 值,然后使用如下配置:
 
 ```yaml
 discovery:
@@ -97,12 +104,12 @@ discovery:
       port: # enter apiServer port value here
     client:
       token: # enter serviceaccount token value here
-      #token_file: # enter file path here
+      #token_file: # enter token file path here
 ```
 
-## Kubernetes 服务发现模块的查询接口
+### 单集群模式 Kubernetes 服务发现的查询接口
 
-Kubernetes 服务发现模块遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供查询接口
+单集群模式 Kubernetes 服务发现遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供节点查询接口。
 
 **函数:**
 nodes(service_name)
@@ -114,7 +121,118 @@ service_name 必须满足格式: [namespace]/[name]:[portName]
 
 + name: Endpoints 的资源名
 
-+ portName: Endpoints 定义包含的 portName,如果 Endpoints 没有定义 portName,请使用 targetPort,Port 代替
++ portName: Endpoints 定义包含的 ports.name 值,如果 Endpoints 没有定义 ports.name,请依次使用 targetPort, port 代替
+
+**返回值:**
+以如下 Endpoints 为例:
+
+  ```yaml
+  apiVersion: v1
+  kind: Endpoints
+  metadata:
+    name: plat-dev
+    namespace: default
+  subsets:
+    - addresses:
+        - ip: "10.5.10.109"
+        - ip: "10.5.10.110"
+      ports:
+        - port: 3306
+          name: port
+  ```
+
+nodes("default/plat-dev:port") 调用会得到如下的返回值:
+
+  ```
+   {
+       {
+           host="10.5.10.109",
+           port= 3306,
+           weight= 50,
+       },
+       {
+           host="10.5.10.110",
+           port= 3306,
+           weight= 50,
+       },
+   }
+  ```
+
+### 多集群模式 Kubernetes 服务发现的配置格式
+
+多集群模式 Kubernetes 服务发现的完整配置如下:
+
+```yaml
+discovery:
+  kubernetes:
+  - id: release  # a custom name refer to the cluster, pattern ^[a-z0-9]{1,8}
+    service:
+      # apiserver schema, options [http, https]
+      schema: https #default https
+
+      # apiserver host, options [ipv4, ipv6, domain, environment variable]
+      host: "1.cluster.com"
+
+      # apiserver port, options [port number, environment variable]
+      port: "6443"
+
+    client:
+      # serviceaccount token or token_file
+      token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+
+      #token: |-
+       # eyJhbGciOiJSUzI1NiIsImtpZCI6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEif
+       # 6Ikx5ME1DNWdnbmhQNkZCNlZYMXBsT3pYU3BBS2swYzBPSkN3ZnBESGpkUEEifeyJhbGciOiJSUzI1NiIsImtpZCI
+
+    default_weight: 50 # weight assigned to each discovered endpoint. default 50, minimum 0
+
+    # kubernetes discovery support namespace_selector
+    # you can use one of [equal, not_equal, match, not_match] filter namespace
+    namespace_selector:
+      # only save endpoints with namespace equal default
+      equal: default
+
+      # only save endpoints with namespace not equal default
+      #not_equal: default
+
+      # only save endpoints with namespace match one of [default, ^my-[a-z]+$]
+      #match:
+       #- default
+       #- ^my-[a-z]+$
+
+      # only save endpoints with namespace not match one of [default, ^my-[a-z]+$]
+      #not_match:
+       #- default
+       #- ^my-[a-z]+$
+
+    # kubernetes discovery support label_selector
+    # for the expression of label_selector, please refer to https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
+    label_selector: |-
+      first="a",second="b"
+
+    # reserved lua shared memory size,1m memory can store about 1000 pieces of endpoint
+    shared_size: 1m #default 1m
+```
+
+多集群模式 Kubernetes 服务发现没有为 `service` 和 `client` 域填充默认值,你需要根据集群配置情况自行填充。
+
+### 多集群模式 Kubernetes 服务发现的查询接口
+
+多集群模式 Kubernetes 服务发现遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供节点查询接口。
+
+**函数:**
+nodes(service_name)
+
+**说明:**
+service_name 必须满足格式: [id]/[namespace]/[name]:[portName]
+
++ id: Kubernetes 服务发现配置中定义的集群 id 值
+
++ namespace: Endpoints 所在的命名空间
+
++ name: Endpoints 的资源名
+
++ portName: Endpoints 定义包含的 ports.name 值,如果 Endpoints 没有定义 ports.name,请依次使用 targetPort, port 代替
 
 **返回值:**
 以如下 Endpoints 为例:
@@ -131,9 +249,10 @@ service_name 必须满足格式: [namespace]/[name]:[portName]
         - ip: "10.5.10.110"
       ports:
         - port: 3306
+          name: port
   ```
 
-nodes("default/plat-dev:3306") 调用会得到如下的返回值:
+nodes("release/default/plat-dev:port") 调用会得到如下的返回值:
 
   ```
    {
@@ -165,13 +284,50 @@ nodes("default/plat-dev:3306") 调用会得到如下的返回值:
 ---
 
 > Q: APISIX 继承了 Nginx 的多进程模型,是否意味着每个 APISIX 工作进程都会监听 Kubernetes Endpoints \
-> A: Kubernetes 服务发现模块只使用特权进程监听 Kubernetes Endpoints,然后将其值存储\
-> 到 ngx.shared.kubernetes,工作进程通过查询 ngx.shared.kubernetes 来获取结果
+> A: Kubernetes 服务发现只使用特权进程监听 Kubernetes Endpoints,然后将其值存储\
+> 到 ngx.shared.DICT,工作进程通过查询 ngx.shared.DICT 来获取结果
+
+---
+
+> Q: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要的权限有哪些 \
+> A: [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 需要集群级 [ get,list,watch ] endpoints 资源的的权限,其声明式定义如下:
+>
+>```yaml
+>kind: ServiceAccount
+>apiVersion: v1
+>metadata:
+> name: apisix-test
+> namespace: default
+>---
+>
+>kind: ClusterRole
+>apiVersion: rbac.authorization.k8s.io/v1
+>metadata:
+> name: apisix-test
+>rules:
+>- apiGroups: [ "" ]
+>  resources: [ endpoints ]
+>  verbs: [ get,list,watch ]
+>---
+>
+>apiVersion: rbac.authorization.k8s.io/v1
+>kind: ClusterRoleBinding
+>metadata:
+> name: apisix-test
+>roleRef:
+> apiGroup: rbac.authorization.k8s.io
+> kind: ClusterRole
+> name: apisix-test
+>subjects:
+> - kind: ServiceAccount
+>   name: apisix-test
+>   namespace: default
+>```
 
 ---
 
-> Q: 怎样获取指定 ServiceAccount 的 Token 值 \
-> A: 假定你指定的 ServiceAccount 资源名为 “kubernetes-discovery“, 命名空间为 “apisix”, 请按如下步骤获取其 Token 值
+> Q: 怎样获取指定 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 的 Token 值 \
+> A: 假定你指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 资源名为 “kubernetes-discovery“, 命名空间为 “apisix”, 请按如下步骤获取其 Token 值
 >
 > 1. 获取 _Secret_ 资源名: \
      > 执行以下命令,输出的第一列内容就是目标 _Secret_ 资源名