Renovate 的 Kustomize Manager 完全指南：自动更新 `kustomization.yaml` 中的远程资源、镜像与 Helm Chart

Renovate 的 Kustomize Manager 完全指南：自动更新kustomization.yaml中的远程资源、镜像与 Helm Chart

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate

Renovate 内置的 Kustomize manager 专注于自动维护 Kubernetes 声明式配置文件kustomization.yaml，可以自动提取并升级其中的远程资源（remote resources）、镜像标签（image tags）、组件（components）与 Helm Chart，并在满足条件时自动执行 Helm Chart 的膨胀（inflate）操作。读完本文，你将掌握 Kustomize manager 的全部能力边界、depType细分控制方式、kustomizeInflateHelmCharts等关键配置，以及其底层提取逻辑与已知限制。

一、Kustomize Manager 是什么

Kustomize manager 是 Renovate 众多 package manager 中的一个，位于仓库源码的 lib/modules/manager/kustomize 目录。它专门用于解析仓库中的kustomization.yaml文件，将其中的外部引用识别为依赖并保持更新。

从 index.ts 的默认配置可以看出它的匹配规则与行为基调：

export const defaultConfig = { managerFilePatterns: ['/(^|/)kustomization\\.ya?ml$/'], pinDigests: false, };

• 文件匹配模式为/(^|/)kustomization\.ya?ml$/，即同时覆盖kustomization.yaml与kustomization.yml两种命名；
• 默认不固定 digest（pinDigests: false），只在有升级时顺带更新。

它归属的类别是categories: ['kubernetes']，参考文档主页为 kubectl.docs.kubernetes.io/references/kustomize）。

支持管理的内容

Renovate 的 Kustomize manager 可以管理kustomization.yaml中的以下五个部分：

1. remote resources：通过resources字段引用的远程构建资源；
2. image tags：通过images字段声明的镜像标签（配合newTag、newName、digest使用）；
3. components：通过components字段引用的远程 Kustomize Component；
4. helm charts：通过helmCharts字段引用的 Helm Chart；
5. remote bases：通过bases字段引用的远程基础（自 Kustomizev2.1.0起已废弃）。

其中 remote bases 虽然已被 Kustomize 官方弃用，但 Renovate 仍然兼容解析，以便存量项目平滑过渡。

二、工作流程：四步完成依赖更新

官方 readme（lib/modules/manager/kustomize/readme.md）给出了完整的执行流程：

1. Renovate 在每个仓库中搜索所有kustomization.yaml文件；
2. 从远程 bases、image tags 和 Helm charts 中提取依赖；
3. Renovate 解析依赖的源仓库，检查是否存在 SemVer 标签；
4. 如果发现更新，则直接改写kustomization.yaml文件。

整个流程在源码中的落点是 extract.ts 的extractPackageFile函数：它先通过parseKustomize将 YAML 解析为Kustomize结构，再依次遍历bases、resources、components、images、helmCharts五个字段提取依赖，最后以{ deps }形式返回；只有当kind为Kustomization或Component时才继续处理（见 parseKustomize）。

提取时依赖解析所支持的 datasource 在 index.ts 中声明：

export const supportedDatasources = [ DockerDatasource.id, GitTagsDatasource.id, GithubTagsDatasource.id, HelmDatasource.id, ];

即 Docker、GitTags、GithubTags、Helm 四种 datasource，分别对应镜像、通用 Git 仓库、GitHub 仓库与 Helm Chart 的版本探测。

三、用 depType 精细控制升级范围

为了对“哪些依赖该升级”进行精细控制，Kustomize manager 使用了三种depType。注意：readme 中列出的四个名称中，实际由 dep-types.ts 声明的knownDepTypes为：

而在实际提取时，OCI 风格的 Helm Chart（仓库地址形如oci://...）会通过 helmv3/oci.ts 的getOciChartDep生成依赖，从而在 extract.ts 中得到以 Docker 作为 datasource 的OCIChartdepType。因此 readme 中的四个 depType（Component、Kustomization、HelmChart、OCIChart）在运行期都是真实存在的。

你可以像下面这样使用packageRules对不同的 depType 采取不同策略：

{ "packageRules": [ { "matchDepTypes": ["HelmChart", "OCIChart"], "matchManagers": ["kustomize"], "enabled": false } ] }

结合matchFileNames、matchDatasources等字段，可以做到“镜像只升级 patch 版本、Helm Chart 全部忽略、远程资源走独立频率”之类的细粒度控制。

四、Helm Charts 膨胀（Inflate）机制

Kustomize 在helmCharts字段中引用 Helm Chart 后，执行kustomize build时会把 Chart 的内容展开到本地目录（默认是charts/）。Renovate 会在以下任一条件成立时，对 kustomization 中引用的 Helm Chart 执行膨胀操作：

1. Renovate 升级前的版本本身就是被膨胀过的（即本地charts/<name>-<version>目录已存在）；
2. 在postUpdateOptions中启用了kustomizeInflateHelmCharts选项。

kustomizeInflateHelmCharts在 lib/config/options/index.ts 中被登记为postUpdateOptions的合法取值之一。启用方式是在 renovate 配置中追加该选项：

{ "postUpdateOptions": ["kustomizeInflateHelmCharts"] }

膨胀的具体执行在 artifacts.ts 的updateArtifacts中：它会过滤出depType === 'HelmChart'且版本发生变化的依赖，通过helm pull --untar --untardir ... --version ...命令把新旧版本的 Chart 拉到chartHome（默认charts，可用helmGlobals.chartHome覆盖）下；若旧版本目录已存在则先删除，再拉取新版本。期间生成的增删文件会作为 artifact 提交到 PR 中。

判断“是否膨胀”的日志与逻辑（artifacts.ts）：

Not inflating Helm chart for ${depName} as kustomizeInflateHelmCharts is not enabled and the current version isn't inflated

同时，执行helm命令时会通过 common.ts 的generateHelmEnvs注入安全环境变量：把HELM_REGISTRY_CONFIG、HELM_REPOSITORY_CONFIG、HELM_REPOSITORY_CACHE指向 Renovate 的私有缓存目录，避免文件与凭据泄露；当 Helm 版本约束低于3.8.0时还会设置HELM_EXPERIMENTAL_OCI=1以兼容 OCI 仓库。

注意：为防止 Renovate 去更新那些被展开（inflate）出来的 Chart 目录里的依赖，需要手动把这些目录从 Helm 相关 manager 中排除。官方推荐的配置：

{ "packageRules": [ { "matchFileNames": ["**/charts/**"], "matchManagers": ["helmv3", "helm-values"], "enabled": false } ] }

这段配置让**/charts/**目录下的文件不再被helmv3与helm-values两个 manager 处理，从而避免双重更新或对已展开内容的误改。

五、镜像提取的规则与边界

images字段的解析集中在 extractImage，其行为直接决定了哪些镜像能被正确识别与更新。

5.1 标签可以来自 newTag，键顺序无关

Kustomize 的images列表项中，name、newTag等键的书写顺序不限，Renovate 都能正确解析：

- name: image/name newTag: v0.0.1 # 或 - newTag: v0.0.1 name: image/name

5.2 digest 可写在 newTag 或 digest 中

Digest 可以以两种形式出现：

- name: image/name newTag: v0.0.1@sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f # 不带版本时，digest 按 :latest 追踪 - name: image/name digest: sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f

从源码看，纯digest形式会生成带currentDigest、replaceString: digest的依赖；而newTag: tag@digest形式则使用autoReplaceStringTemplate: '{{newValue}}{{#if newDigest}}@{{newDigest}}{{/if}}'来拼接新值。由于pinDigests: false，digest 默认不会被单独固定。

5.3 用 newName 更换镜像仓库

newName用于把镜像指向另一个仓库，支持多种写法：

- name: image/name newName: custom-image/name:v0.0.1 - name: image/name newName: custom-image/name:v0.0.1@sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f - name: image/name newName: custom-image/name@sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f - name: image/name newName: custom-image/name newTag: v0.0.1@sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f - name: image/name newName: custom-image/name digest: sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f

在实现上，extractImage以newName ?? name作为实际的解析名称（见 extract.ts），并复用dockerfilemanager 的getDep来拆分仓库、标签与 digest。

5.4 会被 Kustomize 忽略的写法将被跳过

为了避免歧义，Renovate 会跳过那些 Kustomize 自身会忽略的镜像写法。最典型的是同时声明newTag与digest的情况——Kustomize 会忽略newTag，此时 Renovate 会记录skipReason: 'invalid-dependency-specification'并跳过该依赖：

# bad：被跳过，因为设置了 digest 时 newTag 会被忽略 - name: image/name newTag: v0.0.1 digest: sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f # good：把 digest 并入 newTag - name: image/name newTag: v0.0.1@sha256:3eeba3e2caa30d2aba0fd78a34c1bbeebaa1b96c7aa3c95ec9bac44163c5ca4f

此外，newTag或digest不是合法字符串（如newTag直接以sha256:开头、digest不以sha256:开头）时，依赖会被标记为skipReason: 'invalid-value'；镜像只有name而没有newTag/newName/digest时则返回null，不生成依赖。

六、远程资源与 Git 仓库引用的解析

resources、bases、components中的远程引用由 extractResource 负责。它支持 Kustomize 官方 URL 规范（对齐 hashicorp go-getter 的 URL 格式），能识别以下形式的 URL：

• git@github.com:moredhel/remote-kustomize.git?ref=v0.0.1（SSH 形式）
• github.com/fluxcd/flux/deploy?ref=1.19.0（短路径形式）
• https://github.com/user/test-repo.git?ref=v0.0.1
• 带//子目录的形式，如git@github.com:kubernetes-sigs/kustomize.git//examples/helloWorld?ref=v2.0.0
• 带_git分隔符的 Azure DevOps 风格地址，如git::https://itfs.mycompany.com/collection/project/_git/somerepos?ref=...

解析时优先匹配_git、.git等特征，再尝试带额外//的路径，最后回到通用格式（见 extract.ts 中的四个正则）。版本取自查询参数ref或version（ref优先，见 extract.ts）。

• 若路径命中github.com，则使用GithubTagsDatasource，depName为去掉.git后缀的仓库路径；
• 否则使用GitTagsDatasource，并额外携带packageName指向完整 URL。

这些依赖的depType会被标记为文件本身的kind（Kustomization或Component），因此你可以通过matchDepTypes单独控制远程资源与镜像的更新策略。

测试用例（extract.spec.ts）覆盖了github.com/fluxcd/flux/deploy?ref=1.19.0、git@github.com:moredhel/remote-kustomize.git?ref=v0.0.1、github.com/user/repo//deploy?ref=v0.0.1等典型场景，可作为理解解析行为的参考。

七、Helm Chart 的提取

helmCharts字段的每个条目包含name、repo、version三项（见 types.ts）：

helmCharts: - name: minecraft repo: https://itzg.github.io/minecraft-server-charts version: 3.1.3

extractHelmChart 的处理逻辑：

• 若repo是 OCI 仓库（oci://开头），走getOciChartDep，以 Docker 作为 datasource 生成OCIChart类型依赖；
• 否则以HelmDatasource生成依赖，registryUrls指向repo，版本取version字段，depType 为HelmChart。

Helm Chart 的更新同样遵循 SemVer 标签探测原则：Renovate 会在 chart 仓库中查找符合 SemVer 语义的版本标签，再回写version字段。

八、已知限制

官方 readme 明确列出的限制如下，使用时需注意：

1. 使用 HTTPS 拉取远程 Git 仓库未经测试——即https://形式的远程资源引用虽然在解析层面被支持，但端到端更新流程未经过完整测试验证；
2. images 列表中键的顺序可以是任意顺序（已在上文 5.1 说明，Renovate 均能解析）；
3. digest 可以固定在newTag或digest中（见 5.2，不带版本的 digest 按:latest追踪）；
4. 镜像仓库可以用newName更换（见 5.3）；
5. 被 Kustomize 忽略的镜像写法会被跳过以避免歧义（见 5.4）。

另外从源码结构可以推断：artifacts.ts的膨胀流程依赖本地 Helm 二进制（通过toolConstraints声明，必要时由 Renovate 自动安装），如果helm pull失败会把 stderr 以artifactError形式反馈在 PR 上。

九、端到端配置示例

把以上内容组合成一个完整的 Renovate 配置，即可覆盖 Kustomize 场景的常见诉求：

{ "kustomize": { "fileMatch": ["(^|/)kustomization\\.ya?ml$"] }, "postUpdateOptions": ["kustomizeInflateHelmCharts"], "packageRules": [ { "matchFileNames": ["**/charts/**"], "matchManagers": ["helmv3", "helm-values"], "enabled": false }, { "matchManagers": ["kustomize"], "matchDepTypes": ["HelmChart", "OCIChart"], "separateMinorPatch": true }, { "matchManagers": ["kustomize"], "matchDatasources": ["docker"], "pinDigests": true } ] }

要点说明：

• fileMatch可以按需覆盖默认的kustomization.ya?ml匹配，例如加入**/kustomization.yaml之外的自定义路径；
• kustomizeInflateHelmCharts保证首次未膨胀的 Chart 也能被拉取展开；
• 对**/charts/**的排除规则防止膨胀产物被helmv3/helm-values重复处理；
• 通过matchDepTypes与matchDatasources可对 Chart 类依赖与 Docker 镜像采取不同的升级与 digest 策略。

十、相关源码导航

如果你希望深入阅读实现细节，推荐按以下路径继续探索当前仓库：

Kustomize manager 的官方说明文档为 lib/modules/manager/kustomize/readme.md，其中记录了本文所述的能力范围与限制的权威出处。

结语

Renovate 的 Kustomize manager 用一套统一的提取与更新机制，覆盖了kustomization.yaml中远程资源、镜像标签、组件与 Helm Chart 的全部主要更新场景，并通过depType体系把控制粒度下放到每一类依赖。理解其提取规则（尤其是镜像字段的各种合法/非法组合）与kustomizeInflateHelmCharts膨胀机制，是让 Kubernetes 配置仓库实现“声明式自动化更新”的关键一步。配合postUpdateOptions与packageRules，你可以把它无缝嵌入现有的 GitOps 工作流中。

【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate