Velero Backup API 类型详解：从 Backup CRD 配置到备份生命周期控制

Velero Backup API 类型详解从 Backup CRD 配置到备份生命周期控制【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文以 Velero 官方 API 类型文档site/content/docs/v1.1.0/api-types/backup.md为骨架系统讲解Backup这一核心自定义资源CRD的完整字段语义、YAML 编写规范、生命周期阶段流转并结合当前仓库源码pkg/apis/velero/v1/backup_types.go、pkg/controller/backup_controller.go等说明各字段在控制器中的实际处理逻辑。读完本文你将能独立编写一个可运行的 Velero 备份清单理解每个字段的默认值与边界行为并能在出问题时通过status字段快速定位原因。Backup 是什么一次备份的“请求单”在 Velero 中BackupAPI 类型是用户向 Velero Server 发出的“执行一次备份”的请求。它属于 API 组版本velero.io/v1一旦创建Velero Server 会立即启动备份流程无需再调用任何其他命令。从 Backup 类型定义 可以看出它遵循标准 Kubernetes 对象结构由metadata、spec、status三部分组成spec备份的参数清单——备份哪些命名空间、哪些资源、是否做卷快照、存到哪里、保留多久、执行哪些钩子status由 Velero Server 回写的执行结果——当前阶段、开始/完成时间、快照数量、错误与告警计数用户不应手动设置任何status字段。完整 Backup 对象示例字段逐条注释# 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. Must be the namespace of the Velero server. Required. 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. If not specified, # a default value of 30 days will be used. The default can be configured on the velero server # by passing the flag --default-backup-ttl. 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. 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 version of this Backup. The only version currently supported is 1. version: 1 # The date and time when the Backup is eligible for garbage collection. expiration: null # The current phase. Valid values are New, FailedValidation, InProgress, Completed, PartiallyFailed, Failed. phase: # An array of any validation errors encountered. validationErrors: null # Date/time when the backup started being processed. startTimestamp: 2019-04-29T15:58:43Z # Date/time when the backup finished being processed. completionTimestamp: 2019-04-29T15:58:56Z # Number of volume snapshots that Velero tried to create for this backup. volumeSnapshotsAttempted: 2 # Number of volume snapshots that Velero successfully created for this backup. volumeSnapshotsCompleted: 1 # Number of warnings that were logged by the backup. warnings: 2 # Number of errors that were logged by the backup. errors: 0spec 核心字段逐项精讲选择“备份什么”命名空间与资源过滤includedNamespaces/excludedNamespaces按命名空间做 include/exclude*表示全部。两者都留空时等价于includedNamespaces: [*]。源码在 prepareBackupRequest 中还会把打了velero.io/exclude-from-backuptrue标签的命名空间自动并入excludedNamespaces该标签常量定义见 labels_annotations.go因此无需在清单里手工重复排除。includedResources/excludedResources按资源类型过滤资源名可写简称如po也可写全限定名如persistentvolumes*表示全部。includeClusterResources三态布尔true/false/ 未设置。这是最容易踩坑的字段true所有集群级资源都纳入仍受 include/exclude 资源与 labelSelector 约束false不备份任何集群级资源未设置当全部命名空间都被包含且没有排除命名空间时备份所有集群级资源否则只备份“与本次备份中包含的命名空间级资源关联的”集群级资源——典型例子是 PVC 被包含时其关联的集群级 PV 也会被一并备份。labelSelector对象级过滤仅备份匹配该标签选择器的对象。当前版本的类型定义中还额外提供了orLabelSelectors多个选择器按 OR 连接且它与labelSelector互斥详见 backup_types.go。从 v1.1.0 类型定义看资源过滤字段已细化为集群级与命名空间级两组includedClusterScopedResources、excludedClusterScopedResources、includedNamespaceScopedResources、excludedNamespaceScopedResources控制器会调用 modifyResourceIncludeExclude 对它们做合法性校验与自动排除合并例如自动排除与备份流程自身相关的资源具体以你所使用的 Velero 版本为准。卷快照snapshotVolumes 与存储位置snapshotVolumes三态布尔。true表示对备份对象集合中引用的 PV 做云厂商快照false不做未设置时只要 Velero 配置了持久卷快照提供方Azure/GCE/AWS 等原生快照或 CSI 快照插件就执行快照。当前版本还支持通过defaultVolumesToFsBackup开启文件系统级备份Pod 卷数据备份defaultVolumesToRestic已被标记为废弃并自动映射到前者见 backup_types.go 与 prepareBackupRequest。storageLocation指定本次备份的 tarball 与日志存储到哪个BackupStorageLocationBSL。留空时控制器会优先使用带spec.default: true标记的 BSL其次回退到 server 启动参数--default-backup-storage-location见 backup_controller.go。确定后备份对象会被打上velero.io/storage-locationname标签便于后续筛选标签键定义于 labels_annotations.go。volumeSnapshotLocations卷快照要存放的VolumeSnapshotLocationVSL列表每个云厂商至多一个。保留策略ttl 与默认值注入ttl指定备份在多久之后进入“可被垃圾回收”的状态格式为time.Duration可解析字符串如24h0m0s。不设置时默认 30 天Server 端可用velero server --default-backup-ttl覆盖默认值该参数的默认定义见 config.go 与 server 参数注册。控制器在 prepareBackupRequest 中的处理逻辑是当spec.ttl为 0 时注入默认 TTL随后立即按“当前时间 TTL”计算出status.expirationbackup_controller.go到期后由 GC 控制器回收备份对象及其存储数据。其他几个时间类字段也有同样的“为 0 则注入默认值”逻辑csiSnapshotTimeout默认 10 分钟等待 CSI 快照转为 ReadyToUse、itemOperationTimeout默认 4 小时等待异步 BackupItemAction 操作见 backup_controller.go。备份钩子hookshooks用于在备份过程中对特定资源执行自定义动作目前唯一支持的类型是通过 pod exec API 在 Pod 容器内执行命令其类型定义见 backup_types.gohooks.resources一组按命名空间 / 资源 / 标签选择器圈定作用范围的钩子规则规则字段includedNamespaces、excludedNamespaces、includedResources、excludedResources、labelSelector与备份级别的过滤字段语义一致。pre在“把对象写入备份归档之前”、且在所有自定义 action 的附加项处理之前执行。post在所有自定义 action 与附加项处理完之后执行。exec钩子字段container命令执行的容器名缺省用 Pod 第一个容器command命令数组必填且 schema 校验要求至少 1 个元素kubebuilder:validation:MinItems1onError命令执行出错时的行为合法值为Fail与Continue默认Fail枚举约束见 backup_types.go。执行器在 item_hook_handler.go 中按该模式决定是中止后续钩子还是记录后继续timeout命令最长等待时间默认 30 秒。钩子处理的实际执行位于 item_hook_handler.go它同时支持通过 Pod 注解如hook.backup.velero.io/command、hook.backup.velero.io/on-error、hook.backup.velero.io/timeout声明与 Backup 清单声明两种方式。status 字段与备份生命周期status全部由 Velero Server 写入用户只需读取。其完整字段在 BackupStatus 中定义本文档示例中的核心字段语义如下version备份格式主版本号当前仅支持 1当前源码已引入formatVersion完整的主.次.补丁版本如1.1.0常量见 backup.goversion标记为废弃。expiration可被垃圾回收的时间点。phase备份当前所处阶段。validationErrors校验错误数组——凡是非空备份不会真正执行。startTimestamp/completionTimestamp开始与完成时间即使失败也会记录完成时间。volumeSnapshotsAttempted/volumeSnapshotsCompleted尝试创建与成功创建的卷快照数量两者不一致说明有快照失败。warnings/errors备份过程中记录的告警与错误条数明细在对象存储中的备份日志文件里。phase的合法值在类型定义中通过 kubebuilder 枚举约束限定backup_types.go。除文档示例中提到的New、FailedValidation、InProgress、Completed、PartiallyFailed、Failed之外当前源码还包含Queued、ReadyToStart、WaitingForPluginOperations、Finalizing、Deleting等阶段用于表达异步插件操作上传数据、最终收尾与删除进行中等中间状态。备份控制器 backup_controller.go 是这套状态机的驱动者其关键流转如下备份创建后处于New阶段入队等待处理Queued调谐时先通过 prepareBackupRequest 注入默认值并校验存储位置、快照位置、资源列表等若存在validationErrors置为FailedValidation并终止否则置为InProgress并记录startTimestampbackup_controller.go执行真正备份逻辑runBackup结束时收敛到终态Completed全部成功、PartiallyFailed部分对象出错但整体跑完、Failed发生阻止完成的错误见 backup_controller.go。备份执行成功后会把集群对象与卷数据打包写入对象存储当前实现格式版本为1.1.0见 writeBackupVersion并通过status.progresstotalItems/itemsBackedUp汇报进度。命令行创建备份字段到 Flag 的映射Backup清单通常由velero backup create命令生成各 flag 与 spec 字段一一对应定义见 create.goCLI Flag对应 spec 字段说明--include-namespacesincludedNamespaces默认*可用*表示全部--exclude-namespacesexcludedNamespaces排除的命名空间--include-resourcesincludedResources格式如storageclasses.storage.k8s.io*表示全部--exclude-resourcesexcludedResources排除的资源类型--include-cluster-scoped-resources/--exclude-cluster-scoped-resourcesincludedClusterScopedResources/excludedClusterScopedResources集群级资源过滤--include-namespace-scoped-resources/--exclude-namespace-scoped-resourcesincludedNamespaceScopedResources/excludedNamespaceScopedResources命名空间级资源过滤--labels/--annotationsmetadata.labels/metadata.annotations给备份对象打标签/注解--ttlttl默认 720h30 天--storage-locationstorageLocation不指定时用默认 BSL--volume-snapshot-locationsvolumeSnapshotLocations每提供方至多一个--or-selectororLabelSelectors多个选择器 OR 连接--ordered-resourcesorderedResources控制同 Kind 内对象的备份顺序--csi-snapshot-timeoutcsiSnapshotTimeout默认 10 分钟--item-operation-timeoutitemOperationTimeout默认 4 小时--snapshot-volumessnapshotVolumes是否做卷快照--backup-typebackupTypeFull或Incremental--wait/-w—等待备份完成并展示进度典型用法# 备份全部命名空间与全部资源TTL 3 天等待完成 velero backup create full-backup --include-namespaces * --include-resources * --ttl 72h --wait # 只备份指定命名空间并排除部分资源类型 velero backup create ns-backup \ --include-namespaces app-prod \ --exclude-resources events,storageclasses.storage.k8s.io \ --snapshot-volumes true # 从既有 Schedule 的模板创建备份不能与其他过滤参数混用 velero backup create --from-schedule daily-backup小结BackupAPI 是 Velero 数据保护体系中“输入侧”的唯一入口它用一份标准的 Kubernetes 清单表达“何时备份、备份什么、备份到哪、留多久、要不要做额外动作”的全部意图再由备份控制器与各插件按velero.io/v1约定的语义逐步执行并把结果写回status。理解本文的字段语义与状态机流转是编写可靠备份策略、排查备份失败优先查看validationErrors与phase以及理解调度器Schedule如何生成备份的基础。想进一步查看当前仓库中的类型与实现可继续阅读 backup_types.go、backup_controller.go 与 backup.go以及 API 类型目录下的其余文档site/content/docs/v1.1.0/api-types/。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考