呱呱聚合
← 返回基因库
运维部署

在 live Kubernetes 集群上调试 Flux…

适用于用户报告 live 集群上的 Flux 资源失败、卡住、未就绪、reconciliation 错误、控制器问题、artifact 拉取失败、镜像自动化未更新标签、通知或 webhook 未投递，以及需要 live 集群 Flux Operator 故障排查时。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 rose.xiao 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 60/100 ×0.15

适用场景

在 live Kubernetes 集群特定

解决思路

  1. 通用规则：不要假设任何 Kubernetes 或 Flux 资源的 apiVersion；先调用 get_kubernetes_api_versions 查找正确版本。
  2. 通用规则：判断 Kubernetes 资源是否由 Flux 管理时，查看资源 metadata 中的 fluxcd 标签。
  3. 通用规则：切换到新集群上下文后，先调用 get_flux_instance 确定 Flux Operator 状态、版本和设置，然后再做其他事。
  4. 通用规则：在集群上创建或更新资源时，生成 Kubernetes YAML manifest 并调用 apply_kubernetes_manifest 工具。
  5. 通用规则：当目标资源由 Flux 管理时，apply_kubernetes_manifest 除非 overwrite 设为 true，否则会报错。
  6. 通用规则：除非用户明确要求，不要应用资源。
  7. 通用规则：生成任何 YAML manifest 前，对照 assets/schemas/ 中的字段索引验证准确字段名和嵌套。
  8. 通用规则：字段索引文件命名约定为 {kind}-{group}-{version}.fields.txt；每行是点分字段路径。
  9. 通用规则：按路径前缀用 grep 查询字段索引，例如 grep '^spec\.' assets/schemas/kustomization-kustomize-v1.fields.txt，而不是读取整个文件。
  10. 通用规则：无法读取 Kubernetes Secrets 的值；MCP server 只返回 data 字段的键，值为空。
  11. 集群上下文：若用户指定集群名，调用 get_kubeconfig_contexts 列出可用上下文。
  12. 集群上下文：找到匹配用户集群名的上下文。
  13. 集群上下文：调用 set_kubeconfig_context 切换到该上下文。
  14. 集群上下文：调用 get_flux_instance 验证该集群上的 Flux 安装。
  15. 集群上下文：若未指定集群，在当前上下文调试。
  16. 集群上下文：仍要在开始时调用 get_flux_instance 了解 Flux 安装。
  17. 调试深度：根据用户请求调整深度；针对性问题（如“为什么我的 HelmRelease 失败？”）可直接跳到相关工作流；宽泛请求（如“debug my cluster”）应从安装检查开始。
  18. Workflow 1 Flux 安装检查第1步：调用 get_flux_instance 检查 Flux Operator 状态和设置。
  19. Workflow 1 第2步：验证 FluxInstance 报告 Ready: True。
  20. Workflow 1 第3步：检查控制器 deployment 状态——所有控制器应处于运行状态。
  21. Workflow 1 第4步：查看 FluxReport，获取集群范围的 reconciliation 摘要。
  22. Workflow 1 第5步：若控制器未运行或 crashlooping，对控制器 Pod 使用 get_kubernetes_logs 分析其日志。
  23. Workflow 2 HelmRelease 调试第1步：调用 get_flux_instance 检查 helm-controller deployment 状态和 HelmRelease kind 的 apiVersion。
  24. Workflow 2 第2步：调用 get_kubernetes_resources 获取 HelmRelease，然后分析 spec、status、inventory 和 events。
  25. Workflow 2 第3步：通过 annotations 确定哪个 Flux 对象管理 HelmRelease——可能是 Kustomization 或 ResourceSet。
  26. Workflow 2 第4步：若存在 valuesFrom，获取所有引用的 ConfigMap 和 Secret 资源。
  27. Workflow 2 第5步：通过 chartRef 或 sourceRef 字段确定 HelmRelease 源。
  28. Workflow 2 第6步：调用 get_kubernetes_resources 获取源，然后分析源 status 和 events。
  29. Workflow 2 第7步：若 HelmRelease 处于 failed 状态或 in progress，检查 inventory 中的托管资源。
  30. Workflow 2 第8步：调用 get_kubernetes_resources 获取托管资源并分析其状态。
  31. Workflow 2 第9步：若托管资源失败，使用 get_kubernetes_logs 分析其日志。
  32. Workflow 2 第10步：创建 root cause analysis report；若未发现问题，报告 HelmRelease 及其托管资源和容器镜像的当前状态。
  33. Workflow 3 Kustomization 调试第1步：调用 get_flux_instance 检查 kustomize-controller deployment 状态和 Kustomization kind 的 apiVersion。
  34. Workflow 3 第2步：调用 get_kubernetes_resources 获取 Kustomization，然后分析 spec、status、inventory 和 events。
  35. Workflow 3 第3步：通过 annotations 确定哪个 Flux 对象管理 Kustomization——可能是另一个 Kustomization 或 ResourceSet。
  36. Workflow 3 第4步：若存在 substituteFrom，获取所有引用的 ConfigMap 和 Secret 资源。
  37. Workflow 3 第5步：通过 sourceRef 字段确定 Kustomization 源。
  38. Workflow 3 第6步：调用 get_kubernetes_resources 获取源，然后分析源 status 和 events。
  39. Workflow 3 第7步：若 Kustomization 处于 failed 状态或 in progress，检查 inventory 中的托管资源。
  40. Workflow 3 第8步：调用 get_kubernetes_resources 获取托管资源并分析其状态。
  41. Workflow 3 第9步：若托管资源失败，使用 get_kubernetes_logs 分析其日志。
  42. Workflow 3 第10步：创建 root cause analysis report；若未发现问题，报告 Kustomization 及其托管资源的当前状态。
  43. Workflow 4 ResourceSet 调试第1步：调用 get_flux_instance 检查 Flux Operator 状态和 ResourceSet kind 的 apiVersion。
  44. Workflow 4 第2步：调用 get_kubernetes_resources 获取 ResourceSet，然后分析 spec、status conditions 和 events。
  45. Workflow 4 第3步：若 ResourceSet 使用 inputsFrom，获取每个引用的 ResourceSetInputProvider 并检查其状态；Stalled 或 Ready: False 的 provider 意味着 ResourceSet 没有可渲染输入。
  46. Workflow 4 第4步：若 ResourceSet 有 dependsOn，获取每个依赖并验证其 Ready；ResourceSet 依赖可引用任何 Kubernetes 资源 kind（其他 ResourceSets、Kustomizations、HelmReleases、CRDs）——检查每个条目中的 apiVersion 和 kind。
  47. Workflow 4 第5步：检查 ResourceSet inventory 中生成的资源；获取生成的 Kustomizations、HelmReleases 或其他 Flux 资源并分析其状态。
  48. Workflow 4 第6步：若生成资源失败，按 Workflow 2（HelmRelease）或 Workflow 3（Kustomization）单独调试。
  49. Workflow 4 第7步：创建 root cause analysis report；区分 ResourceSet 级失败（模板错误、缺少输入、RBAC）和生成资源中的失败。
  50. Workflow 5 Source 调试第1步：调用 get_flux_instance 检查 source-controller deployment 状态和 source kind 的 apiVersion。
  51. Workflow 5 第2步：调用 get_kubernetes_resources 获取源，然后分析 status conditions（Ready、FetchFailed、ArtifactInStorage）、artifact revision 和 events。
  52. Workflow 5 第3步：对于认证错误，获取引用的 secretRef Secret 并验证其存在且具有预期 key 名称（值被屏蔽）；对于无 Secret 的云 registries，检查 .spec.provider 和工作负载身份。
  53. Workflow 5 第4步：对于 HelmChart 失败，先验证引用的 HelmRepository 或 GitRepository 是 Ready——chart 错误通常是上游源错误。
  54. Workflow 5 第5步：比较最后 reconcile 时间与 .spec.interval——陈旧 artifact 且无错误可能意味着源 suspended 或控制器过载。
  55. Workflow 5 第6步：识别下游消费者（sourceRef 指向该源的 Kustomizations/HelmReleases），并注意它们卡在哪个 revision。
  56. Workflow 5 第7步：创建 root cause analysis report；加载 references/troubleshooting.md（Source Failures）获取每种源的原因列表——auth key names、Cosign verification、layerSelector mismatches、semver constraints。
  57. Workflow 6 Image Automation 调试第1步：调用 get_flux_instance 并验证 image-reflector-controller 和 image-automation-controller 在 components 中列出并运行。
  58. Workflow 6 第2步：获取 ImageRepository——检查 Ready、上次扫描时间和 status 中的 tag 数量；Auth 失败指向 secretRef 或 .spec.provider。
  59. Workflow 6 第3步：获取 ImagePolicy——检查 Ready 和 status.latestImage；若未选中任何内容，比较 policy rules 与实际扫描的 tags。
  60. Workflow 6 第4步：获取 ImageUpdateAutomation——检查 Ready、上次 push 时间和 events；验证其 sourceRef GitRepository 具有可写 credentials，且 .spec.git.push.branch 是用户关注的分支。
  61. Workflow 6 第5步：若所有都 Ready 但没有 commit 出现，验证 .spec.update.path 下的 manifests 包含针对正确 <namespace>:<policy-name> 的 $imagepolicy markers，且 latestImage 与 Git 不同。
  62. Workflow 6 第6步：创建 root cause analysis report，追踪 ImageRepository → ImagePolicy → ImageUpdateAutomation → GitRepository。
  63. Workflow 7 Notification 调试第1步：调用 get_flux_instance 检查 notification-controller deployment 状态。
  64. Workflow 7 第2步：Provider 和 Alert 没有 status conditions——从 notification-controller logs 诊断投递（Workflow 8）：查找 dispatch errors 如 HTTP 401/404 或 timeouts。
  65. Workflow 7 第3步：获取 Alert 并验证 .spec.eventSources 匹配预期产生事件的资源，且 .spec.eventSeverity 没有过滤掉它们。
  66. Workflow 7 第4步：获取引用的 Provider 并验证 .spec.type、.spec.address 和 secretRef Secret key 名称。
  67. Workflow 7 第5步：对于 Receivers（有 Ready condition）：验证 status.webhookPath 和 webhook Secret，然后检查 logs 中到该路径的传入请求——没有请求意味着外部服务没有调用 webhook。
  68. Workflow 7 第6步：要生成测试事件，建议对受监控资源发起手动 reconcile 请求，并观察 logs 中的 dispatch 尝试；加载 references/troubleshooting.md（Notification Failures）获取原因列表。
  69. Workflow 8 Kubernetes Logs 分析第1步：用 get_kubernetes_resources 获取管理 Pod 的 Kubernetes Deployment。
  70. Workflow 8 第2步：从 deployment spec 提取 matchLabels 和容器名。
  71. Workflow 8 第3步：用找到的 matchLabels 通过 get_kubernetes_resources 列出 Pod。
  72. Workflow 8 第4步：用 pod 名和容器名调用 get_kubernetes_logs 获取日志。
  73. Workflow 8 第5步：分析日志中的 errors、warnings 和 patterns，以指示 root cause。
  74. 使用 Flux CRD Reference 表检查 API 版本，并在需要时 grep 字段索引：flux-operator FluxInstance apiVersion fluxcd.controlplane.io/v1 字段索引 assets/schemas/fluxinstance-fluxcd-v1.fields.txt；flux-operator FluxReport apiVersion fluxcd.controlplane.io/v1 字段索引 assets/schemas/fluxreport-fluxcd-v1.fields.txt；flux-operator ResourceSet apiVersion fluxcd.controlplane.io/v1 字段索引 assets/schemas/resourceset-fluxcd-v1.fields.txt；flux-operator ResourceSetInputProvider apiVersion fluxcd.controlplane.io/v1 字段索引 assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt；source-controller GitRepository apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/gitrepository-source-v1.fields.txt；source-controller OCIRepository apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/ocirepository-source-v1.fields.txt；source-controller Bucket apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/bucket-source-v1.fields.txt；source-controller HelmRepository apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/helmrepository-source-v1.fields.txt；source-controller HelmChart apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/helmchart-source-v1.fields.txt；source-controller ExternalArtifact apiVersion source.toolkit.fluxcd.io/v1 字段索引 assets/schemas/externalartifact-source-v1.fields.txt；source-watcher ArtifactGenerator apiVersion source.extensions.fluxcd.io/v1beta1 字段索引 assets/schemas/artifactgenerator-source-v1beta1.fields.txt；kustomize-controller Kustomization apiVersion kustomize.toolkit.fluxcd.io/v1 字段索引 assets/schemas/kustomization-kustomize-v1.fields.txt；helm-controller HelmRelease apiVersion helm.toolkit.fluxcd.io/v2 字段索引 assets/schemas/helmrelease-helm-v2.fields.txt；notification-controller Provider apiVersion notification.toolkit.fluxcd.io/v1beta3 字段索引 assets/schemas/provider-notification-v1beta3.fields.txt；notification-controller Alert apiVersion notification.toolkit.fluxcd.io/v1beta3 字段索引 assets/schemas/alert-notification-v1beta3.fields.txt；notification-controller Receiver apiVersion notification.toolkit.fluxcd.io/v1 字段索引 assets/schemas/receiver-notification-v1.fields.txt；image-reflector-controller ImageRepository apiVersion image.toolkit.fluxcd.io/v1 字段索引 assets/schemas/imagerepository-image-v1.fields.txt；image-reflector-controller ImagePolicy apiVersion image.toolkit.fluxcd.io/v1 字段索引 assets/schemas/imagepolicy-image-v1.fields.txt；image-automation-controller ImageUpdateAutomation apiVersion image.toolkit.fluxcd.io/v1 字段索引 assets/schemas/imageupdateautomation-image-v1.fields.txt。
  75. 加载 references/flux-crds.md：当需要详细 CRD 字段描述、status conditions、常见故障或资源关系图时。
  76. 加载 references/troubleshooting.md：当诊断特定故障模式或需要通用调试检查清单时。
  77. 在追踪任何调试工作流时，记录每个检查过的资源（kind、name、namespace、status），用于构建报告中的依赖链。
  78. 按 markdown 报告组织调试发现，包含第1节 Summary——集群名、Flux 版本、调查中的资源、当前状态。
  79. 报告第2节 Resource Analysis——详细分解资源 spec、status conditions 和 events。
  80. 报告第3节 Dependency Chain——追踪从 source 到 applier 到托管资源（例如 GitRepository → Kustomization → Deployments）。
  81. 报告第4节 Root Cause——识别根因，并用 status conditions、events 和 logs 中的证据支持。
  82. 报告第5节 Recommendations——按优先级给出解决步骤，包含确切命令或 manifest 修改。
  83. Edge Case 无 Flux 安装：若 get_flux_instance 返回 no FluxInstance，告诉用户集群上未安装 Flux，并建议安装 Flux Operator。
  84. Edge Case MCP server 不可用：若 MCP 工具连接失败，告诉用户 flux-operator-mcp server 未运行，并提供安装命令。
  85. Edge Case Suspended resources：若 Flux 资源有 .spec.suspend: true，说明它被有意暂停，直到恢复前不会 reconcile；除非用户期望它处于 active，否则不要标记为错误。
  86. Edge Case Progressing resources：若资源显示 Ready: Unknown 且 reason 为 Progressing，说明它正在主动 reconcile；在诊断前等待 reconciliation 完成，并记录 last transition time。
  87. Edge Case Flux-managed resources：带 fluxcd 标签的资源由 Flux 管理；在应用手动更改前警告用户，Flux 会在下次 reconciliation 时回滚这些更改。
  88. Edge Case Stale status：若最后 reconciliation 时间相对于配置的 interval 很旧，控制器可能过载或卡住；检查控制器日志中的 backpressure 或错误。
  89. Edge Case Cluster context not found：若用户集群名不匹配任何可用上下文，列出可用上下文并请用户澄清。

适用边界 · 注意事项