企业官网建设流程全解析

Velero BackupStorageLocation 详解：备份存储位置的 CRD 定义、参数配置与云厂商实战

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

导读

BackupStorageLocation（简称 BSL）是 Velero 中定义"备份数据存储到哪里"的核心 CRD 资源，它决定了备份文件与对象存储（Object Storage）之间的映射关系。本文以官方 API 类型文档为主线，结合当前仓库中 CRD 定义、CRD Schema 清单与控制器实现源码，系统讲解 BSL 的完整字段语义、AWS/Azure/GCP 三家的差异化配置，以及如何通过 YAML 与velero backup-location命令行创建和管理存储位置，读完即可独立为 Velero 配置可用、可验证、可多租户隔离的备份后端。

BackupStorageLocation 是什么

Velero 可以把备份存储在多种不同的位置（云端对象存储、S3 兼容存储等），这些位置在 Kubernetes 集群内统一通过BackupStorageLocation这个 CRD 来表示。它在集群中的角色类似于"备份后端的连接配置"：声明了使用哪个云厂商、哪个 bucket、目录前缀以及厂商专属的参数。

当前仓库的 CRD 结构定义在 pkg/apis/velero/v1/backupstoragelocation_types.go，其 CRD 完整 Schema 位于 config/crd/v1/bases/velero.io_backupstoragelocations.yaml。从 CRD 元数据可以看到该资源的常用快捷方式：

• 资源全名：backupstoragelocations.velero.io，命名空间级别（scope: Namespaced），通常部署在velero命名空间；
• 短名（shortName）：bsl，日常kubectl get bsl即可查询；
• 附加打印列：Phase（Available/Unavailable）、Last Validated（最近一次校验时间）、Default（是否为默认存储位置），方便直接观察每个存储位置的健康状态。

从源码结构看，StorageType当前只有一种受支持的类型ObjectStorage（见 backupstoragelocation_types.go），即所有存储位置最终都归结为对某个对象存储的访问。

最少一个默认存储位置：default的语义

Velero 集群中至少需要存在一个BackupStorageLocation，否则系统无法正常工作。这一点在控制器与存储工具中都有体现：internal/storage/storagelocation.go 的ListBackupStorageLocations在查询结果为空时直接返回错误 "no backup storage locations found"。

默认情况下，这个必需的位置被约定命名为default，但名字可以更改：

• 通过velero server的--default-backup-storage-location参数指定服务器侧默认位置名；
• 通过 BSL 自身的spec.default字段标记哪个位置是默认位置（CRD 的打印列也暴露了spec.default）。

没有显式指定存储位置的 Backup，会被保存到这个默认的BackupStorageLocation上。因此，规划默认位置时要选容量、可用性、成本都合适的后端。

需要注意：自 v0.10.0 起，BackupStorageLocation取代了旧的Config.backupStorageProvider配置键。当前文档对应的 v0.11.0 已是新机制；若迁移自更早版本，请将旧的 provider 配置迁移为 BSL 资源。

一个最简的 BackupStorageLocation YAML

官方文档给出的最简示例（AWS 场景）如下：

apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: provider: aws objectStorage: bucket: myBucket config: region: us-west-2

将上述内容保存为bsl-default.yaml后，用kubectl apply -f bsl-default.yaml创建即可。创建后，backup_storage_location_controller.go 会立刻对该位置进行连通性校验：

1. 调用location.Validate()校验 spec 合法性；
2. 通过backupStoreGetter.Get()按 provider 初始化对应的对象存储客户端（需要加载对应的 Object Store 插件）；
3. 调用backupStore.IsValid()实际探测 bucket 是否可达、凭证是否有效；
4. 将结果写回status.phase（Available或Unavailable）以及status.message。

因此，创建后可以马上用kubectl get bsl观察 Phase 是否为Available，这是判断配置是否成功的最直接手段。

主配置参数参考（Main Config Parameters）

官方文档将顶层参数归纳为以下表格，这些字段与 BackupStorageLocationSpec 一一对应：

补充：顶层还有哪些字段

对照 CRD Schema 与类型定义，除了上表外，spec还包含以下可选项（均标为+optional）：

• credential：SecretKeySelector，指向存放该位置专属凭证的 Secret（键为 Secret 名称、值为 Secret 内的数据键名），用于多位置使用不同凭证的场景；
• default：bool，标记该位置为默认存储位置；
• accessMode：枚举ReadOnly/ReadWrite，声明该位置的读写权限（定义见 backupstoragelocation_types.go）；
• backupSyncPeriod：metav1.Duration，多长时间从对象存储同步一次 Backup API 对象，设为0可禁用同步；
• validationFrequency：metav1.Duration，多长时间校验一次该对象存储的可用性，设为0可禁用校验。

其中校验频率的优先级规则在 internal/storage/storagelocation.go 的IsReadyToValidate中实现：BSL 自身配置的validationFrequency优先于服务器默认值；负值会被回退到服务器默认值；首次部署时无论频率如何都会强制校验一次。控制器在 backup_storage_location_controller.go 中每 10 秒触发一次周期入队，再依据上述规则决定是否真正执行校验，从而保证默认 1 分钟级别的校验频率不会因为排队而产生明显漂移。

另外objectStorage下还有两个 TLS 相关字段（当前文档未提及，但对自建 S3 兼容存储很实用）：

• caCert：[]byte，直接内嵌用于校验对象存储 TLS 连接的 CA 证书包（已标记 Deprecated）；
• caCertRef：SecretKeySelector，引用同命名空间下存放 CA 证书包的 Secret（推荐用法）。

这两者互斥，不能同时设置。验证逻辑在 backupstoragelocation_types.go 的Validate()方法，对应测试见 backupstoragelocation_types_test.go：五个用例分别覆盖两者均未设置、仅设caCert、仅设caCertRef、两者同时设置（应报错）、以及objectStorage为 nil 的情况。

AWS（含其他 S3 兼容存储）配置

AWS 及 S3 兼容存储（如 MinIO）的专属参数放在spec.config下：

实战示例 1：MinIO 本地存储

结合s3ForcePathStyle、s3Url与prefix，一个面向 MinIO 的完整配置如下：

apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: provider: aws objectStorage: bucket: velero prefix: velero config: region: minio s3ForcePathStyle: "true" s3Url: http://minio:9000 publicUrl: https://minio.example.com

要点说明：

• s3Url必须指向 MinIO 服务可达地址（集群内可用 Service 名，如http://minio:9000）；
• s3ForcePathStyle: "true"让客户端使用 path-style 访问而非 virtual-hosted style，这是 MinIO 类服务的硬性要求；
• prefix让所有备份数据落在velero桶的velero/目录下，避免与其他数据混放；
• publicUrl用于集群外（如 CLI 端）下载日志等场景。

实战示例 2：AWS S3 服务端加密

apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: aws-encrypted namespace: velero spec: provider: aws objectStorage: bucket: my-encrypted-bucket config: region: us-east-1 kmsKeyId: alias/velero-backup-key

启用 KMS 加密时请确保 Velero 使用的 IAM 凭证具备对该 KMS 密钥的kms:Encrypt、kms:Decrypt权限。

Azure 配置

Azure 的专属配置同样放在spec.config下：

Azure 场景下的 BSL 示例：

apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: provider: azure objectStorage: bucket: velero prefix: velero config: resourceGroup: my-resource-group storageAccount: my-storage-account

注意：Azure 的bucket字段语义对应其 Blob 容器（Container）名称。从控制器对错误信息的处理（backup_storage_location_controller.go 的sanitizeStorageError）可以看到，Azure 返回的错误往往包含冗长的 HTTP 响应与 XML 报文，Velero 会提取其中的错误码与 Message（如ContainerNotFound），同时脱敏 URL 中的 SAS 令牌参数（sig、se、sp等），最终将简洁可读的错误写入status.message——这意味着 Azure 场景下排查配置问题时，直接看kubectl get bsl -o yaml的status.message会比看控制器日志更高效。

GCP 配置

GCP（Google Cloud Storage）无需任何config参数：

apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: provider: gcp objectStorage: bucket: my-velero-bucket

GCP 的凭证与 region 等上下文由环境变量或spec.credential引用的 Secret 提供，spec.config保持为空即可。

通过 CLI 创建与管理存储位置

除了手写 YAML，Velero 提供了完整的velero backup-location子命令族，对应源码位于 pkg/cmd/cli/backuplocation：

创建（create）

velero backup-location create <NAME> \ --provider aws \ --bucket velero \ --prefix velero \ --config region=us-east-1,s3ForcePathStyle=true,s3Url=http://minio:9000 \ --default

对应 create.go 支持的常用参数：

从 create.go 可以看到校验逻辑：--provider与--bucket必填、--backup-sync-period必须非负、--credential最多一对键值。另外 create.go 强制"默认位置唯一性"：若集群已存在默认位置，再次使用--default创建会直接报错，需先取消旧默认位（见下方set）。

其他管理命令

• velero backup-location get：列出所有存储位置及其 Phase、校验时间等信息（对应 get.go）；
• velero backup-location set --default：将某个已有位置设为默认（对应 set.go）；
• velero backup-location delete：删除指定位置（对应 delete.go）。

多存储位置与默认位置仲裁机制

当集群中存在多个 BSL 时，控制器会执行默认位置仲裁（backup_storage_location_controller.go 的ensureSingleDefaultBSL）：

• 若发现多个spec.default=true的位置，保留creationTimestamp最新的一个为默认，其余自动改为false；
• 若没有任何默认位置，会记录告警日志：There is no existing BackupStorageLocation set as default. Please see velero backup-location -h for options.

也就是说，即使误配了多个默认位置，系统也会收敛到唯一默认，避免"备份到底存到哪"的歧义。结合spec.credential、spec.accessMode与prefix，可以在一个集群内按团队、环境或合规要求拆分多个存储后端（例如：默认位置存日常备份、ReadOnly位置只用于异地恢复读取），实现灵活的多存储管理。

排障速查：从 Phase 到 message

BackupStorageLocation的生命周期阶段定义在 backupstoragelocation_types.go：

校验失败时status.message会记录脱敏后的错误摘要，控制器也会按"全部不可用 / 部分不可用 / 无默认位"三种情况输出不同级别的日志（backup_storage_location_controller.go）。常见排查路径：

# 查看所有存储位置及状态 kubectl get bsl -n velero # 查看具体位置的错误详情 kubectl get bsl default -n velero -o yaml

重点关注status.phase、status.message、status.lastValidationTime：若lastValidationTime长期停留在过去，说明按当前validationFrequency尚未到下一次校验时间；若Unavailable且message提示凭证/桶不存在，则优先检查 Secret 凭证、bucket 名称与s3Url/region是否正确。

小结

BackupStorageLocation是 Velero 备份链路的第一环，也是最容易踩坑的一环：bucket、region、path-style、凭证、默认位归属任何一个不对，备份都会失败。本文以官方 API 文档为基础，补充了 CRD 结构、控制器校验流程、默认位置仲裁规则、CLI 参数与排障手段。实践时建议按"先kubectl apply创建 → 再kubectl get bsl观察 Phase → 最后发起一次测试备份"的顺序验证配置，确保后端连通后再投入正式备份任务。

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero