部署 Keeper 仲裁组

只有在 ClickHouse 旁运行一个小型协调服务时,ClickHouse 才能使表的多个副本保持同步(复制)。在 ClickHouse 中,该服务称为 Keeper。它使用与 Apache ZooKeeper 相同的协议,因此实例清单在 zookeeper 下引用它。

operator 通过 ClickHouseKeeperInstallation 资源(简称 chk)为你部署和管理 Keeper。你声明所需的成员数量及其数据存储位置;operator 负责其余所有事项:

  • 容器镜像:与 operator 提供给数据库 Pod 的 ClickHouse server 镜像相同,因此仲裁组始终运行产品随附的构建版本,在隔离网络环境中也无需额外镜像;
  • Keeper 配置,包括每个成员独有的 server id 和成员列表;
  • 每个成员一个 Service、一个客户端 Service,以及一个 PodDisruptionBudget;
  • 满足 Pod Security Admission restricted 配置文件要求的安全上下文:用户和组均为 101(镜像内置的 clickhouse 账户)、fsGroup: 101,以便数据卷可写;禁止权限提升,并删除所有 capabilities。

然后,ClickHouseInstallation 按名称引用该仲裁组。operator 会等待仲裁组就绪,然后将每个成员的地址写入 ClickHouse 配置本身。

步骤概览

  1. 检查先决条件。
  2. 在清单中填写占位符并应用清单。
  3. 检查三个成员是否已选出 leader。
  4. 将 ClickHouse 实例指向该仲裁组。

预计用时约十分钟。

开始之前:你要构建的内容

  • 为什么是三个成员。成员会对每项变更进行投票,而决策需要多数票。三个成员可以在一个成员宕机时继续工作,在两个成员宕机时停止工作。三个成员是能够容忍一次故障的最小规模,也是本产品经过测试的布局。这样的成员组称为 quorum。
  • 为什么使用 infra 节点。在 ACP 上,infra 节点专用于平台服务,Keeper 应部署在这些节点上。该清单会将 Pod 固定到这些节点,并将其分散部署,使每个节点承载一个成员。
INFO

还有第二种受支持的布局:让 Keeper 运行在 ClickHouse Pod 内部,使具有一个分片和三个副本的实例自身成为一个仲裁组。相关说明请参阅知识库文章 How to Deploy a Replicated ClickHouse Cluster with Embedded ClickHouse Keeper(KB260600102)。如果你希望使用单个工作负载,并且接受 Keeper 与 ClickHouse Pod 共享资源且随其一同重启,请选择此布局。本页面将 Keeper 单独部署,以便独立调整其规格、放置位置和升级,并允许多个 ClickHouse 实例共享它。

前置条件

你需要的内容详细信息
已安装 operator版本 v4.5.1 或更高版本。kubectl get crd clickhousekeeperinstallations.clickhouse-keeper.altinity.com 必须执行成功。
operator 监视的 quorum 命名空间如果 operator 是为单个命名空间安装的,请在该命名空间中创建 quorum。operator 不监视的命名空间中的资源会被静默忽略。
为成员准备三个节点在 ACP 上,这些通常是 infra 节点:标记为 node-role.kubernetes.io/infra,并使用相同的键进行污点标记。该 manifest 可容忍此污点,并且只会调度到具有该标签的节点上。如果此类节点少于三个,请删除 podAntiAffinity 块;这样,两个成员会共享一个节点,并在该节点发生故障时一起停止。
一个 StorageClass任意能提供 ReadWriteOnce 卷的 StorageClass。Keeper 存储的数据很少,因此每个成员 10 GiB 就足够了。请显式指定其名称:在没有默认 StorageClass 的集群中,不带 class 的卷声明会保持为 Pending。
一个命名空间最简单的选择是 ClickHouse 实例所在的命名空间。也可以使用其他命名空间;此时,实例会在其引用中指定该命名空间,如步骤 3 所示。

步骤 1:填写并应用 manifest

将下面的 manifest 复制到名为 keeper.yaml 的文件中,并替换占位符:

占位符替换为
<chk-name>quorum 的名称,例如 keeper。它会出现两次;请替换这两处。
<quorum-namespace>先决条件中指定的 namespace。
<storage-class>Keeper 卷使用的 StorageClass。
apiVersion: clickhouse-keeper.altinity.com/v1
kind: ClickHouseKeeperInstallation
metadata:
  name: <chk-name>
  namespace: <quorum-namespace>
spec:
  defaults:
    templates:
      podTemplate: keeper-pod
      dataVolumeClaimTemplate: keeper-data
  configuration:
    clusters:
      - name: keeper
        layout:
          replicasCount: 3
  templates:
    podTemplates:
      - name: keeper-pod
        spec:
          tolerations:
            - key: node-role.kubernetes.io/infra
              operator: Exists
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                  - matchExpressions:
                      - key: node-role.kubernetes.io/infra
                        operator: Exists
            podAntiAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                - topologyKey: kubernetes.io/hostname
                  labelSelector:
                    matchLabels:
                      clickhouse-keeper.altinity.com/chk: <chk-name>
    volumeClaimTemplates:
      - name: keeper-data
        spec:
          accessModes:
            - ReadWriteOnce
          storageClassName: <storage-class>
          resources:
            requests:
              storage: 10Gi

修改前需要了解以下几点:

  • 不设置 image、command 或 security context。请将它们省略。operator 会填充这些内容;当 operator 之后迁移到新的 server image 时,也会将 quorum 滚动更新到该 image,每次更新一个成员。
  • Pod 模板不列出任何容器。它唯一的作用是进行调度:tolerations、node affinity 和 anti-affinity 会合并到 operator 创建的 pod 中。
  • 节点排空会每次停止一个成员。operator 会创建名为 chk-<chk-name>-keeper 的 PodDisruptionBudget,通过 maxUnavailable: 1 覆盖 Keeper pod,因此集群维护不会同时停止两个成员。
  • 一个集群,三个成员。replicasCount 是 Keeper 成员的数量。请保持为奇数。

应用文件并等待 quorum:

kubectl -n <quorum-namespace> apply -f keeper.yaml
kubectl -n <quorum-namespace> get chk <chk-name> -w

当 STATUS 显示为 Completed 时,停止监视。operator 会逐个创建成员,因此这需要几分钟。如果它一直处于 InProgress,请使用 kubectl -n <quorum-namespace> get pods -l clickhouse-keeper.altinity.com/chk=<chk-name> -o wide 列出 pod;持续处于 Pending 状态的 pod 通常意味着可用的 infra 节点少于三个,或者 StorageClass 无法提供卷。

步骤 2:检查 quorum

Completed 状态表示每个成员的 pod 都是 Ready。它本身并不能证明成员就 leader 达成了一致,因此请询问每个成员所扮演的角色。Keeper 会在其客户端端口 2181 上响应内置状态命令 mntr:发送这四个字母后,它会回复一个统计信息列表。该 image 既没有 nc,也没有 socat,因此下面的命令使用 bash 内置的网络支持:

for pod in $(kubectl -n <quorum-namespace> get pods \
    -l clickhouse-keeper.altinity.com/chk=<chk-name> -o name); do
  echo "== ${pod}"
  kubectl -n <quorum-namespace> exec "${pod}" -c clickhouse-keeper -- bash -c \
    'exec 3<>/dev/tcp/127.0.0.1/2181; printf mntr >&3; timeout 5 cat <&3' \
    | grep -E 'zk_server_state|zk_synced_followers'
done

恰好有一个成员报告 zk_server_state leader,该成员还会报告 zk_synced_followers 2。另外两个成员报告 zk_server_state follower。这表示 quorum 正常工作。

如果某个成员响应 This instance is not currently serving requests,说明它正在运行,但尚未加入 quorum。请检查另外两个成员的日志,并使用 -o wide 确认三个 pod 是否已调度到三个不同的节点上。

第 3 步:将实例指向它

在 ClickHouse 实例 manifest 中,在 zookeeper.keeper 下指定 quorum:

spec:
  configuration:
    zookeeper:
      keeper:
        name: <chk-name>
        namespace: <quorum-namespace>

当 quorum 与实例位于同一命名空间时,可以省略 namespace。无需列出地址或端口:operator 会将该引用解析为每个成员的地址,并将这些地址写入 ClickHouse 配置。如果 quorum 尚未就绪,实例会等待它。

WARNING

请勿在同一个块中同时设置 zookeeper.nodes 和 zookeeper.keeper。operator 会将从 keeper 解析出的成员添加到 nodes 中已有的成员列表,因此实例将同时配置两个不同 quorum 的成员。

实例运行后,按照配置 replicated 集群中的说明,在实例的任意 pod 中使用 clickhouse-client 运行以下查询,从数据库侧确认它能够访问 Keeper:

SELECT name FROM system.zookeeper WHERE path = '/';

该查询会返回一个简短的名称列表,例如 clickhouse 和 keeper。如果返回错误而不是名称列表,则表示实例无法访问 quorum;请检查 kubectl get chk 是否报告 Completed,并确认引用中的名称和命名空间正确。

日常操作

  • 通过资源更改大小,切勿使用 kubectl scale。 operator 负责管理成员 StatefulSet 以及 Keeper 配置中的成员列表。手动扩缩 StatefulSet 会产生其他成员并不知晓的成员。
  • 切勿删除数据卷。 删除 ClickHouseKeeperInstallation 会移除其 pod;如果同时删除卷声明,还会删除协调数据,之后所有使用此 quorum 的 replicated 表都会变为只读,直到其副本重新注册。请将 Keeper 卷视为数据库的一部分。
  • 丢失一个成员没有问题;丢失两个成员则会导致服务中断。 只剩一个成员时,quorum 会停止提供服务。随后副本会变为只读(is_readonly = 1 位于 system.replicas 中),对 replicated 表的插入会因 TABLE_IS_READ_ONLY 而失败。第二个成员恢复后,服务会自行恢复。

从手动 Keeper StatefulSet 迁移到 ClickHouseKeeperInstallation

本页面的早期版本手动构建 quorum,将其创建为名为 keeper 的 StatefulSet,并配有 ConfigMap、无头 Service 和 PodDisruptionBudget;实例则在 zookeeper.nodes 下列出其成员。

升级 operator 不会影响此类 quorum。 operator 从未管理过它,也不会对其进行操作;列出 zookeeper.nodes 的实例在升级后仍会像之前一样正常工作。你不必迁移。仅当你希望由 operator 管理 Keeper 生命周期,并让其为你持续使用产品的服务器镜像时,才需要迁移。

将实例迁移到新的 quorum 会迁移其协调数据,而新 quorum 并不包含这些数据。ClickHouse 可以使用每个 Replica 保存在自身磁盘上的表数据片段,通过 SYSTEM RESTORE REPLICA 重建这些数据。以下操作步骤会针对每个复制表执行此操作。操作需要一个维护窗口,在此期间实例的复制表不能有任何写入。

WARNING

此操作步骤适用于 ReplicatedMergeTree 系列的表。如果实例中存在使用 Replicated 引擎的数据库(SELECT name FROM system.databases WHERE engine = 'Replicated' 返回行),请勿使用此操作步骤;请先联系支持团队。

1. 在旧 quorum 旁创建新 quorum

按照本页面的第 1 步和第 2 步操作,并使用不会与旧 StatefulSet 冲突的名称,例如 <chk-name> = keeper-managed。在此过程中,旧 quorum 会继续提供服务。只有当第 2 步显示一个 leader 和两个已同步 follower 时,才能继续。

2. 停止写入并等待复制完成

停止所有向实例写入的客户端。然后,在每个 Replica 上等待其复制队列为空,并记录其持有的数据:

SYSTEM SYNC REPLICA <database>.<table>;          -- for every replicated table
SELECT database, table, count() AS parts, sum(rows) AS rows
FROM system.parts
WHERE active AND database NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema')
GROUP BY database, table
ORDER BY database, table;

保留每个 Replica 的第二个查询的输出。同一 shard 的 Replica 必须报告相同的行数;如果不相同,请等待,然后再次运行 SYSTEM SYNC REPLICA,再继续操作。

3. 将实例指向新 quorum

在实例中,将整个 zookeeper 块替换为第 3 步中的引用——完全移除 nodes——并在同一项更改中设置 restart: RollingUpdate:

spec:
  restart: RollingUpdate
  configuration:
    zookeeper:
      keeper:
        name: keeper-managed
        namespace: <quorum-namespace>

必须重启。新的协调设置会在不重启 Pod 的情况下传递到 ClickHouse 配置中,而运行中的服务器随后会继续使用其部分旧的协调状态:尤其是承载 ON CLUSTER 语句的队列仍会附加到旧 quorum,因此第 4 步中的 ON CLUSTER 语句会超时。restart: RollingUpdate 会使 operator 逐个主机重启每个 ClickHouse Pod,从而让每台服务器都能以干净状态连接到新 quorum。

应用更改,并等待实例再次报告 Completed:

kubectl -n <namespace> get chi <instance-name> -w

然后再次移除 restart,这样之后对实例的更改就不会重启所有 Pod:

kubectl -n <namespace> patch chi <instance-name> --type=json -p='[{"op":"remove","path":"/spec/restart"}]'

不要改为在 StatefulSet 上使用 kubectl rollout restart 重启 Pod。这样会绕过 operator 独立重启主机,并且可能同时重启多个主机;在其对等主机重启期间启动的服务器可能会获得不完整的集群视图。

重启后,每个复制表都将处于只读状态,因为新 quorum 没有关于这些表的记录:SELECT database, table FROM system.replicas WHERE is_readonly 会列出这些表。

4. 重建协调数据

在一个 Replica 上,对上一步列出的每个表执行:

SYSTEM RESTORE REPLICA <database>.<table> ON CLUSTER '<cluster-name>';

<cluster-name> 是实例 spec.configuration.clusters 中的集群名称。每个 Replica 都会在新 quorum 中注册自身,并重新公布其保存在自身磁盘上的数据片段;不会从旧 quorum 复制任何内容。

5. 验证,然后恢复写入

  • SELECT database, table FROM system.replicas WHERE is_readonly 在任何 Replica 上都不返回行。
  • SELECT database, table, total_replicas, active_replicas FROM system.replicas 显示每个 shard 的所有 Replica 均已注册且处于活动状态。
  • 第 2 步中的 system.parts 查询在每个 Replica 上都返回与之前相同的行数。

然后重启客户端。

6. 移除旧 quorum

迁移所有使用旧 quorum 的实例后,删除其 StatefulSet、Service、ConfigMap 和 PodDisruptionBudget。在确定不再需要回退之前,请保留其卷声明;删除卷声明是不可逆的。

如需回退,请在第 5 步恢复写入之前执行:恢复实例中之前的 zookeeper.nodes 块,并同时恢复 restart: RollingUpdate,等待 Completed,然后像第 3 步一样移除 restart。旧 quorum 仍然保留着与第 2 步完全一致的协调数据,因此不需要执行 SYSTEM RESTORE REPLICA。一旦已针对新 quorum 恢复写入,旧 quorum 就不再与磁盘上的数据匹配;请勿切换回旧 quorum。


ClickHouse 是 ClickHouse, Inc. 的注册商标。https://clickhouse.com

Alauda 是独立供应商。本产品与 ClickHouse, Inc. 没有关联,也未获得其认可或赞助。所有商标均归其各自所有者所有,此处仅用于标识目的。