Argo CD CLI 实战argocd app manifests命令完整参考与源码级解析【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd导读argocd app manifests是 Argo CD 命令行工具中用于**打印指定 Application 的清单manifests**的核心命令它允许开发者在终端中直接查看某个应用的目标清单来自 Git 或本地目录或当前运行在集群中的实际清单live 状态。本篇文章以官方命令参考文档为主体结合仓库中命令的 Go 源码实现cmd/argocd/commands/app.go完整讲解该命令的语法、全部参数、多源multi-source应用按修订revision查看清单的技巧以及底层调用链与输出格式让你能够熟练运用它进行应用清单的调试、审计与 CI 集成。一、命令概览与使用场景argocd app manifests命令的作用是Print manifests of an application即打印一个应用程序的清单。在实际的 GitOps 工作流中它常被用于验证期望状态查看 Argo CD 认为某应用应部署的清单默认来自 Git 仓库的git源对比实时状态通过--source live查看集群中当前实际运行的资源清单按版本排查在回滚或故障定位时查看某个特定 revision 的清单内容本地预渲染检查在提交代码前用--local让 CLI 直接从本地目录生成清单快速核对模板渲染结果CI 集成在流水线中获取应用清单用于静态分析或审计。该命令隶属于argocd app命令组在源码中通过command.AddCommand(NewApplicationManifestsCommand(clientOpts))注册参见 cmd/argocd/commands/app.go。基本语法argocd app manifests APPNAME [flags]其中APPNAME为必填参数即 Application 的名称。若应用位于非默认命名空间可通过-N/--app-namespace指定。二、官方示例详解文档给出了四组典型示例覆盖了单源、指定修订、多源按名称、多源按位置四种场景# 1. 获取应用的清单默认使用 git 源、当前目标修订 argocd app manifests my-app # 2. 获取应用在指定修订revision下的清单 argocd app manifests my-app --revision 0.0.1 # 3. 多源应用为指定 source 名称source-names分别获取对应修订的清单 argocd app manifests my-app --revisions 0.0.1 --source-names src-base --revisions 0.0.2 --source-names src-values # 4. 多源应用为指定 source 位置source-positions分别获取对应修订的清单 argocd app manifests my-app --revisions 0.0.1 --source-positions 1 --revisions 0.0.2 --source-positions 2示例 1是最常见用法不附加任何修订参数时命令取用 Application 当前的目标状态target state即 Argo CD 已经为应用计算的、来自清单仓库的期望资源集合。示例 3 与 4针对的是多源应用spec.sources中存在多个 source。两者都需要配合--revisionsstringArray 类型可重复出现使用区别在于定位 source 的方式--source-names使用多源中每个 source 的name字段定位--source-positions使用 source 在spec.sources列表中的从 1 开始计数的位置定位。两者的底层实现都落在同一套逻辑上--source-names会被转换为位置后再查询。在 NewApplicationManifestsCommand 中源码首先从已获取的 Application 对象上调用getSourceNameToPositionMap(app)构建「名称 → 位置」映射然后把名称一一翻译成位置if len(sourceNames) 0 { sourceNameToPosition : getSourceNameToPositionMap(app) for _, name : range sourceNames { pos, ok : sourceNameToPosition[name] if !ok { log.Fatalf(Unknown source name %s, name) } sourcePositions append(sourcePositions, pos) } }而getSourceNameToPositionMapcmd/argocd/commands/app.go的实现非常直观遍历app.Spec.Sources跳过未设置name的 source将name映射为i 1位置从 1 开始func getSourceNameToPositionMap(app *argoappv1.Application) map[string]int64 { sourceNameToPosition : make(map[string]int64) for i, s : range app.Spec.Sources { if s.Name ! { sourceNameToPosition[s.Name] int64(i 1) } } return sourceNameToPosition }这也解释了为什么文档中--source-positions的说明强调 Counting start at 1计数从 1 开始。三、专属选项Options全参数说明以下是该命令自身的全部选项及其含义选项简写类型默认值说明--app-namespace-Nstring空Application 所在的命名空间--help-hbool-显示 manifests 子命令的帮助信息--local-string空若设置则展示本地生成的清单。取值为清单仓库中应用清单的绝对路径例如/home/username/apps/env/app-1--local-repo-root-string.本地仓库根目录路径。与--local一起使用用于设定仓库根例如/home/username/apps--revision-string空展示指定修订revision下的清单--revisions-stringArray空数组为--source-positions对应位置上的 source 分别指定修订可重复传入--source-stringgit清单来源取值为live或git之一--source-names-stringArray空数组source 名称列表--source-positions-int64Slice空数组source 位置列表计数从 1 开始参数使用要点--source选择目标清单还是实时清单git默认展示目标状态target state即从 Git 清单仓库渲染出的期望资源live展示实时状态live state即当前部署在目标集群中的实际资源。--revision与--revisions的区别--revision用于单源应用直接指定一个修订号--revisions是 stringArray 类型可以重复出现多次如示例 3、4 所示用于多源应用为不同的 source 指定不同的修订必须与--source-positions或--source-names数量一一对应。--local与--local-repo-root两者必须搭配使用--local指向应用清单所在目录--local-repo-root指向本地仓库根。CLI 会在本地直接调用 repo-server 的清单生成逻辑repository.GenerateManifests见 cmd/argocd/commands/app_diff.go渲染清单而无需先提交代码需要特别注意的是源码注释明确标注getLocalObjects为Deprecated: Prefer server-side generation since local side generation does not support plugins已弃用优先使用服务端生成因为本地生成不支持插件。同时本地生成模式下 Secret 资源会被跳过并输出警告参见 cmd/argocd/commands/app_diff.go因为本地 diff 无法可靠地使用服务端配置隐藏 Secret 数据。因此该模式更适合快速的模板渲染检查生产环境请优先使用默认的服务端生成方式。四、继承自父命令的全局选项argocd app manifests还继承了argocd根命令的全部全局选项常见于连接与认证配置选项说明--argocd-context要使用的 Argo CD server 上下文名称--auth-token认证令牌设置此参数或ARGOCD_AUTH_TOKEN环境变量--client-crt/--client-crt-key客户端证书文件及密钥文件--configArgo CD 配置文件路径默认/home/user/.config/argocd/config--controller-nameApplication controller 名称安装 Helm chart 时名称可能与默认不同默认argocd-application-controller也支持ARGOCD_APPLICATION_CONTROLLER_NAME环境变量--core若为 trueCLI 直接与 Kubernetes 通信而不经过 Argo CD API server--grpc-web启用 gRPC-web 协议当 Argo CD server 位于不支持 HTTP2 的代理之后时有用--grpc-web-root-path启用 gRPC-web 协议并设置 web 根路径-H, --header为所有 Argo CD CLI 请求附加额外的 header可重复添加也支持逗号分隔的多个 header--http-retry-max建立到 Argo CD server 的 HTTP 连接的最大重试次数--insecure跳过服务器证书与域名验证--kube-context指定命令使用的 kube-context--logformat日志格式json或text默认json--loglevel日志级别debug、info、warn或error默认info--plaintext禁用 TLS--port-forward使用端口转发连接一个随机 argocd-server 端口--port-forward-namespace端口转发使用的命名空间名称--prompts-enabled强制启用/禁用可选交互提示覆盖本地配置未指定时使用本地配置值默认 false--redis-compress当 Application controller 启用了 Redis 压缩时启用可选gzip、none默认gzip--redis-haproxy-nameRedis HA Proxy 名称HA Proxy 名称标签与默认不同时设置默认argocd-redis-ha-haproxy也支持ARGOCD_REDIS_HAPROXY_NAME--redis-nameRedis deployment 名称默认argocd-redis也支持ARGOCD_REDIS_NAME--repo-server-nameRepo server 名称默认argocd-repo-server也支持ARGOCD_REPO_SERVER_NAME--serverArgo CD server 地址--server-crt/--server-name服务器证书文件 / API server 名称--server-name默认argocd-server也支持ARGOCD_SERVER_NAME实际使用示例# 使用 core 模式直接与 Kubernetes 通信无需 argocd-server argocd app manifests my-app --core # 通过端口转发连接服务器 argocd app manifests my-app --port-forward # 使用 token 认证并指定服务器地址 argocd app manifests my-app --server argocd.example.com:443 --auth-token $ARGOCD_AUTH_TOKEN五、源码级原理命令的执行流程理解了参数后我们深入 NewApplicationManifestsCommand 的实现梳理整条执行链路。命令的Run逻辑大致分为五个阶段阶段 1参数校验if len(args) ! 1 { c.HelpFunc()(c, args) os.Exit(1) } if len(sourceNames) 0 len(sourcePositions) 0 { errors.Fatal(errors.ErrorGeneric, Only one of source-positions and source-names can be specified.) } if len(sourcePositions) 0 len(revisions) ! len(sourcePositions) { errors.Fatal(errors.ErrorGeneric, While using --revisions and --source-positions, length of values for both flags should be same.) } if len(sourceNames) 0 len(revisions) ! len(sourceNames) { errors.Fatal(errors.ErrorGeneric, While using --revisions and --source-names, length of values for both flags should be same.) } for _, pos : range sourcePositions { if pos 0 { log.Fatal(source-position cannot be less than or equal to 0, Counting starts at 1) } }从源码可以确认以下三条硬性校验规则--source-names与--source-positions不能同时使用否则直接报错退出使用--revisions时其数量必须与--source-positions或--source-names的数量严格相等即一一配对--source-positions中的每个位置必须 0计数从 1 开始。阶段 2解析应用名称并建立客户端连接appName, appNs : argo.ParseFromQualifiedName(args[0], appNamespace) clientset : headless.NewClientOrDie(clientOpts, c) conn, appIf : clientset.NewApplicationClientOrDieWithContext(ctx)应用名称支持namespace/name形式的限定名-N指定的命名空间作为兜底。随后建立与 Argo CD API server 的 gRPC 连接获取 ApplicationService 客户端并调用appIf.Get拉取 Application 对象。阶段 3获取受管资源ManagedResourcesresources, err : appIf.ManagedResources(ctx, application.ResourcesQuery{ ApplicationName: appName, AppNamespace: appNs, })这一步从 server 端取回应用当前管理managed的所有资源的ResourceDiff列表——每个ResourceDiff中同时携带了该资源的 target state目标状态与 live state实时状态的 JSON 快照。这正是后续git源默认分支与live源能够直接打印的基础数据。阶段 4按--source分支生成 unstructured 对象源码中switch source分两大分支git分支默认又分三种子情形--local已设置进入本地生成流程。代码会依次获取 Argo CD 设置settings、目标集群信息cluster与项目project再调用getLocalObjects(ctx, app, proj.Project, local, localRepoRoot, argoSettings, cluster.Info)实现见 cmd/argocd/commands/app_diff.go最终经由repository.GenerateManifests在本地渲染清单--revisions--source-positions已设置多源指定修订构造application.ApplicationManifestQuery一次性传入Revisions与SourcePositions调用appIf.GetManifests(ctx, q)由 server 端渲染返回的每个清单字符串通过argoappv1.UnmarshalToUnstructured反序列化为 unstructured 对象--revision已设置单源指定修订构造仅含Revision的ApplicationManifestQuery并调用appIf.GetManifests默认无修订参数直接复用阶段 3 拉回的resources通过targetObjects(resources.Items)cmd/argocd/commands/app.go把每个ResourceDiff的target状态反序列化为 unstructured 对象func targetObjects(resources []*argoappv1.ResourceDiff) ([]*unstructured.Unstructured, error) { objs : make([]*unstructured.Unstructured, len(resources)) for i, resState : range resources { obj, err : resState.TargetObject() ... } return objs, nil }live分支调用cmdutil.LiveObjects(resources.Items)cmd/util/app.go逻辑与targetObjects对称反序列化每个ResourceDiff的live状态func LiveObjects(resources []*argoappv1.ResourceDiff) ([]*unstructured.Unstructured, error) { objs : make([]*unstructured.Unstructured, len(resources)) for i, resState : range resources { obj, err : resState.LiveObject() ... } return objs, nil }其他--source取值会被拒绝并报错log.Fatalf(Unknown source type %s, source)。阶段 5序列化输出for _, obj : range unstructureds { fmt.Println(---) yamlBytes, err : yaml.Marshal(obj) errors.CheckError(err) fmt.Printf(%s\n, yamlBytes) }最终每个对象以YAML 文档形式打印对象之间用---分隔符隔开——这与kubectl get -o yaml的输出风格一致便于直接 pipe 给kubectl apply -f -或yq等工具继续处理。整个对象集合经过 yaml.Marshal 序列化输出的是 Kubernetes 资源的完整 YAML含 apiVersion、kind、metadata 等。一条调用链小结argocd app manifests my-app └─ NewApplicationManifestsCommand (cmd/argocd/commands/app.go) ├─ appIf.Get → 获取 Application 对象 ├─ appIf.ManagedResources → 获取 ResourceDiff 列表target live 快照 ├─ targetObjects / LiveObjects → 反序列化为 unstructured 对象 │ 或 GetManifests 走 server 端渲染或 getLocalObjects 走本地渲染 └─ yaml.Marshal --- 分隔 → 输出 YAML 文档流六、进阶实战场景场景一审计指定 revision 的期望清单回滚前核对某次提交到底会部署什么argocd app manifests my-app --revision 0.0.1 expected-v0.0.1.yaml场景二对比目标与实时清单先导出目标清单再导出实时清单用diff快速找出漂移argocd app manifests my-app --source git target.yaml argocd app manifests my-app --source live live.yaml diff target.yaml live.yaml注意git与live两个分支的数据来源不同——git默认分支直接来自ManagedResources中的 target 快照未带修订参数时而live分支始终来自同一批ResourceDiff中的 live 快照两者天然对齐可比。场景三多源应用的修订级清单假设应用my-app有src-base和src-values两个 source# 按 source 名称指定不同修订 argocd app manifests my-app \ --revisions v1.0.0 --source-names src-base \ --revisions v2.0.0 --source-names src-values # 等价写法按 source 位置指定位置从 1 开始 argocd app manifests my-app \ --revisions v1.0.0 --source-positions 1 \ --revisions v2.0.0 --source-positions 2场景四本地快速渲染检查在提交代码前验证本地 Helm/Kustomize 渲染结果注意插件不可用、Secret 会被跳过argocd app manifests my-app \ --local /home/username/apps/env/app-1 \ --local-repo-root /home/username/apps场景五在脚本/CI 中消费输出由于输出是标准 YAML 文档流可直接与 Kubernetes 工具链串联# 统计应用期望清单中的资源数量 argocd app manifests my-app | grep -c ^kind: # 抽取所有 Deployment 的镜像 argocd app manifests my-app | yq eval-all .spec.template.spec.containers[].image - 2/dev/null || true七、相关命令与进一步阅读argocd app manifests是argocd app命令族的一员。在 cmd/argocd/commands/app.go 中可以看到它与其他子命令并列注册其中与该命令功能最相近的是argocd app get获取应用整体详情状态、同步状态、参数等见 argocd app 命令参考argocd app diff对比目标清单与实时清单的差异其底层同样复用了targetObjects/LiveObjects与本地生成逻辑getLocalObjects实现于 cmd/argocd/commands/app_diff.goargocd app sync将应用同步到目标状态manifests输出的 YAML 可以帮助你在执行同步前确认将要 apply 的内容。若需要了解 Application 多源multi-source的配置方式、spec.sources的字段定义可查阅仓库中对应的 API 类型定义 pkg/apis/application/v1alpha1 下的 Application 结构体以及官方操作手册中关于多源应用的章节。结语argocd app manifests虽然参数不多但通过--source、--revision/--revisions、--local的组合覆盖了「目标/实时/指定修订/本地渲染」四种清单查看维度是多源应用与 CI 审计场景下的高频命令。理解其背后的ManagedResources→ResourceDiff→ YAML 序列化的调用链cmd/argocd/commands/app.go能帮助你在排查部署问题时更准确地判断清单数据的来源与可信度。建议在实际环境中动手运行几次示例命令结合--source live与--source git的输出差异建立对 Argo CD 目标状态与实时状态模型的直观认识。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考