Argo CD 集群管理实战指南添加、跳过协调与移除集群【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本指南面向需要在命令行CLI层面管理 Kubernetes 集群的 Argo CD 运维人员覆盖argocd cluster系列命令的完整用法如何将一个集群加入 Argo CD、如何在不删除集群的前提下暂停其被 controller 协调reconcile以及如何安全地移除集群。读完本文你将掌握argocd cluster add / list / get / set / rm / rotate-auth的全部关键参数与底层行为并理解in-cluster的特殊约束及其配置项。如果你更倾向于用 Kubernetes 资源来管理集群请参阅 声明式配置Declarative Setup 中关于集群的章节。一、argocd cluster命令族概览argocd cluster是 Argo CD CLI 中用于管理集群凭据cluster credentials的子命令。其注册入口位于 cmd/argocd/commands/cluster.go共挂载了 6 个子命令子命令用途argocd cluster add CONTEXT将 kubeconfig 中的某个 context 对应的集群加入 Argo CDargocd cluster list列出已配置的集群argocd cluster get SERVER/NAME查看单个集群的详细信息argocd cluster set NAME修改集群的名称、可管理命名空间、标签与注解argocd cluster rm SERVER/NAME移除集群凭据argocd cluster rotate-auth SERVER/NAME轮换集群的认证凭据完整的命令参考见 argocd cluster Command Reference。需要特别说明的是argocd cluster的所有子命令既可通过 Argo CD API Server 工作也可在--core模式下直连 Kubernetes 集群各子命令还共享一批父级参数如--server、--auth-token、--grpc-web、--insecure等具体见命令参考文档。在解析集群参数时CLI 通过getQueryBySelector判断传入的是 Server URL 还是集群名称凡是^https?://开头的字符串会被当作 Server 地址否则按名称匹配见 cluster.go。二、添加集群argocd cluster add2.1 基本用法添加集群的命令很简单argocd cluster add context-name其中context-name是 kubeconfig 中的上下文名称。如果不确定有哪些上下文先执行kubectl config get-contexts命令执行时CLI 会读取本地 kubeconfig连接目标集群并在目标集群上安装 Argo CD 所需的 RBAC 资源从而使 Argo CD 获得管理该集群的权限。从源码看cmd/argocd/commands/cluster.go默认流程是通过clusterauth.InstallClusterManagerRBAC在目标集群的kube-system命名空间可通过--system-namespace修改默认即kube-system创建名为argocd-manager的 ServiceAccount 及相关 RBAC获取该 ServiceAccount 的 Bearer Token超时时间由common.BearerTokenTimeout定义作为 Argo CD 访问目标集群的凭据构造argoappv1.Cluster对象并通过 API 调用clusterIf.Create注册到 Argo CD。注意执行此操作需要具备目标集群的特权访问权限privileged access因为要创建集群级 RBAC。命令运行前若在交互式终端且未加-y会弹出确认提示内容为将以全集群/命名空间级权限创建argocd-managerServiceAccount。2.2 常用参数详解argocd cluster add支持以下关键参数完整列表见 argocd_cluster_add.md参数说明--name string覆盖集群名称默认沿用 context 名--namespace stringArray允许 Argo CD 管理的命名空间列表不指定则管理全部命名空间--cluster-resources是否管理集群级资源仅当--namespace列表非空时生效--project string指定集群所属的 Project用于 RBAC 隔离--label stringArray设置集群元数据标签如--label keyvalue可重复--annotation stringArray设置集群元数据注解如--annotation keyvalue可重复--service-account string指定系统命名空间中已有的 ServiceAccount不设置则创建默认的argocd-manager--system-namespace string指定系统命名空间默认kube-system--upsert当同名集群已存在且 spec 不同时覆盖更新--in-cluster表示 Argo CD 本身运行在该集群内使用内部地址kubernetes.default.svc连接--cluster-endpoint string选择端点来源kubeconfig、kube-public或internal与--in-cluster互斥--aws-cluster-name/--aws-profile/--aws-role-arnEKS 场景下使用 AWS CLI 获取 token 认证--exec-command及--exec-command-*通过 Exec 插件提供客户端凭据需自定义 Argo CD 镜像保证命令运行时可用--proxy-url string本地连接集群时使用的代理--server-proxy-url string指定 Argo CD Server 侧连接该集群使用的代理显式传空字符串表示不使用代理--shard int指定集群分片号默认 -1即由主机名推断-y, --yes跳过确认提示关于--server-proxy-url源码中的applyServerProxyOverridecluster.go体现了常见场景本地机器需要走代理访问集群但两个集群之间可以直连此时可用空字符串显式取消代理。2.3 添加集群时的认证方式选择从 cluster.go 的switch逻辑可以看到三种认证路径指定了--aws-cluster-name走 AWS IAM Authenticator可配合--aws-profile、--aws-role-arn生成 token指定了--exec-command走 Exec 凭据插件对应argoappv1.ExecProviderConfig其他情况默认创建/复用 ServiceAccount 并获取 Bearer Token。对于 EKS 等场景还有使用 argocd-k8s-auth 与 IRSA / Pod Identity 的声明式 Secret 示例见 declarative-setup.md。三、查看与修改集群3.1 列出集群# 默认 wide 表格格式 argocd cluster list # 以 JSON / YAML 输出 argocd cluster list -o json argocd cluster list -o yaml # 仅输出 Server 地址列表便于脚本处理 argocd cluster list -o serverlist的默认输出格式为wide其表格列由printClusterTable生成cluster.goSERVER、NAME、VERSION、STATUS、MESSAGE、PROJECT。当集群只管理部分命名空间时Server 列会以https://... (N namespaces)的形式附加命名空间数量STATUS/MESSAGE反映的是 controller 探测到的连接状态。3.2 查看单个集群argocd cluster get example-cluster argocd cluster get https://12.34.567.89 argocd cluster get in-cluster argocd cluster get example-cluster -o wideget默认以 YAML 输出也支持json、wide、server格式。wide模式会打印服务器 URL、名称、Kubernetes 版本、可管理命名空间、TLS 配置客户端证书、证书校验是否开启、认证方式Basic / OAuth BearerToken / AWS、是否禁用压缩、是否使用代理等细节见 printClusterDetails。3.3 修改集群# 修改集群显示名称并放开全部命名空间 argocd cluster set CLUSTER_NAME --name new-cluster-name --namespace * # 仅允许管理指定命名空间可多次指定 argocd cluster set CLUSTER_NAME --name new-cluster-name --namespace namespace-one --namespace namespace-two # 打标签与注解 argocd cluster set CLUSTER_NAME --label envprod --annotation teamplatformset的实现逻辑在 cluster.go 的checkFieldsToUpdate只有显式提供的字段才会被更新--name、--namespace、--label、--annotation四类。注意--namespace *会被转换为空字符串语义表示管理所有命名空间。如果没有任何字段被指定命令会提示Specify the cluster field to be updated.四、跳过集群协调Skipping Cluster Reconciliation在某些场景下例如集群正在维护、升级或目标集群暂时不可达你可能希望暂停 Argo CD 对某个集群的协调但又不想删除集群记录。此时可以在该集群对应的 Secret 上添加注解kubectl -n argocd annotate secret cluster-secret-name argocd.argoproj.io/skip-reconciletrue添加注解后集群仍会出现在argocd cluster list中但 application controller 会跳过所有以该集群为目标的 Application 的协调。需要恢复协调时移除该注解即可kubectl -n argocd annotate secret cluster-secret-name argocd.argoproj.io/skip-reconcile-4.1 底层原理Secret 驱动集群配置Argo CD 的集群配置本身是以 Kubernetes Secret 形式存放的添加注解实际是修改 Secret 的 metadata。完整的声明式写法见 Declarative Setup - Skipping Cluster ReconciliationapiVersion: v1 kind: Secret metadata: name: mycluster-secret labels: argocd.argoproj.io/secret-type: cluster annotations: argocd.argoproj.io/skip-reconcile: true type: Opaque stringData: name: mycluster.example.com server: https://mycluster.example.com config: | { bearerToken: authentication token, tlsClientConfig: { insecure: false, caData: base64 encoded certificate } }该机制与 Skip Application Reconcile 使用相同的注解语义只是作用层级从单个 Application 扩展到了整个集群集群被跳过协调后controller 将其视为不受管理unmanaged但集群对象在 API 响应中依然可见。使用场景包括临时下线集群、避免在集群维护窗口期间产生大量失败的状态同步尝试等。五、移除集群argocd cluster rm# 按 Server 地址移除 argocd cluster rm https://12.34.567.89 # 按名称移除 argocd cluster rm cluster-name # 跳过删除确认提示 argocd cluster rm cluster-name -y移除操作会删除该集群在 Argo CD 中的凭据记录并清理此前安装的目标集群 RBACclusterauth.UninstallClusterManagerRBAC见 cluster.go。rm支持一次传入多个集群交互式确认时可输入A表示对剩余集群全部确认。删除集群前请注意所有部署到该集群的 Application 会进入Unknown健康状态。5.1 关于in-cluster的注意事项in-cluster无法通过argocd cluster rm移除。in-cluster是 Argo CD 默认注册的、指向自身所在集群即 Argo CD 安装所在 Kubernetes 集群的特殊集群条目它没有对应的可清理 RBAC因此不允许被删除。若你希望禁用in-cluster配置需要修改argocd-cmConfigMap将cluster.inClusterEnabled设置为falsedata: # cluster.inClusterEnabled 表示是否允许 in-cluster 服务器地址。默认启用。 cluster.inClusterEnabled: false该配置项的说明与示例位于 argocd-cm.yaml完整字段语义可参考 argocd-cm-yaml 配置参考。在升级场景中如 2.14 升级到 3.0显式配置cluster.inClusterEnabled: false会影响当前配置为 in-cluster 的 Application具体迁移注意事项见 upgrading/2.14-3.0.md。5.2 轮换集群认证凭据如果集群的 ServiceAccount Token 等凭据疑似泄露或需要定期轮换可以使用argocd cluster rotate-auth https://12.34.567.89 argocd cluster rotate-auth cluster-name该命令由NewClusterRotateAuthCommand实现cluster.go调用 API 完成凭据轮换成功后输出Cluster name rotated auth。六、补充完整命令快速参考以下示例均出自 argocd cluster Command Reference可直接用于日常操作# 以 JSON 格式列出所有已注册集群 argocd cluster list -o json # 添加 kubeconfig 中名为 example-cluster 的 context 对应的集群 argocd cluster add example-cluster # 以 wide 文本格式查看集群详情 argocd cluster get example-cluster -o wide # 移除集群 context argocd cluster rm example-cluster # 修改集群名称并放开全部命名空间 argocd cluster set CLUSTER_NAME --name new-cluster-name --namespace *七、小结集群管理是 Argo CD 多集群部署的基础操作。通过argocd cluster命令族你可以快速完成集群的注册、查看、配置调整与下线通过argocd.argoproj.io/skip-reconcile注解可以在保留集群记录的前提下灵活暂停协调配合维护窗口使用尤为合适而in-cluster作为特殊集群条目只能通过cluster.inClusterEnabled配置来启停。所有命令的底层实现都可以在 cmd/argocd/commands/cluster.go 中查阅各子命令的参数与默认值以 docs/user-guide/commands 下的命令参考文档为准。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考