Argo CD 故障排查笔记：解决 cluster "..." not found 错误

一、问题现象 (Symptom)

在持续部署 (CD) 阶段，Argo CD 无法创建或同步 Application，并报告以下或类似的错误信息：

Unable to create application: application destination spec is invalid:
unable to find destination server: error getting cluster name by server "https://<K8S_API_SERVER_IP>:<PORT>":
rpc error: code = NotFound desc = cluster "https://<K8S_API_SERVER_IP>:<PORT>" not found

这个错误表明，部署流程失败的根本原因是 Argo CD 在其已知的集群列表中，找不到你指定的目标 Kubernetes 集群。

二、问题根源 (Root Cause)

Argo CD 作为一个中心化的 GitOps 部署工具，它本身运行在一个 Kubernetes 集群（我们称之为“主控集群”）中，但它可以管理和部署应用到多个其他的 Kubernetes 集群（我们称之为“目标集群”）。

为了安全和管理，Argo CD 不会自动发现网络上的所有 Kubernetes 集群。每一个需要由 Argo CD 管理的目标集群，都必须被显式地、手动地注册到 Argo CD 的配置中。

因此，出现此错误的唯一原因就是：
你要部署的目标集群，尚未被添加到 Argo CD 的受管集群列表中。

三、诊断步骤 (Diagnostics)

在可以执行 argocd CLI 的服务器上，按照以下步骤进行诊断。

1. 登录 Argo CD 实例
   确保你已经通过 argocd login 命令成功登录到你的 Argo CD 服务器。

   # 使用域名登录，避免证书IP SANs问题
   argocd login <argocd.your-company.com> --username <user> --password <pass>
   

2. 列出当前已注册的集群
   这是最关键的诊断命令。它会显示 Argo CD 目前知道的所有集群。

   argocd cluster list
   

3. 核对集群列表
   仔细检查 SERVER 列的输出，确认你要部署的目标集群的 API Server 地址（例如 https://<K8S_API_SERVER_IP>:<PORT>）是否出现在列表中。

   • 如果不在列表中 -> 诊断确认，你需要执行下一步的解决方案。
   • 如果在列表中，但 STATUS 异常 -> 问题可能出在凭证或网络连接上，但这不是 “not found” 错误，需另行排查。

四、解决方案 (Solution)

解决方案的核心是：将目标集群的连接凭证安全地注册到 Argo CD 中。 最推荐的方法是使用 argocd cluster add 命令，它能自动完成大部分工作。

前提条件

你需要在一台机器上，同时满足：

• 安装并配置好了 argocd CLI，且已登录。
• 安装并配置好了 kubectl CLI。
• 拥有目标集群的 kubeconfig 文件。

操作步骤

1. 获取目标集群的 kubeconfig 文件
   从你的云服务商控制台（如 AWS EKS, 华为云 CCE, 阿里云 ACK 等）或通过你的集群管理工具，下载目标集群的 kubeconfig 配置文件。

2. 将 kubeconfig 文件放置到操作服务器上
   使用 scp 或其他方式，将 kubeconfig 文件（例如 target-cluster.yaml）上传到你准备执行 argocd 命令的服务器上。

3. 临时设置 KUBECONFIG 环境变量
   打开一个新的终端会话，执行 export 命令。这会使当前会话中的 kubectl 和 argocd 命令都使用这个新的配置文件，而不会影响系统的默认配置。

   export KUBECONFIG=/path/to/your/target-cluster.yaml
   

4. 验证与目标集群的连接
   这是关键的验证步骤，确保 kubeconfig 文件有效且网络可达。

   kubectl get nodes
   

   如果此命令成功列出了目标集群的节点，说明准备工作就绪。

5. 获取目标集群的上下文名称 (Context Name)
   argocd 命令需要使用 kubeconfig 文件中定义的上下文名称来定位集群信息。

   kubectl config get-contexts
   

   记下 NAME 列的值（通常只有一行）。我们假设这个名字是 target-cluster-context。

6. 执行添加命令，将集群注册到 Argo CD
   使用上一步获取的上下文名称，并可以自定义一个更有意义的名字。

   # argocd cluster add <上下文名称> --name <在ArgoCD中显示的自定义名称>
   argocd cluster add target-cluster-context --name my-awesome-prod-cluster
   

   • 命令会提示你确认，因为它需要在目标集群上创建一个用于管理的 ServiceAccount (argocd-manager) 并授予其集群管理员权限。输入 y 并回车确认。

7. 最终验证
   再次运行 argocd cluster list 命令。

   argocd cluster list
   

   这一次，你应该能在列表中看到你刚刚添加的集群，其 NAME 是 my-awesome-prod-cluster，SERVER 地址也正确无误，STATUS 最终会变为 Successful。

五、后续操作

集群成功添加到 Argo CD 后，你就可以：

1. 重新触发你的部署流水线，或者
2. 重新创建或同步你的 Argo CD Application。

这一次，Argo CD 将能够成功匹配到 destination 服务器，部署流程将顺利进行。

核心知识点: Argo CD 的多集群管理是基于显式注册的。任何部署目标都必须预先配置并获得授权。argocd cluster add 是实现这一目标的最主要、最安全的工具。