zh:sync sidecar-injection (#2806)

content_zh/docs/setup/kubernetes/sidecar-injection/index.md

@@ -1,17 +1,21 @@
 ---
 title: 注入 Istio sidecar
 description: 介绍两种将 Istio sidecar 注入应用 Pod 的方法：使用 Sidecar 注入 Webhook 自动完成，或使用 istioctl 客户端工具手工完成。
-weight: 50
+weight: 30
 keywords: [kubernetes,sidecar,注入]
 ---
 
 ## 注入
 
-手工注入过程会修改控制器（例如 Deployment）的配置。这种注入方法通过修改 Pod template 的手段，把 Sidecar 注入到目标控制器生成的所有 Pod 之中。要加入、更新或者移除 Sidecar，就需要修改整个控制器。
+网格中的每个 Pod 都必须伴随一个 Istio 兼容的 Sidecar 一同运行。
+
+下文中将会介绍两种把 Sidecar 注入到 Pod 中的方法：使用 `istioctl` 客户端工具进行注入，或者使用 Istio sidecar injector 自动完成注入过程。
+
+手工注入过程会修改控制器（例如 Deployment）的配置。这种注入方法会修改 Pod template，把 Sidecar 注入到目标控制器生成的所有 Pod 之中。要加入、更新或者移除 Sidecar，就需要修改整个控制器。
 
 自动注入过程会在 Pod 的生成过程中进行注入，这种方法不会更改控制器的配置。手工删除 Pod 或者使用滚动更新都可以选择性的对 Sidecar 进行更新。
 
-手工或自动注入都会从 `istio-system` 命名空间的 `istio-sidecar-injector` 以及 `istio` ConfigMap 中获取配置信息。手工注入方式还可以从本地文件中读取配置。
+手工或自动注入都会从 `istio-system` 命名空间的 `istio-sidecar-injector` 以及 `istio` ConfigMap 中获取配置信息。手工注入方式还可以选择从本地文件中读取配置。
 
 ### 手工注入 Sidecar
 
@@ -23,7 +27,7 @@ $ istioctl kube-inject -f @samples/sleep/sleep.yaml@ | kubectl apply -f -
 
 此外还可以使用本地的配置信息来进行注入。
 
-> `kube-inject` 操作不具备幂等性，因此 `istioctl kube-inject` 的输出内容是无法再次进行注入的。要进行更新的话，建议保留原本的未经注入的 `yaml` 文件，这样数据平面的 Sidecar 就可以被更新了。
+> `istioctl kube-inject` 操作不具备幂等性，因此 `istioctl kube-inject` 的输出内容是无法再次进行注入的。要对手工注入的工作负载进行更新，建议保留原本的未经注入的 `yaml` 文件，这样数据平面的 Sidecar 就可以被更新了。
 
 {{< text bash >}}
 $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml
@@ -36,8 +40,9 @@ $ kubectl -n istio-system get configmap istio -o=jsonpath='{.data.mesh}' > mesh-
 $ istioctl kube-inject \
     --injectConfigFile inject-config.yaml \
     --meshConfigFile mesh-config.yaml \
-    --filename samples/sleep/sleep.yaml \
+    --filename @samples/sleep/sleep.yaml@ \
-    --output sleep-injected.yaml | kubectl apply -f -
+    --output sleep-injected.yaml
+$ kubectl apply -f sleep-injected.yaml
 {{< /text >}}
 
 检查被注入到 Deployment 中的 Sidecar：
@@ -64,7 +69,7 @@ admissionregistration.k8s.io/v1beta1
 
 #### Webhook 的禁用或升级
 
-缺省情况下，用于 Sidecar 注入的 Webhook 是启用的。如果想要禁用它，可以用 [Helm](/zh/docs/setup/kubernetes/helm-install/) ，将 `sidecarInjectorWebhook.enabled` 参数设为 `false`，生成一个 `istio.yaml` 进行更新。也就是：
+缺省情况下，用于 Sidecar 注入的 Webhook 是启用的。如果想要禁用它，可以用 [Helm](/zh/docs/setup/kubernetes/helm-install/)，将 `sidecarInjectorWebhook.enabled` 参数设为 `false`，生成一个 `istio.yaml` 进行更新。也就是：
 
 {{< text bash >}}
 $ helm template --namespace=istio-system --set sidecarInjectorWebhook.enabled=false install/kubernetes/helm/istio > istio.yaml
@@ -72,14 +77,14 @@ $ kubectl create ns istio-system
 $ kubectl apply -n istio-system -f istio.yaml
 {{< /text >}}
 
-另外这个 Webhook 在 `values.yaml` 中还有一些其他的配置参数。可以覆盖这些缺省值来对安装过程进行定义。
+另外这个 Webhook 在 `values.yaml` 中还有一些其它的配置参数。可以覆盖这些缺省值来对安装过程进行定义。
 
 #### 应用部署
 
 部署 `sleep` 应用，检查一下是不是只产生了一个容器。
 
 {{< text bash >}}
-$ kubectl apply -f samples/sleep/sleep.yaml
+$ kubectl apply -f @samples/sleep/sleep.yaml@
 $ kubectl get deployment -o wide
 NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE       CONTAINERS   IMAGES       SELECTOR
 sleep     1         1         1            1           12m       sleep        tutum/curl   app=sleep
@@ -138,7 +143,7 @@ sleep-776b7bcdcd-gmvnr   1/1       Running       0          2s
 
 `istio-system` 命名空间中的 ConfigMap `istio-sidecar-injector` 中包含了缺省的注入策略以及 Sidecar 的注入模板。
 
-##### **策略**
+##### **policy**
 
 `disabled` - Sidecar 注入器缺省不会向 Pod 进行注入。在 Pod 模板中加入 `sidecar.istio.io/inject` 注解并赋值为 `true` 才能覆盖缺省值并启用注入。
 
@@ -163,7 +168,7 @@ spec:
         command: ["/bin/sleep","infinity"]
 {{< /text >}}
 
-##### **模板**
+##### **template**
 
 Sidecar 注入模板使用的是 [golang 模板](https://golang.org/pkg/text/template)，当解析和执行时，会解码为下面的结构，其中包含了将要注入到 Pod 中的容器和卷。
 
@@ -182,8 +187,8 @@ type SidecarInjectionSpec struct {
 type SidecarTemplateData struct {
     ObjectMeta  *metav1.ObjectMeta
     Spec        *v1.PodSpec
-    ProxyConfig *meshconfig.ProxyConfig  // 定义来自于 https://istio.io/docs/reference/config/service-mesh.html#proxyconfig
+    ProxyConfig *meshconfig.ProxyConfig  // 定义来自于https://istio.io/docs/reference/config/service-mesh.html#proxyconfig
-    MeshConfig  *meshconfig.MeshConfig   // 定义来自于  https://istio.io/docs/reference/config/service-mesh.html#meshconfig
+    MeshConfig  *meshconfig.MeshConfig   // 定义来自于 https://istio.io/docs/reference/config/service-mesh.html#meshconfig
 }
 {{< /text >}}
 
@@ -227,6 +232,42 @@ containers:
   - sleep
 {{< /text >}}
 
+#### 更多控制：加入例外
+
+有时用户不具备控制 Pod 创建过程的能力，例如其他人创建了 Pod。这样一来就无法将注解 `sidecar.istio.io/inject` 加入 Pod，也就不能显式的控制是否进行 Sidecar 的注入了。
+
+设想一下一些中间步骤中的辅助性 Pod，例如用于将源码构建为应用程序的 [OpenShift Builds](https://docs.okd.io/latest/dev_guide/builds/index.html)。二进制交付物构建成功之后，应用程序准备就绪，中间 Pod 就可以删除了。显而易见，即使注入策略被设置为 `enabled` 并且所在命名空间被正确的标记为进行自动注入的情况下，这种中间 Pod 也是不该注入 Sidecar 的。
+
+这种情况下可以设置 Istio **不要对这些 Pod 进行注入**，这种设置也是通过标签来进行的。要编辑 `istio-sidecar-injector` ConfigMap，加入 `neverInjectSelector` 条目，这一条目的取值是一个 Kubernetes 标签选择器的数组，数组各个判断之间是逻辑或的关系，首次匹配之后就会停止后面的匹配，来看一个例子：
+
+{{< text yaml >}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: istio-sidecar-injector
+data:
+  config: |-
+    policy: enabled
+    neverInjectSelector:
+      - matchExpressions:
+        - {key: openshift.io/build.name, operator: Exists}
+      - matchExpressions:
+        - {key: openshift.io/deployer-pod-for.name, operator: Exists}
+    template: |-
+      initContainers:
+...
+{{< /text >}}
+
+上面配置的含义：如果 Pod 包含标签 `openshift.io/build.name` **或者** `openshift.io/deployer-pod-for.name`，并且不论标签的值是什么，正如前面提到的 OpenShift Builds 的 Pod 一样，这种 Pod 不会进行 Sidecar 注入（源码到镜像的过程中使用的辅助 Pod 就包含了这些标签）。
+
+为了完整起见，还可以使用一个 `alwaysInjectSelector` 字段，这个字段的语法和前面的类似，功能是对符合标签选择器条件的 Pod 进行注入，这一决策不受全局策略的影响。
+
+这里用到的标签选择器方式，给实际工作中的例外场景带来了很多弹性。参看 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements)，可以更好的使用这一特性。
+
+Pod 注解的优先级是高于标签选择器的，所以具体的注入评估顺序是：
+
+> `Pod Annotations → NeverInjectSelector → AlwaysInjectSelector → Default Policy`
+
 #### 删除 Sidecar 注入器
 
 {{< text bash >}}