企业官网建设流程全解析

Velero 备份创建命令全解析：从ark create backup到velero backup create

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

本篇技术指南以仓库中 site/content/docs/v0.6.0/cli-reference/ark_create_backup.md 为骨架，系统讲解 Velero（v0.6.0 时代名为 Ark）创建备份的 CLI 命令：从命令语法、每一个筛选/快照/生命周期参数，到命令背后对应的BackupAPI 对象，再到现代版本velero backup create在源码 pkg/cmd/cli/backup/create.go 中的完整实现与校验逻辑。读完本文，你将能熟练使用该命令按命名空间、资源类型、标签选择器等维度精确控制备份范围，正确设置卷快照与 TTL，并理解命令参数如何映射为 Kubernetes 中的Backup自定义资源。

命令概览与历史沿革

命令层级：ark create backup

在 v0.6.0 版本中，创建备份的命令位于create子命令之下。父命令 ark create 用于“创建 Ark 资源”，其下包含三个子命令：

• ark create backup— 创建一个备份
• ark create restore— 创建一个恢复
• ark create schedule— 创建一个定时备份

而ark create backup本身又属于ark backup命令族（见 ark_backup_create.md，两者参数完全一致），最终向上汇聚到 ark 主命令。

Synopsis（命令语法）

ark create backup NAME [flags]

• NAME：备份的名称，即后续生成的Backup自定义资源（Custom Resource）的名字。备份产物将以此名称保存（见 concepts.md 中 "These ad-hoc backups are saved with the<BACKUP NAME>specified during creation" 的说明）。
• flags：下表所列的全部可选参数。

与现代版本的关系

随着项目从 Heptio Ark 演进为 VMware Velero，该命令在现代版本中演变为velero backup create NAME [flags]。从当前仓库源码 pkg/cmd/cli/backup/create.go 可以看到，NewCreateCommand中的命令定义为Use: use + " NAME"，Short描述同样是 "Create a backup"，参数语义一脉相承，且新增了大量参数（如--from-schedule、--storage-location、--wait等）。下文将同时对照两个时期的内容展开。

全部参数详解

原文档共定义了 12 个专属参数（不含继承参数），下表完整继承并逐一补充说明：

三个关键参数的语义深化

--include-cluster-resources（optionalBool 三态）：该参数在 v0.6.0 文档对应的 Backup API 类型定义 中给出了精确的三态语义：

• true：包含全部集群级资源（受 include/exclude resources 与标签选择器约束）；
• false：不包含任何集群级资源；
• 未设置（null）：仅当所有命名空间都被包含且无排除命名空间时才包含全部集群级资源；只要includedNamespaces或excludedNamespaces中指定了任何命名空间，则仅备份与所包含的命名空间级资源相关联的集群级资源——例如某个 PersistentVolumeClaim 被包含时，其关联的 PersistentVolume（集群级）也会被备份。

--snapshot-volumes（optionalBool 三态）：根据 backup.md，该设置仅对 Azure、GCE、AWS 的 PersistentVolume 生效。未设置时，只要为 Ark 配置了持久卷提供商，就会执行快照。在现代源码 create.go 中，该参数通过f.NoOptDefVal = cmd.TRUE实现“裸写--snapshot-volumes等价于--snapshot-volumes=true”的行为，与文档中optionalBool[=true]的标注完全吻合；且只有当o.SnapshotVolumes.Value != nil时才写入备份对象（见 create.go），从而保留了“未设置”的第三态。

--ttl（生存时间）：默认720h0m0s（30 天）。TTL 到期后，Ark/Velero 的垃圾回收机制会同时删除Backup资源本身与对象存储中的备份文件（见 concepts.md 中 "Expired backup deletion" 一节）。在源码中，TTL 通过flags.DurationVar(&o.TTL, "ttl", ...)绑定（create.go），最终经TTL(o.TTL)写入备份 spec（create.go）。

从父命令继承的全局参数

创建备份时还会继承 CLI 主命令的日志与连接参数，完整列表如下：

参数如何映射为 Backup API 对象

ark create backup的本质是：在集群中创建一份Backup自定义资源，随后由 Ark/Velero 服务端立即启动备份流程。v0.6.0 文档在 api-types/backup.md 中给出了完整的对象定义，CLI 参数与 spec 字段存在一一对应关系：

一个完整的 v0.6.0Backup对象示例（含 hooks 定义）可以在 site/content/docs/v0.6.0/api-types/backup.md 中查看。值得注意的是，对象创建后，服务端会维护status字段（如phase：New、FailedValidation、InProgress、Completed、Failed），该字段由系统写入，用户不应手动设置。

实战示例

以下示例完整取自现代版本源码 create.go 中的命令Example定义（命令名为velero backup create，语义与 v0.6.0 的ark create backup一致，参数名相同）：

# 创建包含所有资源的备份 velero backup create backup1 # 仅包含 nginx 命名空间 velero backup create nginx-backup --include-namespaces nginx # 排除 velero 与 default 命名空间 velero backup create backup2 --exclude-namespaces velero,default # 基于名为 daily-backup 的调度模板创建备份 velero backup create --from-schedule daily-backup # 预览一份不做卷快照的备份 YAML（不发送到服务器） velero backup create backup3 --snapshot-volumes=false -o yaml # 等待备份完成后命令才返回 velero backup create backup4 --wait

结合 v0.6.0 参数进一步组合的实战写法：

# 仅备份 default 命名空间中带 app=web 标签的 deployment 与 service，TTL 设为 7 天 ark create backup web-backup \ --include-namespaces default \ --include-resources deployments.apps,services \ --selector 'app=web' \ --ttl 168h0m0s # 全量备份但排除 storageclass，并禁止集群级资源 ark create backup app-backup \ --exclude-resources storageclasses.storage.k8s.io \ --include-cluster-resources=false # 使用 json 格式预览将提交的 Backup 对象 ark create backup preview --snapshot-volumes=false -o json

注意-o/--output的“dry-run”语义：文档明确说明 "For create commands, display the object but do not send it to the server"，因此在真正提交前可用-o yaml/-o json检查参数组合是否如预期。

源码视角：参数校验与执行流程

现代实现将整个流程拆分为Complete→Validate→Run三个阶段（见 create.go），这既是命令可用的保证，也解释了文档中诸多参数的约束来源。

名称与基本合法性校验（Args 与 Validate）

在 create.go 的Args函数中：

• 最多只允许 1 个位置参数（备份名称）；
• 若未提供--from-schedule且没有名称，报错 "a backup name is required, unless you are creating based on a schedule"；
• 备份名称必须满足 Kubernetes 的DNS1123Subdomain规范，否则拒绝创建。

Validate阶段（create.go）还额外校验：

• --selector与--or-selector不能同时使用；
• --from-schedule一旦指定必须为非空值；
• include 与 exclude 的命名空间集合必须合法（collections.ValidateNamespaceIncludesExcludes）；
• 新旧两套资源过滤参数不能混用：--include-resources/--exclude-resources/--include-cluster-resources属于旧参数，不能与--include-cluster-scoped-resources/--exclude-cluster-scoped-resources/--include-namespace-scoped-resources/--exclude-namespace-scoped-resources这组新参数同时使用（见 create.go）；
• 指定的--storage-location与--volume-snapshot-locations对应的 BackupStorageLocation / VolumeSnapshotLocation 必须真实存在于集群中。

备份对象构建（BuildBackup）

BuildBackup（create.go）使用builder.BackupBuilder将全部参数组装为velerov1api.Backup对象：命名空间包含/排除、资源包含/排除、标签选择器、TTL、存储位置、快照位置、CSI 快照超时、异步插件操作超时、数据移动器（data mover）、备份类型等。三态布尔参数（SnapshotVolumes、SnapshotMoveData、IncludeClusterResources、DefaultVolumesToFsBackup）只有在用户显式设置（Value != nil）时才写入对象，这正是文档中optionalBool[=true]三态语义的代码体现。

提交与等待（Run）

Run（create.go）的执行顺序为：

1. 若指定了-o，先按table/json/yaml打印对象并直接返回，不访问服务器；
2. 通过 client 将Backup对象创建到集群（o.client.Create），并输出Backup request "xxx" submitted successfully.；
3. 若指定了--wait/-w，则通过 SharedInformer 监听同名 Backup 对象的状态更新，直到进入Completed、Failed、FailedValidation或PartiallyFailed终态（create.go），期间可安全 Ctrl-C，备份仍会在后台继续；
4. 未指定--wait时，提示使用velero backup describe <name>或velero backup logs <name>查看详情。

这也解释了 v0.6.0 文档中为何存在--label-columns、--show-labels、-o这类“输出展示”参数——它们控制的是命令终端输出格式，而非备份内容本身。

备份命令之外的关联阅读

• Backup API 类型完整定义（v0.6.0）：含 hooks（如 pod exec 钩子）的完整 YAML 示例与 status 字段说明
• Ark/Velero 核心概念：备份、调度、恢复三大操作类型，TTL 过期删除与对象存储同步机制
• 父命令 ark create 参考：create 子命令族结构
• 现代实现源码 pkg/cmd/cli/backup/create.go：velero backup create的参数绑定、校验与执行全流程
• 现代命令族入口 pkg/cmd/cli/backup/backup.go：velero backup子命令族组织方式

小结

ark create backup（现代版本为velero backup create）是 Velero/Ark 最核心的日常操作命令。掌握其参数语义，尤其是--include-cluster-resources与--snapshot-volumes两个三态布尔参数的细微差别、--ttl对垃圾回收的影响，以及-o的 dry-run 能力，是精确控制备份范围、避免意外排除集群级资源、合理规划存储成本的关键。命令的所有参数都会在提交时被转换为Backup自定义资源的 spec 字段，并交由服务端异步执行——理解这一映射关系，也就理解了 Velero 备份体系的工作模型。

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