#配置 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 端点。支持带有写入端点的 VictoriaMetrics。如果 Monitoring 功能暴露的端点接受 remote write 流量，基于 Prometheus 或 Thanos 的 Monitoring 也可以使用。
• 你希望连接的每个集群都由 global 集群管理。
• 你希望连接的每个集群都已启用 Monitoring 功能。
• Fleet Monitoring Operator 软件包已推送到所需集群，或已在 OperatorHub 中可用。Fleet Monitoring 以 Agnostic Operators 形式交付，默认不包含在平台安装包中。
• 已具备 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 的更多信息，请参见 Upload Packages。

#在 global 集群上启用 Fleet Monitoring

1. 进入 管理员。

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. 验证 Alauda Container Platform Fleet Monitoring Central Service 在 OperatorHub 中已处于 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 recording rules。

   你也可以检查 phase：

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

   期望的 phase 为 Ready。

#将集群连接到 Fleet Monitoring

在你希望纳入 Fleet Monitoring 的每个集群上重复以下步骤。

1. 进入 管理员。

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. 验证 Alauda Container Platform Fleet Monitoring Cluster Service 在 OperatorHub 中已处于 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 资源，例如 rules 和 workload 资源。
   Ready	集群已准备好写入 Fleet Monitoring 数据，或者由于受支持的原因，该集群被有意跳过。

   你也可以检查 phase 和检测到的集群名称：

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

   期望的 phase 为 Ready。常见的 Ready 原因包括：

   • WorkloadReady：该集群已部署 VMAgent，并已准备好写入 Fleet Monitoring 数据。
   • SkippedForGlobal：该集群是 global 集群，因此 Cluster Service 会跳过将 VMAgent 再部署回同一个 Global 存储。
   • 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，并验证该集群是否出现在监控面板数据中。

#配置采集间隔

采集间隔在每个已连接集群的 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 recording rules 会继续以 federation 所使用的系统管理间隔进行评估。在 global 集群以及复用 Global VictoriaMetrics 后端、且未部署 Fleet Monitoring VMAgent 的集群上，本地 Fleet Monitoring rules 会遵循 spec.interval。

#配置自定义指标和 recording rules

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

当你想将用户定义的指标报告到 Fleet Monitoring 时，请使用以下流程：

1. 在已连接的业务集群上，定义一个本地 Fleet recording rule，将源指标转换为 Fleet 指标名称。
2. 将该已记录的指标名称添加到 Fleet 允许列表中，以便 Fleet Monitoring VMAgent 对其进行 federation 并 remote-write 到 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 的 namespace 中，创建或更新 fleet-monitoring-custom-metrics ConfigMap。

该 ConfigMap 有两个作用：

• metrics.yaml 会将指标名称添加到 Fleet Monitoring VMAgent federate 允许列表中。
• recording-rules-prometheus.yaml 或 recording-rules-victoriametrics.yaml 会定义生成 Fleet 指标的本地 recording rule。

示例：

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 会将指标名称追加到内置允许列表中。

对于 recording rules，Cluster Service 只会加载与本地 Monitoring 栈匹配的 key：

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

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

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

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

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

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

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

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

检查渲染后的本地规则：

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

确认以下内容：

• 自定义 group 出现在 spec.groups 中
• 自定义已记录指标出现在规则列表中
• 渲染后的规则包含 labels.cluster=<connected-cluster-name>

检查渲染后的 VMAgent federate 允许列表：

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

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

#添加自定义 Hub 汇总规则

如果你希望自定义 Fleet 指标具有 Fleet 级别汇总，例如 1 小时聚合，请在 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 rules，也不应使用 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）中
• 在 metrics.yaml 中添加源指标名称，而不是已记录的 Fleet 指标名称
• 定义了本地 recording rule，但没有将已记录的 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 处于 ready 状态。

#故障排除

#未显示 Fleet Monitoring 数据

检查以下项目：

• global 集群上已安装 Alauda Container Platform Fleet Monitoring Central Service。
• FleetMonitoringHub 资源已存在且 ready 条件满足。
• global 集群具有可用的 VictoriaMetrics 存储和写入端点。仅 Prometheus 的 Monitoring 无法接收 Fleet Monitoring remote write 数据。
• 内置监控面板和 global rules 已应用。

#Connected Clusters 中缺少某个集群

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

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

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

检查该监控面板是否已在 global 集群上创建，以及 cpaas-system namespace 中的监控面板资源是否具有以下标签：

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

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

#数据新鲜度异常

检查以下项目：

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

#了解更多

• Fleet Monitoring
• Monitoring 监控面板管理