Argo CD 集群凭据管理完全指南：argocd cluster 命令详解

Argo CD 集群凭据管理完全指南argocd cluster 命令详解【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cdArgo CD 作为声明式 Kubernetes 持续交付工具其核心能力在于把一个或多个目标集群纳入统一管理。argocd cluster命令族正是完成集群凭据注册、查询、更新与移除的入口。本文基于 Argo CD 仓库中的官方命令参考文档与 CLI 源码实现完整覆盖argocd cluster及add、list、get、set、rm、rotate-auth六个子命令的全部参数与典型用法并深入底层讲解argocd-manager服务账号、命名空间权限、集群分片与代理等实现机制帮助你系统掌握 Argo CD 的集群管理能力。命令总览argocd clusterargocd cluster是用于管理集群凭据cluster credentials的一级命令其下挂载了全部集群操作子命令argocd cluster [flags]官方文档给出的典型用法如下# 以 JSON 格式列出所有已注册集群 argocd cluster list -o json # 添加一个目标集群配置到 Argo CD该 context 必须已存在于你的 kubectl config 中 argocd cluster add example-cluster # 以 wide 纯文本格式查看某个集群的详细信息 argocd cluster get example-cluster -o wide # 从 Argo CD 中移除目标集群的凭据 argocd cluster rm example-cluster # 修改目标集群的配置信息 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父命令级选项Optionsargocd cluster本身支持以下选项参数类型说明--cluster stringstring使用的 kubeconfig cluster 名称--context stringstring使用的 kubeconfig context 名称-h, --help—显示 cluster 命令帮助--insecure-skip-tls-verifybool为 true 时不校验服务器证书有效性将使 HTTPS 连接不安全--kubeconfig stringstringkube config 文件路径仅在集群外使用时需要-n, --namespace stringstring本 CLI 请求的命名空间作用域--password stringstring访问 API server 的基本认证密码--proxy-url stringstring提供后将通过该 URL 建立代理连接--request-timeout stringstring单次服务器请求的超时等待时间非零值需带时间单位如 1s、2m、3h零值表示不超时默认0--token stringstring访问 API server 的 Bearer token--user stringstring使用的 kubeconfig user 名称--username stringstring访问 API server 的基本认证用户名全局继承选项Options inherited from parent commands所有argocd cluster子命令还会继承来自根命令的全局参数常用项包括参数默认值说明--server string—Argo CD server 地址--auth-token string—认证令牌可设置此参数或ARGOCD_AUTH_TOKEN环境变量--config string/home/user/.config/argocd/configArgo CD 配置文件路径--corefalse为 true 时 CLI 直接与 Kubernetes 通信而不经过 Argo CD API server--port-forwardfalse通过端口转发连接一个随机 argocd-server 端口--insecurefalse跳过服务器证书与域名校验--plaintextfalse禁用 TLS--grpc-webfalse启用 gRPC-web 协议Argo CD server 位于不支持 HTTP2 的代理之后时使用--grpc-web-root-path string—启用 gRPC-web 协议并设置 web 根路径--logformat stringjson日志格式取值为json或text--loglevel stringinfo日志级别取值为debug、info、warn、error--kube-context string—指定命令使用的 kube-context--controller-name stringargocd-application-controllerApplication controller 名称Helm 安装导致名称标签不同时可通过此参数或ARGOCD_APPLICATION_CONTROLLER_NAME环境变量设置--server-name stringargocd-serverArgo CD API server 名称支持同名环境变量ARGOCD_SERVER_NAME--repo-server-name stringargocd-repo-serverRepo server 名称支持ARGOCD_REPO_SERVER_NAME环境变量--redis-name stringargocd-redisRedis deployment 名称支持ARGOCD_REDIS_NAME环境变量--redis-haproxy-name stringargocd-redis-ha-haproxyRedis HA Proxy 名称支持ARGOCD_REDIS_HAPROXY_NAME环境变量--redis-compress stringgzip当 application controller 启用了 redis 压缩时启用可选值gzip、none--http-retry-max int—建立到 Argo CD server 的 http 连接的最大重试次数-H, --header strings—为 Argo CD CLI 的所有请求附加额外 header可重复添加也支持逗号分隔--client-crt string/--client-crt-key string/--server-crt string—客户端/服务器证书文件及密钥文件--prompts-enabled默认 false取决于本地配置强制启用或禁用可选的交互提示子命令速查与文档索引argocd cluster共包含 6 个子命令对应仓库中的独立命令参考文档argocd cluster add — 添加集群argocd cluster add CONTEXTargocd cluster get — 获取集群信息argocd cluster list — 列出已配置集群argocd cluster rm — 移除集群凭据argocd cluster rotate-auth — 轮换集群认证凭据argocd cluster set — 设置集群信息根命令入口见 argocd.mdargocd controls an Argo CD server。在 CLI 源码层面这些命令统一实现在 cmd/argocd/commands/cluster.go 中NewClusterCommand负责组装子命令第 50 行起随后依次是NewClusterAddCommand第 86 行、NewClusterSetCommand第 258 行、NewClusterGetCommand第 347 行、NewClusterListCommand第 525 行和NewClusterRotateAuthCommand第 572 行。argocd cluster add注册目标集群argocd cluster add用于把 kubeconfig 中已存在的 context 注册为 Argo CD 可管理的目标集群语法为argocd cluster add CONTEXT [flags]完整参数说明参数类型默认值说明--annotation stringArraystringArray—设置元数据注解例如--annotation keyvalue--aws-cluster-name stringstring—AWS 集群名称设置后使用aws cli eks token命令访问集群--aws-profile stringstring—AWS profile设置后 AWS IAM Authenticator 使用该 profile 而非默认 AWS 凭据链执行集群操作--aws-role-arn stringstring—AWS role ARN设置后 AWS IAM Authenticator 会先扮演该角色再执行集群操作--cluster-endpoint stringstring—要使用的集群端点取值之一kubeconfig、kube-public、internal--cluster-resourcesboolfalse是否管理集群级别资源仅在受管命名空间列表非空时生效--disable-compressionboolfalse绕过对服务器的自动 GZip 压缩请求--exec-command stringstring—为集群提供客户端凭据而要执行的命令你可能需要构建自定义 Argo CD 镜像以保证运行时该命令可用--exec-command-api-version stringstring—--exec-command可执行文件期望的 ExecInfo 输入版本--exec-command-args stringArraystringArray—传给--exec-command可执行文件的参数--exec-command-env stringToStringstringToString[]运行--exec-command可执行文件时设置的环境变量--exec-command-install-hint stringstring—当--exec-command可执行文件似乎不存在时显示给用户的提示文本--in-clusterboolfalse表示 Argo CD 位于该集群内部应使用内部 k8s hostnamekubernetes.default.svc连接--kubeconfig stringstring—使用特定的 kubeconfig 文件--label stringArraystringArray—设置元数据标签例如--label keyvalue--name stringstring—覆盖集群名称--namespace stringArraystringArray—允许管理的命名空间列表--project stringstring—集群所属的 project--proxy-url stringstring—使用代理连接集群--server-proxy-url stringstring—让 Argo CD server 连接该集群时使用不同的代理 URL表示无代理省略时使用--proxy-url或 kubeconfig 中的值--service-account stringstring—用于 Kubernetes 资源管理的 system 命名空间服务账号未设置时默认创建argocd-managerSA--shard intint-1集群分片号未设置时从主机名推断--system-namespace stringstringkube-system使用不同的 system 命名空间--upsertboolfalse即使 spec 不同也覆盖已存在的同名集群-y, --yesboolfalse跳过显式确认add 的底层流程argocd-manager 与 RBAC 安装从源码 cmd/argocd/commands/cluster.go 可以看出add的执行链路远比表面命令复杂校验 context 存在未传入 CONTEXT 参数时命令会打印 kubeconfig 中所有可用 context 并退出对应文档中“context 必须已存在于 kubectl config”的前提。互斥校验--in-cluster与--cluster-endpoint不能同时使用。读取 REST 配置通过getRestConfig从指定 context 构建连接配置若指定--proxy-url则解析后设置conf.Proxy。按凭据类型分支设置--aws-cluster-name时构造AWSAuthConfig含 ClusterName、RoleARN、Profile使用aws cli eks token认证设置--exec-command时构造ExecProviderConfigCommand、Args、Env、APIVersion、InstallHint通过 exec 插件获取客户端凭据默认情况下安装 RBAC 资源若指定了--service-account直接获取该 SA 的 Bearer token否则在交互终端且未加-y时提示“WARNING: This will create a service accountargocd-manageron the cluster referenced by context...with full cluster/namespace level privileges”确认后调用clusterauth.InstallClusterManagerRBAC创建argocd-manager服务账号并授予足够的集群管理权限实现见 util/clusterauth。组装 Cluster 对象解析--label/--annotation为标签与注解映射通过cmdutil.NewCluster构建 Cluster CRD 对象若显式传了--server-proxy-url则以该值覆盖 Argo CD server 连接该集群所用的代理空串表示“无代理”典型场景是本地需要代理而集群间可直连。端点覆盖--cluster-endpoint internal会把clst.Server设为kubernetes.default.svcKubernetesInternalAPIServerAddr--cluster-endpoint kube-public则从集群的kube-publicConfigMap 获取公网端点与 CA 数据失败时回退到 kubeconfig context 中的端点。分片与项目归属--shard 0时写入 Shard 字段指定--project时设置 Project。调用 API构造ClusterCreateRequest{Cluster, Upsert}通过 gRPC 客户端调用clusterIf.Create成功输出Cluster server added。add 实战示例# 最基本的添加方式使用 kubeconfig 中的 context自动创建 argocd-manager SA argocd cluster add prod-cluster # 跳过交互确认 argocd cluster add prod-cluster -y # 只允许管理指定命名空间后续再配合 --cluster-resources 管理集群级资源 argocd cluster add prod-cluster --namespace default --namespace observability # 覆盖集群名称并附加标签/注解 argocd cluster add prod-cluster --name production-us-east-1 \ --label envprod --annotation teamplatform # 使用 AWS EKS 认证 argocd cluster add eks-cluster --aws-cluster-name my-eks --aws-profile prod # 通过代理连接目标集群 argocd cluster add proxy-cluster --proxy-url http://proxy.example.com:3128 # 集群已存在但 spec 有变化时强制覆盖 argocd cluster add prod-cluster --upsertargocd cluster list列出已配置集群argocd cluster list用于查看当前 Argo CD 已注册的全部集群argocd cluster list [flags]支持-h, --help与-o, --output两个选项输出格式取值为json、yaml、wide、server默认wide。官方示例# 默认 wide 格式列出集群 argocd cluster list # 通过指定 server 地址列出集群 argocd cluster list --server ARGOCD_SERVER_ADDRESS # JSON 格式 argocd cluster list -o json --server ARGOCD_SERVER_ADDRESS # YAML 格式 argocd cluster list -o yaml --server ARGOCD_SERVER_ADDRESS # 仅列出集群 server 地址 argocd cluster list -o server ARGOCD_SERVER_ADDRESS从源码 cluster.go 看list通过 gRPC 调用clusterIf.List获取全部集群然后按输出格式分发yaml/json走PrintResourceList打印完整 CRD 对象server走printClusterServers只输出地址列表wide/空值走printClusterTable输出表格未知格式则报错退出。这意味着-o json输出的正是 Cluster CRD 的完整结构server、name、namespaces、config、labels 等字段可直接用于脚本解析或审计。argocd cluster get查看单个集群信息argocd cluster get SERVER/NAME [flags]get支持按服务器地址或集群名称两种方式定位集群argocd cluster get https://12.34.567.89 argocd cluster get in-cluster选项与list相同-h, --help与-o, --output但默认输出格式为yaml与list的默认wide不同同样支持json|yaml|wide|server四种格式。get常用于查看某个集群的完整配置细节例如命名空间授权范围、TLS 配置、标签注解等便于排障与审计。argocd cluster set修改集群信息argocd cluster set NAME [flags]set用于就地更新已有集群的配置官方示例与argocd cluster父命令中的示例一致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支持参数参数类型说明--annotation stringArraystringArray设置元数据注解如--annotation keyvalue-h, --help—显示帮助--label stringArraystringArray设置元数据标签如--label keyvalue--name stringstring覆盖集群名称--namespace stringArraystringArray允许管理的命名空间列表指定*表示管理所有命名空间注意set只支持名称定位NAME这点与get、rm、rotate-auth支持SERVER/NAME双定位不同。其中--namespace *是放开全部命名空间授权的常用写法而显式罗列多个命名空间则是受限授权场景的典型用法。argocd cluster rm移除集群凭据argocd cluster rm SERVER/NAME [flags]官方示例支持按服务器地址或集群名称移除argocd cluster rm https://12.34.567.89 argocd cluster rm cluster-name选项仅有两个-h, --help与-y, --yes关闭移除集群资源前的确认提示。由于rm会同时清理 Argo CD 侧保存的凭据及其关联状态默认带交互确认脚本化执行时记得加-y。argocd cluster rotate-auth轮换认证凭据argocd cluster rotate-auth SERVER/NAME [flags]当目标集群侧的argocd-manager服务账号令牌需要轮换例如安全策略要求定期更换、怀疑令牌泄露时使用该命令argocd cluster rotate-auth https://12.34.567.89 argocd cluster rotate-auth cluster-name该命令仅支持-h, --help。从源码 cluster.go 看rotate-auth解析单个参数后调用clusterIf.RotateAuth成功后输出Cluster server rotated auth。其底层会为目标集群生成新的认证凭据并更新 Argo CD 中保存的 Cluster 配置从而在不重新执行add的情况下完成凭据更换。深入理解Cluster 模型与关键概念Cluster CRD 与 in-cluster 特例argocd cluster系列命令操作的核心对象是argoproj.io下的 Cluster 资源定义于 pkg/apis/application/v1alpha1 的 Cluster 类型。每个集群记录包含 server 地址、名称、认证配置Config、受管命名空间Namespaces、标签注解、所属 Project 与 Shard 等字段。其中in-cluster是 Argo CD 自身的集群其 server 地址为https://kubernetes.default.svc。在add时使用--in-cluster或--cluster-endpoint internal即会写入该内部地址源码中的KubernetesInternalAPIServerAddr常量因此argocd cluster get in-cluster可以直接查看内建集群配置。命名空间授权与 cluster-resources--namespace与--cluster-resources共同决定了 Argo CD 在目标集群的管控范围默认未指定--namespace时Argo CD 通过argocd-manager获得集群级权限可管理任意命名空间中的资源指定一个或多个--namespace后argocd-manager的 RBAC 会被限定在这些命名空间内对应add交互提示中的namespace level privileges此时--cluster-resources决定是否额外授予集群级资源管理权限——文档明确说明该设置“仅在受管命名空间列表非空时生效”。这种受限授权模式适合多租户隔离、合规要求严格的场景。集群分片shard--shard用于把不同集群分配到 application controller 的不同分片实现水平扩展。add中该参数默认-1表示未显式指定此时分片会从集群主机名推断。多 controller 部署时正确配置 shard 可以让不同集群的编排工作负载均衡到不同 controller 实例。认证方式的多样化add命令支持四种认证路径覆盖了绝大多数云环境默认 RBAC 服务账号自动创建/使用argocd-managerSA适用于普通 Kubernetes 集群AWS IAM Authenticator--aws-cluster-name等通过 EKS token 认证exec 凭据插件--exec-command系列复用 kubeconfig 的 exec 认证模式如 gcloud、azure 等插件由于该命令需要运行在 Argo CD 侧文档特别提示可能需自定义镜像来内置可执行文件代理访问通过--proxy-url/--server-proxy-url在受限网络下访问集群其中--server-proxy-url专门控制 Argo CD server 侧的出站连接。延伸阅读集群相关命令的源码实现cmd/argocd/commands/cluster.go各子命令官方参考add、list、get、set、rm、rotate-authCLI 根命令参考argocd认证安装相关实现util/clusterauth【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考