添加集群时配置 Velero 镜像源

添加集群时的镜像源只用于让 Testudo 在业务集群中安装 Velero 组件。它对应 Cluster.spec.veleroInstall.imageRegistry，作用范围是 Velero 自身的 Deployment、Node Agent、插件 initContainer 和安装辅助镜像。

这个配置不负责业务应用镜像改写，也不负责把业务镜像同步到目标仓库。

什么时候需要配置

在以下场景中，需要在添加集群时填写 Velero 镜像源：

• 业务集群不能访问公网镜像仓库。
• Velero 官方镜像需要提前同步到内网仓库。
• 客户环境只允许从指定 Harbor 或 Registry 拉取镜像。
• 镜像仓库需要用户名和密码认证。

如果业务集群可以直接拉取默认 Velero 镜像，可以不配置该项。

配置含义

veleroInstall.imageRegistry 是一个镜像仓库前缀，格式不要带 http:// 或 https://。

示例：

harbor.example.com/disaster

Testudo 会基于这个前缀生成 Velero 安装 values，使业务集群中的 Velero 相关镜像指向内网仓库：

组件	默认来源	配置后的目标
Velero	velero/velero:v1.17.0	harbor.example.com/disaster/velero:v1.17.0
AWS 插件	velero/velero-plugin-for-aws:v1.13.0	harbor.example.com/disaster/velero-plugin-for-aws:v1.13.0
kubectl 辅助镜像	registry.example.com/disaster/kubectl:1.20.14	harbor.example.com/disaster/kubectl:1.20.14

镜像必须提前推送到目标仓库。Testudo 只改写安装时使用的镜像地址，不负责复制镜像。

控制台操作

进入 资源配置 / 集群配置管理，点击 添加集群。

在填写集群名称、认证方式和 kubeconfig/token 后，如果目标业务集群需要从内网仓库拉取 Velero 镜像，继续填写 Velero 镜像源：

• 镜像仓库前缀：例如 harbor.example.com/disaster。
• 用户名：镜像仓库需要认证时填写。
• 密码：镜像仓库需要认证时填写。

保存后，server 会在管理命名空间保存镜像仓库凭据，operator 会把凭据同步到业务集群的 velero 命名空间，并在安装 Velero 时引用该 pull secret。

API 示例

通过 kubeconfig 添加集群时，可以在请求体中携带 veleroInstall：

{
  "name": "prod-a",
  "description": "生产集群 A",
  "kubeConfig": "<base64-or-raw-kubeconfig>",
  "veleroInstall": {
    "imageRegistry": "harbor.example.com/disaster",
    "username": "registry-user",
    "password": "registry-password"
  }
}

如果仓库不需要认证，只保留 imageRegistry：

{
  "name": "prod-a",
  "kubeConfig": "<base64-or-raw-kubeconfig>",
  "veleroInstall": {
    "imageRegistry": "harbor.example.com/disaster"
  }
}

用户名和密码必须同时提供。imageRegistry 不能带 URL scheme，例如不要写成 https://harbor.example.com/disaster。

注册后验证

集群保存后，先确认 Cluster 资源记录了 Velero 镜像源：

kubectl get clusters.testudo.softcdata.com prod-a \
  -o jsonpath='{.spec.veleroInstall.imageRegistry}{"\n"}'

如果配置了认证，确认管理集群存在对应 Secret：

kubectl -n disaster-system get secret
kubectl get clusters.testudo.softcdata.com prod-a \
  -o jsonpath='{.spec.veleroInstall.registryCredentialSecretRef.name}{"\n"}'

再到业务集群检查 Velero 组件：

kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy,ds,pod
kubectl --kubeconfig prod-a.kubeconfig -n velero get secret
kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy velero \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
kubectl --kubeconfig prod-a.kubeconfig -n velero get deploy velero \
  -o jsonpath='{.spec.template.spec.imagePullSecrets}{"\n"}'

期望结果：

• Velero Deployment 和 Node Agent 正常运行。
• Velero 镜像前缀是配置的 imageRegistry。
• 配置了认证时，业务集群 velero 命名空间存在 velero-regcred-<cluster-name>。
• Velero Pod 没有 ImagePullBackOff、ErrImagePull 或认证失败事件。

常见问题

现象	可能原因	处理方式
Velero Pod ImagePullBackOff	目标仓库没有同步 Velero 镜像	先把 Velero、插件和 kubectl 镜像推送到 imageRegistry 前缀下
拉取镜像返回 unauthorized	用户名或密码错误，或 Secret 没有同步到业务集群	更新集群的 veleroInstall 凭据，检查业务集群 velero 命名空间中的 pull secret
提交时报 imageRegistry must not include a URL scheme	imageRegistry 写了 http:// 或 https://	改为 harbor.example.com/disaster 这种仓库前缀
Pod 事件提示 x509 或证书错误	私有仓库使用自签 CA，节点不信任	在业务集群节点或容器运行时配置仓库 CA
Pod 事件提示 connection refused 或 timeout	业务集群节点到镜像仓库网络不通	检查节点到仓库地址和端口的网络连通性

和业务镜像的边界

veleroInstall.imageRegistry 只保证 Velero 组件能在业务集群安装和运行。业务工作负载恢复后的镜像是否能拉取，仍取决于业务镜像是否存在于目标仓库、业务命名空间是否具备 imagePullSecret、节点是否信任目标仓库。

如果只是在添加集群阶段解决 Velero 安装问题，配置 veleroInstall.imageRegistry 就够了。