Velero VolumeSnapshotLocation 详解：卷快照位置的 API 设计、参数参考与源码实现

Velero VolumeSnapshotLocation 详解卷快照位置的 API 设计、参数参考与源码实现【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/veleroVolumeSnapshotLocationVSL是 Velero 中描述“卷快照存放在哪里”的核心 API 类型一个 VSL 声明了一个云厂商provider加上该厂商下的一个具体位置如 AWS 的 region credential 配置。读完本文你将完整掌握 VSL 的资源结构、全部可配置参数provider / config / credential、创建与查看 VSL 的 CLI 操作以及备份控制器在备份运行时如何校验、选择和注入凭据的完整源码链路从而能够为多区域、多云场景正确配置卷快照位置。什么是 VolumeSnapshotLocation卷快照位置volume snapshot location是 Velero 备份时存放卷快照的位置。Velero 可以被配置为从多个云厂商的存储上创建卷快照并且允许每个 provider 配置多个可用的VolumeSnapshotLocation但每次备份执行时每个 provider 只能选择一个位置。每个 VolumeSnapshotLocation 描述一个 “provider location” 的组合在集群中通过VolumeSnapshotLocationCRD 表示。Velero 对每个云厂商至少需要一个VolumeSnapshotLocation否则涉及该厂商卷的备份无法执行。从 API 类型定义看VolumeSnapshotLocation 结构体 由TypeMeta、ObjectMeta、Spec和Status四部分组成且带有几个值得注意的标记// kubebuilder:resource:shortNamevsl // kubebuilder:object:generatetrue // kubebuilder:storageversion // kubebuilder:printcolumn:nameProvider,typestring,JSONPath.spec.provider,... // kubebuilder:printcolumn:namePhase,typestring,JSONPath.status.phase,... // kubebuilder:printcolumn:nameAge,typedate,JSONPath.metadata.creationTimestamp短名称vsl即kubectl get vsl -n velero可以直接查询所有快照位置三个打印列Provider / Phase / Agekubectl get vsl输出中会直接显示 provider 名、可用阶段和创建时间storageversion标记表明 v1 版本是该 CRD 的存储版本与 CRD 清单 中scope: Namespaced、served: true、storage: true的设置一致。VolumeSnapshotLocation 完整示例一个典型的 YAMLVolumeSnapshotLocation如下以 AWS 为例快照存放在 us-west-2 区域apiVersion: velero.io/v1 kind: VolumeSnapshotLocation metadata: name: aws-default namespace: velero spec: provider: aws credential: name: secret-name key: key-in-secret config: region: us-west-2 profile: default对应地也可以直接用 Velero CLI 创建等价的资源。create 命令实现 暴露了四个 flagvelero snapshot-location create NAME \ --provider aws \ --config regionus-west-2 \ --config profiledefault \ --credential secret-namekey-in-secret--provider卷快照提供者的名称如 aws、azure、gcp必填源码中的校验为--provider is required见 Validate 方法--config传给 volume snapshotter 插件的 key-value 配置项可多次指定--labels应用到该 VSL 上的标签可用于后续velero snapshot-location get --selector过滤--credential以“Secret 名 Secret 内数据键”的一对键值指定凭据只允许 1 个 key/value pair对应 API 中的spec.credential字段。创建成功后CLI 输出Snapshot volume location NAME configured successfully.。此外 CLI 还提供了velero snapshot-location get列出或按名称获取 VSL支持-llabel selector 过滤也支持 shell 补全函数CompleteVolumeSnapshotLocationNamesvelero snapshot-location set目前仅支持更新已有 VSL 的--credential字段。参数参考VSL 的可配置参数如下这里在原文档基础上补充了 API 类型定义 和 CRD schema 中的字段级细节主要配置参数KeyTypeDefault含义providerStringRequired Field用于创建/存放卷快照的存储 provider 名称。该值必须与集群中 volume snapshotter 插件注册的 provider 名一致应参考对应 provider 插件文档中的取值。configmap string stringNone (Optional)传给 volume snapshotter 插件的 provider 特定配置键值对如 AWS 的region、profile。具体可用的键由各 provider 插件决定。credentialcorev1.SecretKeySelectorOptional Field该位置使用的凭据信息是一个 Kubernetes SecretKeySelector指向 Velero 命名空间下的 Secret。credential/nameStringOptional Field包含凭据信息的 Secret 名称位于 Velero 命名空间内。在 CRD schema 中该字段默认值为空字符串注释说明其“实际上必填”。credential/keyStringOptional Field在该 Secret 中要使用的数据键。CRD schema 中credential对象的required列表只包含key见 CRD credential schema。需要注意两个 API 结构上的细节provider是spec中唯一在 CRD 层required的字段schema required 段其余均为可选credential的 Go 类型直接复用corev1.SecretKeySelector见 VolumeSnapshotLocationSpec因此它继承了 K8s 原生结构的所有字段name、key、optional但 Velero 的 CLI 层只接受“Secret 名 数据键”这一种表达方式。Status 字段Phasespec之外VSL 还有一个生命周期状态。VolumeSnapshotLocationStatus 只包含一个phase字段取值为枚举Available/Unavailable由 kubebuilder 的kubebuilder:validation:EnumAvailable;Unavailable约束Available该位置可读写Unavailable该位置当前不可用。该状态由 volume snapshotter 插件在CheckLocation调用中返回并反映到status.phase通过kubectl get vsl -n velero的 Phase 列即可查看。备份时如何选择 VolumeSnapshotLocationCLI 层的velero backup create支持--volume-snapshot-locations参数显式指定位置而真正决定“用哪个 VSL”的逻辑在备份控制器的validateAndGetSnapshotLocations方法中实现。其规则可以概括为四条存在性校验备份spec.volumeSnapshotLocations中的每个名字必须在同一命名空间中存在对应的VolumeSnapshotLocation对象否则备份失败并报告a VolumeSnapshotLocation CRD for the location ... needs to be created before this snapshot can be executed每个 provider 恰好一个位置如果 backup spec 中对同一 provider 指定了多个不同的 VSL 名字例如同时给了两个 aws 的位置会报more than one VolumeSnapshotLocation name specified for provider ...默认位置兜底如果某 provider 有多个候选 VSL 而 backup spec 又没有显式指定则使用--default-vsl启动参数配置的默认位置名若连默认位置都没有配置则报provider ... has more than one possible volume snapshot location, and none were specified explicitly or as a default唯一位置自动使用如果某 provider 在集群中只有一个 VSL则自动使用该位置无需任何显式配置。校验通过后控制器会遍历所有选中的 VSL调用凭据注入逻辑// add credential to config for each location for _, location : range providerLocations { err volume.UpdateVolumeSnapshotLocationWithCredentialConfig(location, b.credentialFileStore) ... }凭据如何注入到插件配置VSL 的credential字段并不是直接透传给插件的而是经过 UpdateVolumeSnapshotLocationWithCredentialConfig 处理若spec.config为空则初始化为空 map先删除用户自己写入的credentialsFile键——源码注释明确说明这是为了“防止路径穿越path traversal漏洞”不允许用户在config里伪造一个插件读取的凭据文件路径如果 VSL 声明了credential且存在 credential file store则通过credentialStore.Path(location.Spec.Credential)把 Secret 内容解析为服务器本地磁盘上的一个临时文件并把该路径写入spec.config[credentialsFile]交给插件使用。这解释了为什么 AWS 插件文档中的region、profile等config键是用户可写的而credentialsFile是受保留语义保护的键。快照器实例的生命周期与快照元数据在备份执行阶段每个选中的 VSL 都会映射到一个 volume snapshotter 插件实例。VolumeSnapshotterCache 以 VSL 的Name为 key 做缓存首次SetNX(location)时通过GetVolumeSnapshotter(location.Spec.Provider)按 provider 名取出插件再用snapshotter.Init(location.Spec.Config)初始化此时传入的 config 已包含上一步注入的credentialsFile之后同一 VSL 复用同一实例。这也印证了 API 设计中“每个 VSL 描述一个独立的 provider 位置组合”的语义——不同位置即使 provider 相同也会持有各自独立的插件实例与配置。备份完成后每个卷快照的记录中会保存它所属的 VSL 名字。SnapshotSpec 中的Location字段即“该快照存储所在的 VolumeSnapshotLocation 名称”与BackupName、PersistentVolumeName、ProviderVolumeID、VolumeType、VolumeAZ等一起被序列化进备份归档。这一设计保证恢复restore阶段能够知道该去哪里查找云厂商侧的快照 IDProviderSnapshotID是备份与恢复两端能闭环的关键元数据。小结VolumeSnapshotLocation是 Namespaced CRD短名vsl核心语义是provider 位置provider必填config传插件特定配置credential用 SecretKeySelector 指向 Velero 命名空间下的 Secret一个 provider 可配置多个 VSL但每次备份每个 provider 只能选一个未显式指定时按“唯一位置自动使用 / 默认位置兜底”的规则解析逻辑见 backup 控制器credential会在服务器侧被转换为config.credentialsFile的本地文件路径注入给插件且用户自行写入的credentialsFile会被强制剥离以防路径穿越查看与创建入口分别是 get 命令 与 create 命令API 与 CRD 定义分别在 volume_snapshot_location_type.go 和 velero.io_volumesnapshotlocations.yaml。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考