Refactor: Polish 2.2.x governance doc

spring-cloud-alibaba-docs/src/main/asciidoc-zh/governance.adoc

@@ -9,17 +9,51 @@ image::pic/resource-transform.png[]
 
 Microservices Governance的规则转换模块会将不同控制面下发的规则进行统一的转换，目前支持将来自Istio，OpenSergo等控制面下发的规则统一转换为Spring Cloud Alibaba统一抽象出的数据结构以供后续使用
 
-如果在项目中使用Istio来实现规则转换，首先注意需要搭建一个Kubernetes集群，并且在其中部署Istio，具体参考 https://istio.io/latest/zh/docs/setup/install[Istio安装]。然后在需要接收到来自Istio规则的应用（一般为服务消费者）中添加如下starter依赖：
+如果在项目中使用 `Istio` 来实现规则转换，首先注意需要搭建一个Kubernetes集群，并且在其中部署Istio，具体参考 https://istio.io/latest/zh/docs/setup/install[Istio安装]。然后在需要接收到来自Istio规则的应用中添加如下starter依赖：
 [source,xml,indent=0]
 ----
 <dependency>
   <groupId>com.alibaba.cloud</groupId>
   <artifactId>spring-cloud-starter-xds-adapter</artifactId>
 </dependency>
 ----
-OpenSergo请参考 https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples]
+OpenSergo请参考 https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples]。
 
-之后，在application.yml配置文件中设置如下配置内容：
+其中，连接 `Istio` 控制面有如下两种手段：
+
+==== 注入pilot-agent(推荐)
+
+用户可以通过注入 `pilot-agent` 作为 `xds` 协议的代理，以轻松地对接到 `Istio` 控制平面，只需要在Spring Cloud Alibaba应用所在pod上加上如下 `annotation`：
+
+[source,yaml,indent=0]
+----
+template:
+    metadata:
+      annotations:
+        inject.istio.io/templates: grpc-agent
+        proxy.istio.io/config: '{"holdApplicationUntilProxyStarts": true}'
+----
+
+并且在 `application.yml` 中启用 `pilot-agent`：
+
+[source,yaml,indent=0]
+----
+server:
+  port: ${SERVER_PORT:80}
+spring:
+  cloud:
+    governance:
+      auth:
+        enabled: ${ISTIO_AUTH_ENABLE:true}
+    istio:
+      config:
+        enabled: ${ISTIO_CONFIG_ENABLE:true}
+        use-agent: ${USE_AGENT:true}
+----
+
+==== 直连Istio控制面
+
+用户如果想要本地调试治理模块的代码，则可以不注入 `pilot-agent` 直连 `Istio` 控制面。若不注入 `pilot-agent` 则用户需要在 `application.yml` 配置文件中设置如下配置内容：
 
 [source,yaml,indent=0]
 ----
@@ -35,10 +69,11 @@ spring:
         enabled: ${ISTIO_CONFIG_ENABLE:true}
         host: ${ISTIOD_ADDR:127.0.0.1}
         port: ${ISTIOD_PORT:15010}
-        polling-pool-size: ${POLLING_POOL_SIZE:10}
-        polling-time: ${POLLING_TIMEOUT:10}
+        pod-name: ${POD_NAME:auth-5ffd65b7b8-l8tpf}
+        namespace-name: ${NAMESPACE_NAME:default}
         istiod-token: ${ISTIOD_TOKEN:}
         log-xds: ${LOG_XDS:true}
+        use-agent: ${USE_AGENT:false}
 ----
 
 各字段的含义如下:
@@ -47,20 +82,42 @@ spring:
 |是否开启鉴权| spring.cloud.governance.auth.enabled|true|
 |是否连接Istio获取鉴权配置| spring.cloud.istio.config.enabled|true|
 |Istiod的地址| spring.cloud.istio.config.host|127.0.0.1|
-|Istiod的端口| spring.cloud.istio.config.port|15012|注：连接15010端口无需TLS，连接15012端口需TLS认证
-|应用从Istio拉取配置的线程池大小| spring.cloud.istio.config.polling-pool-size|10|
-|应用从Istio拉取配置的间隔时间| spring.cloud.istio.config.polling-time|30|单位为秒
-|连接Istio 15012端口时使用的JWT token| spring.cloud.istio.config.istiod-token|应用所在pod的 `/var/run/secrets/tokens/istio-token` 文件的内容|
+|Istiod的端口| spring.cloud.istio.config.port|15012|注：连接15010端口无需TLS，连接15012端口需认证
+|应用所处k8s pod名| spring.cloud.istio.config.pod-name|POD_NAME环境变量的值|
+|应用所处k8s namespace| spring.cloud.istio.config.namespace-name|NAMESPACE_NAME环境变量的值|
+|连接Istio 15012端口时使用的JWT token| spring.cloud.istio.config.istiod-token|应用所在pod的 `/var/run/secrets/tokens/istio-token` 文件的内容(暂时只支持third-part jwt, 后续也会支持first-part jwt)|
 |是否打印xDS相关日志| spring.cloud.istio.config.log-xds|true|
+|是否注入pilot-agent| spring.cloud.istio.config.use-agent|false|
 |===
+其中，若要在直连istio控制面时连接istio控制面的15012端口，需要将此应用的 `serviceaccount` 作为 `projected volumn` 挂载到k8s的 `/var/run/secrets/tokens/istio-token` 路径上，具体操作如下：
 
-注意，应用运行在K8s环境中，在非默认命名空间下的应用，需要接收Istiod下发的规则，需要将运行的应用K8s的元信息注入以下环境变量中，具体操作方式可参考 https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information[Kubernetes文档]:
+1.为Spring Cloud Alibaba应用所在pod声明一个 `projected volumn`：
 
-|===
-|环境变量名|K8s pod metadata name
-|POD_NAME|metadata.name
-|NAMESPACE_NAME|metadata.namespace
-|===
+[source,yaml,indent=0]
+----
+spec:
+  volumes:
+    - name: istio-token
+      projected:
+        defaultMode: 420
+        sources:
+          - serviceAccountToken:
+              audience: istio-ca
+              expirationSeconds: 43200
+              path: istio-token
+----
+
+2.将这个 `projected volumn` 挂载到 `/var/run/secrets/tokens/istio-token` 路径上：
+
+[source,yaml,indent=0]
+----
+spec:
+  containers:
+    volumeMounts:
+      - mountPath: /var/run/secrets/tokens
+        name: istio-token
+----
+在本地进行调试时，如果您想模拟其他工作负载的身份，可以在 `application.yml` 的 `istio-token` 字段中直接填入其他工作负载的token。
 
 === 路由
 

spring-cloud-alibaba-docs/src/main/asciidoc/governance.adoc

@@ -10,17 +10,51 @@ image::pic/resource-transform.png[]
 
 The resource-transform adapter of Microservices Governance will uniformly transform the rules published by different control planes, like Istio and OperSergo, into the unified abstract data structure of Spring Cloud Alibaba for subsequent use.
 
-If you use Istio in your project to transform the rule, first of all, note that you need to build a Kubernetes cluster and deploy Istio in it. For details, refer to https://istio.io/latest/zh/docs/setup/install[Istio installation], you need to add a following starter dependency application(Generally added to service consumer application):
+If you use Istio in your project to transform the rule, first of all, note that you need to build a Kubernetes cluster and deploy Istio in it. For details, refer to https://istio.io/latest/zh/docs/setup/install[Istio installation], you need to add a following starter dependency application:
 [source,xml,indent=0]
 ----
 <dependency>
   <groupId>com.alibaba.cloud</groupId>
   <artifactId>spring-cloud-starter-xds-adapter</artifactId>
 </dependency>
 ----
-If you want to use OpenSergo, you can refer to https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples]
+If you want to use OpenSergo, you can refer to https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples].
 
-After that, configure the following configuration in the application.yml:
+There are two ways to connect to `Istio` control plane:
+
+==== Inject pilot-agent(recommend)
+
+Users can easily connect to the `Istio` control plane by injecting pilot-agent as a proxy for the xds protocol, simply by adding the following annotation to the pod of Spring Cloud Alibaba workload:
+
+[source,yaml,indent=0]
+----
+template:
+    metadata:
+      annotations:
+        inject.istio.io/templates: grpc-agent
+        proxy.istio.io/config: '{"holdApplicationUntilProxyStarts": true}'
+----
+
+And enable `pilot-agent` in `application.yml`:
+
+[source,yaml,indent=0]
+----
+server:
+  port: ${SERVER_PORT:80}
+spring:
+  cloud:
+    governance:
+      auth:
+        enabled: ${ISTIO_AUTH_ENABLE:true}
+    istio:
+      config:
+        enabled: ${ISTIO_CONFIG_ENABLE:true}
+        use-agent: ${USE_AGENT:true}
+----
+
+==== Connect to istio control plane directly
+
+Users who want to debug the code of the governance module locally can directly connect to the `Istio` control plane without injecting the pilot-agent. If `pilot-agent` is not injected, the user needs to set the following configuration contents in the `application.yml` configuration file:
 
 [source,yaml,indent=0]
 ----
@@ -36,10 +70,11 @@ spring:
         enabled: ${ISTIO_CONFIG_ENABLE:true}
         host: ${ISTIOD_ADDR:127.0.0.1}
         port: ${ISTIOD_PORT:15010}
-        polling-pool-size: ${POLLING_POOL_SIZE:10}
-        polling-time: ${POLLING_TIMEOUT:10}
+        pod-name: ${POD_NAME:auth-5ffd65b7b8-l8tpf}
+        namespace-name: ${NAMESPACE_NAME:default}
         istiod-token: ${ISTIOD_TOKEN:}
         log-xds: ${LOG_XDS:true}
+        use-agent: ${USE_AGENT:false}
 ----
 
 Here's an explanation of each field:
@@ -49,19 +84,40 @@ Here's an explanation of each field:
 |Whether to connect to Istio to obtain authentication configuration| spring.cloud.istio.config.enabled|true|
 |Host of Istiod| spring.cloud.istio.config.host|127.0.0.1|
 |Port of Istiod| spring.cloud.istio.config.port|15012|15010 port does not need TLS，but 15012 does
-|Thread pool size for application to pull the config| spring.cloud.istio.config.polling-pool-size|10|
-|Time interval for application to pull the config| spring.cloud.istio.config.polling-time|30|The unit is second
-|JWT token for application to connect to 15012 port| spring.cloud.istio.config.istiod-token|Content of file `/var/run/secrets/tokens/istio-token` in the pod of application|
+|Pod name| spring.cloud.istio.config.pod-name|value of environment variable POD_NAME|
+|Namespace name| spring.cloud.istio.config.namespace-name|value of environment variable NAMESPACE_NAME|
+|JWT token for application to connect to 15012 port| spring.cloud.istio.config.istiod-token|Content of file `/var/run/secrets/tokens/istio-token` in the pod of application.(Only support third-part-jwt now, first-part-jwt will be supported later)|
 |Whether to print logs about xDS| spring.cloud.istio.config.log-xds|true|
+|Whether to inject pilot-agent| spring.cloud.istio.config.use-agent|false|
 |===
 
-Note that the application runs in the K8s environment, and the application in the non-default namespace needs to receive the rules issued by Istiod, and needs to inject the meta information of the running application Kubernetes into the following environment variables. For the specific operation method, please refer to https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information[Kubernetes documentation]
+If you want to connect to port 15012 of the `Istio` control plane when directly connecting the istio control plane, you need to apply `serviceaccount` as `projected volumn` mount to k8s path `/ var/run/secrets/tokens/istio-token`:
 
-|===
-|Environment variable name|K8s pod metadata name
-|POD_NAME|metadata.name
-|NAMESPACE_NAME|metadata.namespace
-|===
+1.Apply a `projected volumn` for the pod of Spring Cloud Alibaba workload:
+[source,yaml,indent=0]
+----
+spec:
+  volumes:
+    - name: istio-token
+      projected:
+        defaultMode: 420
+        sources:
+          - serviceAccountToken:
+              audience: istio-ca
+              expirationSeconds: 43200
+              path: istio-token
+----
+
+2.Mount the `projected volumn` to path `/var/run/secrets/tokens/istio-token`:
+[source,yaml,indent=0]
+----
+spec:
+  containers:
+    volumeMounts:
+      - mountPath: /var/run/secrets/tokens
+        name: istio-token
+----
+If you want to emulate the identity of other workloads when debugging locally, you can fill the `istio-token` field of `application.yml` with the tokens of other workloads.
 
 === Routing
 ==== Component support description

spring-cloud-alibaba-examples/governance-example/authentication-example/readme-zh.md

@@ -29,8 +29,8 @@
     <artifactId>spring-cloud-starter-xds-adapter</artifactId>
 </dependency>
 ```
-2. 在应用的 `src/main/resources/application.yml` 配置文件中配置Istio相关元数据:
-
+2. 参照[文档](https://github.com/alibaba/spring-cloud-alibaba/blob/2.2.x/spring-cloud-alibaba-docs/src/main/asciidoc-zh/governance.adoc)，实现与`Istio`控制面的对接
+并在`application.yml`中打开鉴权开关：
 ```yml
 server:
   port: ${SERVER_PORT:80}
@@ -39,35 +39,7 @@ spring:
     governance:
       auth:
         enabled: ${ISTIO_AUTH_ENABLE:true}
-    istio:
-      config:
-        enabled: ${ISTIO_CONFIG_ENABLE:true}
-        host: ${ISTIOD_ADDR:127.0.0.1}
-        port: ${ISTIOD_PORT:15010}
-        polling-pool-size: ${POLLING_POOL_SIZE:10}
-        polling-time: ${POLLING_TIMEOUT:10}
-        istiod-token: ${ISTIOD_TOKEN:}
-        log-xds: ${LOG_XDS:true}
-```
-下面解释一下各字段的含义:
-|配置项|key|默认值|说明
-|--|--|--|--|
-|是否开启鉴权| spring.cloud.governance.auth.enabled|true|
-|是否连接Istio获取鉴权配置| spring.cloud.istio.config.enabled|true|
-|Istiod的地址| spring.cloud.istio.config.host|127.0.0.1|
-|Istiod的端口| spring.cloud.istio.config.port|15012|注：连接15010端口无需TLS，连接15012端口需TLS认证|
-|SCA去Istio拉取配置的线程池大小| spring.cloud.istio.config.polling-pool-size|10|
-|SCA去Istio拉取配置的间隔时间| spring.cloud.istio.config.polling-time|30|单位为秒
-|连接Istio<br>15012端口时使用的JWT token| spring.cloud.istio.config.istiod-token|应用所在pod的`/var/run/secrets/tokens/istio-token`文件的内容|
-|是否打印xDS相关日志| spring.cloud.istio.config.log-xds|true|
-### 运行应用
-注意，应用运行在K8s环境中，在非默认命名空间下的应用，需要接收Istiod下发的规则，需要将运行的应用K8s的元信息注入以下环境变量中，具体操作方式可参考 [Kubernetes文档](https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information)
-|环境变量名|K8s pod metadata name|
-|--|--|
-|POD_NAME|metadata.name|
-|NAMESPACE_NAME|metadata.namespace|
-
-**注：您部署的应用所在的pod不需要被Istio执行自动注入，因为SCA的各个治理模块将会被用来替代Envoy Proxy的各种功能。**
+```
 ### 效果演示
 下面给出几个简单的鉴权规则配置的示例:
 #### IP黑白名单

spring-cloud-alibaba-examples/governance-example/authentication-example/readme.md

@@ -29,37 +29,17 @@ Before launching the example for demonstration, let's look at how a Spring Cloud
     <artifactId>spring-cloud-starter-xds-adapter</artifactId>
 </dependency>
 ```
-2. Configure Istio related metadata in the `src/main/resources/application` yml configuration file:
-
+2. Connect to `Istio` control plane according to [doc](https://github.com/alibaba/spring-cloud-alibaba/blob/2.2.x/spring-cloud-alibaba-docs/src/main/asciidoc/governance.adoc),
+   and set default route algorithm in `application.yml`.
 ```yml
 server:
-  port: ${SERVER_PORT:80}
+   port: ${SERVER_PORT:80}
 spring:
-  cloud:
-    governance:
-      auth:
-        enabled: ${ISTIO_AUTH_ENABLE:true}
-    istio:
-      config:
-        enabled: ${ISTIO_CONFIG_ENABLE:true}
-        host: ${ISTIOD_ADDR:127.0.0.1}
-        port: ${ISTIOD_PORT:15010}
-        polling-pool-size: ${POLLING_POOL_SIZE:10}
-        polling-time: ${POLLING_TIMEOUT:10}
-        istiod-token: ${ISTIOD_TOKEN:}
-        log-xds: ${LOG_XDS:true}
-```
-Here's an explanation of each field:
-|Configuration Item|key|Default Value|Description
-|--|--|--|--|
-|Whether to enable authentication| spring.cloud.governance.auth.enabled|true|
-|Whether to connect to Istio to obtain authentication configuration| spring.cloud.istio.config.enabled|true|
-|Host of Istiod| spring.cloud.istio.config.host|127.0.0.1|
-|Port of Istiod| spring.cloud.istio.config.port|15012|15010 port does not need TLS，but 15012 does
-|Thread pool size for application to pull the config| spring.cloud.istio.config.polling-pool-size|10|
-|Time interval for application to pull the config| spring.cloud.istio.config.polling-time|30|The unit is second|
-|JWT token for application to connect to 15012 port| spring.cloud.istio.config.istiod-token|Content of file `/var/run/secrets/tokens/istio-token` in the pod of application|
-|Whether to print logs about xDS| spring.cloud.istio.config.log-xds|true|
+   cloud:
+      governance:
+         auth:
+            enabled: ${ISTIO_AUTH_ENABLE:true}
+```
 
 ### Run the application
 Note that the application runs in the K8s environment, and the application in the non-default namespace needs to receive the rules issued by Istiod, and needs to inject the meta information of the running application Kubernetes into the following environment variables. For the specific operation method, please refer to [Kubernetes documentation](https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information):