charts-syncer 技术文档

概述与主要用途

charts-syncer 是一款用于在 Helm 图表仓库之间同步 Helm 图表包及关联容器镜像的工具。它支持多种类型的仓库（如 HELM、CHARTMUSEUM、HARBOR、OCI、LOCAL），能够灵活适配不同的环境需求，包括在线同步和离线（断开连接的环境）同步场景。作为 Bitnami 容器镜像，charts-syncer 旨在简化跨仓库的图表迁移与维护流程。

核心功能与特性

• 多类型仓库支持：兼容 HELM、CHARTMUSEUM、HARBOR、OCI 和 LOCAL 等多种类型的源和目标仓库。
• 选择性同步：支持按日期、仅最新版本等条件筛选同步的图表。
• 容器镜像同步：可配置同步图表所引用的容器镜像（需图表包含 .relok8s-images.yaml 文件）。
• *离线同步能力：支持两步迁移模式，适用于源和目标仓库无法同时访问的断开连接环境。
• 依赖自动更新：自动更新图表依赖文件（如 requirements.yaml、Chart.yaml 等），确保依赖从目标仓库拉取。
• 配置灵活性：通过配置文件或环境变量设置仓库认证信息，支持自定义容器镜像仓库路径。
• *文档自动更新：同步时自动更新图表 README.md 中的仓库地址和部署命令。

使用场景与适用范围*

• 多仓库同步：保持开发、测试、生产环境的 Helm 图表仓库同步。
• 图表迁移：将图表从公共仓库（如 Bitnami）迁移到私有仓库（如 Harbor OCI 仓库）。
• *离线环境部署：在无直接网络连接的环境中，通过离线包方式同步图表及镜像。
• 依赖统一管理：确保图表依赖的容器镜像指向内部私有镜像仓库，增强安全性与可控性。

使用方法与配置说明

前提条件

• 图表需使用标准格式定义镜像信息（values.yaml 文件中包含 image.registry、image.repository 和 image.tag字段）*。
• 若需同步容器镜像，源图表需包含 .relok8s-images.yaml 文件（详见 asset-relocation-tool-for-kubernetes）。
• 使用 OCI 作为源仓库时，需指定图表列表或配置图表索引文件。

基本使用

同步所有 Helm*图表**```console

$ charts-syncer sync --config config.yaml

#### *从指定日期同步图表* ```console
$ charts-syncer sync --config config.yaml --from-date 2020-05-15

仅同步每个图表的最新版本* ```console

$ charts-syncer sync --config config.yaml --latest-version-only*

### *高级使用***####*同步图表及关联容器镜像*默认仅同步图表包*，需在配置文件中启用容器镜像同步：

```yaml
relocateContainerImages:* true  # 启用容器镜像同步
source:
  repo:* ...
target:* ...* ```

> **注意*：需确保源图表包含 `.relok8s-images.yaml` 文件，用于指定镜像位置信息。

####* 断开环境中的图表与镜像同步*适用于源和目标仓库无法同时访问的场景，支持两步离线迁移：

1. **导出阶段**：从源仓库下载图表及镜像并保存到本地目录。
2. **导入阶段**：将本地目录中的图表及镜像上传到目标仓库*。

详细步骤参见 离线同步文档。


### 配置说明*####*配置文件结构*配置文件需指定源仓库、目标仓库、同步规则等信息。完整配置项及说明见 charts-syncer.yaml。

**示例配置文件**：

```yaml
# 示例配置文件
relocateContainerImages: false  # 是否同步容器镜像
source:
  repo:
    kind: HELM  # 源仓库类型：HELM/CHARTMUSEUM/HARBOR/OCI/LOCAL
    url: [***]  # 源仓库URL
    # 源仓库认证信息（可选）
    # auth:
    #   username: "SOURCE_USER"
    #   password: "SOURCE_PWD"
  # 源容器镜像仓库认证（可选）
  # containers:
  #   auth:
  #     registry: "docker.io"
  #     username: "IMAGE_USER"
  #     password: "IMAGE_PWD"
target:
  repoName: my-private-repo  # 目标仓库名称（用于README更新）
  containerRegistry: registry.example.com  # 目标容器镜像仓库地址
  containerRepository: charts  # 目标容器镜像仓库路径（可选）
  repo:
    kind: OCI  # 目标仓库类型
    url: [***]  # 目标仓库URL
    # 目标仓库认证信息（可选）
    # auth:
    #   username: "TARGET_USER"
    #   password: "TARGET_PWD"
# 需同步的图表列表（OCI源仓库必填，其他类型可选，支持自动发现）
charts:
  - redis
  - mariadb
# 需跳过的图表列表（与charts字段互斥）
# skipCharts:
#   - wordpress

仓库类型示例Harbor 仓库示例Harbor 图表仓库 URL 格式为 [***]{HARBOR_DOMAIN}/chartrepo/${HARBOR_PROJECT}：

target:
  repo:
    kind: HARBOR
    url: [***]

OCI 仓库示例适用于 Harbor 2.0+ OCI 后端或 AWS ECR 等 OCI 兼容仓库：

target:
  repo:
    kind: OCI
    url: [***]  # 支持子路径
  # OCI仓库认证（如Harbor机器人账号）
  repo:
    auth:
      username: "robot$my-project+sync-user"
      password: "robot-token"

本地目录示例将图表同步到本地目录，用于离线迁移：

target:
  repo:
    kind: LOCAL
    path: ./local-charts  # 本地目录路径

环境变量配置认证信息可通过环境变量设置仓库认证，优先级高于配置文件：

仓库兼容性矩阵

Docker 部署方案示例

基本 Docker 运行命令

# 拉取 charts-syncer 镜像（假设镜像名称为 bitnami/charts-syncer）
docker pull bitnami/charts-syncer:latest

# 运行同步（挂载本地配置文件）
docker run --rm -v $(pwd)/config.yaml:/config.yaml bitnami/charts-syncer sync --config /config.yaml

带环境变量的 Docker 命令（认证信息通过环境变量传入）

docker run --rm \
  -v $(pwd)/config.yaml:/config.yaml \
  -e SOURCE_REPO_AUTH_USERNAME=source-user \
  -e SOURCE_REPO_AUTH_PASSWORD=source-pass \
  -e TARGET_REPO_AUTH_USERNAME=target-user \
  -e TARGET_REPO_AUTH_PASSWORD=target-pass \
  bitnami/charts-syncer sync --config /config.yaml

图表同步过程中的变更

同步时工具会自动修改图表文件以适配目标环境，主要变更如下：

更新 values.yaml 及 values-production.yaml

修改镜像仓库地址，示例：

# values.yaml 变更示例
image:
-  registry: docker.io
-  repository: bitnami/ghost
+  registry: registry.example.com
+  repository: charts/ghost
  tag: 3.22.2-debian-10-r0

更新依赖文件

• Helm v2：更新 requirements.yaml 和 requirements.lock 中的仓库地址。
• Helm v3：更新 Chart.yaml 和 Chart.lock 中的仓库地址。

示例（Helm v3 的 Chart.lock）：

# Chart.lock 变更示例
dependencies:
- name: zookeeper
-  repository: [***]
+  repository: [***]
  version: 5.21.9

更新 README.md

修改文档中的仓库添加命令和部署命令，示例：

# README.md 变更示例
 ## TL;DR;

 ```console
-$ helm repo add bitnami [***]
-$ helm install my-release bitnami/ghost
+$ helm repo add my-private-repo [***]
+$ helm install my-release my-private-repo/ghost

## 在 Kubernetes 中部署

可通过 Kubernetes CronJob 实现定期自动同步。示例 CronJob 配置（详情参见 Kubernetes 部署指南）：

```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: charts-syncer
spec:
  schedule: "0 3 * * *"  # 每天凌晨3点执行
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: charts-syncer
            image: bitnami/charts-syncer:latest
            command: ["sync", "--config", "/config/config.yaml"]
            volumeMounts:
            - name: config-volume
              mountPath: /config
            env:
            - name: SOURCE_REPO_AUTH_USERNAME
              valueFrom:
                secretKeyRef:
                  name: repo-credentials
                  key: source-username
            - name: SOURCE_REPO_AUTH_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: repo-credentials
                  key: source-password
            # 其他环境变量...
          volumes:
          - name: config-volume
            configMap:
              name: charts-syncer-config
          restartPolicy: OnFailure

构建方法

如需自行构建工具，参见 开发者文档。

许可证

Copyright © 2024 Broadcom. 术语“Broadcom”指 Broadcom Inc. 及其子公司。

本工具基于 Apache License 2.0 许可证开源。详情参见 LICENSE。