安装

本章介绍如何在全新的平台上安装日志堆栈。如果要将现有的 ACP 4.3 安装迁移到 4.4,请参阅从 ACP 4.3 升级到 4.4。

该堆栈由三个部分组成,并按以下顺序安装:

  1. 日志存储 — 部署 ClickHouse 或 OpenSearch,以及 Kafka,然后安装 Log Storage operator 并向其提供端点。此组件在每个存储集群上运行。
  2. Log Collector — 在需要收集其日志、事件或审计记录的每个集群上安装 collector 插件,并将其指向存储集群。
  3. Log Essentials — 仅在 global 集群上安装一次;发布控制台使用的查询 API。

完成后,ACP 控制台即可在 Operations Center > Logs 中查询收集的数据。

要安装的组件

该堆栈以三个集群组件的形式提供 — 两个插件(Log Essentials 和 Log Collector)以及一个 operator(Log Storage Management)。仅安装与您的拓扑匹配的组件。

组件类型安装位置用途
Alauda Container Platform Log Storage ManagementOperator每个存储日志的集群部署 log-storage-operator;该组件监视 PlatformLogForward,并针对 ClickHouse 或 OpenSearch 构建存储端数据路径(aggregate-vector、Razor、schema-migrations)。后端选择保存在 PLF 中,而不在 operator 安装表单中。
Alauda Container Platform Log CollectorPlugin每个需要收集其数据的集群部署节点级 collector(nevermore),并将数据转发到指定的存储集群。
Alauda Container Platform Log EssentialsPlugin仅 global 集群,每个平台一次发布控制台使用的日志、事件和审计查询 API。

单个存储集群选择 ClickHouse 或 OpenSearch 作为后端,并为多个 collector 集群提供服务;单个 collector 集群只能将数据发送到一个存储集群。

如需并排比较 ClickHouse 和 OpenSearch,请参阅日志组件选择指南。

WARNING
  • 要从使用 Log Storage for Elasticsearch 的 ACP 4.2 或 4.3 升级? 不要按照本章操作。请改为遵循从 Log Storage for Elasticsearch 升级和历史数据迁移。在 chart 管理的安装之上应用全新的 PlatformLogForward 会与 operator 的自动接管路径冲突。
  • Alauda Container Platform Log Storage for Elasticsearch 不在 ACP 4.4 中提供。 全新安装只能选择 ClickHouse 或 OpenSearch;没有可供回退的 Elasticsearch 安装表单。

1. 安装日志存储

在每个将存储日志的集群上执行此操作。

1.1 准备外部组件

存储端依赖两个外部系统:一个 Kafka 集群(必需)以及一个 ClickHouse 或 OpenSearch 集群(二选一)。请在安装 Log Storage operator 之前准备好这些组件。

1.1.1 Kafka

Kafka 在 collector 与存储后端之间缓冲记录。ClickHouse 和 OpenSearch 后端都需要 Kafka。

项目要求
版本Kafka 3.7 或更高版本(基线版本:4.2.0)。
身份验证SASL/SCRAM-SHA-512(推荐)、SASL/SCRAM-SHA-256 或 SASL/PLAIN。
TLS可选。启用后,SASL listener 通过 TLS 运行。
主题存储 operator 运行前必须存在以下三个主题:ALAUDA_LOG_TOPIC、ALAUDA_EVENT_TOPIC、ALAUDA_AUDIT_TOPIC。
账户 ACL一个 SASL 账户,在全部三个主题上具有 Read、Write、Create、Delete、Describe 权限,并在三个 consumer group alauda_log、alauda_event、alauda_audit 上具有 Read、Describe 权限。
Broker 配置message.max.bytes 和 replica.fetch.max.bytes 至少为 10 MiB,以免偶尔超过 1 MiB 的审计批次被拒绝。

如果您已运行 Kafka 集群,请在其中配置账户、主题和 ACL,然后继续执行第 1.1.2 节。

使用 Alauda Container Platform Kafka。 ACP 提供自己的 Kafka 产品(Alauda Kafka Operator,以独立的集群插件形式交付)。有关完整的安装、调优和运维指南,请参阅 Alauda Container Platform Kafka 文档。

用于启动日志记录 Kafka 集群的最小 CR 集如下所示。以下 kind 使用 Alauda strimzi fork(middleware.alauda.io/v1、RdsKafka / RdsKafkaUser / RdsTopic),这是 ACP 上推荐的路径。上游 strimzi(kafka.strimzi.io/v1beta2、Kafka / KafkaUser / KafkaTopic)同样可用 — operator 不关心您使用哪个 fork,只要 mq-conn Secret 以及 broker 端的 ACL / 主题保持一致即可。

本节的权威参考为 log-storage-operator/config/samples/quickstart_external_ch_kafka.yaml;下面的代码片段为文档需要而进行了缩减。

应用前编辑 — 以下字段没有安全默认值

下面的 manifest 包含占位符和示例值,您 必须 根据集群进行自定义。请勿直接 kubectl apply。

  • 密码(Secret platform-logging-password.stringData.password):将 <generate a strong password of at least 32 characters> 替换为通过所示 openssl 命令之一生成的真实 Secret。在 FIPS 主机上会强制执行此要求:少于 32 个字符会被 broker 静默拒绝。
  • StorageClass(RdsKafka.spec.storage.class 和 RdsKafka.spec.controller.storage.class):填写集群的 StorageClass。保留为 "" 仅在集群具有默认 StorageClass 时有效;否则 broker 会因 PVC 而处于 Pending 状态。
  • Broker 存储大小(RdsKafka.spec.storage.size):默认值 100Gi 适用于评估集群。对于生产环境,请根据 retention.ms × daily volume × replication factor 设置大小。
  • 副本数(RdsKafka.spec.replicas、RdsKafka.spec.controller.replicas、RdsTopic.spec.replicas):manifest 显示的是生产环境值(3 / 3 / 3)。对于单节点评估集群,请将它们全部设置为 1。将生产环境主题副本数与单 broker 集群混用会阻止主题创建。
  • 主题分区数(RdsTopic.spec.partitions):30 是生产环境的起始值。小型集群应降低该值;该值必须与下游预期的 aggregate-vector 并行度匹配,或能够整除该并行度。
  • 复制因子配置(RdsKafka.spec.config.default.replication.factor / min.insync.replicas / offsets.topic.replication.factor / transaction.state.log.replication.factor / transaction.state.log.min.isr):manifest 为 3-broker 生产集群提供了 3 / 2 / 3 / 3 / 2。对于单 broker 评估集群,请将每个 3 设置为 1,并将每个 2 设置为 1;在单 broker 集群上使用 3-broker 配置会使 __consumer_offsets 处于副本不足状态,且任何 consumer 都无法提交。
  • 资源(RdsKafka.spec.resources、controller.resources、entityOperator.topicOperator.resources / userOperator.resources、kafkaExporter.resources):示例中的 limits/requests 是合理的单 broker 基线。请根据流量进行调优 — broker 随吞吐量扩展,而 entity-operator 保持较小规模。
  • 容忍度(controller.template.pod.tolerations、kafka.template.pod.tolerations、entityOperator.template.pod.tolerations、kafkaExporter.template.pod.tolerations):manifest 容忍所有污点,以便单节点评估集群(控制平面带污点的节点承载工作负载)能够调度。对于希望 Kafka 仅运行在 worker 节点上的生产集群,请收紧或移除这些设置。
  • upgradeOption.autoUpgrade(RdsKafka.spec.upgradeOption.autoUpgrade):false 会固定版本 — 升级由 SRE 驱动。设置为 true 后,CSV 更新可能会在无人值守的情况下滚动升级 broker。

只有在替换上述所有占位符后才能应用。

# 1. SASL password Secret. On Alauda OS / FIPS hosts the password MUST be
# at least 32 characters; below that, the broker rejects the KafkaUser with
# UnacceptableCredential. Generate with one of:
#   openssl rand -base64 24 | tr -d '\n'   # 32 chars base64
#   openssl rand -hex 16                   # 32 chars hex
apiVersion: v1
kind: Secret
metadata:
  name: platform-logging-password
  namespace: cpaas-system
type: Opaque
stringData:
  password: "<generate a strong password of at least 32 characters>"
---
# 2. The Kafka cluster. Alauda's `RdsKafka` is a strimzi fork whose
# schema differs from upstream Kafka: `version` / `config` / `replicas`
# / `mode` / `controller` / `storage` sit at `spec.*` top level (NOT
# under `spec.kafka.*`), and `spec.kafka.listeners` is a MAP keyed by
# `plain` / `tls` / `external` (NOT a list). Listener authentication is
# SCRAM-SHA-512. The five `config` values below are MANDATORY for
# logging — the broker defaults are too small for the audit-ingest
# batch size and will silently drop audit batches otherwise.
apiVersion: middleware.alauda.io/v1
kind: RdsKafka
metadata:
  name: cpaas-kafka
  namespace: cpaas-system
spec:
  version: 4.2.0
  mode: KRaft                       # MANDATORY: v4.4 kafka runs in KRaft mode (no ZooKeeper)
  replicas: 3                       # broker count — 1 for single-node evaluation, 3 for production
  upgradeOption:
    autoUpgrade: false              # SRE pins the version; set true only if you accept rolling upgrades on CSV bumps
  storage:
    class: ""                       # fill in your StorageClass; leave "" to use the cluster default
    size: 100Gi
  resources:                        # broker pod sizing — tune to your traffic
    limits:
      cpu: "2"
      memory: 4Gi
    requests:
      cpu: 200m
      memory: 1Gi
  config:
    # MANDATORY. Broker default 1 MiB is too small for K8s audit batches
    # (~1.1-1.5 MiB decompressed) and rejects all audit ingest. Value
    # aligns with razor producer max.request.size (10 MiB).
    message.max.bytes: "10485760"
    # MANDATORY. Must be >= message.max.bytes or replica sync stalls.
    replica.fetch.max.bytes: "10485760"
    # MANDATORY. Supports an 8 MiB batch envelope plus SASL overhead.
    socket.request.max.bytes: "104857600"
    # MANDATORY. Prevents ghost topics when razor / aggregate-vector are
    # temporarily misconfigured.
    auto.create.topics.enable: "false"
    # MANDATORY. Prevents silent data loss on broker crash.
    unclean.leader.election.enable: "false"
    # Production replication defaults for a 3-broker cluster. For a
    # single-broker evaluation cluster set every "3" below to "1" and
    # min.insync.replicas / transaction.state.log.min.isr to "1".
    default.replication.factor: "3"
    min.insync.replicas: "2"
    offsets.topic.replication.factor: "3"
    transaction.state.log.replication.factor: "3"
    transaction.state.log.min.isr: "2"
    # Retention sizing — razor consumes within seconds, 48h window is
    # the usual production SLO for replay / incident forensics.
    log.retention.ms: "172800000"             # 48 hours
    log.retention.bytes: "4928307200"         # ~4.6 GiB / partition
    num.partitions: "30"                      # default when auto.create is on; topics below pin this explicitly
  controller:                       # MANDATORY in KRaft mode: dedicated controller quorum
    replicas: 3                     # 1 for single-node evaluation, 3 for production quorum
    roles: [controller]
    storage:
      class: ""                     # same as broker; leave "" for cluster default SC
      size: 5Gi                     # controller logs are small, 5Gi is enough
    resources:
      limits:
        cpu: "1"
        memory: 2Gi
      requests:
        cpu: 200m
        memory: 512Mi
    template:
      pod:
        tolerations:                # tolerate control-plane taint so single-node evaluation clusters schedule
          - operator: Exists
  kafka:
    authorization:
      type: simple
    listeners:                      # MAP keyed by `plain` / `tls` / `external`, NOT a list
      plain:                        # SASL/SCRAM over plain TCP on :9092
        authentication:
          type: scram-sha-512
      # To enable SASL-over-TLS on :9093, add a `tls:` entry here (same
      # `authentication` block as `plain:`) and set `tls.ca` + bootstrap
      # port 9093 in the mq-conn Secret below.
    template:
      pod:
        tolerations:
          - operator: Exists
  entityOperator:
    topicOperator:
      resources:
        limits:
          cpu: 500m
          memory: 1Gi
        requests:
          cpu: 100m
          memory: 256Mi
    userOperator:
      resources:
        limits:
          cpu: 500m
          memory: 1Gi
        requests:
          cpu: 100m
          memory: 256Mi
    template:
      pod:
        tolerations:
          - operator: Exists
  kafkaExporter:                    # exposes broker metrics for the aggregate-vector lag watchdog and dashboards
    resources:
      limits:
        cpu: 200m
        memory: 256Mi
      requests:
        cpu: 100m
        memory: 128Mi
    template:
      pod:
        tolerations:
          - operator: Exists
---
# 3. The SASL account. The nine ACL rules below are ALL required — the
# storage operator's preflight check reports each missing rule by name
# and refuses to roll out until they are in place.
apiVersion: middleware.alauda.io/v1
kind: RdsKafkaUser
metadata:
  name: platform-logging
  namespace: cpaas-system
  labels:
    middleware.alauda.io/cluster: cpaas-kafka
spec:
  authentication:
    type: scram-sha-512
    password:
      valueFrom:
        secretKeyRef:
          name: platform-logging-password
          key: password
  authorization:
    type: simple
    acls:
      # (a) All permissions on the three topics.
      - resource: {type: topic, name: ALAUDA_LOG_TOPIC,   patternType: literal}
        operation: All
        host: "*"
      - resource: {type: topic, name: ALAUDA_EVENT_TOPIC, patternType: literal}
        operation: All
        host: "*"
      - resource: {type: topic, name: ALAUDA_AUDIT_TOPIC, patternType: literal}
        operation: All
        host: "*"
      # (b) Read on the three aggregate-vector consumer groups.
      - resource: {type: group, name: alauda_log,   patternType: literal}
        operation: Read
        host: "*"
      - resource: {type: group, name: alauda_event, patternType: literal}
        operation: Read
        host: "*"
      - resource: {type: group, name: alauda_audit, patternType: literal}
        operation: Read
        host: "*"
      # (c) Read on the razor and LogForward consumer-group prefixes.
      # Without these, razor and LogForward tenants get silent
      # GroupAuthorizationFailed and drop to 0 throughput.
      - resource: {type: group, name: razor-,      patternType: prefix}
        operation: Read
        host: "*"
      - resource: {type: group, name: logforward-, patternType: prefix}
        operation: Read
        host: "*"
      # (d) DescribeConfigs on the cluster (used by the preflight check).
      - resource: {type: cluster, name: kafka-cluster, patternType: literal}
        operation: DescribeConfigs
        host: "*"
---
# 4. The three topics. `spec.topicName` must match the values you put in
# the Kafka connection Secret in Section 1.3 and the ACL literal names
# in step 3. Set `replicas` to `1` for a single-node evaluation cluster
# and `3` for a production three-broker cluster.
apiVersion: middleware.alauda.io/v1
kind: RdsTopic
metadata:
  name: alauda-log-topic                 # DNS-safe CR name
  namespace: cpaas-system                # must match the RdsKafka cluster's namespace
  labels:
    middleware.alauda.io/cluster: cpaas-kafka
spec:
  topicName: ALAUDA_LOG_TOPIC            # broker-side topic name (uppercase)
  partitions: 30
  replicas: 3
  config:
    retention.ms: "172800000"            # 48 hours
    max.message.bytes: "10485760"        # MANDATORY, must match broker
---
apiVersion: middleware.alauda.io/v1
kind: RdsTopic
metadata:
  name: alauda-event-topic
  namespace: cpaas-system
  labels:
    middleware.alauda.io/cluster: cpaas-kafka
spec:
  topicName: ALAUDA_EVENT_TOPIC
  partitions: 30
  replicas: 3
  config:
    retention.ms: "172800000"
    max.message.bytes: "10485760"
---
apiVersion: middleware.alauda.io/v1
kind: RdsTopic
metadata:
  name: alauda-audit-topic
  namespace: cpaas-system
  labels:
    middleware.alauda.io/cluster: cpaas-kafka
spec:
  topicName: ALAUDA_AUDIT_TOPIC
  partitions: 30
  replicas: 3
  config:
    retention.ms: "172800000"
    max.message.bytes: "10485760"
两个名称,同一个主题

CR 的 metadata.name 是 DNS 安全的 kebab-case 名称(alauda-log-topic),而 spec.topicName 是 broker 对外提供的实际名称(ALAUDA_LOG_TOPIC,使用大写字母和下划线)。Alauda Container Platform Log Collector 和存储 operator 始终读取 broker 端名称,因此您在第 1.3 节 Kafka connection Secret 中粘贴的值必须与 spec.topicName 匹配,而不是 metadata.name。

1.1.2 ClickHouse 或 OpenSearch

每个存储集群选择一个后端。如果尚未决定,请参阅日志组件选择指南。

ClickHouse
项目要求
版本ClickHouse 24.x 或更高版本(基线版本:25.8)。
Operator在集群范围内安装 ClickHouse Operator(altinity/clickhouse-operator v0.20 或更高版本)。
端点:8123 上的 HTTP 或 :8443 上的 HTTPS。
集群名称必须与 ClickHouseInstallation 上的 spec.configuration.clusters[0].name 以及平台使用 ON CLUSTER 时的名称匹配。ACP 基线默认值:replicated。
数据库ACP 基线默认值:observability。必须在安装存储 operator 之前存在。
账户一个在目标数据库上具有完整 DDL/DML 权限的账户。ACP 基线默认值:platform-logging。

集群拓扑。 选择以下配置之一,并在第 1.4 节填写 PlatformLogForward 时使用相同的 shards / replicas 值。将 PlatformLogForward 值设置得更低会静默导致部分 shards 或 replicas 未使用;设置得更高则会使数据路径尝试访问不存在的节点。

配置ShardsReplicas节点总数
单节点评估111
三节点 HA133
六节点横向扩展236
九节点横向扩展339

有关每种配置下的组件容量规划,请参阅日志组件容量规划。

如果您已运行 ClickHouse 集群,请确保其中已配置数据库和日志账户。若要从头开始构建集群,请参阅 Alauda Container Platform ClickHouse 文档。

OpenSearch
项目要求
版本OpenSearch 3.7.0(已测试版本)。
Operator在集群范围内安装 opensearch-project/opensearch-operator。
端点:9200 上的 HTTPS(支持 HTTP,但不推荐)。
分析器插件analysis-ik(兼容 OpenSearch 3.7.0 的构建版本),安装在每个 OpenSearch 节点上。必需。 查询路径默认使用 ik_smart 分析器;没有该插件时,每个关键字或中文内容查询都会返回 HTTP 400,控制台日志页面将无法使用。
账户一个具有 cluster-manage 和 log-index manage 权限的账户。ACP 基线默认值:platform-logging。

如果您已运行 OpenSearch 集群,请确保每个节点都安装了 analysis-ik,并且日志账户已存在。若要从头开始构建集群,请遵循 Alauda Container Platform OpenSearch 产品文档。

1.2 安装 Log Storage operator

Alauda Container Platform Log Storage Management 会在存储集群上安装 log-storage-operator。一个 operator 同时支持 ClickHouse 和 OpenSearch 后端;后端选择在第 1.4 节创建的 PlatformLogForward 中进行,而不是在 operator 安装表单中进行。

Console

  1. 导航到 Marketplace > Cluster Plugins,然后选择存储集群。
  2. 找到 Alauda Container Platform Log Storage Management,并单击其所在行中的 Install。
  3. 接受默认值。也可以选择设置节点选择器和容忍度,将 log-storage-operator 固定到 infra 节点。
  4. 单击 Install。

验证

kubectl -n cpaas-system get deployment log-storage-operator

READY 列必须显示 1/1。

1.3 创建连接 Secrets

cpaas-system 中的两个 Secret 携带外部堆栈的端点和凭据。log-storage-operator 使用其默认名称(platform-default-*)读取这些 Secret;请勿重命名。

本节中的每个命令都在存储集群上运行。

1.3.1 Kafka Secret

两个后端都需要此 Secret。

应用前编辑
  • bootstrap:Kafka bootstrap Service 的 FQDN:port 。示例 cpaas-kafka-kafka-bootstrap.cpaas-system.svc:9092 与第 1.1.1 节 RdsKafka 上的普通 SASL listener 匹配;如果您的 RdsKafka 使用其他名称,请更改主机名;只有在 RdsKafka 中额外启用了 tls: listener 时,才将端口更改为 :9093。
  • kafkaClusterName:您的 RdsKafka CR 的 metadata.name。
  • username:使用 RdsKafkaUser 创建的 SASL 账户(第 1.1.1 节使用 platform-logging)。
  • password:从 KafkaUser.spec.authentication.password.valueFrom 获取(明文 — operator 读取此 Secret,而不是 broker 读取的 K8s SASL Secret)。获取命令位于 manifest 下方。
  • 默认情况下关闭 TLS:此示例在 :9092 上使用普通 SASL。如果您在 RdsKafka 中启用了 tls: listener,请添加包含 broker CA PEM 的 tls.ca: key(可从 Secret <RdsKafka name>-cluster-ca-cert 的 ca.crt key 读取),并将 bootstrap 指向 :9093。

只有在替换上述所有占位符后才能应用。

apiVersion: v1
kind: Secret
metadata:
  name: platform-default-mq-conn
  namespace: cpaas-system
type: Opaque
stringData:
  # Required. Comma-separated host:port. The bootstrap Service name is
  # `<RdsKafka name>-kafka-bootstrap` and the plain SASL listener runs on
  # :9092. Defaults in this example match the RdsKafka in Section 1.1.
  bootstrap: "cpaas-kafka-kafka-bootstrap.cpaas-system.svc:9092"

  # Required. Name of the Kafka cluster CR.
  kafkaClusterName: "cpaas-kafka"

  # Required. SASL username.
  username: "platform-logging"

  # Required. SASL password.
  password: "<kafka-password>"

  # Optional. Defaults to SCRAM-SHA-512.
  # Allowed: SCRAM-SHA-512, SCRAM-SHA-256, PLAIN.
  sasl_mechanism: "SCRAM-SHA-512"

  # Optional. Topic names. Defaults shown. Must match the topics you created.
  topics.log: "ALAUDA_LOG_TOPIC"
  topics.event: "ALAUDA_EVENT_TOPIC"
  topics.audit: "ALAUDA_AUDIT_TOPIC"

  # SASL-over-TLS is optional. If you enabled the `tls:` listener in the
  # RdsKafka above, change `bootstrap` to port :9093 and add a `tls.ca` key
  # here with the broker CA PEM — read it from the strimzi-maintained
  # Secret `<RdsKafka name>-cluster-ca-cert` (key `ca.crt`). Omit `tls.ca`
  # entirely for the plain :9092 listener shown above.

读取当前未掌握的值:

# Bootstrap Service and its port
kubectl -n cpaas-system get svc cpaas-kafka-kafka-bootstrap

# Kafka SASL password (from the Secret you created in Section 1.1.1)
kubectl -n cpaas-system get secret platform-logging-password \
  -o jsonpath='{.data.password}' | base64 -d

# Kafka CA — ONLY needed if you enabled a `tls:` listener on the RdsKafka.
# Omit this step for the plain :9092 listener used by the default example.
#   kubectl -n cpaas-system get secret cpaas-kafka-cluster-ca-cert \
#     -o jsonpath='{.data.ca\.crt}' | base64 -d

将 manifest 保存为 platform-default-mq-conn.yaml 并应用:

kubectl apply -f platform-default-mq-conn.yaml
WARNING

请勿添加 tls.insecure_skip_verify: "true"。当 listener 使用 TLS 时,请提供 tls.ca;当使用明文时,请省略 tls.ca,并通过普通端口连接。

1.3.2 ClickHouse Secret

如果使用 OpenSearch,请跳过本节。

应用前编辑
  • endpoint:ClickHouse 的 HTTPS 或 HTTP URL,即原生 HTTP 接口(默认端口为 8123 / TLS 8443),不是原生 TCP 端口 9000。
  • username / password:operator 将用于连接的 ClickHouse 用户。示例中的 <clickhouse-password> 只是占位符,请在此处填写真实密码。该用户必须在日志数据库上拥有 CREATE DATABASE、CREATE TABLE、INSERT、SELECT(razor 的 schema-migrations job 会在首次运行时创建该数据库)。请在此处填写明文密码,而不是哈希值。一些 ClickHouse 部署指南(例如 ecosystem 团队的 deploy_as_logging_storage 操作指南)会要求你将 sha256_hex 摘要写入 ClickHouseInstallation manifest;该摘要供 ClickHouse 服务器本身使用。platform-default-ch-conn Secret 会由 razor-api / aggregate-vector 读取,以实际连接到 ClickHouse,因此其中必须使用匹配的明文值。混用二者会导致 PLF 进入 Ready 状态,但 schema-migrations Job 每次 CREATE TABLE ... ON CLUSTER 都因 516 Authentication failed 而失败。
  • tls.ca:仅当 ClickHouse 使用 HTTPS,且 K8s pod 尚未信任其证书时才需要。将 <clickhouse-ca-certificate> 替换为 PEM 块;使用 HTTP 或系统已信任的 CA 时,请将其移除。

请仅在替换上述所有占位符后应用。

apiVersion: v1
kind: Secret
metadata:
  name: platform-default-ch-conn
  namespace: cpaas-system
type: Opaque
stringData:
  # Required. HTTP endpoint, scheme and port included.
  #   http://…:8123     (plain HTTP)
  #   https://…:8443    (HTTPS)
  endpoint: "http://clickhouse-cpaas-clickhouse.cpaas-system.svc:8123"

  # Required. Must match spec.configuration.clusters[0].name on the CHI.
  # ACP baseline default: replicated
  cluster: "replicated"

  # Required. Target database. Must exist. ACP baseline default: observability
  database: "observability"

  # Required. Account with full permission on the target database.
  # ACP baseline default: platform-logging
  username: "platform-logging"
  password: "<clickhouse-password>"

  # Optional. TLS CA for HTTPS with a private CA. Omit for plain HTTP or a
  # trusted CA.
  tls.ca: |-
    -----BEGIN CERTIFICATE-----
    <clickhouse-ca-certificate>
    -----END CERTIFICATE-----

读取值:

# ClickHouse Service and port
kubectl -n cpaas-system get svc -l clickhouse.altinity.com/chi=cpaas-clickhouse

# Cluster name, database, shards, replicas
kubectl -n cpaas-system get chi cpaas-clickhouse \
  -o jsonpath='{"cluster="}{.spec.configuration.clusters[0].name}{"  database="}{.spec.configuration.settings.default_database}{"  shards="}{.spec.configuration.clusters[0].layout.shardsCount}{"  replicas="}{.spec.configuration.clusters[0].layout.replicasCount}{"\n"}'

应用:

kubectl apply -f platform-default-ch-conn.yaml
WARNING

请勿添加 tls.insecure_skip_verify: "true"。对于 HTTPS 端点,请提供 tls.ca;对于普通 HTTP 端点,请将其省略。

1.3.3 OpenSearch Secret

如果使用 ClickHouse,请跳过本节。

应用前编辑
  • endpoints:OpenSearch 的 HTTPS 或 HTTP URL(默认端口为 9200)。多节点协调时使用逗号分隔。
  • username / password:operator 将用于连接的 OpenSearch 账户。示例中的 <opensearch-password> 只是占位符,请在此处填写真实密码。该用户必须能够管理日志索引模式上的索引模板和 ILM 策略。
  • tls.ca:仅当 OpenSearch 使用 HTTPS,且 K8s pod 尚未信任其证书时才需要。对于 HTTP 或系统已信任的 CA,请移除整个 tls.ca 键。

请仅在替换上述所有占位符后应用。

apiVersion: v1
kind: Secret
metadata:
  name: platform-default-os-conn
  namespace: cpaas-system
type: Opaque
stringData:
  # Required. Comma-separated HTTP(S) URLs. Put the highly-available
  # coordinator or load balancer first; some data paths use only the first
  # entry.
  endpoints: "https://cpaas-opensearch.cpaas-system.svc:9200"

  # Required unless the OpenSearch cluster allows anonymous access.
  # ACP baseline default: platform-logging
  username: "platform-logging"
  password: "<opensearch-password>"

应用:

kubectl apply -f platform-default-os-conn.yaml
INFO

OpenSearch Secret 不包含 tls.ca 字段。平台连接 OpenSearch 时会禁用证书验证,因此使用私有 CA 的端点无需在此处提供 CA 材料。在 endpoints 中使用 https://,无论签发者是谁,连接都能成功。

1.4 创建 PlatformLogForward

PlatformLogForward(PLF)是集群范围的 CR,log-storage-operator 会监视它以构建数据路径。它始终命名为 platform-default,每个存储集群恰好有一个。

应用前编辑

以下三个部分与环境相关——在执行 kubectl apply 前,请选择与集群规模匹配的值:

  • externalStorage.shards / .replicas 必须与第 1.1.2 节中选择的 ClickHouse 配置匹配。将它们设置得低于 ClickHouse 拓扑会导致部分节点在无提示的情况下闲置;将它们设置得更高则会使数据路径访问不存在的节点。单节点评估 = 1 / 1;三节点 HA = 1 / 3;六节点横向扩展 = 2 / 3;九节点横向扩展 = 3 / 3。
  • aggregateVector.replicas 用于扩展 Kafka→ClickHouse ingest 层。评估环境 = 1;生产环境 = 3(operator 默认值),高 ingest 吞吐量场景还应进一步提高。
  • razor.replicas 和 razor.resources 用于扩展为 razor-api 提供服务的查询平面。以下示例值是每个 pod 的合理基线;查询负载较高的生产环境应提高副本数(3 个以上),并根据预期的并发查询预算调整限制。

请仅在三个容量规划选择与目标拓扑匹配后应用。

apiVersion: log.alauda.io/v1alpha1
kind: PlatformLogForward
metadata:
  name: platform-default                            # fixed singleton name; do not change
spec:
  output:
    type: clickhouse                                # required for ClickHouse
  externalStorage:
    type: clickhouse
    shards: 1                                       # match the profile from Section 1.1.2
    replicas: 1                                     # match the profile from Section 1.1.2
    secretRef:
      name: platform-default-ch-conn
      namespace: cpaas-system
  externalMessageQueue:
    type: kafka
    secretRef:
      name: platform-default-mq-conn
      namespace: cpaas-system
  aggregateVector:
    replicas: 1                                     # Kafka→CH ingest tier; raise to 3+ for production throughput
  razor:
    replicas: 1                                     # query-plane serving tier; raise for heavier query load
    resources:
      limits:
        cpu: "4"
        memory: 2Gi
      requests:
        cpu: "1"
        memory: 512Mi

对于 OpenSearch:

应用前编辑

为与 ClickHouse schema 保持一致,OpenSearch 分支仍接受 externalStorage.shards / .replicas,但 OpenSearch 会在每个索引上自行管理分片/副本分配。将它们设置为 1 / 1 对所有拓扑都是安全的——这些字段仅供 operator 参考,不会传递到 OpenSearch 集群。按照上面 ClickHouse 分支中的方式扩展 aggregateVector.replicas 和 razor.replicas。

apiVersion: log.alauda.io/v1alpha1
kind: PlatformLogForward
metadata:
  name: platform-default                            # fixed singleton name; do not change
spec:
  # No `output.type` on OpenSearch — `externalStorage.type` is the source of
  # truth for backend routing (added in pt L, 2026-08). The ClickHouse branch
  # predates that refactor and its admission + provisioning paths still read
  # `output.type: clickhouse`; the OpenSearch branch was added after and never
  # inherited that legacy field. Setting `output.type: clickhouse` on an
  # OpenSearch PLF is accepted but ignored — the scenario is still routed
  # by `externalStorage.type`.
  externalStorage:
    type: opensearch
    shards: 1                                       # informational on the OS branch; keep as 1
    replicas: 1                                     # informational on the OS branch; keep as 1
    secretRef:
      name: platform-default-os-conn
      namespace: cpaas-system
  externalMessageQueue:
    type: kafka
    secretRef:
      name: platform-default-mq-conn
      namespace: cpaas-system
  aggregateVector:
    replicas: 1                                     # Kafka→OS ingest tier; raise to 3+ for production throughput
  razor:
    replicas: 1                                     # query-plane serving tier; raise for heavier query load
    resources:
      limits:
        cpu: "4"
        memory: 2Gi
      requests:
        cpu: "1"
        memory: 512Mi

将文件保存为 platform-log-forward.yaml 并应用:

kubectl apply -f platform-log-forward.yaml

监视资源,直到 Phase 变为 Ready 且 Ready 变为 True,然后使用 Ctrl-C 停止:

kubectl get platformlogforward platform-default -w

如果大约十分钟后仍未进入 Ready 状态,请读取状态条件:

kubectl get platformlogforward platform-default \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

仅在需要时设置的可选字段:

字段默认值设置时机
spec.aggregateVector.replicas3在单节点评估集群上降低为 1。
spec.razor.replicas2相同指导原则。
spec.razor.resources.limits.cpu1如果观察到 collector 端缓冲区增长并伴随 Razor CPU 饱和,请提高到 2–4。
spec.clickhouse.ttl.*请参阅 plugin 文档更改每种日志类型的保留期限。
spec.clickhouse.tieredPolicy + spec.clickhouse.coldTTL + spec.clickhouse.s3ColdSecretRef(已禁用)在 S3 上启用 ClickHouse 热冷分层存储。请参阅 ClickHouse S3 Storage。
Adopt 模式不适用于全新安装

当 log-storage-operator 在已包含来自旧版 ACP 4.2 或 4.3 安装的 chart 管理型 ClickHouse 或 Kafka 资源的集群上启动时,它会自行创建带有 installMode: Adopt 的 PlatformLogForward/platform-default,以便以非破坏方式继续迁移。

在全新安装中不应发生这种情况。如果在应用 manifest 前,kubectl get platformlogforward platform-default 返回了一个资源,并且其 spec.installMode 为 Adopt,则表示集群中的某些内容被误判为旧版安装。请删除自动创建的对象,并一步重新应用你的对象,以进行恢复:

kubectl delete platformlogforward platform-default && kubectl apply -f platform-log-forward.yaml

kubectl -n cpaas-system annotate secret platform-default-mq-conn platform-default-ch-conn \
  log.alauda.io/derived-by=sre-managed --overwrite

对于 OpenSearch,请将 platform-default-ch-conn 替换为 platform-default-os-conn。

如果集群确实包含旧版日志数据(存在 AppRelease/logclickhouse,或之前 ACP 版本创建的 PVC 仍处于绑定状态),请在此处停止,并改为按照 Upgrade from Log Storage for Elasticsearch 和 Historical Data Migration 中的说明操作。

2. 安装 Log Collector

在需要收集日志、事件或审计记录的每个集群上安装此插件。如果还需要收集 global 集群自身的数据,则该集群也包括在内。

控制台

  1. 前往 Marketplace > 集群插件,然后选择目标集群。
  2. 找到 Alauda Container Platform Log Collector,并点击其所在行中的 安装。
  3. 配置参数:
参数值
Log Center Plugin设置为 Standard。这是由 log-storage-operator 管理的当前数据路径,适用于 ClickHouse 和 OpenSearch 后端。同一下拉菜单中的 ClickHouse 和 ElasticSearch 选项属于早期版本通过 chart 安装的堆栈;在 ACP 4.4 中,这些选项仅供 collector 仍指向通过 chart 安装的存储集群的升级客户使用。全新安装必须选择 Standard。
Storage Cluster Name输入 PlatformLogForward/platform-default 为 Ready 的集群名称。如果 collector 和存储位于同一集群,请输入该集群的名称。在 Standard 分支中,此字段为纯文本输入框。
Storage Pathcollector 本地工作数据的绝对路径。默认值为 /cpaas/data/nevermore。在 Alauda OS 节点上使用 /var/cpaas/data/nevermore。安装后无法更改。
Mount Paths可选。包含 collector 必须读取的日志文件的主机绝对路径。
Audit、Event、Kubernetes、Platform、System、Workload要收集的日志类型。默认启用 Audit、Event、System 和 Workload。
  1. 可选。展开高级表单,通过节点选择器和容忍度将 collector 固定到特定节点。
  2. 点击 安装。

YAML

应用前请先编辑

每个 <...> 都是占位符,版本字符串仅为示例。直接应用会失败 — ACP 的 cluster-transformer 会拒绝 ModuleInfo,原因可能是名称/标签无法解析,或版本未注册。

  • 将 metadata.labels.cpaas.io/cluster-name 和 metadata.name 中的两个 <collector-cluster> 替换为运行 collector 的集群名称。两者必须一致,且 K8s 名称约束不允许使用 < / > / 大写字母。
  • 将 spec.config.crossClusterDependency.logstorage 中的 <storage-cluster> 替换为 PlatformLogForward/platform-default 处于 Ready 状态的集群。
  • 将 spec.version: v4.4.0 替换为集群实际使用的版本:kubectl get moduleconfigs | grep logagent,并复制一个 logagent-v4.4.x 名称。必须存在针对所设版本的 ModuleConfig CR,否则 webhook 会以 moduleconfig <name> not found 拒绝请求。
  • 检查 spec.config.dataSource.* 和 spec.config.components.nevermore.storageSpec.dataDir:对于标准 Alauda 主机,默认值适用;但 Alauda OS 使用 /var/cpaas/data/nevermore,而隔离网络站点可能需要使用其他卷。

请仅在替换上述所有占位符后应用。

apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleInfo
metadata:
  annotations:
    cpaas.io/display-name: logagent
    cpaas.io/module-name: '{"en": "Alauda Container Platform Log Collector", "zh": "Alauda Container Platform Log Collector"}'
  labels:
    cpaas.io/cluster-name: <collector-cluster>
    cpaas.io/module-name: logagent
    cpaas.io/module-type: plugin
    cpaas.io/product: Platform-Center
  name: <collector-cluster>-logagent
spec:
  version: v4.4.0                                   # substitute the version reported by ModuleConfig
  config:
    crossClusterDependency:
      logstorage: <storage-cluster>                 # cluster where PlatformLogForward is Ready
    dataSource:
      audit: true
      event: true
      kubernetes: false
      platform: false
      system: true
      workload: true
    components:
      nevermore:
        storageSpec:
          dataDir: /cpaas/data/nevermore            # on Alauda OS: /var/cpaas/data/nevermore
    storage:
      type: Standard                                # v4.4 data path via log-storage-operator

关键字段:

字段说明
spec.config.crossClusterDependency.logstoragePlatformLogForward/platform-default 为 Ready 的存储集群名称。v4.4 Standard 分支通过此单一字段同时指定 ClickHouse 和 OpenSearch。不要设置旧版 logcenter 或 logclickhouse 键。
spec.config.storage.type在全新的 4.4 安装中必须设为 Standard。ClickHouse 和 ElasticSearch 保留供 collector 仍指向通过 chart 安装的存储集群的升级客户使用;新部署请勿使用。
spec.config.dataSource.*要收集的日志类型。
spec.config.components.nevermore.storageSpec.dataDir节点上的本地工作数据路径。安装后无法更改。

验证

在 global 集群中运行:

kubectl get moduleinfo -l cpaas.io/module-name=logagent

每个 collector 集群对应的行都必须显示 STATUS=Running。

3. 安装 Log Essentials

在 global 集群中运行。 每个平台安装一次。安装流程与早期版本保持不变。

控制台

  1. 导航至 Marketplace > 集群插件,选择 global 集群。
  2. 找到 Alauda Container Platform Log Essentials,然后点击其所在行中的 安装。
  3. 接受默认设置,然后点击 安装。

YAML

应用前编辑

将 spec.version: v4.4.0 替换为集群中实际注册的版本:kubectl get moduleconfigs | grep log-api,并复制一个 log-api-v4.4.x 名称。如果该版本未注册,cluster-transformer 会以 moduleconfig <name> not found 拒绝此 ModuleInfo。metadata.name(global-log-api)和 metadata.labels.cpaas.io/cluster-name(global)是固定值 — log-api 插件仅是全局集群组件。

apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleInfo
metadata:
  annotations:
    cpaas.io/display-name: log-api
    cpaas.io/module-name: '{"en": "Alauda Container Platform Log Essentials", "zh": "Alauda Container Platform Log Essentials"}'
  labels:
    cpaas.io/cluster-name: global
    cpaas.io/module-name: log-api
    cpaas.io/module-type: plugin
    cpaas.io/product: Platform-Center
  name: global-log-api
spec:
  version: v4.4.0                                   # substitute the version reported by ModuleConfig

验证

kubectl get moduleinfo -l cpaas.io/module-name=log-api

STATUS 列必须为 Running。

4. 端到端验证

每个插件都处于 Running 状态后,验证新记录是否确实从 collector 集群流入存储后端。

  1. 在每个存储集群上:

    kubectl get platformlogforward platform-default \
      -o jsonpath='{"phase="}{.status.phase}{"  ready="}{.status.conditions[?(@.type=="Ready")].status}{"\n"}'

    必须显示 Ready / True。

  2. 在每个存储集群上:

    kubectl -n cpaas-system get pods -l app.kubernetes.io/managed-by=log-storage-operator

    aggregate-vector-* 和 razor-* Pod 必须处于 Running 状态;schema-migrations-* Job 必须显示 STATUS=Completed。

  3. 登录 ACP 控制台,打开 Operations Center > 日志 > 日志查询分析,在页面顶部的集群选择器中选择存储集群,然后查询正在产生日志的命名空间中的 工作负载日志。应显示最近的记录。

如果十分钟内没有记录到达,在更改配置之前,请按顺序检查各层:collector ModuleInfo 状态 → PlatformLogForward 条件 → Kafka 主题活动 → 后端摄取。

后续步骤

当上述每个插件都报告已安装后:

  • 按照 如何验证全新安装的日志堆栈 中的七步检查清单进行操作,确认写入路径和读取路径均端到端正常工作。
  • 如果某个步骤失败,请直接跳转到 排查日志堆栈问题 中的对应条目。
  • 最终停用此安装时,请按照 如何卸载日志堆栈 进行操作。外部 ClickHouse(或 OpenSearch)集群、外部 Kafka 集群以及两个由 SRE 编写的连接 Secret 不属于插件生命周期的一部分;该页面列出了回收每项资源所需的确切命令。