versions-renovate

版本与 Renovate 管理

版本存放在 kubernetes/platform/versions.env 中。Renovate 在 .github/renovate.json5 中的自定义 regex manager 会解析每个条目上一行的 # renovate: 注解。Flux 在协调时会将 ${var} 引用替换进 HelmRelease spec。

选择初始版本

务必从来源处核实最新的稳定 tag——绝不要凭记忆猜测。 训练数据滞后于现实数月到数年，因此记忆中的 tag 几乎总是过时的。在写入任何 *_version= 条目或硬编码的镜像 tag 之前，先查询：

# Docker/OCI registry (GHCR shown; anonymous pull token)
TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:<org>/<image>:pull&service=ghcr.io" | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/<org>/<image>/tags/list" | jq -r '.tags[]' | sort -V | tail

skopeo list-tags docker://ghcr.io/<org>/<image>          # if skopeo available
git ls-remote --tags --refs https://github.com/<org>/<repo>.git | sort -V | tail   # github-releases/tags

匹配 registry 实际使用的 tag 格式（v2.7.1 还是 2.7.1）。选择最新的稳定 semver；除非用户要求，否则跳过 beta/rc/nightly/latest。之后 Renovate 会使其保持最新，但全新部署必须从当前发布版本开始，而不是某个古老的版本。

注解语法

# renovate: datasource=<source> depName=<name> [packageName=<pkg>] [extractVersion=<regex>] [registryUrl=<url>] [versioning=<scheme>]
variable_name=<value>

键的顺序是固定的：datasource、depName、packageName、extractVersion、registryUrl、versioning。重新排列键会导致 Renovate 静默跳过该条目。

字段	是否必填	用途
datasource	是	Renovate 查询的位置（helm、docker、github-releases、github-tags）
depName	是	在 Renovate PR 中显示的可读名称
packageName	否	特定于 registry 的查询路径（OCI registry、GitHub 仓库）
extractVersion	否	用于转换上游版本的正则（例如去掉 v 前缀）
registryUrl	否	HTTP Helm 仓库 URL（不适用于 OCI）
versioning	否	针对非 semver 的版本方案覆盖（例如 loose）

Datasource 选择

HTTP Helm registry    --> datasource=helm + registryUrl=<url>
OCI Helm registry     --> datasource=docker + packageName=<full-path>   (no oci:// prefix)
GitHub release        --> datasource=github-releases + packageName=<org/repo>
GitHub tag            --> datasource=github-tags + packageName=<org/repo>

示例

# HTTP Helm registry
# renovate: datasource=helm depName=grafana registryUrl=https://grafana.github.io/helm-charts
grafana_version=10.5.15

# OCI Helm registry
# renovate: datasource=docker depName=app-template packageName=ghcr.io/bjw-s-labs/helm/app-template
app_template_version=4.6.2

# GitHub releases (keep v prefix)
# renovate: datasource=github-releases depName=talos packageName=siderolabs/talos
talos_version=v1.12.2

# GitHub tags (strip v prefix with extractVersion)
# renovate: datasource=github-tags depName=kubernetes packageName=kubernetes/kubernetes extractVersion=^v(?<version>.*)$
kubernetes_version=1.35.0

# Strip v from Helm chart releases
# renovate: datasource=helm depName=cert-manager extractVersion=^v(?<version>.*)$ registryUrl=https://charts.jetstack.io
cert_manager_version=1.19.3

# Non-semver versions
# renovate: datasource=docker depName=cloudnative-vectorchord packageName=ghcr.io/tensorchord/cloudnative-vectorchord versioning=loose
vectorchord_version=18.1-1.0.0

YAML 容器镜像注解

对于 Helm values 文件中硬编码的镜像 tag（sidecar、init 容器）：

image:
  repository: ghcr.io/kashalls/kromgo
  # renovate: datasource=docker depName=ghcr.io/kashalls/kromgo
  tag: v0.7.5

initContainers:
  # renovate: datasource=docker depName=ghcr.io/home-operations/postgres-init
  image: ghcr.io/home-operations/postgres-init:18

Package 规则

添加到 .github/renovate.json5 以对相关 chart 分组或阻止自动合并：

{
  "matchDepNames": ["my-chart", "related-chart"],
  "groupName": "my stack"
}

matchDepNames 的值必须与注解中的 depName 匹配。默认情况下，minor/patch 更新会在 3 天后自动合并（.renovate/automerge.json5）。基础设施关键分组（talos、kubernetes、cilium、gateway-api、flux）已禁用自动合并。

更改后，运行 task renovate:validate。

调试

症状	原因	修复
被静默忽略	键的顺序错误	遵循上面的确切顺序
找不到 package	packageName 中有 oci:// 前缀	移除 oci:// 前缀
版本带有不需要的 v	缺少 extractVersion	添加 extractVersion=^v(?<version>.*)$
找不到 OCI chart	对 OCI 使用了 datasource=helm	使用 datasource=docker
跳过非 semver	缺少 versioning=loose	添加 versioning=loose
正则不匹配	注解不在上一行	必须紧挨在 key=value 上方

还要检查：Renovate GitHub issue 中的依赖仪表盘、renovate.json5 中的 ignorePaths。