Argo CD Helm 应用管理完全指南：声明式渲染、Values 体系、Hooks 映射与插件实践

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 文件（valueFiles）

Helm 允许使用一个或多个替代的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）：

文件如何传递给 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.yaml

valueFiles: - 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）会原样传给 Helm，URL 中的 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开头先收集全部显式路径到explicitPaths，glob 展开时命中显式路径就跳过，并用seen集合保证每个绝对路径只入列一次（reposerver/repository/repository.go）。

无匹配时的行为

如果某个 glob 模式没有匹配到任何文件，Argo CD 会保留该 Application spec（spec 本身合法，文件可能稍后才会加入仓库），并在 Application 上暴露一个ComparisonError条件：

values file glob "nonexistent/*.yaml" matched no files

在模式匹配到至少一个文件或模式被移除之前，应用会保持在降级状态。文件加入仓库后无需再更新 spec。这一错误类型对应源码中的GlobNoMatchError（reposerver/repository/repository.go），注释中明确它是"运行时条件而非 spec 错误"。

如果想让未匹配的模式静默跳过而不报错，可把 glob 与ignoreMissingValueFiles组合使用：

source: helm: valueFiles: - envs/*.yaml ignoreMissingValueFiles: true

这适用于"覆盖文件在某些环境中可能不存在"的默认/覆盖模式。

Values（values / valuesObject）

Argo 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键以字符串形式传递 values：

source: 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.com

Helm 参数（parameters）

Helm 支持用--set设置参数值来覆盖values.yaml中的内容，例如service.type是许多 chart 暴露的常见参数：

helm template . --set service.type=LoadBalancer

类似地，Argo CD 可用argocd app set命令以-p PARAM=VALUE形式覆盖参数：

argocd app set helm-guestbook -p service.type=LoadBalancer

声明式写法：

source: helm: parameters: - name: "service.type" value: LoadBalancer

Helm 取值优先级

各类 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 → 结果 param1=value3000

parameters: - name: "param1" value: value2 - name: "param1" value: value1 → 结果 param1=value1

values: | param1: value2 param1: value5 → 结果 param1=value5

注意：当使用 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.key=path/to/file.ext

或在 YAML 中使用fileParameters：

source: helm: fileParameters: - name: some.key path: path/to/file.ext

Helm Release 名称（releaseName）

默认情况下，Helm release 名称等于其所属 Application 的名称。在集中式 Argo CD 上有时需要覆盖该名称，CLI 可用--release-name：

argocd app set helm-guestbook --release-name myRelease

或 YAML 中的releaseName：

source: 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 Hooks

Helm hooks 与 Argo CD hooks 类似。在 Helm 中，hook 是任何带有helm.sh/hook注解的普通 Kubernetes 资源。

Argo CD 通过把 Helm 注解映射到自身的 hook 注解来支持大多数 Helm hooks。这是注解层面的兼容，不保证 hook 生命周期语义与 Helm 完全一致：

不支持的 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 但它们并非 hook）；PreDelete/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' 与 'sync'

Argo 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 主题）。

随机数据（randAlphaNum）

Helm 模板在渲染时可通过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 password=abc123

构建环境变量（Build Environment）

Helm 应用可以访问标准构建环境变量，通过参数替换使用。

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_REVISION

Helm 插件（Helm plugins）

Argo CD 对云服务商与 Helm 插件的选择持开放态度，因此官方镜像不内置任何插件。若需要自定义插件（例如用支持gs://协议的 GCS/S3 存储类插件来访问私有 chart 仓库），有两种安装方式：修改 Argo CD 容器镜像，或使用 KubernetesinitContainer。

方式一：修改 Argo CD 容器镜像

准备一个包含插件的自有 Argo CD 镜像，示例 Dockerfile：

FROM 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_VERSION="0.3.5" ARG GCS_PLUGIN_REPO="https://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: true

Helm--skip-crds

Helm 默认在 CRD 不存在时从 chart 的crds目录安装自定义资源定义。如需跳过 CRD 安装步骤，CLI 使用helm-skip-crds：

argocd app set helm-guestbook --helm-skip-crds

或声明式写法：

spec: source: helm: skipCrds: true

Helm--skip-schema-validation

Helm 会用values.schema.json校验 values 文件。如需跳过 schema 校验，CLI 使用helm-skip-schema-validation：

argocd app set helm-guestbook --helm-skip-schema-validation

或声明式写法：

spec: source: helm: skipSchemaValidation: true

Helm--skip-tests

默认情况下，Helm 渲染时会包含测试 manifest。Argo CD 目前会跳过包含其不支持的 hook 的 manifest，包括 Helm 测试 hook；该行为覆盖了大多数测试场景，但与--skip-tests并不完全一致，因此提供了显式的--skip-tests选项。如需跳过测试 manifest，CLI 使用helm-skip-tests：

argocd 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