Velero API 类型全解Backup、BackupStorageLocation 与 VolumeSnapshotLocation 的 YAML 配置实战【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读Velero 的大部分能力可以通过veleroCLI 触发但某些关键配置——尤其是备份钩子hooks——只能通过 Kubernetes 自定义资源CRD的 JSON/YAML 清单直接编写。本文以仓库中 API 类型文档目录 为骨架系统讲解Backup、BackupStorageLocation、VolumeSnapshotLocation三个 API 类型的完整字段语义、YAML 示例与各云厂商参数表并结合仓库源码 pkg/apis/velero/v1 中的类型定义说明底层实现帮助你脱离 CLI 限制直接用 YAML 精确控制 Velero 的备份行为。为什么需要直接编写 API 类型Velero 以一组velero.io/v1自定义资源CRD作为控制面核心。绝大多数日常操作都可以通过 CLI 完成但正如 api-types 目录说明 指出的这里列出的是那些只能通过 JSON/YAML 配置、而无法通过veleroCLI 完成某些功能配置的 API 类型如 hooks。也就是说这三类资源是理解 Velero 配置体系的基石Backup一次备份的完整请求包含资源过滤、卷快照、钩子、存储目标等全部语义BackupStorageLocation备份归档tarball 与日志存放的对象存储位置VolumeSnapshotLocation卷快照的存放位置。三者由仓库中的类型定义与 CRD 清单共同支撑对应的类型源码位于 pkg/apis/velero/v1/backup_types.go、pkg/apis/velero/v1/backupstoragelocation_types.go 和 pkg/apis/velero/v1/volume_snapshot_location_type.goCRD 清单则位于 config/crd/v1。一、Backup备份请求的完整定义1.1 用途与 API 版本Backup是提交给 Velero Server 的备份请求。一旦创建Velero Server 会立即启动备份流程无需额外触发。它隶属于 API 组velero.io/v1。对应源码中Backup结构体Backup struct及BackupSpec、BackupStatus定义在 backup_types.go。1.2 完整 YAML 示例含逐字段注释backup.md 给出了一个字段齐全的样例以下完整继承并整理# Standard Kubernetes API Version declaration. Required. apiVersion: velero.io/v1 # Standard Kubernetes Kind declaration. Required. kind: Backup # Standard Kubernetes metadata. Required. metadata: # Backup name. May be any valid Kubernetes object name. Required. name: a # Backup namespace. Required. Must be the namespace of the Velero server. namespace: velero # Parameters about the backup. Required. spec: # Array of namespaces to include in the backup. If unspecified, all namespaces are included. # Optional. includedNamespaces: - * # Array of namespaces to exclude from the backup. Optional. excludedNamespaces: - some-namespace # Array of resources to include in the backup. Resources may be shortcuts (e.g. po for pods) # or fully-qualified. If unspecified, all resources are included. Optional. includedResources: - * # Array of resources to exclude from the backup. Resources may be shortcuts (e.g. po for pods) # or fully-qualified. Optional. excludedResources: - storageclasses.storage.k8s.io # Whether or not to include cluster-scoped resources. Valid values are true, false, and # null/unset. If true, all cluster-scoped resources are included (subject to included/excluded # resources and the label selector). If false, no cluster-scoped resources are included. If unset, # all cluster-scoped resources are included if and only if all namespaces are included and there are # no excluded namespaces. Otherwise, if there is at least one namespace specified in either # includedNamespaces or excludedNamespaces, then the only cluster-scoped resources that are backed # up are those associated with namespace-scoped resources included in the backup. For example, if a # PersistentVolumeClaim is included in the backup, its associated PersistentVolume (which is # cluster-scoped) would also be backed up. includeClusterResources: null # Individual objects must match this label selector to be included in the backup. Optional. labelSelector: matchLabels: app: velero component: server # Whether or not to snapshot volumes. This only applies to PersistentVolumes for Azure, GCE, and # AWS. Valid values are true, false, and null/unset. If unset, Velero performs snapshots as long as # a persistent volume provider is configured for Velero. snapshotVolumes: null # Where to store the tarball and logs. storageLocation: aws-primary # The list of locations in which to store volume snapshots created for this backup. volumeSnapshotLocations: - aws-primary - gcp-primary # The amount of time before this backup is eligible for garbage collection. ttl: 24h0m0s # Actions to perform at different times during a backup. The only hook currently supported is # executing a command in a container in a pod using the pod exec API. Optional. hooks: # Array of hooks that are applicable to specific resources. Optional. resources: - # Name of the hook. Will be displayed in backup log. name: my-hook # Array of namespaces to which this hook applies. If unspecified, the hook applies to all # namespaces. Optional. includedNamespaces: - * # Array of namespaces to which this hook does not apply. Optional. excludedNamespaces: - some-namespace # Array of resources to which this hook applies. The only resource supported at this time is # pods. includedResources: - pods # Array of resources to which this hook does not apply. Optional. excludedResources: [] # This hook only applies to objects matching this label selector. Optional. labelSelector: matchLabels: app: velero component: server # An array of hooks to run before executing custom actions. Currently only exec hooks are supported. # DEPRECATED. Use pre instead. hooks: # Same content as pre below. # An array of hooks to run before executing custom actions. Currently only exec hooks are supported. pre: - # The type of hook. This must be exec. exec: # The name of the container where the command will be executed. If unspecified, the # first container in the pod will be used. Optional. container: my-container # The command to execute, specified as an array. Required. command: - /bin/uname - -a # How to handle an error executing the command. Valid values are Fail and Continue. # Defaults to Fail. Optional. onError: Fail # How long to wait for the command to finish executing. Defaults to 30 seconds. Optional. timeout: 10s # An array of hooks to run after all custom actions and additional items have been # processed. Currently only exec hooks are supported. post: # Same content as pre above. # Status about the Backup. Users should not set any data here. status: # The date and time when the Backup is eligible for garbage collection. expiration: null # The current phase. Valid values are New, FailedValidation, InProgress, Completed, Failed. phase: # An array of any validation errors encountered. validationErrors: null # The version of this Backup. The only version currently supported is 1. version: 1 # Information about PersistentVolumes needed during restores. volumeBackups: # Each key is the name of a PersistentVolume. some-pv-name: # The ID used by the cloud provider for the snapshot created for this Backup. snapshotID: snap-1234 # The type of the volume in the cloud provider API. type: io1 # The availability zone where the volume resides in the cloud provider. availabilityZone: my-zone # The amount of provisioned IOPS for the volume. Optional. iops: 100001.3 spec 字段语义要点对照源码 backup_types.go 中BackupSpec的定义可进一步确认以下语义字段说明includedNamespaces/excludedNamespaces纳入/排除的命名空间数组两者均未指定时包含全部命名空间。includedResources/excludedResources纳入/排除的资源类型数组支持po这类短名或storageclasses.storage.k8s.io这类全限定名。includeClusterResources三态布尔true/false/null。null时若全量命名空间且无排除项则包含全部集群级资源否则仅包含与被纳入的命名空间级资源关联的集群级资源如被纳入的 PVC 所关联的 PV。labelSelector对象级标签选择器只备份匹配的对象。snapshotVolumes是否对 PV 做卷快照null时只要配置了持久卷提供者就执行快照。在 v0.11.0 文档语境下仅适用于 AWS/Azure/GCE 的 PersistentVolume。storageLocation指定存储 tarball 与日志的BackupStorageLocation名称。volumeSnapshotLocations卷快照存放位置名称列表。ttl可被 GC 回收之前的保留时长Gotime.Duration可解析格式如24h0m0s。hooks备份钩子目前仅支持基于 Pod exec API 在容器内执行命令的exec钩子。从源码看BackupSpec中相关字段均标记为optional/nullable并定义了Hooks BackupHooks、StorageLocation string、VolumeSnapshotLocations []string等BackupResourceHookSpec则包含PreHooks对应 YAML 的pre与PostHooks对应 YAML 的post钩子错误处理模式由HookErrorModeFail/Continue控制这与示例中onError: Fail、timeout: 10s的取值一一对应。1.4 hooks 的正确写法示例中值得注意顶层的hooks字段即hooks数组已被标记为DEPRECATED应改用pre。当前受支持的钩子类型只有execcontainer执行命令的容器名缺省时使用 Pod 的第一个容器command要执行的命令数组必填onError命令执行出错时的处理方式合法值Fail、Continue默认Failtimeout等待命令完成的超时时间默认 30 秒。钩子的适用对象通过includedNamespaces/excludedNamespaces/includedResources/excludedResources/labelSelector组合限定当前includedResources仅支持pods。更完整的钩子行为说明可参阅 hooks.md。1.5 status 字段只读的观测面status由 Velero Server 写入用户不应设置任何数据。核心字段包括expiration备份可被垃圾回收的时间点由spec.ttl推导phase当前阶段合法值为New、FailedValidation、InProgress、Completed、FailedvalidationErrors校验失败时的错误数组version备份格式版本当前仅支持 1volumeBackups以 PV 名为键的卷备份信息映射记录snapshotID、type、availabilityZone、iops供恢复时使用。在仓库当前主线代码中BackupStatus已经演进为包含FormatVersion、StartTimestamp、CompletionTimestamp、VolumeSnapshotsAttempted/Completed、Warnings、Errors、Progress等更丰富的观测字段见 backup_types.goBackupPhase也扩展出Queued、ReadyToStart、PartiallyFailed、Deleting等更多中间状态——这说明 API 类型本身是随版本持续演进的编写 YAML 时务必以所部署版本的 CRD 为准。二、BackupStorageLocation备份归档的存储位置2.1 核心概念BackupStorageLocation以 CRD 形式在集群内描述对象存储位置Velero 将备份 tarball 与日志上传到该位置。要点如下见 backupstoragelocation.mdVelero必须至少有一个BackupStorageLocation默认名称约定为default可通过velero server的--default-backup-storage-location参数更改未显式指定存储位置的备份会保存到该默认BackupStorageLocation从 v0.10.0 起BackupStorageLocation取代了旧的Config.backupStorageProvider配置键。2.2 样例 YAMLapiVersion: velero.io/v1 kind: BackupStorageLocation metadata: name: default namespace: velero spec: provider: aws objectStorage: bucket: myBucket config: region: us-west-22.3 主配置参数KeyTypeDefaultMeaningproviderStringVelero 原生支持aws、gcp、azure其他提供方可通过外部插件接入必填实际存储备份所用云厂商的名称。objectStorageObjectStorageLocation—指定该提供方的对象存储。objectStorage/bucketString必填备份上传的目标存储桶。objectStorage/prefixString可选存储桶内用于上传备份的目录。configmap[string]string无可选传给云厂商的配置键值对参见各厂商专属配置。从源码 backupstoragelocation_types.go 看BackupStorageLocationSpec还包含Credential指定该位置专用凭据的 SecretKeySelector、Default bool标记默认位置、AccessModeReadOnly/ReadWrite与BackupSyncPeriod、ValidationFrequency等进阶字段ObjectStorageLocation除bucket、prefix外还支持caCert/caCertRef自定义 CA 证书两者不可同时设置见同文件的Validate()方法。位置的整体管理说明可参考 locations.md。2.4 AWS及 S3 兼容存储config 参数适用于 AWS S3 或其他 S3 兼容存储。KeyTypeDefaultMeaningregionstring空示例us-east-1。完整列表见 AWS 官方文档未提供时向 AWS S3 API 查询。s3ForcePathStyleboolfalse使用 Minio 等本地存储服务时设为true。s3Urlstring非 AWS 托管存储必填示例http://minio:9000。也可显式指定 AWS S3 URL主要用于 Minio 等本地存储服务。publicUrlstring空示例https://minio.mycluster.com。指定后生成下载 URL如日志时优先使用它而非s3Url主要用于本地存储服务。kmsKeyIdstring空示例502b409c-4da1-419f-a16e-eif453b3i49f或alias/KMS-Key-Alias-Name。指定 AWS KMS 密钥 ID 或别名以启用 S3 中备份的加密仅适用于 AWS S3可能需显式授予密钥使用权限。signatureVersionstring4用于 velero CLI 下载备份/获取日志的签名 URL 的签名算法版本可选1与4。通常默认版本 4 正确但 Quobyte 等部分 S3 兼容提供方仅支持版本 1。AWS 侧的完整配置流程含 IAM 权限、S3 桶与 secret 设置参见 aws-config.md仓库中awsprovider 的对象存储实现可从 internal/credentials 与插件框架代码中进一步溯源。2.5 Azure config 参数KeyTypeDefaultMeaningresourceGroupstring必填包含本备份存储位置所用存储账户的资源组名称。storageAccountstring必填本备份存储位置的存储账户名称。Azure 侧完整配置参见 azure-config.md。2.6 GCP config 参数无需任何参数。相关完整配置参见 gcp-config.md。三、VolumeSnapshotLocation卷快照的存储位置3.1 核心概念VolumeSnapshotLocation描述卷快照的存放位置见 volumesnapshotlocation.md每个VolumeSnapshotLocation描述一个provider 位置组合以 CRD 形式存在于集群中Velero每个云厂商至少需要一个VolumeSnapshotLocationVelero 可为多个 provider 配置卷快照也允许同一 provider 下配置多个位置但备份时每个 provider 只能选择一个位置spec.volumeSnapshotLocations与备份中的volumeSnapshotLocations字段对应。3.2 样例 YAMLapiVersion: velero.io/v1 kind: VolumeSnapshotLocation metadata: name: aws-default namespace: velero spec: provider: aws config: region: us-west-23.3 主配置参数KeyTypeDefaultMeaningproviderStringVelero 原生支持aws、gcp、azure其他提供方可通过外部插件接入必填存储卷快照所用云厂商名称。config见各厂商专属配置—传给云厂商的配置键值对。源码 volume_snapshot_location_type.go 中VolumeSnapshotLocationSpec除provider、config外同样支持Credential字段其status.phase为Available/Unavailable可观测位置是否可用。3.4 AWS config 参数KeyTypeDefaultMeaningregionstring空示例us-east-1。完整列表见 AWS 官方文档未提供时向 AWS S3 API 查询。3.5 Azure config 参数KeyTypeDefaultMeaningapiTimeoutmetav1.Duration2m0s等待 Azure API 请求完成的超时时间。resourceGroupstring可选卷快照的存放资源组名称与集群所在资源组不同时指定。3.6 GCP config 参数无需任何参数。四、三个 API 类型如何协同工作一次典型的 YAML 驱动备份流程中三者按如下方式协作提前创建BackupStorageLocation如default与VolumeSnapshotLocation如aws-default二者均位于 Velero 所在命名空间创建Backup对象通过spec.storageLocation指定归档存储位置通过spec.volumeSnapshotLocations指定卷快照位置若不指定则回落到--default-backup-storage-location指定的默认位置Velero Server 立即开始备份备份 tarball 与日志写入对象存储位置卷快照由云厂商在快照位置创建备份对象的status.phase从New依次流转到InProgress、Completed/Failedstatus.volumeBackups记录每个 PV 的快照元数据供恢复使用。在仓库当前主线中三者的 CRD 清单集中在 config/crd/v1控制器实现分别位于 pkg/controller/backup_controller.go、pkg/controller/backup_storage_location_controller.go 等文件中可结合阅读以理解各字段在运行时如何被消费。五、实战建议与版本注意钩子必须走 YAMLhooks目前是 CLI 无法覆盖的配置面只能通过Backup对象的 YAML 提交编写时请使用pre/post而非已废弃的hooks字段。默认位置命名若希望省略spec.storageLocation请确保存在名为default或--default-backup-storage-location指定的名称的BackupStorageLocation。对象存储 vs 卷快照对象存储tarball/日志与卷快照是两套独立的位置体系分别由BackupStorageLocation与VolumeSnapshotLocation管理不要混用。版本演进本文示例基于仓库中 v0.11.0 版本文档如snapshotVolumes仅适用于 AWS/Azure/GCE 的 PV而仓库主线代码中的BackupSpec已新增orderedResources、resourcePolicy、csiSnapshotTimeout、itemOperationTimeout、snapshotMoveData、uploaderConfig、backupType等字段。实际使用时请以所部署版本的 CRD 清单 与velero describe backup输出为准避免因字段差异导致校验失败。备份状态观测创建后可用velero backup describe或直接kubectl get backup -n velero -o yaml查看status中的phase与validationErrors快速定位配置问题。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考