#配置 Fleet Monitoring

#概述

Fleet Monitoring 使用两项服务：

• Alauda Container Platform Fleet Monitoring Central Service 在 global 集群上运行，并启用 Fleet Monitoring 的 Global 侧功能。
• Alauda Container Platform Fleet Monitoring Cluster Service 在要纳入 Fleet Monitoring 的每个集群上运行。

启用 Fleet Monitoring 后，已连接的集群会将 fleet 级指标写入 Global VictoriaMetrics 存储。内置 Fleet Monitoring 监控面板使用这些指标显示 fleet 健康状况、资源使用情况、数据新鲜度和项目配额使用情况。

#开始之前

配置 Fleet Monitoring 前，请确保满足以下要求：

• 你具有平台管理员权限，或具有安装 Operator 和创建 Fleet Monitoring 资源所需的权限。
• Global 集群具有可用的 Fleet Monitoring 数据 remote write 端点。支持带 write 端点的 VictoriaMetrics。如果 Monitoring 功能公开的端点接受 remote write 流量，也可以使用基于 Prometheus 或 Thanos 的 Monitoring。
• 要连接的每个集群都由 Global 集群管理。
• 要连接的每个集群都已启用 Monitoring 功能。
• Fleet Monitoring Operator 软件包已推送到所需集群，或已在 OperatorHub 中可用。Fleet Monitoring 以 Agnostic Operator 的形式交付，默认不包含在平台安装中。
• New Web Console 插件部署功能可用。Fleet Monitoring Operator 通过 New Web Console OperatorHub 工作流部署。有关更多信息，请参阅安装 New Web Console。

#推送 Fleet Monitoring Operator 软件包

在从 OperatorHub 安装 Fleet Monitoring 前，使用 violet 推送 Fleet Monitoring Operator 软件包。

将 Alauda Container Platform Fleet Monitoring Central Service 推送到 Global 集群：

violet push <path/to/fleet-monitoring-central-service-operator-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --clusters "global"

将 Alauda Container Platform Fleet Monitoring Cluster Service 推送到要安装 Cluster Service 的每个集群。如果还要将 Global 集群纳入 Fleet Monitoring 数据，请在集群列表中包含 global：

violet push <path/to/fleet-monitoring-cluster-service-operator-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --clusters "global,<workload-cluster-1>,<workload-cluster-2>"

推送软件包后，相应的 Operator 会显示在所选集群的 Marketplace > OperatorHub 中。有关 violet push 的更多信息，请参阅上架软件包。

#在 Global 集群上启用 Fleet Monitoring

1. 转到 Administrator。

2. 在左侧导航栏中，单击 Marketplace > OperatorHub。

3. 在页面顶部，选择 global 集群。

4. 搜索 Alauda Container Platform Fleet Monitoring Central Service。

5. 如果 Operator 状态不是 Installed，单击 Install。除非环境需要不同的 channel、namespace 或升级策略，否则保留默认安装配置。

   参数	推荐配置
   Channel	使用 Operator 软件包提供的默认 channel。
   Installation Mode	Cluster。Operator 管理该集群的 Fleet Monitoring 资源。
   Installation Place	使用 Operator 软件包提供的推荐 namespace。
   Upgrade Strategy	Manual，除非平台升级策略要求自动升级。

6. 在 OperatorHub 中确认 Alauda Container Platform Fleet Monitoring Central Service 的状态为 Installed。

   如果选择 Manual 升级策略，且 OperatorHub 显示待处理的安装计划，请批准该安装计划以完成安装。

7. 确认 Global 集群具有可用的 VictoriaMetrics write 端点。

   Fleet Monitoring 使用 Global VictoriaMetrics write 端点接收来自已连接集群的数据。如果 Global 集群只有 Prometheus 或 Thanos Query 可用，则已连接集群无法将 Fleet Monitoring 数据写入 Global 集群。

8. 在 Global 集群上创建 FleetMonitoringHub 资源。

   apiVersion: monitoring.alauda.io/v1alpha1
   kind: FleetMonitoringHub
   metadata:
     name: fleet-monitoring-hub
   spec: {}

   FleetMonitoringHub 是集群范围的资源。请勿设置 metadata.namespace。

   字段	必需	描述
   metadata.name	是	必须为 fleet-monitoring-hub。
   metadata.namespace	否	请勿设置此字段。FleetMonitoringHub 是集群范围的资源。
   spec	是	使用空对象 {}。创建资源会启用 Fleet Monitoring 的 Global 侧功能。

9. 验证 FleetMonitoringHub 状态。

   kubectl get fleetmonitoringhub fleet-monitoring-hub -o yaml

   检查以下条件是否已就绪：

   条件	描述
   ConfigurationReady	Global 存储和数据库信息可用。
   DashboardsReady	已应用内置 Fleet Monitoring 监控面板。
   GlobalRulesReady	已应用 Global 记录规则。

   也可以检查阶段：

   kubectl get fleetmonitoringhub fleet-monitoring-hub -o jsonpath='{.status.phase}{"\n"}'

   预期阶段为 Ready。

#将集群连接到 Fleet Monitoring

在要纳入 Fleet Monitoring 的每个集群上重复执行以下步骤。

1. 转到 Administrator。

2. 在左侧导航栏中，单击 Marketplace > OperatorHub。

3. 在页面顶部，选择目标集群。

4. 搜索 Alauda Container Platform Fleet Monitoring Cluster Service。

5. 如果 Operator 状态不是 Installed，单击 Install。除非环境需要不同的 channel、namespace 或升级策略，否则保留默认安装配置。

   参数	推荐配置
   Channel	使用 Operator 软件包提供的默认 channel。
   Installation Mode	Cluster。Operator 管理所选集群的 Fleet Monitoring 资源。
   Installation Place	使用 Operator 软件包提供的推荐 namespace。
   Upgrade Strategy	Manual，除非平台升级策略要求自动升级。

6. 在 OperatorHub 中确认 Alauda Container Platform Fleet Monitoring Cluster Service 的状态为 Installed。

   如果选择 Manual 升级策略，且 OperatorHub 显示待处理的安装计划，请批准该安装计划以完成安装。

7. 在目标集群上创建 FleetMonitoringAgent 资源。

   apiVersion: monitoring.alauda.io/v1alpha1
   kind: FleetMonitoringAgent
   metadata:
     name: fleet-monitoring-agent
   spec:
     interval: 5m

   FleetMonitoringAgent 是集群范围的资源。请勿设置 metadata.namespace。

   字段	必需	描述
   metadata.name	是	必须为 fleet-monitoring-agent。
   metadata.namespace	否	请勿设置此字段。FleetMonitoringAgent 是集群范围的资源。
   spec.interval	否	采集间隔。支持的值为 5m、10m、15m 和 30m。默认值为 5m。

   若要将 Global 集群本身纳入 Fleet Monitoring 数据，还需在 Global 集群上安装 Alauda Container Platform Fleet Monitoring Cluster Service，并在那里创建 FleetMonitoringAgent 资源。

8. 验证 FleetMonitoringAgent 状态。

   kubectl get fleetmonitoringagent fleet-monitoring-agent -o yaml

   检查以下条件：

   条件	描述
   ConfigurationReady	集群名称、本地 Monitoring 访问信息和数据库信息可用。
   ResourcesApplied	已应用 Fleet Monitoring 资源，例如规则和 workload 资源。
   Ready	集群已准备好写入 Fleet Monitoring 数据，或因受支持的原因而被有意跳过。

   也可以检查阶段和检测到的集群名称：

   kubectl get fleetmonitoringagent fleet-monitoring-agent -o jsonpath='Phase: {.status.phase}{"\n"}Cluster: {.status.cluster}{"\n"}'

   预期阶段为 Ready。常见的 Ready 原因包括：

   • WorkloadReady：集群部署了 VMAgent，已准备好写入 Fleet Monitoring 数据。
   • SkippedForGlobal：该集群是 Global 集群，因此 Cluster Service 跳过向同一 Global 存储部署 VMAgent。
   • SkippedBackendReuse：集群复用了 Global VictoriaMetrics 后端，因此 Cluster Service 跳过部署 Fleet Monitoring VMAgent，以避免写入环路。

   如果目标集群向 Global 存储写入数据，请确认数据库信息可用：

   kubectl -n <fleet-monitoring-namespace> get secret fleet-monitoring-database

   将 <fleet-monitoring-namespace> 替换为安装 Alauda Container Platform Fleet Monitoring Cluster Service 的 namespace。

9. 打开 Platform > Observe > Fleet Monitoring，确认集群显示在监控面板数据中。

#升级 Fleet Monitoring

Fleet Monitoring 通过安装时使用的同一 OperatorHub 工作流进行升级。升级不会删除 Fleet Monitoring 数据。已连接集群写入 Global 存储的指标仍然可用。

#兼容性矩阵

下表列出了支持的版本：

#升级路径指南

• 补丁级升级：同一 minor 版本内的 patch 版本之间兼容，可以直接升级，例如 1.0.0 → 1.0.1。
• 升级顺序：先升级 Global 集群上的 Alauda Container Platform Fleet Monitoring Central Service，再升级每个已连接集群上的 Alauda Container Platform Fleet Monitoring Cluster Service。
• 两项服务在升级窗口期间可以运行不同版本。Global 集群升级期间，已连接集群会继续写入 Fleet Monitoring 数据。

#升级操作步骤

1. 使用 violet push 推送新的 Operator 软件包，方式与初始安装相同。将 Central Service 软件包推送到 Global 集群，并将 Cluster Service 软件包推送到每个已连接集群。

2. 转到 Administrator > Marketplace > OperatorHub，然后选择目标集群。

3. 打开 Fleet Monitoring Operator 并开始升级。

   • 使用 Automatic 升级策略时，OperatorHub 会在新版本可用后升级 Operator。
   • 使用 Manual 升级策略时，请批准待处理的安装计划以开始升级。

4. 在运行 Fleet Monitoring Operator 的每个集群上重复前两步。

5. 确认已安装新版本。

   kubectl -n <fleet-monitoring-namespace> get csv

   Fleet Monitoring ClusterServiceVersion 必须以 Succeeded 阶段报告新版本。

6. 按照前面章节中的说明，再次验证 FleetMonitoringHub 和 FleetMonitoringAgent 状态。

请注意以下事项：

• 升级时不要删除并重新创建 FleetMonitoringHub 或 FleetMonitoringAgent。这两个资源都会保留，并由新 Operator 版本进行协调。
• 如果新版本提供了新的 VMAgent 镜像，部署 VMAgent 的集群上的 Fleet Monitoring VMAgent pod 会重启。采集会在重启期间暂停，然后自动恢复。

#配置采集间隔

采集间隔在每个已连接集群的 FleetMonitoringAgent 资源上配置。

支持的值：

• 5m
• 10m
• 15m
• 30m

示例：

apiVersion: monitoring.alauda.io/v1alpha1
kind: FleetMonitoringAgent
metadata:
  name: fleet-monitoring-agent
spec:
  interval: 10m

更新 spec.interval 后，Fleet Monitoring Cluster Service 会协调本地采集配置。

在部署 Fleet Monitoring VMAgent 的集群上，VMAgent 采集间隔遵循 spec.interval，而 Fleet Monitoring 记录规则继续按照系统为联邦配置的间隔进行评估。在 Global 集群以及复用 Global VictoriaMetrics 后端、无需部署 Fleet Monitoring VMAgent 的集群上，本地 Fleet Monitoring 规则遵循 spec.interval。

#配置自定义指标和记录规则

Fleet Monitoring 包含内置指标和记录规则。集群管理员可以在每个已连接集群上追加自定义指标和记录规则。

要将用户定义的指标报告到 Fleet Monitoring，请使用以下工作流：

1. 在已连接的业务集群上定义本地 Fleet 记录规则，将源指标转换为 Fleet 指标名称。
2. 将该记录指标名称添加到 Fleet allowlist，使 Fleet Monitoring VMAgent 将其联邦并 remote-write 到 Global 集群。
3. 如果需要 1 小时聚合等 Fleet 级汇总，请在 Global 集群上另行添加自定义 Hub 侧 PrometheusRule。
4. 使用 Fleet Monitoring 查询或监控面板验证记录指标和汇总指标。

#确定是否仅需要 Agent 侧规则，还是同时需要 Agent 侧和 Hub 侧规则

选择以下模式之一：

• 需要 Global 集群上的原始 Fleet 指标并可以直接查询时，仅使用已连接集群的 ConfigMap。
• 如果还需要用于监控面板或长期视图的 1 小时聚合等 Fleet 级汇总，则同时使用已连接集群的 ConfigMap 和 Global 集群自定义 PrometheusRule。

目标示例：

• 已连接集群上的源指标：node_load15
• 已连接集群上记录的 Fleet 指标：fleet:node:node_load15:avg
• Global 集群上的可选 1 小时汇总：fleet:node:node_load15:avg:avg_over_time_1h

#配置已连接集群

在已连接集群上安装 Alauda Container Platform Fleet Monitoring Cluster Service 的 namespace 中，创建或更新 fleet-monitoring-custom-metrics ConfigMap。

此 ConfigMap 有两个作用：

• metrics.yaml 将指标名称添加到 Fleet Monitoring VMAgent federate allowlist。
• recording-rules-prometheus.yaml 或 recording-rules-victoriametrics.yaml 定义生成 Fleet 指标的本地记录规则。

示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: fleet-monitoring-custom-metrics
  namespace: <fleet-monitoring-namespace>
data:
  metrics.yaml: |
    default:
      - fleet:node:node_load15:avg
  recording-rules-prometheus.yaml: |
    groups:
      - name: fmval-custom
        rules:
          - record: fleet:node:node_load15:avg
            expr: avg by (node) (node_load15)
  recording-rules-victoriametrics.yaml: |
    groups:
      - name: fmval-custom
        rules:
          - record: fleet:node:node_load15:avg
            expr: avg by (node) (node_load15)

将 <fleet-monitoring-namespace> 替换为安装 Alauda Container Platform Fleet Monitoring Cluster Service 的 namespace。

metrics.yaml 会将指标名称追加到内置 allowlist。

对于记录规则，Cluster Service 仅加载与本地 Monitoring 堆栈匹配的键：

• 基于 Prometheus 的集群使用 recording-rules-prometheus.yaml
• 基于 VictoriaMetrics 的集群使用 recording-rules-victoriametrics.yaml

自定义配置可以追加指标和规则，但不会删除或覆盖内置默认值。

如果 ConfigMap 格式无效或包含无效规则，Fleet Monitoring 会保留内置默认值，并在 FleetMonitoringAgent 状态中报告错误。

在部署 Fleet Monitoring VMAgent 的已连接业务集群中，Agent reconciler 会将渲染后的 Fleet Monitoring 记录规则组间隔规范化为 1m。不要依赖 ConfigMap 中的自定义间隔值来控制最终渲染的本地 Fleet Monitoring 规则间隔。

对于自定义 Fleet 指标，请使用 Fleet 命名约定记录指标，例如 fleet:node:node_load15:avg。这样可以确保指标与 Fleet Monitoring 监控面板、汇总和查询模式兼容。

Fleet Monitoring 查询和监控面板要求记录的时间序列带有 cluster 标签。当规则尚未定义该标签时，Agent reconciler 会自动向渲染后的 Fleet Monitoring 记录规则添加 cluster=<local-cluster-name>。

#验证已连接集群的渲染结果

更新 ConfigMap 后，Fleet Monitoring Agent 会自动协调本地规则和 VMAgent 配置，无需重启。

检查渲染后的本地规则：

kubectl -n <fleet-monitoring-namespace> get prometheusrule fleet-monitoring-agent-recording-rules -o yaml

确认：

• 自定义组显示在 spec.groups 中
• 自定义记录指标显示在规则列表中
• 渲染后的规则带有 labels.cluster=<connected-cluster-name>

检查渲染后的 VMAgent federate allowlist：

kubectl -n <fleet-monitoring-namespace> get configmap fleet-monitoring-vmagent -o yaml

确认自定义记录指标显示在 data.prometheus.yml 的 params.match[] 下。

#添加自定义 Hub 汇总规则

如果希望自定义 Fleet 指标具有 1 小时聚合等 Fleet 级汇总，请在 Global 集群上、安装 Alauda Container Platform Fleet Monitoring Central Service 的 namespace 中创建单独的 PrometheusRule。

示例：

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: fmval-custom-hub-rollup
  namespace: <fleet-monitoring-namespace>
  labels:
    prometheus: kube-prometheus
    rule.cpaas.io/is-record: "true"
    alert.cpaas.io/owner: System
    alert.cpaas.io/project: ""
    monitoring.alauda.io/hub: fleet-monitoring-hub
spec:
  groups:
    - name: fmval-custom-rollup-1h
      interval: 1h
      rules:
        - record: fleet:node:node_load15:avg:avg_over_time_1h
          expr: avg_over_time(fleet:node:node_load15:avg[1h])

将 <fleet-monitoring-namespace> 替换为安装 Alauda Container Platform Fleet Monitoring Central Service 的 namespace。

此自定义 PrometheusRule 是追加配置，不需要复制内置 Hub 规则，也不应使用 Fleet Monitoring operator 所有权元数据创建。

#验证 Hub 侧汇总

检查自定义 Hub 侧规则：

kubectl -n <fleet-monitoring-namespace> get prometheusrule fmval-custom-hub-rollup -o yaml

确认：

• 规则存在于 Global 集群上
• 规则使用预期的 Fleet 指标作为输入
• 汇总输出指标名称与计划使用的监控面板或查询表达式一致

#查询自定义 Fleet 指标

通过平台 Monitoring API 或 Fleet Monitoring 监控面板查询 Fleet 指标时，请在选择器中明确包含 vmcluster=~".*"。在当前平台查询路径中，省略此选择器可能导致查询代理将查询范围缩小到 Global Monitoring 后端，并且不返回已连接集群的 Fleet 数据。

查询示例：

• 原始自定义 Fleet 指标：

  avg_over_time(fleet:node:node_load15:avg{vmcluster=~".*",cluster="g1-c1"}[1h])

• 1 小时汇总指标：

  last_over_time(fleet:node:node_load15:avg:avg_over_time_1h{vmcluster=~".*",cluster="g1-c1"}[2h])

#常见错误

请注意以下问题：

• 在 cpaas-system 中创建 fleet-monitoring-custom-metrics，但 Fleet Monitoring 安装在其他 namespace（例如 fleet-monitoring）中
• 将源指标名称而不是记录的 Fleet 指标名称添加到 metrics.yaml
• 定义本地记录规则，却未将记录的 Fleet 指标名称添加到 metrics.yaml
• 期望已连接集群 ConfigMap 中的自定义间隔在渲染后仍然有效
• 查询 Fleet 指标时未在选择器中包含 vmcluster=~".*"
• 尚未创建相应的自定义 Hub 侧规则，却期望 Global Fleet 汇总指标已经存在

#验证数据新鲜度

连接集群后，打开 Platform > Observe > Fleet Monitoring，在概览监控面板上检查以下信息：

• Connected Clusters
• Stale Clusters
• Last Write Ago
• Data Freshness Exceptions

如果集群显示在 Cluster 变量中，但未计入已连接集群，则该集群可能已被平台识别，但尚未写入 Fleet Monitoring 数据。检查该集群是否已从 OperatorHub 安装 Alauda Container Platform Fleet Monitoring Cluster Service，并且具有已就绪的 FleetMonitoringAgent。

#故障排除

#未显示 Fleet Monitoring 数据

检查以下项目：

• Global 集群已安装 Alauda Container Platform Fleet Monitoring Central Service。
• FleetMonitoringHub 资源存在且条件已就绪。
• Global 集群具有可用的 VictoriaMetrics 存储和 write 端点。仅 Prometheus 的 Monitoring 无法接收 Fleet Monitoring remote write 数据。
• 已应用内置监控面板和 Global 规则。

#Connected Clusters 中缺少集群

在目标集群上检查以下项目：

• 已安装 Alauda Container Platform Fleet Monitoring Cluster Service。
• FleetMonitoringAgent 资源存在。
• 集群由 Global 集群管理。
• 集群已启用 Monitoring 功能。
• FleetMonitoringAgent 状态未报告缺少数据库信息或 Monitoring 功能信息无效。
• fleet-monitoring-database Secret 包含指向 Global VictoriaMetrics write 端点的 remoteWriteURL。
• fleet-monitoring-vmagent 日志未报告 remote write 错误。如果日志显示 405 Method Not Allowed，则 remoteWriteURL 可能指向 Prometheus 或 Thanos Query 端点，而不是 VictoriaMetrics write 端点。

#自定义监控面板未显示在 Fleet Monitoring 中

检查该监控面板是否在 Global 集群上创建，并带有以下标签：

cpaas.io/dashboard.tag.fleet-monitoring: "true"

不带此标签的监控面板没有 fleet-monitoring 标签，因此不会列在 Fleet Monitoring 的 Switch 列表中。

同时检查监控面板资源的 namespace。Fleet Monitoring 页面会列出安装 Alauda Container Platform Fleet Monitoring Central Service 的 namespace 中的监控面板，以及 cpaas-system 和平台监控面板配置发布的 namespace 中的监控面板。在其他 namespace 中创建的监控面板不会列出。

#监控面板中缺少新集群或项目

某些图表（例如项目配额图表和长期趋势图表）读取 Global 集群每小时评估一次的 Fleet 级汇总指标。新连接的集群或新创建的项目可能最多需要约一小时才会显示在这些图表中，即使原始 Fleet 指标已经可用。

如果一个汇总间隔后图表仍为空，请按照Connected Clusters 中缺少集群中的检查步骤操作。

#数据新鲜度异常

检查以下项目：

• 已连接集群正在运行。
• Fleet Monitoring Cluster Service pod 健康。
• 已连接集群上的本地 Monitoring 组件健康。
• 已连接集群可以向 Global VictoriaMetrics 存储写入数据。
• FleetMonitoringAgent 状态未报告配置或资源应用错误。

#了解更多

• Fleet Monitoring
• Monitoring 监控面板管理