Velero VolumeSnapshotLocation 配置指南：为 Kubernetes 备份卷快照定义云存储位置-开发者社区

Velero VolumeSnapshotLocation 配置指南：为 Kubernetes 备份卷快照定义云存储位置

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

VolumeSnapshotLocation（卷快照位置）是 Velero 中用于定义"把备份产生的卷快照存到哪里"的核心 CRD 资源。本篇指南以 v0.11.0 文档为骨架，结合仓库中 VolumeSnapshotLocation API 定义与 backup 控制器的实现，系统讲解 VSL 的 YAML 结构、provider 配置参数、CLI 管理命令以及备份时的选择与校验机制，帮助你为多云环境正确规划并落地卷快照存储位置。

VolumeSnapshotLocation 是什么

在 Velero 中，卷快照位置（Volume Snapshot Location，简称 VSL）是备份过程中所创建的卷快照的存储位置。当一次备份包含 PV/PVC 卷时，Velero 会调用云厂商的快照 API（如 AWS EBS、Azure Managed Disk、GCP PD）为卷创建快照，而每个 VSL 就描述了"用哪个云厂商、在哪个区域/资源组存放这些快照"。

从源码看，VSL 是注册在velero.io分组下的标准 CRD，拥有短名vsl，并带有Provider、Phase、Age三个打印列（见 volume_snapshot_location_type.go）：

// VolumeSnapshotLocation is a location where Velero stores volume snapshots. type VolumeSnapshotLocation struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` Spec VolumeSnapshotLocationSpec `json:"spec,omitempty"` Status VolumeSnapshotLocationStatus `json:"status,omitempty"` }

其 Spec 由三部分组成（见 pkg/apis/velero/v1/volume_snapshot_location_type.go）：

provider：提供卷快照能力的云厂商名称；
config：provider 专属的键值配置，如 AWS 的region、Azure 的resourceGroup；
credential（可选）：指定该位置使用的凭据 Secret，优先级高于全局凭据。

Status 中仅有一个Phase字段，取值Available或Unavailable（源码），用来标记该位置当前是否可用。

设计要点：每个 provider 至少一个位置

Velero 可以为多个云厂商分别配置卷快照位置；对同一个 provider，也可以配置多个候选 VSL，但在执行一次备份时，每个 provider 最多只能选中一个位置。也就是说：

如果集群中有 AWS、Azure、GCP 的卷，每个涉及的 provider 都需要至少一个 VSL；
同 provider 下可以有多个 VSL（例如按区域划分aws-us-east-1、aws-us-west-2），但备份时按名称指定后，同名 provider 只能生效一个。

这一点在备份控制器的校验逻辑中体现得很清楚：validateAndGetSnapshotLocations会按备份指定的 VSL 名称逐个加载，一旦发现"同一 provider 被指定了多个位置"，就会报错more than one VolumeSnapshotLocation name specified for provider %s（见 pkg/controller/backup_controller.go）。

VSL YAML 结构示例

一个最典型的 AWS VSL 定义如下（原文档中的标准示例）：

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

要点说明：

apiVersion：velero.io/v1；
metadata.namespace：通常与 Velero 安装在同一命名空间（默认velero），备份控制器只会在该命名空间内查找 VSL；
spec.provider：云厂商标识，Velero 原生支持aws、gcp、azure，其他厂商通过外部插件提供；
spec.config：provider 专属键值对，可空。

如需为同一位置单独指定凭据（不依赖全局--secret-file），可在 Spec 中追加：

spec: provider: aws config: region: us-west-2 credential: name: aws-vsl-creds key: cloud

其中credential是一个标准的SecretKeySelector，指向某 Secret 中的某个数据键。备份执行时，控制器会通过 internal/volume/snapshotlocation.go 的UpdateVolumeSnapshotLocationWithCredentialConfig将该 Secret 落盘路径写入config["credentialsFile"]再传给插件；同时出于安全考虑，该函数会主动删除用户自定义的credentialsFile配置键，防止路径穿越攻击。

参数参考

主配置参数

Key	Type	Default	Meaning
`provider`	String（Velero 原生支持`aws`、`gcp`、`azure`，其他 provider 可通过外部插件获得）	必填	实际用于存储卷快照的云厂商名称
`config`	见下文各 provider 专属配置或对应 provider 插件的文档	可选	provider 专属键值配置
`credential`	`SecretKeySelector`	可选	该 VSL 使用的凭据引用，优先级高于全局凭据

AWS

config

Key	Type	Default	Meaning
`region`	string	空	示例：`"us-east-1"`。完整区域列表参考 AWS 官方文档；若未提供，将从 AWS S3 API 查询得到

region决定快照创建在哪个区域。若省略，Velero 会尝试从 AWS 侧查询默认区域，因此只要集群节点具备相应的 IAM 权限，即使不显式写region也能工作；但显式配置仍是更可控、可复现的做法。

Azure

config

Key	Type	Default	Meaning
`apiTimeout`	metav1.Duration	`2m0s`	Azure API 请求的超时等待时间
`resourceGroup`	string	可选	卷快照的存放资源组；不填时使用集群所在的资源组

apiTimeout控制 Velero 调用 Azure 快照相关 API 的最长等待时间，格式遵循 Kubernetes 的metav1.Duration表示法（如3m、90s）；
当你的快照需要存放在与集群不同的资源组时，通过resourceGroup指定。

GCP

GCP 的 VSL无需任何 config 参数，仅声明provider: gcp即可，插件所需的项目、区域等上下文来自 GCP 凭据与目标卷本身。

注意：上述 AWS/Azure/GCP 参数表来自 v0.11.0 版本文档，属于该版本语境下的原生 provider 配置。当前仓库中具体 provider 插件的参数实现已随插件独立演进，建议以你所安装的 provider 插件版本文档为准；本指南中的 CRD 结构与 CLI 用法对当前仓库仍然成立。

用 CLI 管理 VolumeSnapshotLocation

除了直接kubectl applyYAML，Velero CLI 提供了一组专门命令（实现在 pkg/cmd/cli/snapshotlocation 包中，注册为snapshot-location子命令）。

创建：`velero snapshot-location create`

velero snapshot-location create <NAME> \ --provider <PROVIDER> \ --config <KEY1=VALUE1,KEY2=VALUE2> \ [--credential <SECRET_NAME=SECRET_KEY>] \ [--labels <K=V,...>]

创建命令支持的完整参数（见 create.go）：

Flag	说明
`--provider`	卷快照 provider 名称（如`aws`、`azure`、`gcp`），必填，源码中缺失时校验直接报错`--provider is required`
`--config`	配置键值对，如`region=us-west-2`、`apiTimeout=3m`
`--labels`	附加到 VSL 上的标签
`--credential`	该位置使用的凭据，格式`Secret名=Secret内数据键名`；只能含 1 个键值对（源码 Validate 强制约束）

示例：

velero snapshot-location create aws-default \ --provider aws \ --config region=us-west-2 velero snapshot-location create azure-default \ --provider azure \ --config apiTimeout=3m,resourceGroup=my-backup-rg \ --credential azure-vsl-creds=cloud

查看：`velero snapshot-location get`

velero snapshot-location get # 列出当前命名空间下全部 VSL velero snapshot-location get aws-default # 查看指定 VSL velero snapshot-location get -l tier=prod # 按标签选择器过滤

get命令支持按名称精确获取、按--selector/-l标签过滤，并支持-o输出格式控制（见 get.go），同时具备 VSL 名称的 shell 自动补全。

设置凭据：`velero snapshot-location set`

对已存在的 VSL 更新凭据引用：

velero snapshot-location set <NAME> --credential <SECRET_NAME=SECRET_KEY>

实现上会先Get出目标 VSL，再写入Spec.Credential并Update回集群（见 set.go），同样限制为单个键值对。

安装时自动创建：`velero install`

velero install也支持通过参数直接生成 VSL（见 pkg/cmd/cli/install/install.go）：

velero install \ --provider aws \ --plugins velero/velero-plugin-for-aws:v1.0.0 \ --bucket backups \ --secret-file ./aws-iam-creds \ --backup-location-config region=us-east-2 \ --snapshot-location-config region=us-east-2

--snapshot-location-config：格式key1=value1,key2=value2，用于生成 VSL 的config；
--use-volume-snapshots：默认开启；设为false时不自动创建快照位置，同时--snapshot-location-config必须为空（否则安装校验报错，见 install.go）。

Azure 示例：

velero install \ --provider azure \ --plugins velero/velero-plugin-for-microsoft-azure:v1.0.0 \ --bucket $BLOB_CONTAINER \ --secret-file ./credentials-velero \ --backup-location-config resourceGroup=$AZURE_BACKUP_RESOURCE_GROUP,storageAccount=$AZURE_STORAGE_ACCOUNT_ID \ --snapshot-location-config apiTimeout=<YOUR_TIMEOUT>,resourceGroup=$AZURE_BACKUP_RESOURCE_GROUP

备份时如何选择 VSL：校验与加载流程

当一次备份开始执行时，备份控制器会按以下流程处理 VSL（核心实现在 pkg/controller/backup_controller.go 的validateAndGetSnapshotLocations）：

名称加载：读取backup.Spec.VolumeSnapshotLocations（BackupAPI 中以字符串列表形式保存位置名，见 backup_types.go），逐个Get对应的 VSL；
存在性校验：某个 VSL 不存在时，报错并提示"该备份执行前必须先创建对应的 VolumeSnapshotLocation CRD"；
单 provider 唯一性校验：同一 provider 被指定了多个位置时直接报错（上文提到的more than one VolumeSnapshotLocation...）；
凭据注入：调用UpdateVolumeSnapshotLocationWithCredentialConfig，把 VSL 指定的 Secret 凭据落盘路径写入config["credentialsFile"]传给快照插件，并删除用户自定义的credentialsFile键以防止路径穿越；
按 provider 分组：最终以provider -> VolumeSnapshotLocation的映射交付给快照执行逻辑，供后续对不同厂商的卷分别打快照。

对应的测试用例可在 backup_controller_test.go 中看到：覆盖了"VSL 不存在报错""同一 provider 指定两个位置报错""合法场景下按 provider 正确分组"等典型场景。

在备份/定时备份命令中指定 VSL

创建备份或 Schedule 时，通过--volume-snapshot-locations指定要使用的 VSL 名称（可多个，但同一 provider 只能一个）：

velero backup create my-backup \ --include-namespaces default \ --volume-snapshot-locations aws-default velero schedule create daily-backup \ --schedule "0 2 * * *" \ --include-namespaces default \ --volume-snapshot-locations aws-default

该参数在 backup/create.go 中被定义为StringSlice，并支持 VSL 名称自动补全；若不指定，则使用安装时配置的默认 VSL。服务端还支持通过--default-volume-snapshot-locations（格式provider1:location-01,provider2:location-02）为各 provider 配置默认位置（见 pkg/cmd/server/config/config.go）。

常见问题与排查

备份一直卡在 New 阶段并提示 VSL 缺失：检查backup.Spec.VolumeSnapshotLocations中引用的 VSL 是否真实存在、命名空间是否正确（必须与 Velero 同一命名空间）。错误信息会直接给出缺失的 VSL 名，见上文步骤 2。
同一 provider 被指定多个位置：--volume-snapshot-locations中每个 provider 只能出现一次，若集群卷分布在多个区域，请为每个区域各建一个 VSL 并把不同区域做成不同的备份任务，而不是在同一个备份里传多个同 provider 位置。
快照凭据不符合预期：优先检查 VSL 是否配置了credential字段（它优先于全局凭据），以及velero snapshot-location set是否正确更新；另外任何用户配置的credentialsFile键都会被服务端删除，请通过credential字段注入凭据。
velero install报--snapshot-location-config must be empty：说明同时指定了--use-volume-snapshots=false和--snapshot-location-config，二者互斥。

小结

VolumeSnapshotLocation 是 Velero 卷快照能力的地基：它把"卷快照存到哪里"从备份逻辑中解耦出来，使同一套备份流程可以对接多个云厂商、多区域、多资源组的快照后端。配置 VSL 只需三件事：选好 provider、填对 config、必要时挂上专属凭据，然后通过--volume-snapshot-locations在备份时按需引用。结合本仓库的 API 类型定义、CLI 实现与备份控制器校验逻辑，你可以快速定位配置问题并设计出适合多集群、多云场景的快照存储方案。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Velero VolumeSnapshotLocation 配置指南：为 Kubernetes 备份卷快照定义云存储位置