en, zh: add docs of topology spread constraints and security context (#…

…1184)
pingcap · Apr 29, 2021 · 185d28f · 185d28f
1 parent 37597d7
commit 185d28f
Show file tree

Hide file tree

Showing 12 changed files with 290 additions and 2 deletions.
diff --git a/en/TOC.md b/en/TOC.md
@@ -39,6 +39,7 @@
   - [Enable TLS between TiDB Components](enable-tls-between-components.md)
   - [Enable TLS for DM](enable-tls-for-dm.md)
   - [Renew and Replace TLS Certificate](renew-tls-certificate.md)
+  - [Run TiDB Operator and TiDB Clusters as a Non-root User](containers-run-as-non-root-user.md)
 + Operate
   - [Migrate TiDB to Kubernetes](migrate-tidb-to-kubernetes.md)
   - [Upgrade TiDB Cluster](upgrade-a-tidb-cluster.md)

diff --git a/en/_index.md b/en/_index.md
@@ -52,6 +52,7 @@ The corresponding relationship between TiDB Operator and TiDB versions is as fol
 
 - [Enable TLS for the MySQL Client](enable-tls-for-mysql-client.md)
 - [Enable TLS between TiDB Components](enable-tls-between-components.md)
+- [Run TiDB Operator and TiDB Clusters as a Non-root User](containers-run-as-non-root-user.md)
 
 </NavColumn>
 

diff --git a/en/configure-a-tidb-cluster.md b/en/configure-a-tidb-cluster.md
@@ -649,7 +649,9 @@ TiDB is a distributed database and its high availability must ensure that when a
 
 ### High availability of TiDB service
 
-High availability at other levels (such as rack, zone, region) is guaranteed by Affinity's `PodAntiAffinity`. `PodAntiAffinity` can avoid the situation where different instances of the same component are deployed on the same physical topology node. In this way, disaster recovery is achieved. Detailed user guide for Affinity: [Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity).
+#### Use affinity to schedule pods
+
+By configuring `PodAntiAffinity`, you can avoid the situation in which different instances of the same component are deployed on the same physical topology node. In this way, disaster recovery (high availability) is achieved. For the user guide of Affinity, see [Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity).
 
 The following is an example of a typical service high availability setup:
 
@@ -701,6 +703,46 @@ affinity:
        - ${namespace}
 ```
 
+#### Use topologySpreadConstraints to make pods evenly spread
+
+By configuring `topologySpreadConstraints`, you can make pods evenly spread in different topologies. For instructions about configuring `topologySpreadConstraints`, see [Pod Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/).
+
+> **Note:**
+>
+> To use `topologySpreadConstraints`, you must enable the `EvenPodsSpread` feature gate. If the Kubernetes version in use is earlier than v1.16 or if the `EvenPodsSpread` feature gate is disabled, the configuration of `topologySpreadConstraints` does not take effect.
+
+You can either configure `topologySpreadConstraints` at a cluster level (`spec.topologySpreadConstraints`) for all components or at a component level (such as `spec.tidb.topologySpreadConstraints`) for specific components.
+
+The following is an example configuration:
+
+{{< copyable "" >}}
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+- topologyKey: topology.kubernetes.io/zone
+```
+
+The example configuration can make pods of the same component evenly spread on different zones and nodes.
+
+Currently, `topologySpreadConstraints` only supports the configuration of the `topologyKey` field. In the pod spec, the above example configuration will be automatically expanded as follows:
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+- topologyKey: topology.kubernetes.io/zone
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+```
+
+> **Note:**
+>
+> You can use this feature to replace [TiDB Scheduler](tidb-scheduler.md) for evenly scheduling.
+
 ### High availability of data
 
 Before configuring the high availability of data, read [Information Configuration of the Cluster Typology](https://pingcap.com/docs/stable/location-awareness/) which describes how high availability of TiDB cluster is implemented.

diff --git a/en/containers-run-as-non-root-user.md b/en/containers-run-as-non-root-user.md
@@ -0,0 +1,56 @@
+---
+title: Run TiDB Operator and TiDB Clusters as a Non-root User
+summary: Make TiDB Operator related containers run as a non-root user
+---
+
+# Run TiDB Operator and TiDB Clusters as a Non-root User
+
+In some Kubernetes environments, containers cannot be run as the root user. In this case, you can set [`securityContext`](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) to run containers as a non-root user.
+
+## Configure TiDB Operator containers
+
+For TiDB Operator containers, you can configure security context in the helm `values.yaml` file. All TiDB Operator components (at `<controllerManager/scheduler/advancedStatefulset/admissionWebhook>.securityContext`) support this configuration.
+
+The following is an example configuration:
+
+```yaml
+controllerManager:
+  securityContext:
+    runAsUser: 1000
+    runAsGroup: 2000
+    fsGroup: 2000
+```
+
+## Configure containers controlled by CR
+
+For the containers controlled by CR, you can configure security context in any CRs (TidbCluster/DMCluster/TiInitializer/TiMonitor/Backup/BackupSchedule/Restore) to make the containers run as a non-root user.
+
+You can either configure `podSecurityContext` at a cluster level (`spec.podSecurityContext`) for all components or at a component level (such as `spec.tidb.podSecurityContext` for TidbCluster and `spec.master.podSecurityContext` for DMCluster) for a specific component.
+
+The following is an example configuration at a cluster level:
+
+```yaml
+spec:
+  podSecurityContext:
+    runAsUser: 1000
+    runAsGroup: 2000
+    fsGroup: 2000
+```
+
+The following is an example configuration at a component level:
+
+```yaml
+spec:
+  pd:
+    podSecurityContext:
+      runAsUser: 1000
+      runAsGroup: 2000
+      fsGroup: 2000
+  tidb:
+    podSecurityContext:
+      runAsUser: 1000
+      runAsGroup: 2000
+      fsGroup: 2000
+```
+
+For a component, if both the cluster level and the component level are configured, only the configuration of the component level takes effect.
diff --git a/en/deploy-tidb-dm.md b/en/deploy-tidb-dm.md
@@ -88,6 +88,46 @@ spec:
 
 ```
 
+### Topology Spread Constraint
+
+By configuring `topologySpreadConstraints`, you can make pods evenly spread in different topologies. For instructions about configuring `topologySpreadConstraints`, see [Pod Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/).
+
+> **Note:**
+>
+> To use `topologySpreadConstraints`, you must enable the `EvenPodsSpread` feature gate. If the Kubernetes version in use is earlier than v1.16 or if the `EvenPodsSpread` feature gate is disabled, the configuration of `topologySpreadConstraints` does not take effect.
+
+You can either configure `topologySpreadConstraints` at a cluster level (`spec.topologySpreadConstraints`) for all components or at a component level (such as `spec.tidb.topologySpreadConstraints`) for specific components.
+
+The following is an example configuration:
+
+{{< copyable "" >}}
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+- topologyKey: topology.kubernetes.io/zone
+```
+
+The example configuration can make pods of the same component evenly spread on different zones and nodes.
+
+Currently, `topologySpreadConstraints` only supports the configuration of the `topologyKey` field. In the pod spec, the above example configuration will be automatically expanded as follows:
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+- topologyKey: topology.kubernetes.io/zone
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+```
+
+> **Note:**
+>
+> You can use this feature to replace [TiDB Scheduler](tidb-scheduler.md) for evenly scheduling.
+
 ## Deploy the DM cluster
 
 After configuring the yaml file of the DM cluster in the above steps, execute the following command to deploy the DM cluster:

diff --git a/en/tidb-scheduler.md b/en/tidb-scheduler.md
@@ -75,6 +75,10 @@ Scheduling rule 3: When you perform a rolling update to a TiDB instance, the ins
 
 This ensures stable scheduling and is helpful for the scenario of manually configuring Node IP and NodePort to the LB backend. It can reduce the impact on the cluster during the rolling update because you do not need to adjust the LB configuration when the Node IP is changed after the upgrade.
 
+> **Note:**
+>
+> This rule cannot be implemented by [`topologySpreadConstraints`](configure-a-tidb-cluster.md#use-topologyspreadconstraints-to-make-pods-evenly-spread).
+
 ## How TiDB Scheduler works
 
 ![TiDB Scheduler Overview](/media/tidb-scheduler-overview.png)

diff --git a/zh/TOC.md b/zh/TOC.md
@@ -39,6 +39,7 @@
   - [为 TiDB 组件间开启 TLS](enable-tls-between-components.md)
   - [为 DM 组件开启 TLS](enable-tls-for-dm.md)
   - [更新和替换 TLS 证书](renew-tls-certificate.md)
+  - [以非 root 用户运行 TiDB Operator 和 TiDB 集群](containers-run-as-non-root-user.md)
 + 运维
   - [迁移 TiDB 至 Kubernetes](migrate-tidb-to-kubernetes.md)
   - [升级 TiDB 集群](upgrade-a-tidb-cluster.md)

diff --git a/zh/_index.md b/zh/_index.md
@@ -54,6 +54,7 @@ TiDB Operator 与适用的 TiDB 版本的对应关系如下：
 
 - [为 MySQL 客户端开启 TLS](enable-tls-for-mysql-client.md)
 - [为 TiDB 组件间开启 TLS](enable-tls-between-components.md)
+- [以非 root 用户运行 TiDB Operator 和 TiDB 集群](containers-run-as-non-root-user.md)
 
 </NavColumn>
 

diff --git a/zh/configure-a-tidb-cluster.md b/zh/configure-a-tidb-cluster.md
@@ -619,7 +619,9 @@ TiDB 是分布式数据库，它的高可用需要做到在任一个物理拓扑
 
 ### TiDB 服务高可用
 
-其它层面的高可用（例如 rack，zone，region）是通过 Affinity 的 `PodAntiAffinity` 来保证，通过 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到高可用的目的，Affinity 的使用参考：[Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity)。
+#### 通过 affinity 调度实例
+
+配置 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到高可用的目的。关于 Affinity 的使用说明，请参阅 [Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity)。
 
 下面是一个典型的高可用设置例子：
 
@@ -671,6 +673,46 @@ affinity:
        - ${namespace}
 ```
 
+#### 通过 topologySpreadConstraints 实现 Pod 均匀分布
+
+配置 `topologySpreadConstraints` 可以实现同一组件的不同实例在拓扑上的均匀分布。具体配置方法请参阅 [Pod Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/)。
+
+> **注意：**
+>
+> 配置 `topologySpreadConstraints` 前，你需要开启 `EvenPodsSpread` feature gate。如果 Kubernetes 版本低于 v1.16 或者 `EvenPodsSpread` feature gate 未开启，`topologySpreadConstraints` 的配置将不会生效。
+
+`topologySpreadConstraints` 可以设置在整个集群级别 (`spec.topologySpreadConstraints`) 来配置所有组件或者设置在组件级别 (例如 `spec.tidb.topologySpreadConstraints`) 来配置特定的组件。
+
+以下是一个配置示例：
+
+{{< copyable "" >}}
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+- topologyKey: topology.kubernetes.io/zone
+```
+
+该配置能让同一组件的不同实例均匀分布在不同 zone 和节点上。
+
+当前 `topologySpreadConstraints` 仅支持 `topologyKey` 配置。在 Pod spec 中，上述示例配置会自动展开成如下配置：
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+- topologyKey: topology.kubernetes.io/zone
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+```
+
+> **注意：**
+>
+> 可以用该功能替换 [TiDB Scheduler](tidb-scheduler.md) 来实现均匀调度。
+
 ### 数据的高可用
 
 在开始数据高可用配置前，首先请阅读[集群拓扑信息配置](https://pingcap.com/docs-cn/stable/schedule-replicas-by-topology-labels/)。该文档描述了 TiDB 集群数据高可用的实现原理。

diff --git a/zh/containers-run-as-non-root-user.md b/zh/containers-run-as-non-root-user.md
@@ -0,0 +1,56 @@
+---
+title: 以非 root 用户运行 TiDB Operator 和 TiDB 集群
+summary: 以非 root 用户运行所有 TiDB Operator 相关的容器
+---
+
+# 以非 root 用户运行 TiDB Operator 和 TiDB 集群
+
+在某些 Kubernetes 环境中，无法用 root 用户运行容器。你可以通过配置 [`securityContext`](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) 来以非 root 用户运行容器。
+
+## 配置 TiDB Operator 相关的容器
+
+对于 TiDB Operator 相关的容器，你可以在 helm 的 `values.yaml` 文件中配置安全上下文 (security context) 。所有 operator 的相关组件都支持该配置 (`<controllerManager/scheduler/advancedStatefulset/admissionWebhook>.securityContext`)。
+
+以下是一个配置示例:
+
+```yaml
+controllerManager:
+  securityContext:
+    runAsUser: 1000
+    runAsGroup: 2000
+    fsGroup: 2000
+```
+
+## 配置按照 CR 生成的容器
+
+对于按照 CR 生成的容器，你同样可以在任意一种 CR (TidbCluster/DMCluster/TiInitializer/TiMonitor/Backup/BackupSchedule/Restore) 中配置安全上下文 (security context) 。
+
+`podSecurityContext` 可以配置在集群级别 (`spec.podSecurityContext`) 对所有组件生效或者配置在组件级别 (例如，配置 TidbCluster 的 `spec.tidb.podSecurityContext`，配置 DMCluster 的 `spec.master.podSecurityContext`) 仅对该组件生效。
+
+以下是一个集群级别的配置示例：
+
+```yaml
+spec:
+  podSecurityContext:
+    runAsUser: 1000
+    runAsGroup: 2000
+    fsGroup: 2000
+```
+
+以下是一个组件级别的配置示例：
+
+```yaml
+spec:
+  pd:
+    podSecurityContext:
+      runAsUser: 1000
+      runAsGroup: 2000
+      fsGroup: 2000
+  tidb:
+    podSecurityContext:
+      runAsUser: 1000
+      runAsGroup: 2000
+      fsGroup: 2000
+```
+
+如果同时配置了集群级别和组件级别，则该组件以组件级别的配置为准。
diff --git a/zh/deploy-tidb-dm.md b/zh/deploy-tidb-dm.md
@@ -86,6 +86,46 @@ spec:
       keepalive-ttl: 15
 ```
 
+### 拓扑分布约束
+
+配置 `topologySpreadConstraints` 可以实现同一组件的不同实例在拓扑上的均匀分布。具体配置方法请参阅 [Pod Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/)。
+
+> **注意：**
+>
+> 配置 `topologySpreadConstraints` 前，你需要开启 `EvenPodsSpread` feature gate。如果 Kubernetes 版本低于 v1.16 或者 `EvenPodsSpread` feature gate 未开启，`topologySpreadConstraints` 的配置将不会生效。
+
+`topologySpreadConstraints` 可以设置在整个集群级别 (`spec.topologySpreadConstraints`) 来配置所有组件或者设置在组件级别 (例如 `spec.tidb.topologySpreadConstraints`) 来配置特定的组件。
+
+以下是一个配置示例：
+
+{{< copyable "" >}}
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+- topologyKey: topology.kubernetes.io/zone
+```
+
+该配置能让同一组件的不同实例均匀分布在不同 zone 和节点上。
+
+当前 `topologySpreadConstraints` 仅支持 `topologyKey` 配置。在 Pod spec 中，上述示例配置会自动展开成如下配置：
+
+```yaml
+topologySpreadConstrains:
+- topologyKey: kubernetes.io/hostname
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+- topologyKey: topology.kubernetes.io/zone
+  maxSkew: 1
+  whenUnsatisfiable: DoNotSchedule
+  labelSelector: <object>
+```
+
+> **注意：**
+>
+> 可以用该功能替换 [TiDB Scheduler](tidb-scheduler.md) 来实现均匀调度。
+
 ## 部署 DM 集群
 
 按上述步骤配置完 DM 集群的 yaml 文件后，执行以下命令部署 DM 集群：

diff --git a/zh/tidb-scheduler.md b/zh/tidb-scheduler.md
@@ -75,6 +75,10 @@ kubectl label nodes node1 zone=zone1
 
 这样实现了稳定调度，对于手动将 Node IP + NodePort 挂载在 LB 后端的场景比较有帮助，避免升级集群后 Node IP 发生变更时需要重新调整 LB，这样可以减少滚动更新时对集群的影响。
 
+> **注意：**
+>
+> 该规则 [`topologySpreadConstraints`](configure-a-tidb-cluster.md#通过-topologyspreadconstraints-实现-pod-均匀分布) 无法实现。
+
 ## 工作原理
 
 ![TiDB Scheduler 工作原理](/media/tidb-scheduler-overview.png)