Argo CD Helm 应用管理完全指南声明式渲染、Values 体系、Hooks 映射与插件实践【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本篇指南基于 Argo CD 官方用户文档 docs/user-guide/helm.md 整理而成系统讲解如何用 Argo CD 以 GitOps 声明式方式管理 Helm Chart从 Application 中声明 chart 源、配置 values 文件与参数、理解取值优先级到 Helm hooks 与 Argo CD hooks 的映射关系再到插件安装与各类--skip-*行为开关。读完之后你可以掌握在 Argo CD 中渲染、覆盖、调试 Helm 应用的完整配置手段并结合仓库源码如 reposerver/repository/repository.go理解取值文件解析与 glob 展开的底层实现。核心机制Helm 只负责渲染生命周期由 Argo CD 接管Argo CD 支持通过 UI 或声明式 GitOps 方式安装 Helm chart但必须明确一个关键前提Helm 仅被用于执行helm template渲染 chart应用的安装、同步、删除等生命周期完全由 Argo CD 管理而不是 Helm。相关背景可参考常见问题 docs/faq.md 中关于helm ls看不到 Argo CD 部署的 Helm 应用的说明。一个典型的声明式 Application 示例如下apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: sealed-secrets namespace: argocd spec: project: default source: chart: sealed-secrets repoURL: https://bitnami.github.io/sealed-secrets targetRevision: 1.16.1 helm: releaseName: sealed-secrets destination: server: https://kubernetes.default.svc namespace: kubeseal同样支持 OCI 协议的 Helm chart 仓库注意repoURL中不包含oci://前缀apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: nginx spec: project: default source: chart: nginx repoURL: registry-1.docker.io/bitnamicharts # 注意不写 oci:// 前缀 targetRevision: 15.9.0 destination: name: in-cluster namespace: nginx提示Helm values 有多种提供方式优先级顺序为parameters valuesObject values valueFiles helm 仓库自带的 values.yaml。Helm Value Precedence 小节有更详细的示例。私有 Helm 仓库和私有 OCI 注册表的凭据配置见 docs/operator-manual/declarative-setup.md 中的 Declarative Setup 章节。Values 文件valueFilesHelm 允许使用一个或多个替代的values.yaml文件来提供参数对应helm命令的--values参数可重复指定多个文件。在 Argo CD CLI 中argocd app set helm-guestbook --values values-production.yaml版本历史说明Argo CDv2.6之前values 文件必须与 Helm chart 位于同一个 Git 仓库中如果位于 chart 根目录之外的位置可用相对 chart 根目录的相对路径访问。自v2.6起可以借助 Application 多源特性从独立于 chart 的外部仓库获取 values 文件。声明式写法source: helm: valueFiles: - values-production.yaml忽略缺失的 values 文件ignoreMissingValueFiles如果模板渲染阶段 Helm 收到不存在的 value 文件会直接报错。可以使用--ignore-missing-value-files忽略缺失的文件即不把它传给 Helm这在配合 Application Sets 实现默认值/覆盖值default/override模式时尤其有用source: helm: valueFiles: - values-common.yaml - values-optional-override.yaml ignoreMissingValueFiles: true从源码看这一逻辑实现在 repo-server 的取值文件解析函数getResolvedValueFiles中见 reposerver/repository/repository.go对每个非 glob 的本地路径先做os.Stat存在性检查文件缺失且ignoreMissingValueFiles为真时仅记录 debug 日志并跳过否则继续走 Helm 的报错路径。Glob 模式匹配 values 文件valueFiles条目支持 glob通配模式一次匹配多个文件。当环境覆盖文件的集合事先不可知、或希望新增文件时自动生效而无需改动 Application spec 时非常有用# 单引号可防止 shell 在 Argo CD 接收之前先展开通配符 argocd app set helm-guestbook --values envs/*.yaml声明式写法source: helm: valueFiles: - envs/*.yaml支持的通配语法Glob 展开使用 doublestar 库实现与 Application Set 生成器保持一致。源码中isGlobPath判断路径是否包含*、?、[任一字符即视为 glob 模式reposerver/repository/repository.go模式含义*匹配单个目录层级内任意一段不含分隔符的字符?匹配单个不含分隔符的字符[abc]匹配括号内列出的某个字符[a-z]匹配给定范围内的任意字符**递归匹配任意深度可跨越/分隔符文件如何传递给 Helm每个匹配到的文件都会作为独立的--values path参数按展开后的顺序传给helm template与在valueFiles中逐一列出这些文件完全等价——展开由 Argo CD 在调用 Helm 之前完成。匹配到的文件会在valueFiles列表中原位展开并按字典序字母序排序。由于 Helm 对靠后的--values参数赋予更高优先级因此字典序直接决定了同 key 冲突时哪个文件获胜envs/ a.yaml # 设置 foo: a-value b.yaml # 设置 foo: b-value# envs/*.yaml 展开为: envs/a.yaml, envs/b.yaml字典序 # b.yaml 排最后 → foo b-value source: helm: valueFiles: - envs/*.yaml当valueFiles有多个条目时条目之间的相对顺序保持不变glob 展开只会在单个模式内部重排valueFiles: - base.yaml # 最先传递 - overrides/*.yaml # 按字典序展开在 base.yaml 之后传递 - final.yaml # 最后传递优先级最高使用**递归匹配**可匹配某目录任意深度下的文件# envs/**/*.yaml 会先处理每个目录自身的文件按字母序再下降到子目录。 # # envs/a.yaml ← envs/ 下的扁平文件 a # envs/z.yaml ← envs/ 下的扁平文件 z下降前先处理 # envs/nested/c.yaml ← 位于 envs/nested/ 内在 envs/ 扁平文件之后处理 # # nested/c.yaml 排最后 → foo nested-value source: helm: valueFiles: - envs/**/*.yaml注意**匹配零个或多个路径段因此envs/**/*.yaml也会匹配envs/目录下的直接子文件而非仅子目录中的文件。doublestar 按字典序遍历目录并且先处理每个目录自身的文件按字母序再下降到其子目录。这意味着envs/z.yaml总是排在envs/nested/c.yaml之前即使按字母序n z。为了让顺序完全显式、可预测建议使用数字前缀见下文命名约定。在 glob 模式中使用环境变量构建环境变量会在 glob 求值之前被替换因此可以动态构造模式source: helm: valueFiles: - envs/$ARGOCD_APP_NAME/*.yaml这使得一个 Application 模板可以为每个应用名展开到正确的文件集合。多源multiple sources下的 glob 模式Glob 模式同样支持来自外部仓库的 value 文件。$ref变量会先解析为外部仓库的根目录其余模式在该仓库的目录树内求值sources: - repoURL: https://git.example.com/my-configs.git ref: configs - repoURL: https://git.example.com/my-chart.git path: chart helm: valueFiles: - $configs/envs/*.yaml # 匹配 my-configs 仓库中 envs/ 下的文件命名约定由于文件按字典序排序排序顺序决定了合并优先级。常见做法是用数字前缀显式表达期望顺序values/ 00-defaults.yaml 10-region.yaml 20-env.yaml 30-override.yamlvalueFiles: - values/*.yaml # 展开为: 00-defaults.yaml, 10-region.yaml, 20-env.yaml, 30-override.yaml # 30-override.yaml 拥有最高优先级不加前缀时就是纯字母序。要警惕排序不符合直觉的命名例如values-10.yaml会排在values-9.yaml之前因为字典序上1 9。约束与限制路径边界Glob 模式不能匹配仓库根目录之外的文件即使模式写成../../secrets/*.yaml也不行。Argo CD 在展开之前会先把模式的基础路径相对于仓库根目录解析任何试图逃逸出根目录的匹配都会被拒绝。符号链接Argo CD 在路径边界检查时会跟随符号链接。位于仓库内部但指向仓库外部目标的符号链接会被拒绝即使符号链接自身的路径在仓库内。该检查作用于 glob 展开产生的每一个文件包括多跳符号链接链解析后目标仍在仓库内部的符号链接则被允许。从源码看这一安全检查由verifyGlobMatchesWithinRoot实现reposerver/repository/repository.go由于doublestar.FilepathGlob内部使用os.Lstat返回的是符号链接本身位于仓库内而非其目标路径该函数会把仓库根与每个匹配项都通过filepath.EvalSymlinks规范化后再做前缀比较从而在路径到达 Helm 之前拦截指向外部的链接。绝对路径以/开头的路径被视为相对于仓库根目录而非文件系统根。模式/configs/*.yaml匹配仓库顶层configs/目录中的文件。远程 URL 不做 glob 展开远端 URL 条目如https://raw.../values.yaml会原样传给 HelmURL 中的 glob 字符没有特殊含义若字面字符不是 URL 的一部分会导致请求失败。源码中getResolvedValueFiles对isRemote的路径直接跳过展开逻辑reposerver/repository/repository.go。CLI 中的 shell 引号Shell 会在把参数传给程序之前展开通配符务必给模式加引号# 正确单引号把字面模式原样传给 Argo CD argocd app set myapp --values envs/*.yaml # 错误shell 会先针对当前目录展开 *.yaml argocd app set myapp --values envs/*.yaml去重Deduplication每个文件只会被包含一次但在确定位置时显式条目优先于 glob 匹配。如果某文件同时出现在 glob 模式和显式条目中glob 会跳过它该文件按其显式声明的位置放置valueFiles: - envs/*.yaml # 展开为 base.yaml、prod.yaml——但 prod.yaml 在下面被显式列出 # 因此 glob 跳过它此处只加入 base.yaml - envs/prod.yaml # 放在末尾获得最高 Helm 优先级这意味着你可以用 glob 收拢目录内全部文件再把某个特定文件显式列在 glob 之后钉在末尾最高优先级。若同一文件相同绝对路径被两个 glob 模式匹配它只在第一次匹配的位置出现一次后续重复匹配被静默丢弃同名但不同路径的文件视为不同文件始终都会包含valueFiles: - envs/*.yaml # 匹配 envs/base.yaml、envs/prod.yaml - envs/**/*.yaml # envs/prod.yaml 已在上面匹配跳过 # envs/nested/prod.yaml 是不同路径仍会包含源码中这一行为对应getResolvedValueFiles开头先收集全部显式路径到explicitPathsglob 展开时命中显式路径就跳过并用seen集合保证每个绝对路径只入列一次reposerver/repository/repository.go。无匹配时的行为如果某个 glob 模式没有匹配到任何文件Argo CD 会保留该 Application specspec 本身合法文件可能稍后才会加入仓库并在 Application 上暴露一个ComparisonError条件values file glob nonexistent/*.yaml matched no files在模式匹配到至少一个文件或模式被移除之前应用会保持在降级状态。文件加入仓库后无需再更新 spec。这一错误类型对应源码中的GlobNoMatchErrorreposerver/repository/repository.go注释中明确它是运行时条件而非 spec 错误。如果想让未匹配的模式静默跳过而不报错可把 glob 与ignoreMissingValueFiles组合使用source: helm: valueFiles: - envs/*.yaml ignoreMissingValueFiles: true这适用于覆盖文件在某些环境中可能不存在的默认/覆盖模式。Valuesvalues / valuesObjectArgo CD 支持在 Application manifest 中直接以source.helm.valuesObject键内联一个 values 对象source: helm: valuesObject: ingress: enabled: true path: / hosts: - mydomain.example.com annotations: kubernetes.io/ingress.class: nginx kubernetes.io/tls-acme: true labels: {} tls: - secretName: mydomain-tls hosts: - mydomain.example.com也可以用source.helm.values键以字符串形式传递 valuessource: helm: values: | ingress: enabled: true path: / hosts: - mydomain.example.com annotations: kubernetes.io/ingress.class: nginx kubernetes.io/tls-acme: true labels: {} tls: - secretName: mydomain-tls hosts: - mydomain.example.comHelm 参数parametersHelm 支持用--set设置参数值来覆盖values.yaml中的内容例如service.type是许多 chart 暴露的常见参数helm template . --set service.typeLoadBalancer类似地Argo CD 可用argocd app set命令以-p PARAMVALUE形式覆盖参数argocd app set helm-guestbook -p service.typeLoadBalancer声明式写法source: helm: parameters: - name: service.type value: LoadBalancerHelm 取值优先级各类 values 注入方式的优先级从低到高为最低 - valueFiles - values - valuesObject 最高 - parameters即valuesObject覆盖values此时values被忽略valuesObject和values都覆盖valueFiles而parameters覆盖以上所有。多个 valueFiles 之间列表靠后的文件优先级最高valueFiles: - values-file-2.yaml - values-file-1.yaml 此时 values-file-1.yaml 中的值会覆盖 values-file-2.yaml。同一来源内出现重复 key时后出现者获胜例如 values-file-1.yaml 内容为 param1: value1 param1: value3000 → 结果 param1value3000parameters: - name: param1 value: value2 - name: param1 value: value1 → 结果 param1value1values: | param1: value2 param1: value5 → 结果 param1value5注意当使用 valueFiles 或 values 时chart 会使用来自各种来源的完整 values 集合加上 parameters按上述顺序合并渲染。UI 存在一个已知缺陷对应上游 issue #9213它只展示 parameters并不呈现完整生效的 values 集合。作为变通方案使用 parameters 代替 values/valuesObject 可以获得更接近真实生效值的概览。Helm--set-file支持helm的--set-file参数可通过以下方式在 Argo CD CLI 上使用argocd app set helm-guestbook --helm-set-file some.keypath/to/file.ext或在 YAML 中使用fileParameterssource: helm: fileParameters: - name: some.key path: path/to/file.extHelm Release 名称releaseName默认情况下Helm release 名称等于其所属 Application 的名称。在集中式 Argo CD 上有时需要覆盖该名称CLI 可用--release-nameargocd app set helm-guestbook --release-name myRelease或 YAML 中的releaseNamesource: helm: releaseName: myRelease警告覆盖 release 名称的重要提示覆盖 Helm release 名称在 chart 使用app.kubernetes.io/instance标签时可能引发问题。Argo CD 为了跟踪资源会注入该标签并把值设为 Application 名称。覆盖 release 名称后Application 名称与 release 名称不再一致Argo CD 用 Application 名称覆盖该标签可能导致部分资源上的 label selector 失效。为避免此问题可以在 argocd-cm.yaml 中配置application.instanceLabelKey让 Argo CD 使用另一个标签做跟踪。Helm HooksHelm hooks 与 Argo CD hooks 类似。在 Helm 中hook 是任何带有helm.sh/hook注解的普通 Kubernetes 资源。Argo CD 通过把 Helm 注解映射到自身的 hook 注解来支持大多数 Helm hooks。这是注解层面的兼容不保证 hook 生命周期语义与 Helm 完全一致Helm 注解说明helm.sh/hook: crd-install支持等价于 Argo CD 常规 CRD 处理helm.sh/hook: pre-delete支持等价于argocd.argoproj.io/hook: PreDeletehelm.sh/hook: pre-rollback不支持。Helm stable 中从未使用helm.sh/hook: pre-install支持等价于argocd.argoproj.io/hook: PreSynchelm.sh/hook: pre-upgrade支持等价于argocd.argoproj.io/hook: PreSynchelm.sh/hook: post-upgrade支持等价于argocd.argoproj.io/hook: PostSynchelm.sh/hook: post-install支持等价于argocd.argoproj.io/hook: PostSynchelm.sh/hook: post-delete支持等价于argocd.argoproj.io/hook: PostDeletehelm.sh/hook: post-rollback不支持。Helm stable 中从未使用helm.sh/hook: test-success不支持。Argo CD 无对应概念helm.sh/hook: test-failure不支持。Argo CD 无对应概念helm.sh/hook-delete-policy支持。清理仍遵循 Argo CD 同步语义可能与 Helm 的 hook 事件生命周期不同。另见argocd.argoproj.io/hook-delete-policyhelm.sh/hook-delete-timeout不支持。Helm stable 中从未使用helm.sh/hook-weight支持等价于argocd.argoproj.io/sync-wavehelm.sh/resource-policy: keep支持等价于argocd.argoproj.io/sync-options: Deletefalse不支持的 hook 会被忽略。在 Argo CD 中hook 通过kubectl apply而非kubectl create创建因此如果同名 hook 已存在且没有标注before-hook-creation它不会发生变化。从源码看hook 识别与类型映射分散在 gitops-engine 中gitops-engine/pkg/sync/hook/helm/hook.go 的IsHook判断资源是否带helm.sh/hook注解并排除crd-install因为 Helm 用同一注解标识 CRD 但它们并非 hookPreDelete/PostDelete与pre-delete/post-delete的注解映射则定义在 controller/hook.go 的hookTypeAnnotations中hook 权重对应 sync-wave与删除策略解析分别位于 gitops-engine/pkg/sync/hook/helm/weight.go 和 gitops-engine/pkg/sync/hook/helm/delete_policy.go。警告Helm hooks 与 Argo CD hooks如果你定义了任何 Argo CD 原生 hook所有Helm hooks 都会被忽略。警告install 与 upgrade 与 syncArgo CD 无法知道自己在执行首次 install 还是 upgrade——对 Argo CD 而言每次操作都是 sync。这意味着带pre-install和pre-upgrade的应用这两类 hook 默认会同时执行。注意Hook 删除语义与 Helm 不同Helm hook 注解被映射到 Argo CD hooks但删除策略仍按 Argo CD 的同步阶段和同步结果语义评估这与 Helm 按 hook 事件的生命周期不同。特别是ServiceAccount这类无 Kubernetes 完成态不像Job或Workflow有 success 状态的被动资源hook-succeeded/HookSucceeded的评估时机可能与你在 Helm 中观察到的不同。Hook 编写建议Tips让 hook 保持幂等给pre-install和post-install标注hook-weight: -1确保它们在 upgrade hooks 之前运行到成功给pre-upgrade和post-upgrade标注hook-delete-policy: before-hook-creation确保每次同步都会执行。更多细节可参考 Argo hooks 文档 与 Helm 官方的 hooks 文档charts_hooks 主题。随机数据randAlphaNumHelm 模板在渲染时可通过randAlphaNum函数生成随机数据许多社区 chart 都用到了这个特性。例如某 redis chart 的 secret 模板data: {{- if .Values.password }} redis-password: {{ .Values.password | b64enc | quote }} {{- else }} redis-password: {{ randAlphaNum 10 | b64enc | quote }} {{- end }}Argo CD 应用控制器会周期性地把 Git 状态与 live 状态做对比每次对比都会执行helm template CHART生成 manifest。由于随机值每次对比都会被重新生成使用randAlphaNum的应用将永远处于OutOfSync状态。解决办法是显式设置一个稳定值例如在 values.yaml 中固定或用argocd app set覆盖argocd app set redis -p passwordabc123构建环境变量Build EnvironmentHelm 应用可以访问标准构建环境变量通过参数替换使用。CLI 方式argocd app create APPNAME \ --helm-set-string app${ARGOCD_APP_NAME}声明式写法spec: source: helm: parameters: - name: app value: $ARGOCD_APP_NAME构建环境变量同样可用于 values 文件路径spec: source: helm: valueFiles: - values.yaml - myprotocol://somepath/$ARGOCD_APP_NAME/$ARGOCD_APP_REVISIONHelm 插件Helm pluginsArgo CD 对云服务商与 Helm 插件的选择持开放态度因此官方镜像不内置任何插件。若需要自定义插件例如用支持gs://协议的 GCS/S3 存储类插件来访问私有 chart 仓库有两种安装方式修改 Argo CD 容器镜像或使用 KubernetesinitContainer。方式一修改 Argo CD 容器镜像准备一个包含插件的自有 Argo CD 镜像示例 DockerfileFROM argoproj/argocd:v1.5.7 USER root RUN apt-get update \ apt-get install -y \ curl \ apt-get clean \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* USER argocd ARG GCS_PLUGIN_VERSION0.3.5 ARG GCS_PLUGIN_REPOhttps://github.com/hayorov/helm-gcs.git RUN helm plugin install ${GCS_PLUGIN_REPO} --version ${GCS_PLUGIN_VERSION} ENV HELM_PLUGINS/home/argocd/.local/share/helm/plugins/HELM_PLUGINS环境变量是 Argo CD 正确定位插件所必需的。构建完成后使用该自定义镜像部署 Argo CD。方式二使用 initContainers另一选择是通过initContainers安装 Helm 插件。一些用户认为这比维护自有 Argo CD 镜像更可取。下面示例展示用官方 Argo CD Helm chart 安装时如何注入插件repoServer: volumes: - name: gcp-credentials secret: secretName: my-gcp-credentials volumeMounts: - name: gcp-credentials mountPath: /gcp env: - name: HELM_CACHE_HOME value: /helm-working-dir - name: HELM_CONFIG_HOME value: /helm-working-dir - name: HELM_DATA_HOME value: /helm-working-dir initContainers: - name: helm-gcp-authentication image: alpine/helm:3.16.1 volumeMounts: - name: helm-working-dir mountPath: /helm-working-dir - name: gcp-credentials mountPath: /gcp env: - name: HELM_CACHE_HOME value: /helm-working-dir - name: HELM_CONFIG_HOME value: /helm-working-dir - name: HELM_DATA_HOME value: /helm-working-dir command: [ /bin/sh, -c ] args: - apk --no-cache add curl; helm plugin install https://github.com/hayorov/helm-gcs.git; helm repo add my-gcs-repo gs://my-private-helm-gcs-repository; chmod -R 777 $HELM_DATA_HOME;Helm 版本字段helm.version该字段曾在 Helm 2 到 Helm 3 的过渡期使用在 Helm 2 EOL 之前Argo CD 同时附带 v2 与 v3 两个 Helm 二进制用户可通过该字段指定渲染 chart 使用哪个版本。自 Helm 2 EOL 之后此字段无需再配置仅为向后兼容而保留。从 Argo CD 3.5 版本开始用于渲染 chart 的 Helm 二进制只有官方文档所述的最新一个版本。如果你历史配置中有如下设置spec: source: helm: version: v3无需更新或删除该字段保持原样即可。Helm--pass-credentials自 v3.6.1 起Helm 阻止把仓库凭据发送到与仓库域名不同的域名下载 chart。如需跨域传递凭据可在 CLI 上设置helm-pass-credentials标志argocd app set helm-guestbook --helm-pass-credentials或声明式写法spec: source: helm: passCredentials: trueHelm--skip-crdsHelm 默认在 CRD 不存在时从 chart 的crds目录安装自定义资源定义。如需跳过 CRD 安装步骤CLI 使用helm-skip-crdsargocd app set helm-guestbook --helm-skip-crds或声明式写法spec: source: helm: skipCrds: trueHelm--skip-schema-validationHelm 会用values.schema.json校验 values 文件。如需跳过 schema 校验CLI 使用helm-skip-schema-validationargocd app set helm-guestbook --helm-skip-schema-validation或声明式写法spec: source: helm: skipSchemaValidation: trueHelm--skip-tests默认情况下Helm 渲染时会包含测试 manifest。Argo CD 目前会跳过包含其不支持的 hook 的 manifest包括 Helm 测试 hook该行为覆盖了大多数测试场景但与--skip-tests并不完全一致因此提供了显式的--skip-tests选项。如需跳过测试 manifestCLI 使用helm-skip-testsargocd app set helm-guestbook --helm-skip-tests或声明式写法spec: source: helm: skipTests: true # 或 false【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考