en: add admission webhook document (pingcap#113)

* add admission webhook document * address comments * change unordered lists in zh and en docs Co-authored-by: Ran <[email protected]>
zhenjiaogao · Mar 31, 2020 · d1fba06 · d1fba06
1 parent bb6a746
commit d1fba06
Show file tree

Hide file tree

Showing 5 changed files with 137 additions and 8 deletions.
diff --git a/en/TOC.md b/en/TOC.md
@@ -43,6 +43,7 @@
   - [Collect TiDB Logs](collect-tidb-logs.md)
   - [Maintain TiDB Binlog](maintain-tidb-binlog.md)
   - [Enable Automatic Failover](use-auto-failover.md)
+  - [Enable Admission Controller](enable-admission-webhook.md)
 + Scale
   - [Scale](scale-a-tidb-cluster.md)
   - [Enable Auto-scaling](enable-tidb-cluster-auto-scaling.md)

diff --git a/en/enable-admission-webhook.md b/en/enable-admission-webhook.md
@@ -0,0 +1,124 @@
+---
+title: Enable Admission Controller in TiDB Operator
+summary: Learn how to enable the admission controller in TiDB Operator and the functionality of the admission controller.
+category: how-to
+---
+
+# Enable Admission Controller in TiDB Operator
+
+Kubernetes v1.9 introduces the [dynamic admission control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) to modify and validate resources. TiDB Operator also supports the dynamic admission control to modify, validate, and maintain resources. This document describes how to enable the admission controller and introduces the functionality of the admission controller.
+
+## Enable the admission controller
+
+With a default installation, TiDB Operator disables the admission controller. Take the following steps to manually turn it on.
+
+1. Edit the `values.yaml` file in TiDB Operator.
+
+    Enable the `Operator Webhook` feature:
+
+    ```yaml
+    admissionWebhook:
+      create: true
+    ```
+
+2. Configure the failure policy.
+
+    Prior to Kubernetes v1.15, the management mechanism of the dynamic admission control is coarser-grained and is inconvenient to use. To prevent the impact of the dynamic admission control on the global cluster, you need to configure the [Failure Policy](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#failure-policy).
+
+    * For Kubernetes versions earlier than v1.15, it is recommended to set the `failurePolicy` of TiDB Operator to `Ignore`. This avoids the influence on the global cluster in case of `admission webhook` exception in TiDB Operator .
+
+        ```yaml
+        ......
+        failurePolicy:
+            validation: Ignore
+            mutation: Ignore
+        ```
+
+    * For Kubernetes v1.15 and later versions, it is recommended to set the `failurePolicy` of TiDB Operator to `Failure`. The exception occurs in `admission webhook` does not effect the whole cluster, because the dynamic admission control supports the label-based filtering mechanism.
+
+        ```yaml
+        ......
+        failurePolicy:
+            validation: Failure
+            mutation: Failure
+        ```
+
+3. Install or update TiDB Operator.
+
+    To install or update TiDB Operator, see [Deploy TiDB Operator in Kubernetes](deploy-tidb-operator.md).
+
+## Functionality of admission controller
+
+TiDB Operator implements many functions using the admission controller. This section introduces the admission controller for each resource and its corresponding functions.
+
+* Admission controller for Pod validation
+
+    The admission controller for Pod validation guarantees the safe logon and safe logoff of the PD/TiKV/TiDB component. You can [restart a TiDB cluster in Kubernetes](restart-a-tidb-cluster.md) using this controller. The component is enabled by default if the admission controller is enabled.
+
+    ```yaml
+    admissionWebhook:
+      validation:
+        pods: true
+    ```
+
+* Admission controller for StatefulSet validation
+
+    The admission controller for StatefulSet validation supports the gated launch of the TiDB/TiKV component in a TiDB cluster. The component is disabled by default if the admission controller is enabled.
+
+    ```yaml
+    admissionWebhook:
+      validation:
+        statefulSets: false
+    ```
+
+    You can control the gated launch of the TiDB/TiKV component in a TiDB cluster through two annotations, `tidb.pingcap.com/tikv-partition` and `tidb.pingcap.com/tidb-partition`. To set the gated launch of the TiKV component in a TiDB cluster, execute the following commands. The effect of `partition=2` is the same as that of [StatefulSet Partitions](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#partitions).
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    kubectl annotate tidbcluster <name> -n <namespace> tidb.pingcap.com/tikv-partition=2 &&
+    tidbcluster.pingcap.com/<name> annotated
+    ```
+
+    Execute the following commands to unset the gated launch:
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    kubectl annotate tidbcluster <name> -n <namespace> tidb.pingcap.com/tikv-partition- &&
+    tidbcluster.pingcap.com/<name> annotated
+    ```
+
+    This also applies to the TiDB component.
+
+* Admission controller for TiDB Operator resources validation
+
+    The admission controller for TiDB Operator resources validation supports validating customized resources such as `TidbCluster` and `TidbMonitor` in TiDB Operator. The component is disabled by default if the admission controller is enabled.
+
+    ```yaml
+    admissionWebhook:
+      validation:
+        pingcapResources: false
+    ```
+
+    For example, regarding `TidbCluster` resources, the admission controller for TiDB Operator resources validation checks the required fields of the `spec` field. When you create or update `TidbCluster`, if the check is not passed (for example, neither of the `spec.pd.image` filed and the `spec.pd.baseImage` field are defined), this admission controller refuses the request.
+
+* Admission controller for Pod modification
+
+    The admission controller for Pod modification supports the hotspot scheduling of TiKV in the auto-scaling scenario. To [enable TidbCluster auto-scaling](enable-tidb-cluster-auto-scaling.md), you need to enable this controller. The component is enabled by default if the admission controller is enabled.
+
+    ```yaml
+    admissionWebhook:
+      mutation:
+        pods: true
+    ```
+
+* Admission controller for TiDB Operator resources modification
+
+    The admission controller for TiDB Operator resources modification supports filling in the default values of customized resources, such as `TidbCluster` and `TidbMonitor` in TiDB Operator. The component is enabled by default if the admission controller is enabled.
+
+    ```yaml
+    admissionWebhook:
+      mutation:
+        pingcapResources: true
+    ```
diff --git a/en/enable-tidb-cluster-auto-scaling.md b/en/enable-tidb-cluster-auto-scaling.md
@@ -35,6 +35,8 @@ To turn this feature on, you need to enable some related configurations in TiDB
         pods: true
     ```
 
+    For more information about `Operator Webhook`, see [Enable Admission Controller in TiDB Operator](enable-admission-webhook.md).
+
 2. Install or update TiDB Operator.
 
     To install or update TiDB Operator, see [Deploy TiDB Operator in Kubernetes](deploy-tidb-operator.md).

diff --git a/en/restart-a-tidb-cluster.md b/en/restart-a-tidb-cluster.md
@@ -25,6 +25,8 @@ To activate the graceful logoff feature, you need to enable some related configu
       create: true
     ```
 
+    For more information about `Operator Webhook`, see [Enable Admission Controller in TiDB Operator](enable-admission-webhook.md).
+
 2. Install or update TiDB Operator.
 
     To install or update TiDB Operator, see [Deploy TiDB Operator in Kubernetes](deploy-tidb-operator.md).

diff --git a/zh/enable-admission-webhook.md b/zh/enable-admission-webhook.md
@@ -1,6 +1,6 @@
 ---
 title: 开启 TiDB Operator 准入控制器
-summary: 介绍如何开启 TiDB Operator 准入控制器以及它的作用
+summary: 介绍如何开启 TiDB Operator 准入控制器以及它的作用。
 category: how-to
 ---
 
@@ -45,13 +45,13 @@ TiDB Operator 在默认安装情况下不会开启准入控制器，你需要手
 
 3. 安装/更新 TiDB Operator
 
-    修改完 `values.yaml` 文件中的上述配置项以后，进行 TiDB Operator 部署或者更新。安装与更新 TiDB Operator 请参考[在 Kubernetes 上部署 TiDB Operator](deploy-tidb-operator.md)。 
+    修改完 `values.yaml` 文件中的上述配置项以后，进行 TiDB Operator 部署或者更新。安装与更新 TiDB Operator 请参考[在 Kubernetes 上部署 TiDB Operator](deploy-tidb-operator.md)。
 
 ## TiDB Operator 准入控制器功能
 
 TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在这里介绍各个资源的准入控制器与其相对应的功能。
 
-1. Pod 验证准入控制器:
+* Pod 验证准入控制器:
 
     Pod 准入控制器提供了对 PD/TiKV/TiDB 组件安全下线与安全上线的保证，通过 Pod 验证准入控制器，我们可以实现[重启 Kubernetes 上的 TiDB 集群](restart-a-tidb-cluster.md)。该组件在准入控制器开启的情况下默认开启。
 
@@ -61,7 +61,7 @@ TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在
         pods: true
     ```
 
-2. StatefulSet 验证准入控制器:
+* StatefulSet 验证准入控制器:
 
     StatefulSet 验证准入控制器帮助实现 TiDB 集群中 TiDB/TiKV 组件的灰度发布，该组件在准入控制器开启的情况下默认关闭。
 
@@ -74,7 +74,7 @@ TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在
     通过 `tidb.pingcap.com/tikv-partition` 和 `tidb.pingcap.com/tidb-partition` 这两个 annotation, 你可以控制 TiDB 集群中 TiDB 与 TiKV 组件的灰度发布。你可以通过以下方式对 TiDB 集群的 TiKV 组件设置灰度发布，其中 `partition=2` 的效果等同于 [StatefulSet 分区](https://kubernetes.io/zh/docs/concepts/workloads/controllers/statefulset/#%E5%88%86%E5%8C%BA)
 
     {{< copyable "shell-regular" >}}
-    
+
     ```shell
     $  kubectl annotate tidbcluster <name> -n <namespace> tidb.pingcap.com/tikv-partition=2 
     tidbcluster.pingcap.com/<name> annotated
@@ -91,7 +91,7 @@ TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在
 
     以上设置同样适用于 TiDB 组件。
 
-3. TiDB Operator 资源验证准入控制器:
+* TiDB Operator 资源验证准入控制器:
 
     TiDB Operator 资源验证准入控制器帮助实现针对 `TidbCluster`、`TidbMonitor` 等 TiDB Operator 自定义资源的验证，该组件在准入控制器开启的情况下默认关闭。
 
@@ -103,7 +103,7 @@ TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在
 
     举个例子，对于 `TidbCluster` 资源，TiDB Operator 资源验证准入控制器将会检查其 `spec` 字段中的必要字段。如果在 `TidbCluster` 创建或者更新时发现检查不通过，比如同时没有定义 `spec.pd.image` 或者 `spec.pd.baseImage` 字段，TiDB Operator 资源验证准入控制器将会拒绝这个请求。
 
-4. Pod 修改准入控制器:
+* Pod 修改准入控制器:
 
     Pod 修改准入控制器帮助我们在弹性伸缩场景下实现 TiKV 的热点调度功能，在[启用 TidbCluster 弹性伸缩](enable-tidb-cluster-auto-scaling.md)中需要开启该控制器。该组件在准入控制器开启的情况下默认开启。
 
@@ -113,7 +113,7 @@ TiDB Operator 通过准入控制器的帮助实现了许多功能。我们将在
         pods: true
     ```
 
-5. TiDB Operator 资源修改准入控制器:
+* TiDB Operator 资源修改准入控制器:
 
     TiDB Operator 资源修改准入控制器帮助我们实现 TiDB Operator 相关自定义资源的默认值填充工作，如 `TidbCluster`，`TidbMonitor` 等。该组件在准入控制器开启的情况下默认开启。