#配置 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 后，已连接集群会将集群组级指标写入 Global VictoriaMetrics 存储。内置 Fleet Monitoring 监控面板使用这些指标显示集群组健康状况、资源使用情况、数据新鲜度和项目配额使用情况。

#开始之前

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

• 你具有平台管理员权限，或具有安装 Operator 和创建 Fleet Monitoring 资源所需的权限。
• Global 集群具有可用的 Fleet Monitoring 数据远程写入端点。支持带写入端点的 VictoriaMetrics。如果 Monitoring 功能公开的端点接受远程写入流量，则基于 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、命名空间或升级策略，否则保留默认安装配置。

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

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

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

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

   Fleet Monitoring 使用 Global VictoriaMetrics 写入端点接收来自已连接集群的数据。如果 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、命名空间或升级策略，否则保留默认安装配置。

   参数	推荐配置
   Channel	使用 Operator 软件包提供的默认 channel。
   Installation Mode	Cluster。该 Operator 管理所选集群的 Fleet Monitoring 资源。
   Installation Place	使用 Operator 软件包提供的推荐命名空间。
   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 资源，例如规则和业务资源。
   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 的命名空间。

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

#升级 Fleet Monitoring

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

#兼容性矩阵

下表列出了支持的版本：

#升级路径指南

• 补丁级升级：同一次要版本内的补丁版本之间兼容，可以直接升级，例如 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 对其进行联邦并将其远程写入 Global 集群。
3. 如果需要 Fleet 级聚合（例如 1 小时聚合），请在 Global 集群上另外添加自定义 Hub 侧 PrometheusRule。
4. 使用 Fleet Monitoring 查询或监控面板验证记录指标和聚合指标。

#确定只需 Agent 侧规则还是同时需要 Agent 侧和 Hub 侧规则

选择以下模式之一：

• 需要 Global 集群上的原始 Fleet 指标并可以直接查询时，仅使用已连接集群的 ConfigMap。
• 如果还需要用于监控面板或长期视图的 Fleet 级聚合（例如 1 小时聚合），则同时使用已连接集群的 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 的命名空间中，创建或更新 fleet-monitoring-custom-metrics ConfigMap。

此 ConfigMap 有两个作用：

• metrics.yaml 将指标名称添加到 Fleet Monitoring VMAgent 联邦 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 的命名空间。

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

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

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

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

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

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

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

Fleet Monitoring 查询和监控面板要求记录后的时间序列携带 cluster 标签。如果规则尚未定义该标签，Agent 协调器会自动将 cluster=<local-cluster-name> 添加到渲染后的 Fleet Monitoring 记录规则中。

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

更新 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 联邦 allowlist：

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

确认自定义记录指标在 params.match[] 下出现在 data.prometheus.yml 中。

#添加自定义 Hub 聚合规则

如果希望自定义 Fleet 指标具有 Fleet 级聚合（例如 1 小时聚合），请在 Global 集群上、安装 Alauda Container Platform Fleet Monitoring Central Service 的命名空间中创建单独的 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 的命名空间。

此自定义 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 实际安装在其他命名空间，例如 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 存储和写入端点。仅 Prometheus 的 Monitoring 无法接收 Fleet Monitoring 远程写入数据。
• 已应用内置监控面板和 Global 规则。

#Connected Clusters 中缺少某个集群

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

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

#自定义监控面板未出现在 Fleet Monitoring 中

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

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

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

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

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

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

如果一个聚合间隔后图表仍为空，请按照Connected Clusters 中缺少某个集群中的检查项操作。

#数据新鲜度异常

检查以下项目：

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

#了解更多

• Fleet Monitoring
• Monitoring 监控面板管理