Centralized automation for mirroring and synchronizing third-party container images to Suanova Harbor registries.
本仓库只负责第三方镜像的复制、版本固定与同步。它不构建软件,不部署
Kubernetes,也不管理自研镜像(suanova/、suanova-private/)。新增一个需要
同步的镜像只需要改 YAML,不需要改 workflow。
| 决策 | 原因 |
|---|---|
| Skopeo 直接 registry→registry 复制 | 不依赖 Docker daemon,原样保留 manifest list |
| 仅固定版本(pinned) | 生产环境拉到的字节必须可预测;升级是一次可评审的 PR |
| 复制后比对 manifest digest | 不看 skopeo copy 的退出码,看目标仓库里的实际字节 |
| 目标路径包含源 Registry 主机名 | 从 pull 地址就能看出镜像来源,且不同 Registry 同名仓库不会冲突 |
platforms 是断言而非过滤器 |
skopeo copy --all 复制整个 manifest list;声明的架构缺失即失败 |
只断言 linux/amd64 |
集群只有 amd64 节点;不裁剪 manifest list,digest 仍与上游一致 |
| 单次运行只写一个 authfile | 兼容旧版 skopeo,凭据不落盘到仓库 |
| 版本不盲目清理 | 删除 tag 前确认没有发布线还在 pin 它;当前不用的旧版本可以移除 |
index.json 是机器可读目录 |
下游按 commit 读取,不需要解析 YAML;与清单在同一个 PR 更新 |
images/ 要同步的镜像,按领域分文件(唯一需要日常维护的地方)
config/registries.yaml 源/目标 Registry 声明
config/policies.yaml 全局策略:平台、重试、签名、扫描
scripts/ validate / sync / verify / scan / report
docs/ 新增镜像、路径映射、安全说明
.github/workflows/ PR 校验、手动同步、定时兜底、每周扫描
images/*.yaml 与 Harbor mirrors/ 项目里的实际内容一一对应。每个仓库的
tag、digest 取自 suanova/cubestack-operator 的 [cve-report] issue——每月
扫描会在 issue 正文里附一张 Artifact 表,列出 tag、digest 和推送时间。
清单里钉的 digest 是上游 manifest list(index)digest。Harbor 中绝大多数仓库 保存的本来就是 index,同 tag 的 digest 与上游一致,首次运行会命中 “Already up to date”——清单的作用是把现状固化成可校验、可评审的声明。
有 12 个仓库(cloudnative-pg、opstree/*、perses*、prometheus-operator
等)当初是单架构复制进去的,Harbor 里的 digest 是 amd64 子 manifest digest。
清单按上游 index digest 固定,所以首次同步会把这些 tag 重推成完整 manifest
list;amd64 子 manifest 的字节和 digest 都不变,生产拉取不受影响。
例外:docker.io/nicolaka/netshoot 只有浮动的 latest,按“仅固定版本”策略
不纳入本仓库管理。
-
在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置 Harbor 的 CI 机器人:
类型 名称 内容 Variable CI_BOT_NAMERobot Account 用户名,例如 robot$mirrors+ciSecret CI_BOT_PASSWORD对应密码 workflow 把它们注入为
MIRROR_USERNAME/MIRROR_PASSWORD,脚本据此生成 临时 authfile。公开源(docker.io、quay.io、ghcr.io、registry.k8s.io、 nvcr.io)保持匿名,不需要额外配置。 -
确认 Harbor 上存在
mirrors项目,且 Robot Account 拥有该项目的push+pull权限(见 docs/security.md)。 -
本地预览本次会做什么(不写任何仓库、不需要凭据):
make dry-run make check-sources # 需要网络,只读:确认 tag 存在、架构齐全 -
触发同步:Actions → Sync images → Run workflow,
category选all或 单个文件。合并images/**的 PR 到main也会自动触发。
apiVersion: mirror.suanova.io/v1alpha1
kind: ImageMirrorList
metadata:
name: networking # 必须与文件名一致
spec:
defaults:
platforms: [linux/amd64]
# 可选:只复制 amd64 单架构(用于未压缩 OCI layer 的厂商镜像;此时
# versions[].digest 写 amd64 子 manifest digest)
# multiarch: false
images:
- name: nginx
source: docker.io/library/nginx
target: harbor.isuanova.com/mirrors/docker.io/library/nginx
versions:
- tag: "1.31.8"
# 可选:钉死 digest 后,上游 tag 被重新指向会直接失败
# digest: sha256:…
# 可选:覆盖 defaults(例如上游只发布单架构时)
# platforms: [linux/amd64]
# signature:
# verify: true
# keyless:
# issuer: https://token.actions.githubusercontent.com
# subjectRegExp: https://github.com/org/repo/.+字段约束由 scripts/validate.jq 执行,常见的几条:
versions[]只追加:只要还有发布线在用某个 tag,就不要删除它。source/target必须写全 Registry 主机名,且不能带 tag 或 digest; 版本只能写在versions[]。target必须是<destination>/<project>/<source-host>/<path>,且<source-host>必须与source的主机名一致;同主机迁移 (source host == target host,如 Harbormetax/→mirrors/)可省略<source-host>和源项目前缀,直接<destination>/<project>/<path>, 其中<path>通常沿用镜像的原始上游路径(如cr.metax-tech.com/cloud/gpu-label)。latest默认被拒绝(config/policies.yaml的allowLatest)。- 同一
source:tag或target:tag不允许在多个文件里重复出现。
对 versions[] 中的每一项:
- 解析源 manifest,得到
sha256:…(对原始 manifest 字节做哈希)。 - 如果清单里写了
digest:且与上游不一致 → drift,拒绝复制,任务失败。 - 断言声明的
platforms都存在于源 manifest list 中。 - 若目标仓库该 tag 已是同一 digest → skipped(幂等,可反复执行)。
- 若目标 tag 已存在但 digest 不同:
- 清单钉了
digest→ 视为修复,覆盖为目标应有的字节; - 未钉
digest→ drift,拒绝覆盖。此时无法区分"上游移动了 tag"和 "目标被别的东西占用了",默认选择不冒险;可用verify.allowDigestReplace: true显式放行。
- 清单钉了
skopeo copy --all,失败按指数退避重试。- 重新读取目标 manifest digest,与源比对;不一致即失败。
- 可选:Trivy 扫描刚推上去的 digest,并生成 CycloneDX SBOM。
整体退出码:任一版本 failed / drift / scan-failed 即为非零,且会在
Actions Summary 里生成带 digest 的表格(scripts/generate-report.sh)。
index.json 是 images/*.yaml 的机器可读投影,提交在仓库根:
- 生成:
make index(scripts/generate-index.py,需要 PyYAML); - 校验:
make validate会检查index.json与清单一致,不一致直接失败; - 结构:每个镜像带
id(<category>/<name>)、source、target、versions[](tag / digest / platforms)。
sync-images.yaml 在 main 同步成功后按 vars.MIRROR_NOTIFY_TARGETS 给下游仓库发
repository_dispatch: mirror-updated。该变量是仓库名 JSON 数组:
[
"org/product-a",
"org/product-b"
]payload 只带 catalog_commit。下游按该 commit 重新读取 index.json,只处理自己
引用的 (catalog_id, tag),并自行校验 digest,不信任 payload 内容。
通知目标不写进仓库,是为了让这个 public 仓库保持产品中立、不出现私有仓库名。 需要配置:
vars.MIRROR_APP_ID;secrets.MIRROR_APP_PRIVATE_KEY(GitHub App 需对目标仓库有contents: write);vars.MIRROR_NOTIFY_TARGETS。
未配置时 notify job 只告警、不失败。新增产品只需要:
- 在
MIRROR_NOTIFY_TARGETS加一条目标仓库; - 给 GitHub App 授权该仓库;
- 下游实现自己的
mirror-updatedreceiver。
| Workflow | 触发 | 行为 |
|---|---|---|
validate.yaml |
PR、main push | YAML lint、shellcheck、静态校验;无凭据、无网络 |
sync-images.yaml |
手动、images/** 合入 main |
按文件矩阵并发同步,可选扫描,产出报告;成功后 dispatch 下游 |
scheduled-sync.yaml |
每周一 03:17 | 重新断言固定版本:补缺失、报漂移;不会升级版本 |
security-scan.yaml |
每周一 04:41、手动 | 对 Harbor 中现有 digest 做漏洞扫描 + SBOM |
update-digests.yaml |
sync 成功后、手动 | 从 target 读取缺失 digest,开 PR;不改已有 pin |
sync 与 security-scan 都挂在内置的 production environment 上,可以在
仓库设置里为它加 required reviewers,让写入 Harbor 变成需要审批的动作。
需要 yq (v4)、jq、skopeo (>= 1.7,multiarch: false 使用
--preserve-digests)、python3 + PyYAML;扫描需要 trivy(可用
./scripts/install-trivy.sh 安装固定版本),签名校验需要 cosign。
make index # 重新生成 index.json(改完 images/ 后必跑)
make validate # 静态校验(含 index.json 与清单一致性)
make dry-run # 只打印计划
make check-sources # 只读探测源仓库
make digests # 从 target 补缺失 digest(先 sync)
make sync ARGS="--category observability --tag v3.15.1"
make scanmacOS 自带的 bash 3.2 可用;脚本刻意没有使用 mapfile 等 bash 4 特性。
- 不跟踪上游新版本。 本仓库只做固定版本同步。跟进上游是一次 PR,评审者 能看到版本变化和 digest 变化。
- 不构建镜像。 自研镜像仍走各自的构建流水线,不应出现在本仓库。
- 不修改 Harbor 项目配置。
mirrors项目与 Robot Account 由 Harbor 管理 员维护。