Velero Backup Storage Location 完全指南CRD 参数、默认位置与可用性校验机制【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本指南基于 Velero 官方 API 文档 backupstoragelocation.md系统讲解BackupStorageLocation简称 BSL这一核心 CRD备份存储位置的资源定义、全部可配置参数、默认位置的选择机制以及 Velero 服务端如何通过控制器校验位置的可用性。读完本文你将能够独立编写、校验、创建和管理一个面向任意对象存储提供商的 BSL 资源并理解其背后的源码实现。什么是 BackupStorageLocationVelero 可以将备份数据存储到多种对象存储位置AWS S3、Azure Blob Storage、GCP 云存储、MinIO 等这些位置在集群内统一通过BackupStorageLocationCRD 来表示。从源码结构看BackupStorageLocation是一个命名空间级别Namespaced的 CRD其类型定义位于 pkg/apis/velero/v1/backupstoragelocation_types.go生成的 CRD 清单为 config/crd/v1/bases/velero.io_backupstoragelocations.yaml它拥有短名bsl可以方便地用kubectl get bsl查看。在集群中必须至少存在一个BackupStorageLocation否则 Velero 无法工作。internal/storage/storagelocation.go中的ListBackupStorageLocations函数在找不到任何 BSL 时会直接返回错误no backup storage locations found。默认情况下这个位置的名字约定为default所有未显式指定存储位置的备份都会被保存到这个默认位置。该默认名字可以通过启动velero server时的--default-backup-storage-location参数修改不过该参数在 v1.10 版本中已被标记为DEPRECATED将在 v2.0 移除官方推荐改用velero backup-location set --default命令见 pkg/cmd/server/config/config.go。一个标准的 BSL 配置示例原文档给出如下示例 YAML它声明了一个名为default、位于velero命名空间、使用 AWS S3 作为底层存储的 BSLapiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: backupSyncPeriod: 2m0s provider: aws objectStorage: bucket: myBucket credential: name: secret-name key: key-in-secret config: region: us-west-2 profile: default这是对上面字段的快速解读apiVersion: velero.io/v1当前存储版本为 v1CRD 清单中storage: truev1 是唯一的 served 版本provider: aws指定使用 AWS 对象存储插件config中的region与profile是该插件特有的配置objectStorage.bucket备份上传的目标桶credential引用velero命名空间下一个名为secret-name的 Secret并用其中的key-in-secret键作为访问凭证backupSyncPeriod控制从对象存储同步备份对象的频率。仓库的 tilt-resources/examples/velero_v1_backupstoragelocation.yaml 提供了一个面向 MinIO 的真实最小化示例可作为自建 S3 兼容存储时的参考apiVersion: velero.io/v1 kind: BackupStorageLocation metadata: labels: component: velero name: default namespace: velero spec: config: region: minio s3ForcePathStyle: true s3Url: http://minio.velero.svc:9000 objectStorage: bucket: velero provider: aws注意对于 MinIO 这类 S3 兼容存储provider仍填aws但必须通过s3Url指定服务地址并通过s3ForcePathStyle: true启用路径风格访问。参数参考Main config parameters原文档完整列出了以下核心配置参数下表全部继承并补充了类型定义中的细节KeyTypeDefaultMeaningproviderStringRequired Field存储备份所用的对象存储提供商名称取值需参考对应提供商插件文档见 supported-providers例如aws、azure、gcp。objectStorageObjectStorageLocationRequired Field面向给定提供商的对象存储规格在类型定义StorageType中声明为必填非 nil。objectStorage/bucketStringRequired Field备份上传的目标存储桶。CRD schema 中该字段为必填项。objectStorage/prefixStringOptional Field存储桶内用于存放 Velero 数据的目录前缀可选。objectStorage/caCertStringOptional Field用于校验 TLS 连接的 base64 编码 CA 证书包。注意该字段已被标记为 Deprecated官方推荐改用caCertRef。objectStorage/caCertRefSecretKeySelectorOptional Field引用同命名空间下包含 CA 证书包的 SecretBackupStorageLocationSpec与 Secret 必须在同一命名空间。configmap[string]stringNone (Optional)传递给对象存储插件的提供商特有配置键值对详见提供商插件文档。accessModeStringReadWriteVelero 访问备份存储位置的方式合法值为ReadWrite、ReadOnly。backupSyncPeriodmetav1.DurationOptional FieldVelero 从对象存储同步备份对象的频率默认继承服务端备份同步周期设为0s可禁用同步。validationFrequencymetav1.DurationOptional FieldVelero 校验对象存储有效性的频率默认继承服务端校验频率默认 1 分钟设为0s可禁用校验。credentialcorev1.SecretKeySelectorOptional Field与该位置配套使用的凭证信息。credential/nameStringOptional Field位于 Velero 命名空间、包含凭证信息的 Secret 名称。credential/keyStringOptional Field该 Secret 中使用的键名。defaultBoolOptional Field将该位置标记为默认备份存储位置源码字段见下文默认位置小节。深入源码BSL 的类型与校验逻辑spec 与 status 的结构在 pkg/apis/velero/v1/backupstoragelocation_types.go 中BackupStorageLocationSpec除文档列出的字段外还包含一个Default bool字段用于在 spec 中直接标记默认位置BackupStorageLocationStatus则记录了运行期观测状态PhaseAvailable可用或Unavailable不可用LastSyncedTime/LastValidationTime最近一次同步与校验时间Message状态说明信息LastSyncedRevision与 status 中的AccessMode已被标记 Deprecated将在 v2.0 移除。CRD 清单 config/crd/v1/bases/velero.io_backupstoragelocations.yaml 通过additionalPrinterColumns定义了kubectl get bsl默认展示的列Phase、Last Validated、Age、Default便于一眼看出每个位置的状态与是否默认。校验规则caCert 与 caCertRef 二选一BackupStorageLocation.Validate()实现了一条关键约束caCert与caCertRef不能同时设置否则返回错误cannot specify both caCert and caCertRef in objectStorage。对应的单元测试 pkg/apis/velero/v1/backupstoragelocation_types_test.go 覆盖了四种场景两者都不设置、仅设置caCert、仅设置caCertRef均通过以及两者同时设置预期报错。在配置自定义 CA 时优先使用caCertRef引用 Secret更便于轮换证书。可用性校验控制器Phase 是如何产生的BackupStorageLocation的Available/Unavailable状态由 pkg/controller/backup_storage_location_controller.go 中的backupStorageLocationReconciler维护。其Reconcile流程为列出命名空间内全部 BSL若一个都不存在则记录错误至少需要一个通过ensureSingleDefaultBSL确保默认位置唯一见下一节调用location.Validate()校验 spec即 caCert/caCertRef 互斥规则通过backupStoreGetter.Get(...)获取对象存储客户端并调用backupStore.IsValid()验证真实连通性根据结果更新status.phase与status.message验证失败置为Unavailable并写入原因成功置为Available每次校验都会刷新status.lastValidationTime。控制器同时输出可用性指标每个 Available 的 BSL 注册RegisterBackupLocationAvailableUnavailable 的注册RegisterBackupLocationUnavailable。若所有 BSL 均不可用日志会以 Error 级别输出Current BackupStorageLocations available/unavailable/unknown统计。值得注意的工程细节控制器的周期入队间隔bslValidationEnqueuePeriod被刻意设置为 10 秒因为默认校验频率是 1 分钟若入队间隔也设成 1 分钟每个 BSL 的实际校验间隔会被拉长到 2 分钟见源码注释与 internal/storage/storagelocation.go。validationFrequency 与 IsReadyToValidate 规则internal/storage/storagelocation.go的IsReadyToValidate函数给出了校验频率的精确语义这也是官方文档中0s 禁用校验的源码依据BSL 未显式设置validationFrequency时使用服务端默认频率首次校验无条件进行lastValidationTime为空时返回true保证每个位置至少被校验一次频率为 0 表示禁用校验返回false只有当前时间 ≥ 上次校验时间 校验频率时才再次校验负值会被修正回服务端默认值。默认位置Default BSL的选择机制文档提到默认位置名为default、可通过--default-backup-storage-location修改。结合源码默认位置的实际裁决逻辑比这更细致ensureSingleDefaultBSL会扫描所有spec.default true的 BSL若存在多个保留creationTimestamp 最新的一个并将其余的spec.default改回false若一个都没有则回退到服务端参数velero server --default-backup-storage-location已废弃确定的默认位置若仍没有默认位置控制器会输出警告并提示查看velero backup-location -h。因此v1.10 起推荐直接在 BSL 的 spec 中设置default: true或在创建时使用velero backup-location create --default标记。未显式指定存储位置的备份会落到默认 BSL 上internal/storage/storagelocation.go的GetDefaultBackupStorageLocations专门负责收集所有带默认标记的位置。通过 CLI 管理 BSLBSL 的命令组由 pkg/cmd/cli/backuplocation 提供包含 create / get / delete / set 四个子命令# 创建 BSL常用参数见下 velero backup-location create default \ --provider aws \ --bucket myBucket \ --prefix backup \ --default # 查看所有 BSL 及其状态 velero backup-location get # 删除 BSL velero backup-location delete default # 将某个 BSL 标记为默认位置 velero backup-location set default --default # 修改访问模式 velero backup-location set default --access-mode ReadOnly从 pkg/cmd/cli/backuplocation/create.go 可以看到create支持的全部 flag与 CRD 字段一一对应Flag含义--provider存储提供商名称如 aws、azure、gcp--bucket存放备份的对象存储桶--default将该新位置设为默认 BSL可选--prefix桶内存放 Velero 数据的前缀可选--backup-sync-period从对象存储同步备份对象的频率0s禁用默认 1 分钟--validation-frequency校验 BSL 有效性的频率0s禁用默认 1 分钟--cacert校验 TLS 连接使用的 CA 证书包文件可选典型场景与注意事项多存储位置共存集群中可以同时存在多个 BSL如不同 Region、不同提供商、冷热分层备份时可通过--storage-location指定目标位置ReadOnly访问模式的位置仅用于读取例如异地灾备只读副本不会被写入新备份。配置真实性provider的具体取值以及config中可用的键如 AWS 的region、profile、s3ForcePathStyle、s3UrlAzure 的resourceGroup、storageAccount等由对应对象存储插件决定必须查阅 supported-providers 中链接的插件文档确认Velero 核心代码不解释这些键。排障入口当velero backup-location get显示PhaseUnavailable时查看该 BSL 的status.message即可获得失败原因如凭证错误、桶不存在、网络不通控制器还会对 Azure 等云厂商的冗长 HTTP 错误做脱敏清洗sanitizeStorageError屏蔽 SAS token 等敏感信息后写入 status便于直接阅读。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考