Argo CDargocd app sync命令详解按应用、源与资源粒度选择性同步【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本文以 Argo CD 官方命令参考 argocd_app_sync.md 为核心完整覆盖argocd app sync的全部选项与用法示例并结合 CLI 实现源码 NewApplicationSyncCommand 深入解析其参数校验、资源过滤、同步策略与本地同步等底层行为。读完后你将能够正确选择要同步的应用按名称、标签选择器或项目、对多源应用指定特定源与修订版本、按GROUP:KIND:NAME精确圈定同步资源、并通过重试、策略与预览类标志控制同步全过程。命令概述argocd app sync将应用同步到其目标状态target state。它支持三种互斥的应用选择方式argocd app sync [APPNAME... | -l selector | --project project-name] [flags]位置参数APPNAME...可以传入一个或多个应用名逐个同步-l selector按标签选择应用支持、、!、in、notin、存在与不存在判断匹配的应用必须同时满足所有标签约束--project同步属于指定项目的应用可重复指定。从源码的参数校验逻辑cmd/argocd/commands/app.go#L1769-L1801可以看到三条硬性规则必须提供应用名、-l selector或--project三者之一否则打印帮助并以退出码 1 终止位置参数与-l selector不能混用Cannot use selector option when application name(s) passed as argument(s)--revisions、--source-positions、--source-names要求恰好传入1 个应用名且--source-positions与--source-names二者只能指定其一--revisions与它们的取值个数必须一一对应--source-positions的计数从 1 开始、不允许 0 或负数。若通过 selector 或 project 查询后没有任何匹配应用命令会以No matching apps found for filter:报错终止与argocd app list静默返回空列表不同同步属于破坏性操作未匹配到目标时必须显式失败见 cmd/argocd/commands/app.go#L1835-L1845。官方示例全集以下是命令参考中给出的全部示例可直接复制运行# Sync an app argocd app sync my-app # Sync multiples apps argocd app sync my-app other-app # Sync apps by label, in this example we sync apps that are children of another app (aka app-of-apps) argocd app sync -l app.kubernetes.io/instancemy-app argocd app sync -l app.kubernetes.io/instance!my-app argocd app sync -l app.kubernetes.io/instance argocd app sync -l !app.kubernetes.io/instance argocd app sync -l app.kubernetes.io/instance notin (my-app,other-app) # Sync a multi-source application for specific revision of specific sources argocd app sync my-app --revisions 0.0.1 --source-positions 1 --revisions 0.0.2 --source-positions 2 argocd app sync my-app --revisions 0.0.1 --source-names my-chart --revisions 0.0.2 --source-names my-values # Sync a specific resource # Resource should be formatted as GROUP:KIND:NAME. If no GROUP is specified then :KIND:NAME argocd app sync my-app --resource :Service:my-service argocd app sync my-app --resource argoproj.io:Rollout:my-rollout argocd app sync my-app --resource !apps:Deployment:my-service argocd app sync my-app --resource apps:Deployment:my-service --resource :Service:my-service argocd app sync my-app --resource !*:Service:* # Specify namespace if the application has resources with the same name in different namespaces argocd app sync my-app --resource argoproj.io:Rollout:my-namespace/my-rollout完整选项清单以下为参考文档列出的全部命令级选项-N, --app-namespace string Only sync an application in namespace --apply-out-of-sync-only Sync only out-of-sync resources --assumeYes Assume yes as answer for all user queries or prompts --async Do not wait for application to sync before continuing --dry-run Preview apply without affecting cluster --force Use a force apply -h, --help help for sync --ignore-normalizer-jq-execution-timeout duration Set ignore normalizer JQ execution timeout (default 1s) --info stringArray A list of key-value pairs during sync process. These infos will be persisted in app. --label stringArray Sync only specific resources with a label. This option may be specified repeatedly. --local string Path to a local directory. When this flag is present no git queries will be made --local-repo-root string Path to the repository root. Used together with --local allows setting the repository root (default /) -o, --output string Output format. One of: json|yaml|wide|tree|treedetailed (default wide) --preview-changes Preview difference against the target and live state before syncing app and wait for user confirmation --project stringArray Sync apps that belong to the specified projects. This option may be specified repeatedly. --prune Allow deleting unexpected resources --replace Use a kubectl create/replace instead apply --resource stringArray Sync only specific resources as GROUP:KIND:NAME or !GROUP:KIND:NAME. Fields may be blank and * can be used. This option may be specified repeatedly --retry-backoff-duration duration Retry backoff base duration. Input needs to be a duration (e.g. 2m, 1h) (default 5s) --retry-backoff-factor int Factor multiplies the base duration after each failed retry (default 2) --retry-backoff-max-duration duration Max retry backoff duration. Input needs to be a duration (e.g. 2m, 1h) (default 3m0s) --retry-limit int Max number of allowed sync retries --retry-refresh Indicates if the latest revision should be used on retry instead of the initial one --revision string Sync to a specific revision. Preserves parameter overrides --revisions stringArray Show manifests at specific revisions for source position in source-positions -l, --selector string Sync apps that match this label. Supports , , !, in, notin, exists not exists. Matching apps must satisfy all of the specified label constraints. --server-side Use server-side apply while syncing the application --server-side-diff-concurrency int Max concurrent batches for server-side diff. -1 unlimited, 1 sequential, 2 concurrent (0 invalid) (default -1) --server-side-diff-max-batch-kb int Max batch size in KB for server-side diff. Smaller values are safer for proxies (default 250) --source-names stringArray List of source names. Default is an empty array. --source-positions int64Slice List of source positions. Default is empty array. Counting start at 1. (default []) --strategy string Sync strategy (one of: apply|hook) --timeout uint Time out after this many seconds下面按功能域分组详解各选项的用途与源码中的落点。应用选择标签选择器与项目过滤-l/--selector走的是ApplicationQuery.Selector的服务端过滤cmd/argocd/commands/app.go#L1827-L1850因此可以一次同步成百上千个应用。典型场景是同步 app-of-apps应用的子应用集合子应用由 Application of Applications 自动打上app.kubernetes.io/instance父应用名标签用argocd app sync -l app.kubernetes.io/instancemy-app即可批量同步。--project可重复传入多个项目名与-N/--app-namespace组合可把同步范围限定到某个 Argo CD 实例命名空间内的指定项目。注意-N还会影响位置参数中省略命名空间时的解析未带/的应用名会被自动补全为app-namespace/appnamecmd/argocd/commands/app.go#L1873-L1878。多源应用--revisions/--source-positions/--source-names多源multi-source应用由 Helm 与 Kustomization/目录等多个 source 拼装而成。此时不能再用--revision源码中显式拦截对多源应用使用--revision会报argocd cli does not work on multi-source app with --revision flag. Use --revisions and --source-positions instead.对多源应用使用--local同样被拒绝cmd/argocd/commands/app.go#L1924-L1934。--revisions与--source-positions从 1 计数的源位置数组或--source-names源名称数组经 getSourceNameToPositionMap 换算成位置一一配对表示「为指定源取该修订版本下的清单」。这组参数最终写入ApplicationSyncRequest.Revisions与ApplicationSyncRequest.SourcePositionscmd/argocd/commands/app.go#L1980-L1992由仓库服务器按源生成对应清单。资源级同步--resource与--label--resource按GROUP:KIND:NAME圈定要同步的资源三个字段均可留空并使用*通配前缀!表示排除。解析逻辑在 parseSelectedResources省略 GROUP 时写作:KIND:NAME如:Service:my-service省略 KIND/NAME 时留空即可因此*:Service:*表示全部 Service当应用内同名资源分布在多个命名空间时NAME 字段可写为NAMESPACE/NAME如argoproj.io:Rollout:my-namespace/my-rollout源码中通过resourceFieldNamespaceDelimiter /拆分命名空间与名称可重复传入多个--resource实现「包含某些、排除某些」的组合圈定。解析后的过滤器与应用的Status.Resources做交集filterAppResources 遍历应用已知资源用argo.IncludeResource判断是否命中至少一个过滤器排除式条目用于从命中集中剔除。若最终没有任何资源匹配--resource/--label命令会直接报No matching app resources found for resource filter而不会发起空同步cmd/argocd/commands/app.go#L1936-L1942。--label则是另一条更直观的资源筛选路径先向 API Server 请求该应用的 manifestsGetManifests逐个解析为对象凡是对象 label 与给定keyvalue匹配的资源被自动转换为GROUP:KIND:NAME追加到--resource过滤器中cmd/argocd/commands/app.go#L1880-L1913。找不到匹配资源时同样报错退出。典型用途只同步同一部署中打了tierfrontend标签的那部分资源。同步策略与执行行为--strategy决定同步采用哪种策略源码中的映射为cmd/argocd/commands/app.go#L1994-L2003applykubectl apply 风格的原地应用--force透传为SyncStrategyApply.Forcehook或留空默认执行 Argo CD 生命周期 Hook--force透传为SyncStrategyHook.Force传入其他值会报Unknown sync strategy。--replace、--server-side、--apply-out-of-sync-only三个布尔标志会被打包进SyncOptions.Items字符串化选项列表随同步请求下发见 syncOptionsFactory--replace以 kubectl create/replace 语义代替 apply--server-side同步时启用 server-side apply--apply-out-of-sync-only只同步处于 out-of-sync 状态的资源已同步的资源不再触发 apply可减少无谓的变更扰动。其余行为控制标志--prune允许删除「意外资源」目标中已不存在的资源。同步完成后 CLI 还会检查是否需要剪枝若操作成功但最终状态非 Synced 且存在待剪枝资源会以N resources require pruning提示终止cmd/argocd/commands/app.go#L2048-L2057--dry-run预览 apply 而不影响集群--async发起同步后立即返回不等待结果不加该标志时 CLI 会调用waitOnApplicationStatus阻塞等待操作完成--timeout控制等待上限单位秒--revision同步到指定修订版本保留参数覆盖仅适用于单源应用--infokeyvalue形式的键值对列表经 getInfos 解析后持久化到应用的同步操作信息中可用于在操作历史里标注「本次同步的原因」-o/--output输出格式支持json|yaml|wide|tree|treedetailed默认wide。重试策略--retry-limit与退避参数只要--retry-limit非 0CLI 就会把整组退避参数组装为RetryStrategy随请求下发cmd/argocd/commands/app.go#L2004-L2014标志含义默认值--retry-limit允许的最大同步重试次数0不启用重试--retry-backoff-duration退避基础时长5s--retry-backoff-factor每次失败后乘以基础时长的系数2--retry-backoff-max-duration退避时长上限3m--retry-refresh重试时是否刷新到最新修订版本而非沿用初始版本false默认值对应argoappv1.DefaultSyncRetryDuration、DefaultSyncRetryFactor、DefaultSyncRetryMaxDuration三个 API 默认常量cmd/argocd/commands/app.go#L2070-L2074。注意--retry-limit与其余退避标志是组合生效的不设置--retry-limit时退避参数不会随请求发送。本地同步--local与--local-repo-root--local指定一个本地目录路径CLI 直接在本地生成清单不做任何 git 查询配合--local-repo-root默认/设置仓库根路径。这条路径主要服务于离线/本地开发场景。源码中有两个明确限制cmd/argocd/commands/app.go#L1945-L1957应用若启用了自动同步策略Automated Sync则禁止本地同步除非同时加--dry-run否则报Cannot use local sync when Automatic Sync Policy is enabled except with --dry-run多源应用不支持--local见上文多源一节。同步前预览--preview-changes与--assumeYes--preview-changes会在真正同步之前调用ManagedResources拉取应用的实时与期望状态并打印差异Previewing differences between live and desired state of application ...若未发现差异打印No Differences found后直接返回不发起同步若发现差异会交互式询问Do you want to continue the sync process? (y/n)回答n则以退出码 0 结束加上--assumeYes可跳过所有交互确认适合 CI 管道等无人值守场景。该流程实现于 cmd/argocd/commands/app.go#L2015-L2040。另外若应用带有ServerSideDifftrue比较选项注解预览会自动切换到 server-side diff 路径--server-side-diff-concurrency默认-1即不限制并发批次与--server-side-diff-max-batch-kb默认250KB值越小对代理转发越安全用于控制这一过程的并发与批大小--ignore-normalizer-jq-execution-timeout默认1s则控制忽略差异 JQ 归一化脚本的执行超时。继承自父命令的通用选项argocd app sync继承 argocd 根命令的全部客户端连接选项摘录如下完整列表见参考文档--argocd-context string The name of the Argo-CD server context to use --auth-token string Authentication token; set this or the ARGOCD_AUTH_TOKEN environment variable --client-crt string Client certificate file --client-crt-key string Client certificate key file --config string Path to Argo CD config (default /home/user/.config/argocd/config) --controller-name string Name of the Argo CD Application controller (default argocd-application-controller) --core If set to true then CLI talks directly to Kubernetes instead of talking to Argo CD API server --grpc-web Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. --grpc-web-root-path string Enables gRPC-web protocol. Set web root. -H, --header strings Sets additional header to all requests made by Argo CD CLI. --http-retry-max int Maximum number of retries to establish http connection to Argo CD server --insecure Skip server certificate and domain verification --kube-context string Directs the command to the given kube-context --logformat string Set the logging format. One of: json|text (default json) --loglevel string Set the logging level. One of: debug|info|warn|error (default info) --plaintext Disable TLS --port-forward Connect to a random argocd-server port using port forwarding --port-forward-namespace string Namespace name which should be used for port forwarding --prompts-enabled Force optional interactive prompts to be enabled or disabled, overriding local configuration. --redis-compress string Enable this if the application controller is configured with redis compression enabled. (default gzip) --redis-haproxy-name string Name of the Redis HA Proxy (default argocd-redis-ha-haproxy) --redis-name string Name of the Redis deployment (default argocd-redis) --repo-server-name string Name of the Argo CD Repo server (default argocd-repo-server) --server string Argo CD server address --server-crt string Server certificate file --server-name string Name of the Argo CD API server (default argocd-server)这些选项决定 CLI 如何连接到 Argo CD API Server--server、TLS 证书、gRPC-web、端口转发等在执行任何同步操作前应先确认登录态与服务器地址配置正确。小结与相关命令选应用位置参数 /-l selector/--project三选一selector 与位置参数互斥选源多源应用用--revisions配对--source-positions或--source-names选资源--resourceGROUP:KIND:NAME支持!排除、*通配、NAMESPACE/NAME与--label自动转换为资源过滤器控行为--strategy、--force、--replace、--server-side、--apply-out-of-sync-only、--prune、--dry-run、--async控韧性--retry-limit 三个退避参数 --retry-refresh控确认--preview-changes预览差异 --assumeYes跳过交互。相关命令可参考同一目录下的 argocd app管理应用的父命令以及argocd_app_wait.md、argocd_app_rollback.md、argocd_app_diff.md等姊妹命令文档。本文所有源码路径均基于当前仓库行号对应 cmd/argocd/commands/app.go 的实现版本命令行为可能随版本演进实际使用时请以argocd app sync --help输出为准。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考