#配置 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 dashboard 使用这些指标来展示 fleet 健康状况、资源使用情况、数据新鲜度以及项目配额使用情况。

#开始之前

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

• 你拥有平台管理员权限，或者拥有安装 Operator 和创建 Fleet Monitoring 资源所需的权限。
• Global 集群具有可用于 Fleet Monitoring 数据的可用 remote write endpoint。支持带有 write endpoint 的 VictoriaMetrics。如果 Monitoring 功能暴露的 endpoint 支持 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. 进入 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. 验证 Alauda Container Platform Fleet Monitoring Central Service 在 OperatorHub 中的状态为 Installed。

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

7. 验证 Global 集群具有可用的 VictoriaMetrics write endpoint。

   Fleet Monitoring 使用 Global VictoriaMetrics write endpoint 接收来自已连接集群的数据。如果 Global 集群仅提供 Prometheus 或 Thanos Query，则已连接集群无法将 Fleet Monitoring 数据写入 Global 集群。

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

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

   FleetMonitoringHub 是 cluster-scoped 资源。不要设置 metadata.namespace。

   字段	必需	描述
   metadata.name	是	必须为 fleet-monitoring-hub。
   metadata.namespace	否	不要设置此字段。FleetMonitoringHub 是 cluster-scoped。
   spec	是	使用空对象 {}。创建该资源会启用 Fleet Monitoring 的 Global 侧。

9. 验证 FleetMonitoringHub 的状态。

   kubectl get fleetmonitoringhub fleet-monitoring-hub -o yaml

   检查以下条件是否就绪：

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

   你也可以检查 phase：

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

   预期的 phase 为 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. 验证 Alauda Container Platform Fleet Monitoring Cluster Service 在 OperatorHub 中的状态为 Installed。

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

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

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

   FleetMonitoringAgent 是 cluster-scoped 资源。不要设置 metadata.namespace。

   字段	必需	描述
   metadata.name	是	必须为 fleet-monitoring-agent。
   metadata.namespace	否	不要设置此字段。FleetMonitoringAgent 是 cluster-scoped。
   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 数据，或者由于受支持的原因该集群被有意跳过。

   你也可以检查 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 会跳过向同一个 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，并验证该集群是否出现在 dashboard 数据中。

#配置采集间隔

采集间隔在每个已连接集群的 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 规则遵循 spec.interval。

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

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

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

1. 在已连接的 workload 集群上，定义一个本地 Fleet recording rule，将源指标转换为一个 Fleet 指标名称。
2. 将该录制后的指标名称添加到 Fleet allowlist，以便 Fleet Monitoring VMAgent 将其 federate 并 remote-write 到 Global 集群。
3. 如果你需要 fleet 级别的汇总，例如 1 小时聚合，请在 Global 集群上单独添加一个自定义 Hub 侧 PrometheusRule。
4. 使用 Fleet Monitoring 查询或 dashboard 验证录制指标和汇总指标。

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

请选择以下模式之一：

• 当你只需要在 Global 集群上使用原始 Fleet 指标，并且可以直接查询它时，仅使用已连接集群的 ConfigMap。
• 当你还需要 fleet 级别的汇总，例如用于 dashboard 或长时间范围视图的 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 allowlist。
• 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 会将指标名称追加到内置 allowlist 中。

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

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

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

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

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

对于自定义 Fleet 指标，请为录制后的指标使用 Fleet 命名约定，例如 fleet:node:node_load15:avg。这样可以使该指标与 Fleet Monitoring dashboard、汇总和查询模式保持兼容。

Fleet Monitoring 的查询和 dashboard 要求录制后的时间序列带有 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 allowlist：

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 规则，并且不应使用 Fleet Monitoring operator 的所有权元数据创建。

#验证 Hub 侧汇总

检查自定义 Hub 侧规则：

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

确认以下内容：

• 该规则存在于 Global 集群上
• 该规则使用预期的 Fleet 指标作为输入
• 汇总输出指标名称与计划使用的 dashboard 或查询表达式匹配

#查询自定义 Fleet 指标

通过平台 Monitoring API 或 Fleet Monitoring dashboard 查询 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])

#常见错误

请留意以下问题：

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

#验证数据新鲜度

集群连接完成后，打开 Platform > Observe > Fleet Monitoring，并在概览 dashboard 上检查以下信息：

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

如果某个集群出现在 Cluster 变量中，但未被计为已连接，则说明平台可能已识别该集群，但它尚未写入 Fleet Monitoring 数据。请检查该集群是否已通过 OperatorHub 安装 Alauda Container Platform Fleet Monitoring Cluster Service，并且 FleetMonitoringAgent 是否处于就绪状态。

#故障排查

#未显示任何 Fleet Monitoring 数据

检查以下项目：

• Alauda Container Platform Fleet Monitoring Central Service 是否已安装在 Global 集群上。
• FleetMonitoringHub 资源是否存在并且条件已就绪。
• Global 集群是否具有可用的 VictoriaMetrics 存储和 write endpoint。仅使用 Prometheus 的 Monitoring 无法接收 Fleet Monitoring remote write 数据。
• 是否已应用内置 dashboard 和 Global 规则。

#某个集群未出现在 Connected Clusters 中

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

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

#自定义 dashboard 未出现在 Fleet Monitoring 中

检查 dashboard 是否创建在 Global 集群上，以及 cpaas-system namespace 中的 dashboard 资源是否包含以下标签：

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

没有此标签的 dashboard 不会带有 fleet-monitoring 标签，也不会列在 Fleet Monitoring 的 Switch 列表中。

#数据新鲜度异常

检查以下项目：

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

#了解更多

• Fleet Monitoring
• Management of Monitoring Dashboards