VeleroArkBackup API 类型完全指南字段详解、hooks 与生命周期管理【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/veleroBackup是 Velero前身 Ark中用于向服务器发起备份请求的核心 Kubernetes API 类型创建该对象后Velero 服务器会立即启动备份流程将集群中指定范围的 Kubernetes 资源与持久化卷数据捕获到对象存储。本文以仓库中 site/content/docs/v0.7.1/api-types/backup.md 文档为骨架逐字段拆解Backup对象的完整定义从apiVersion、metadata、spec到status并结合当前仓库源码pkg/apis/velero/v1/backup_types.go与现代版本文档site/content/docs/main/api-types/backup.md讲解字段的演进、默认值与底层实现原理。读完本文你将能够独立编写、校验和排查一个可运行的Backup资源。Backup API 类型的用途BackupAPI 类型作为向 VeleroArk服务器发起备份的请求载体。一旦该对象被创建Ark/Velero 服务器会立即启动备份过程无需额外触发命令。备份过程会依据spec中的包含/排除规则收集并序列化 Kubernetes API 对象依据snapshotVolumes等配置对持久化卷创建云厂商快照将对象清单 tarball 与日志上传至配置的备份存储位置BackupStorageLocation。从当前源码看Backup是一个标准 CustomResourceDefinition 资源kind 为Backup、复数形式backups并定义了短名bak以及Status、Errors、Warnings、Started、Age等附加打印列便于kubectl get backups直接观察状态。相关定义见 config/crd/v1/bases/velero.io_backups.yaml。API GroupVersion在本文档对应的 v0.7.1 版本中Backup属于 API 组ark.heptio.com/v1——这是 Velero 更名前的 Ark 时代命名heptio 为项目原公司名。演进说明依据当前仓库源码随着项目更名为 VeleroAPI 组同步演进为velero.io/v1。当前源码中Backup类型定义于 pkg/apis/velero/v1/backup_types.go并通过kubebuilder:storageversion标记为存储版本对应的 CRD 定义config/crd/v1/bases/velero.io_backups.yaml中spec.group为velero.io版本为v1。因此v0.7.1 及更早Ark 时期apiVersion: ark.heptio.com/v1现代版本VeleroapiVersion: velero.io/v1完整的 Backup 对象定义以下 YAML 是Backup对象的完整样例继承自 v0.7.1 文档其中status部分仅供理解结构用户不应手工设置任何 status 数据# Standard Kubernetes API Version declaration. Required. apiVersion: ark.heptio.com/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. In version 0.7.0 and later, can be any string. Must be the namespace of the Ark server. namespace: heptio-ark # 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: ark 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, Ark performs snapshots as long as # a persistent volume provider is configured for Ark. snapshotVolumes: null # 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: ark 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: 10000下文将按spec与status两大块逐字段展开说明并结合源码给出更完整的默认值与取值范围。spec 字段详解spec是备份的参数部分必填控制备份什么、不备份什么、如何备份。当前源码中这些字段的 Go 定义位于 pkg/apis/velero/v1/backup_types.goCRD 中的 JSON Schema 见 config/crd/v1/bases/velero.io_backups.yaml。命名空间过滤includedNamespaces / excludedNamespacesincludedNamespaces要纳入备份的命名空间数组未指定时默认包含全部命名空间。excludedNamespaces要从备份中排除的命名空间数组。两者均为可选字段。现代版本中二者支持 glob 模式*、?、[abc]其中单独的*仅用于表示空字段即全部的语义详细约定见现代版本文档 site/content/docs/main/api-types/backup.md。在源码中控制器会对命名空间的包含/排除列表进行校验例如针对持久卷保留策略PV Retention相关的命名空间与includeClusterResources组合做一致性检查见 pkg/controller/backup_controller.go 中validateBackup相关逻辑。资源过滤includedResources / excludedResourcesincludedResources要纳入备份的资源数组。资源名可以使用 Kubernetes 短名如po表示pods或全限定名如deployments.apps未指定时默认包含全部资源。excludedResources要排除的资源数组同样支持短名或全限定名。典型用法是排除storageclasses.storage.k8s.io如示例所示避免备份集群级存储类。现代演进在较新版本中资源过滤被拆分为按作用域细分的四组字段includedClusterScopedResources、excludedClusterScopedResources、includedNamespaceScopedResources、excludedNamespaceScopedResources其默认语义为集群作用域资源仅包含与所备份命名空间资源关联的部分命名空间作用域资源默认全部包含。这些字段不能与旧的include-resources/exclude-resources/include-cluster-resources过滤参数同时使用校验逻辑会直接写入validationErrors见 pkg/controller/backup_controller.go。includeClusterResources控制是否纳入集群作用域cluster-scoped资源合法值取值行为true包含所有集群作用域资源仍受 include/exclude 资源列表与 labelSelector 约束false不包含任何集群作用域资源null/未设置当且仅当包含所有命名空间且未排除任何命名空间时才包含全部集群作用域资源否则只备份与已包含的命名空间资源相关联的集群资源。例如备份中包含某 PersistentVolumeClaim 时其关联的 PersistentVolume集群作用域也会被一并备份labelSelector对象级过滤只有匹配该标签选择器的对象才会被纳入备份。示例中要求对象同时带有app: ark与component: server两个标签。现代演进新增orLabelSelectors字段可提供一组标签选择器对象只要匹配其中任意一个即可被纳入但labelSelector与orLabelSelectors二者只能二选一同时指定会触发校验错误源码中明确写入encountered labelSelector as well as orLabelSelectors in backup spec, only one can be specified见 pkg/controller/backup_controller.go。snapshotVolumes是否对卷创建快照在 v0.7.1 文档背景下该字段仅对 Azure、GCE、AWS 上的 PersistentVolume 生效合法值true、false、null/未设置未设置时只要为 Ark/Velero 配置了持久卷提供者persistent volume provider就会执行快照。现代版本中该字段语义保留类型为*bool可空布尔源码注释为是否对备份对象集合中引用的 PV 创建快照见 pkg/apis/velero/v1/backup_types.go。此外现代版本还引入了与 CSI 快照、数据移动snapshotMoveData、datamover相关的能力v0.7.1 文档中尚未包含。ttl备份在垃圾回收GC之前可保留的时长采用 Gotime.Duration可解析的字符串格式例如24h0m0s。现代演进若未指定默认值为 30 天且可通过 Velero 服务器的--default-backup-ttl启动参数修改默认值。到期后status.expiration会记录可被垃圾回收的时间点届时由 GC 控制器清理该备份及其数据。hooks备份钩子hooks用于在备份过程中的不同时机执行自定义行为。v0.7.1 阶段唯一支持的类型是通过Pod exec API在 Pod 的某个容器内执行命令。结构如下hooks.resources针对特定资源的钩子数组。name钩子名称会显示在备份日志中。includedNamespaces/excludedNamespaces钩子生效/不生效的命名空间不指定则作用于所有命名空间。includedResources/excludedResources钩子作用/排除的资源当时仅支持pods。labelSelector仅对匹配标签的对象生效。hooks已废弃DEPRECATED请改用pre。pre在执行自定义动作之前运行的钩子数组。exec钩子类型必须为exec。container执行命令的容器名不指定则使用 Pod 的第一个容器。command要执行的命令及其参数数组形式必填。onError命令执行出错时的处理策略合法值为Fail与Continue默认Fail。timeout等待命令执行完成的最大时长默认 30 秒。post在所有自定义动作与附加条目additional items处理完成之后运行的钩子数组内容同pre。从源码看现代版本的钩子结构演化为BackupHooks仅含resources数组、BackupResourceHookSpec含PreHooks/PostHooks与过滤规则与ExecHook含container、command、onError、timeout且command通过 kubebuilder 校验至少包含 1 个元素onError枚举为Continue/Fail见 pkg/apis/velero/v1/backup_types.go。status 字段详解status由 Velero 服务器写入用户不应手工设置任何数据。v0.7.1 文档中的字段expiration该备份可被垃圾回收的日期时间。phase当前阶段合法值为New、FailedValidation、InProgress、Completed、Failed。validationErrors校验过程中发现的所有错误数组。version备份格式版本当时仅支持1。volumeBackups恢复restore所需的 PersistentVolume 快照信息映射键为 PV 名称值为快照详情snapshotID云厂商快照 ID、type云厂商 API 中的卷类型、availabilityZone卷所在可用区、iops预置 IOPS可选。现代演进当前源码中BackupStatus已大幅扩展见 pkg/apis/velero/v1/backup_types.go新增了phase完整取值kubebuilder:validation:Enum声明New、Queued、ReadyToStart、FailedValidation、InProgress、WaitingForPluginOperations、WaitingForPluginOperationsPartiallyFailed、Finalizing、FinalizingPartiallyFailed、Completed、PartiallyFailed、Failed、DeletingstartTimestamp/completionTimestamp备份开始/完成时间volumeSnapshotsAttempted/volumeSnapshotsCompleted快照尝试/成功数量warnings/errors备份过程中的告警与错误计数详细日志在对象存储中的备份日志文件内failureReason导致整个备份失败的错误信息progress.totalItems/progress.itemsBackedUp备份进度尽力而为hookStatus.hooksAttempted/hookStatus.hooksFailed钩子执行统计queuePosition排队等待时在队列中的位置。从创建到完成备份的校验与执行流程创建Backup对象后其生命周期由 Velero 的 Backup 控制器驱动控制器实现见 pkg/controller/backup_controller.go。结合源码可以还原以下关键环节入队与就绪备份先进入New阶段随后进入队列Queued被调度出队后转为ReadyToStart。控制器支持并发备份数、队列重同步周期等参数见 pkg/controller/backup_controller.go 中backupResyncPeriod与NewBackupReconciler的字段设计。校验阶段控制器对spec做严格校验任何问题都会追加到status.validationErrors并使备份进入FailedValidation。从源码可见的校验点包括备份存储位置BackupStorageLocation是否存在、能否获取include/exclude 命名空间列表是否合法include/exclude 资源列表是否合法含集群作用域、命名空间作用域细分的资源列表labelSelector与orLabelSelectors是否同时出现二选一资源策略resourcePolicy是否有效新旧过滤参数include-resources等是否混用。执行阶段校验通过后进入InProgress依次完成资源收集、钩子执行、卷快照与对象清单归档若存在异步插件操作如快照数据上传会经过WaitingForPluginOperations/Finalizing等中间阶段。终态全部成功为Completed个别条目出错但整体完成则为PartiallyFailed致命错误为Failedttl到期后进入Deleting并由 GC 回收。phase的完整枚举与各阶段语义注释均可在 pkg/apis/velero/v1/backup_types.go 中查到。字段速查表路径类型/取值必填默认/行为metadata.name任意合法 K8s 对象名是—metadata.namespace字符串是必须为 Velero 服务器所在命名空间spec.includedNamespacesstring[]否不指定则包含全部命名空间spec.excludedNamespacesstring[]否排除指定命名空间spec.includedResourcesstring[]支持短名否不指定则包含全部资源spec.excludedResourcesstring[]支持短名否排除指定资源spec.includeClusterResourcestrue/false/null否null 时按关联性智能包含集群资源spec.labelSelectorLabelSelector否对象级标签过滤spec.orLabelSelectorsLabelSelector[]否任一匹配即包含与 labelSelector 互斥spec.snapshotVolumestrue/false/null否null 时只要配置了 PV 提供者即执行快照spec.ttlduration 字符串否现代版本默认 30 天可用--default-backup-ttl调整spec.hooks.resources[].pre/postexec 钩子数组否exec 必填 commandonError 默认 Failtimeout 默认 30sstatus.*见上文否由服务器写入用户勿设参考资料本文关联文档site/content/docs/v0.7.1/api-types/backup.md现代版本文档site/content/docs/main/api-types/backup.md类型定义源码pkg/apis/velero/v1/backup_types.goCRD 定义config/crd/v1/bases/velero.io_backups.yaml控制器实现pkg/controller/backup_controller.go【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考