部署为 ACP 日志存储

Alauda Container Platform 可以将平台日志存储在 ClickHouse 中。日志安装章节假定 ClickHouse 集群已经存在,并要求提供其地址、集群名称、数据库和账号。本页面将构建这样一个集群,采用推荐的三节点高可用布局,并以供您填入日志章节的值结束。

该布局包含一个 分片 和三个 副本。分片是数据的一部分;副本是分片的副本。一个分片包含三个副本,意味着每条日志记录都会存储三次,分别位于三个不同的 infra 节点上,因此即使一个节点丢失,日志也不会丢失。

请在日志安装章节的第 1.2 节之前完成本页面。对于该章节介绍的其他部署方案(单节点评估、六节点或九节点扩展),请更改清单中的 shardsCount 和 replicasCount,并在 PlatformLogForward 中使用相同的两个数字。

步骤概览

  1. 检查先决条件:operator、Keeper 仲裁、infra 节点、存储和可用容量。
  2. 选择两个密码并将其转换为摘要。
  3. 创建集群 Secret。
  4. 填写清单并应用。
  5. 创建 observability 数据库。
  6. 验证,然后将这些值交给日志安装流程。

日志堆栈所需的名称

项目本页面使用的值日志章节读取的位置
命名空间cpaas-system所有连接 Secret 都位于此处
实例名称cpaas-clickhouseService clickhouse-cpaas-clickhouse
端点http://clickhouse-cpaas-clickhouse.cpaas-system.svc:8123endpoint 位于 platform-default-ch-conn 中
集群名称replicatedSecret 中的 cluster;由 ON CLUSTER 使用
数据库observabilitySecret 中的 database;必须预先存在
账号platform-loggingSecret 中的 username / password
拓扑1 个分片 x 3 个副本PlatformLogForward 中的 shards / replicas

这些是 ACP 的基线默认值。如果更改其中任何一个,也请在日志章节中进行相应更改。

前置条件

你需要详细信息
已安装 operator下面的实例通过 operator 创建。
一个 Keeper 仲裁组在 cpaas-system 中名为 keeper 的三成员 ClickHouseKeeperInstallation,按照部署 Keeper 仲裁组中的说明创建。没有它,复制无法启动。使用该指南早期版本手动构建的仲裁组同样适用;请参阅清单下方的注释。
三个 infra 节点已添加标签并设置污点 node-role.kubernetes.io/infra。每个节点承载一个 Keeper 成员和一个 ClickHouse 副本。
用于数据卷的 StorageClass清单使用集群的默认 StorageClass。不必与 Keeper 仲裁组使用的 StorageClass 相同;两个工作负载使用独立的数据卷,因此可以分别选择合适的 StorageClass。请根据日志容量规划指南设置数据卷大小,而不是使用下面示例中的值。
三个节点上的可用容量Kubernetes 会将 Pod 的资源请求与节点上仍未预留的资源进行比较来放置 Pod,而不是与节点当前正在使用的资源进行比较。检查每个 infra 节点的 kubectl describe node <node> 中的“Allocated resources”部分,并确保仍可用的 CPU 和内存足以满足清单中的请求。kubectl top 无法告知你这些信息。在 ACP 中,存储组件(例如 rook-ceph)会在较小的 worker 上预留很大一部分资源,但实际使用量很少;不适合的 Pod 会保持为 Pending,并显示 Insufficient memory。

步骤 1:选择密码

该 manifest 会创建两个 ClickHouse 账户:

  • admin:供您使用,在步骤 5 中创建数据库时使用一次,之后用于检查;
  • platform-logging:供 logging 服务使用,该服务每次写入时都会通过此账户连接。

为每个账户选择一个密码并妥善保管。您需要在步骤 5 中输入 admin 密码,并将 platform-logging 密码填入 logging 章节的连接 Secret 中。

manifest 本身不会包含密码,而是在 admin/password_sha256_hex 和 platform-logging/password_sha256_hex 行中包含每个密码的 SHA-256 摘要(64 个字符的指纹)。针对每个密码分别执行一次以下命令,生成对应摘要:

  printf '%s' '<password>' | sha256sum | cut -d' ' -f1

输出为 64 个十六进制字符。将其复制到步骤 3 中 manifest 的对应行。

步骤 2:创建集群 Secret

三个副本会相互通信以复制数据,该通信由一个名为集群 Secret 的共享密码保护。在 ACP 上,operator 不允许创建 Secrets,因此请在创建实例前自行创建该 Secret。其值是随机的,您无需知道该值:

kubectl -n cpaas-system create secret generic cpaas-clickhouse-cluster-secret \
  --from-literal=secret="$(openssl rand -hex 24)"

不要为此使用 operator 的 secret: auto 选项;请参阅 manifest 下方的说明。

步骤 3:填写并应用 manifest

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

占位符替换为必需
<admin-sha256-hex>步骤 1 中 admin 密码的摘要。是
<platform-logging-sha256-hex>步骤 1 中 platform-logging 密码的摘要。是
<storage-class>仅当您不想使用默认 StorageClass 时:移除 storageClassName 前面的 #,并在此处填入 StorageClass 名称。否

另外,请检查 storage: 200Gi 行以及 CPU 和内存值;容量规划指南会告诉您日志量所需的资源。

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: cpaas-clickhouse
  namespace: cpaas-system
spec:
  defaults:
    templates:
      dataVolumeClaimTemplate: data-volume
      podTemplate: ch-pod
      serviceTemplate: internal
  configuration:
    zookeeper:
      keeper:
        name: keeper
        namespace: cpaas-system
    clusters:
      - name: replicated
        secret:
          valueFrom:
            secretKeyRef:
              name: cpaas-clickhouse-cluster-secret
              key: secret
        layout:
          shardsCount: 1
          replicasCount: 3
    users:
      # One-time administration: creating the database, inspection.
      admin/password_sha256_hex: <admin-sha256-hex>
      admin/networks/ip:
        - "::/0"
      admin/access_management: "1"
      # The account the logging data path uses. Full rights on the target
      # database, plus the right to run ON CLUSTER statements.
      platform-logging/password_sha256_hex: <platform-logging-sha256-hex>
      platform-logging/networks/ip:
        - "::/0"
      platform-logging/grants/query:
        - "GRANT ALL ON observability.*"
        - "GRANT CLUSTER ON *.*"
  templates:
    serviceTemplates:
      - name: internal
        spec:
          type: ClusterIP
          ports:
            - name: http
              port: 8123
            - name: tcp
              port: 9000
    podTemplates:
      - name: ch-pod
        podDistribution:
          - type: ShardAntiAffinity
        spec:
          tolerations:
            - key: node-role.kubernetes.io/infra
              operator: Exists
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                  - matchExpressions:
                      - key: node-role.kubernetes.io/infra
                        operator: Exists
          securityContext:
            runAsUser: 101
            runAsGroup: 101
            fsGroup: 101
            runAsNonRoot: true
            seccompProfile:
              type: RuntimeDefault
          containers:
            - name: clickhouse
              resources:
                requests:
                  cpu: "2"
                  memory: 8Gi
                limits:
                  cpu: "4"
                  memory: 16Gi
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                capabilities:
                  drop:
                    - ALL
    volumeClaimTemplates:
      - name: data-volume
        spec:
          accessModes:
            - ReadWriteOnce
          # storageClassName: <storage-class>   # uncomment to use a StorageClass other than the default
          resources:
            requests:
              storage: 200Gi

各部分的作用如下:

  • zookeeper.keeper 指定先决条件中提到的 Keeper quorum。operator 会将其解析为三个成员的地址;复制和 ON CLUSTER 语句都会通过这些地址执行。如果您运行的是手动构建的 quorum,请将 keeper 块替换为 nodes:,并为每个成员添加一个 - host: keeper-<n>.keeper-headless.cpaas-system 条目;不要同时设置两者。
  • secret.valueFrom.secretKeyRef 指向您在步骤 2 中创建的 Secret,以便副本彼此进行身份验证。不要将其替换为 secret: auto:在 ACP 上,operator 只能读取 Secrets,因此本应由 auto 生成的 Secret 不会出现,所有 pod 都会停留在 CreateContainerConfigError 状态。
  • users 创建两个账户。access_management 允许 admin 管理用户和授权。grants/query 让 platform-logging 在每个副本上获得相应权限,而无需您执行 GRANT 语句;由于 logging schema 迁移使用 ON CLUSTER,因此需要 CLUSTER。请注意,ALL ON observability.* 的范围很广:它还涵盖该数据库中的用户、角色和行策略管理。如果最小权限比简单性更重要,请将其收窄为 SELECT, INSERT, CREATE, ALTER, DROP ON observability.*。
  • networks/ip: "::/0" 允许其他 pod 访问这两个账户。没有此设置时,账户只能从其自身 pod 内连接,因此来自 logging 服务的所有连接都会被拒绝。如果您的策略有要求,请将其收窄为您的 pod 网络范围。
  • serviceTemplate: internal 将实例的 Service 设置为 ClusterIP。默认值为 LoadBalancer;在没有负载均衡器提供程序的集群上,LoadBalancer 永远不会获得地址,而 logging 服务只会从集群内部连接。
  • podDistribution: ShardAntiAffinity 与节点亲和性一起,将三个副本分别放置在三个不同的 infra 节点上。
  • 未指定容器镜像。 operator 会提供其安装时使用的服务器镜像。

应用文件并等待三个副本:

kubectl -n cpaas-system apply -f cpaas-clickhouse.yaml
kubectl -n cpaas-system get statefulset -l clickhouse.altinity.com/chi=cpaas-clickhouse \
  -o custom-columns=NAME:.metadata.name,DESIRED:.spec.replicas,READY:.status.readyReplicas

每个副本都有自己的 StatefulSet,因此第二条命令会列出三个 StatefulSet;请等待每个 StatefulSet 都显示 READY 1。operator 会逐个启动它们,因此需要几分钟。kubectl -n cpaas-system get chi cpaas-clickhouse 会显示实例状态,该状态最终会变为 Completed。

步骤 4:创建数据库

日志记录章节要求在日志存储 operator 启动之前,observability 数据库已经存在。使用步骤 1 中的纯文本 admin 密码,以 admin 的身份创建一次即可。该命令在第一个 Replica 的 Pod 内运行 clickhouse-client;ON CLUSTER 'replicated' 会在全部三个 Replica 上创建数据库:

kubectl -n cpaas-system exec chi-cpaas-clickhouse-replicated-0-0-0 -c clickhouse -- \
  clickhouse-client -u admin --password '<admin-password>' -q \
  "CREATE DATABASE IF NOT EXISTS observability ON CLUSTER 'replicated'"

成功时,该命令不会输出任何内容。

如果命令失败并显示 Code: 999 ... Coordination::Exception: Cannot use any of provided ZooKeeper nodes. (KEEPER_EXCEPTION),则说明实例正常,但无法与三个 Keeper 成员中的任何一个建立会话。这是 Keeper 问题,而不是数据库问题。通常原因如下,按常见程度排序:

  • 仲裁位置与 manifest 中的定义不一致。manifest 在 cpaas-system 中指定了 ClickHouseKeeperInstallation keeper。检查 kubectl -n cpaas-system get chk keeper:它必须存在,并报告 Completed。
  • Pod 存在,但从未形成仲裁。Keeper manifest 需要三个带有 node-role.kubernetes.io/infra 标签的节点,每个节点运行一个 Pod。在此类节点数少于三个的集群中,Pod 会保持为 Pending。 部署 Keeper 仲裁 的步骤 2 介绍了如何检查 leader 和 follower。
  • 端口 2181 被 cpaas-system 中的 NetworkPolicy 阻止。

运行 部署 Keeper 仲裁 的步骤 2 以区分这些情况,然后查看服务器日志:

kubectl -n cpaas-system get pods -l clickhouse-keeper.altinity.com/chk=keeper -o wide
kubectl -n cpaas-system logs chi-cpaas-clickhouse-replicated-0-0-0 -c clickhouse | grep -iE 'keeper|zookeeper' | tail -20

日志会显示具体是哪一种情况:无法解析的名称、连接被拒绝,或会话被拒绝。当某个成员报告 zk_server_state leader 后,再次运行 CREATE DATABASE 命令;无需对实例进行任何更改。

步骤 5:验证

检查集群成员关系以及与 Keeper 的连接。使用与步骤 4 中相同的 clickhouse-client 命令运行每个查询,并在 -q 后传入查询:

SELECT cluster, shard_num, replica_num, host_name
FROM system.clusters WHERE cluster = 'replicated' ORDER BY replica_num;

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

第一个查询返回三行,表示一个分片及其编号为 1 到 3 的 Replica。第二个查询返回一个简短的名称列表。如果第二个查询失败,请先修复 Keeper 仲裁,然后再继续;请参阅 ON CLUSTER DDL fails with NO_ELEMENTS_IN_CONFIG。

然后验证 platform-logging 账户能够执行日志迁移将执行的操作。在 cpaas-system 中任意 Pod 的 shell 中运行以下命令,并使用纯文本 platform-logging 密码。第一个命令在集群上创建一个小型复制表,第二个命令会将其删除:

curl -s "http://clickhouse-cpaas-clickhouse.cpaas-system.svc:8123/" \
  -u "platform-logging:<platform-logging-password>" --data-binary \
  "CREATE TABLE observability.probe ON CLUSTER 'replicated' (ts DateTime) \
   ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/observability/probe', '{replica}') ORDER BY ts"
curl -s "http://clickhouse-cpaas-clickhouse.cpaas-system.svc:8123/" \
  -u "platform-logging:<platform-logging-password>" --data-binary \
  "DROP TABLE observability.probe ON CLUSTER 'replicated'"

两个命令成功时都不会输出任何内容。包含 Not enough privileges 的错误会指出缺少的权限;将其添加到 manifest 中的 grants/query,然后重新应用 manifest。

步骤 6:移交给日志安装

使用以下值继续阅读日志安装章节的第 1.2 节:

字段值
platform-default-ch-conn endpointhttp://clickhouse-cpaas-clickhouse.cpaas-system.svc:8123
platform-default-ch-conn clusterreplicated
platform-default-ch-conn databaseobservability
platform-default-ch-conn username / passwordplatform-logging / 步骤 1 中选择的明文密码
platform-default-ch-conn tls.ca省略;集群内部的端点使用普通 HTTP
PlatformLogForward externalStorage.shards / replicas1 / 3

日志章节中的辅助命令会从 spec.configuration.settings.default_database 读取数据库名称。此实例未设置该字段,因此辅助命令会输出空的数据库名称;请使用 observability。

注意事项

  • 内置的 default 用户不用于日志服务。它只能从其自身的 pod 内进行连接,这是有意设计的。请始终为日志服务提供独立的账户,如上所述。
  • 放置设置应放在此清单中。日志文档指出,不要为放置而修补生成的 ClickHouseInstallation 资源;这适用于日志 operator 自身创建的资源。此实例属于您,其 pod 模板才是配置容忍度和亲和性的正确位置。
  • Keeper 和数据库共享基础设施节点。为每个节点按照一个 Keeper 成员加一个副本的配置进行容量规划:副本所需的容量参照容量规划指南,Keeper 则预留一小部分固定容量。
  • 备份和保留由日志文档处理(PlatformLogForward 中的 TTL、备份操作指南);operator 不提供这两项功能。
  • 嵌入式 Keeper 是一种替代方案。知识库文章如何使用嵌入式 ClickHouse Keeper 部署复制的 ClickHouse 集群(KB260600102)在三个副本内部运行 Keeper,而不是将其作为独立的仲裁集群,并包含日志存储调优设置,例如系统表上的 TTL。如果采用此方案,请将页面顶部表格中的名称、platform-logging 账户和放置设置带入其清单;移交值保持不变。