Velero（Ark v0.8.1）backup create 命令全解析：创建备份的选项、行为与源码实现

Velero（Ark v0.8.1）backup create 命令全解析：创建备份的选项、行为与源码实现

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

导读

本文以 Velero 项目早期版本（Ark v0.8.1）官方 CLI 参考文档 ark_backup_create.md 为骨架，完整梳理ark backup create命令的语法、全部可用选项、继承选项与使用场景，并结合当前仓库的 Go 源码实现 pkg/cmd/cli/backup/create.go 与测试用例 pkg/cmd/cli/backup/create_test.go，深入解释每个参数如何被解析、校验并最终写入Backup自定义资源（CRD）。读完本文，你将能够熟练使用该命令发起按需备份、精确控制备份范围（命名空间、资源类型、集群作用域资源）、控制卷快照行为、设置标签与选择器，并理解命令底层与 Ark Server 的交互机制。

背景说明：本项目（Velero）早期名为 Heptio Ark，CLI 命令为ark，官方命名空间为heptio-ark；后续版本更名并统一为velero命令（如当前源码 pkg/cmd/cli/backup/backup.go 所示）。本文面向 v0.8.1 文档，命令与参数在语义上与现代版本一脉相承，分析源码时以当前仓库实现为准。

命令概要（Synopsis）

ark backup create用于在集群中创建一个备份请求（Backup CR），请求一旦创建，Ark Server 会立即启动备份流程。其基本语法为：

ark backup create NAME [flags]

• NAME是必填的备份名称（除非使用--from-schedule基于调度模板创建，这一用法在现代版本中提供，见 create.go 中的Args校验逻辑）；
• 备份名称必须满足 Kubernetes DNS-1123 子域名规范；
• 命令执行成功后，Ark Server 会异步完成备份，最终产物是对象存储中一份 gzip 压缩的 tar 归档文件。

从源码看，NewCreateCommand定义了Use: use + " NAME"，并通过Args函数执行两项校验（create.go 中NewCreateCommand）：

1. 最多只接受一个位置参数；
2. 若未指定--from-schedule且未提供名称，直接报错a backup name is required, unless you are creating based on a schedule；
3. 若提供了名称，则调用validation.IsDNS1123Subdomain校验其合法性，非法名称（例如Invalid_Name!）会被拒绝。

对应测试用例见 create_test.go 中的TestCreateCommand_Args，覆盖了「无名称且无 from-schedule 报错」「非法名称报错」「from-schedule 存在时可不传名称」「多个位置参数报错」等场景。

核心选项详解（Options）

v0.8.1 文档完整列出了该命令的全部选项，下表逐一给出其作用、默认值与类型：

其中optionalBool是一种「三态布尔」设计：true、false、以及「未设置」三种状态各有语义。这一点在源码中得到精确体现：CreateOptions中的SnapshotVolumes与IncludeClusterResources均为flag.OptionalBool类型（create.go 中CreateOptions定义），并通过f.NoOptDefVal = cmd.TRUE实现「只写--snapshot-volumes即等价于--snapshot-volumes=true」的快捷用法；BuildBackup中只有在该值非 nil 时才会写入BackupSpec.SnapshotVolumes/BackupSpec.IncludeClusterResources字段。

include-cluster-resources 的推断规则

根据同版本 Backup API 类型文档，includeClusterResources取值为true、false或null/unset时的行为分别是：

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

资源类型格式

--include-resources/--exclude-resources接受resource.group格式（如storageclasses.storage.k8s.io、deployments.apps）。按 Backup API 类型文档 的说明，资源既可以写完整限定名，也可以使用 Kubernetes 的快捷别名（如用po表示pods）。

继承自父命令的选项

ark backup create继承自ark backup与ark父命令，主要包括连接配置与日志控制两大类：

--alsologtostderr 同时向标准错误与文件输出日志 --kubeconfig string kubeconfig 文件路径；未设置时依次尝试环境变量 KUBECONFIG 与集群内配置 --kubecontext string 指定 kubectl context；未设置时使用当前 context --log_backtrace_at traceLocation 当日志到达 file:N 时输出堆栈（默认 :0） --log_dir string 日志输出目录（非空时写文件） --logtostderr 向标准错误而非文件输出日志 -n, --namespace string 操作命名空间（默认 "heptio-ark"） --stderrthreshold severity ≥ 该级别的日志输出到 stderr（默认 2） -v, --v Level V 级别日志的详细程度 --vmodule moduleSpec file-filtered logging 的 pattern=N 列表

关键点：

• --kubeconfig/--kubecontext决定命令如何连接 Kubernetes API Server；未显式指定时会回落到KUBECONFIG环境变量或集群内配置，这对应源码中 client/config.go 的配置解析逻辑；
• -n, --namespace指定 Ark 所在命名空间（v0.8.1 默认heptio-ark），Backup资源就创建在该命名空间下，Ark Server 也在该命名空间运行。相关说明见 namespace.md；
• 日志相关选项（--logtostderr、--v、--vmodule等）沿用了 Google glog 的经典参数体系，主要用于排查备份过程问题。

实战用法示例

结合 create.go 中NewCreateCommand的Example文本与文档选项，推荐如下高频用法：

# 1. 创建包含全部资源的备份 ark backup create backup1 # 2. 只备份 nginx 命名空间 ark backup create nginx-backup --include-namespaces nginx # 3. 排除 velero 与 default 命名空间 ark backup create backup2 --exclude-namespaces velero,default # 4. 不创建卷快照（如仅需资源清单），且只生成 YAML 预览、不提交到服务端 ark backup create backup3 --snapshot-volumes=false -o yaml # 5. 仅备份匹配标签的资源 ark backup create selective-backup --selector app=nginx # 6. 为备份对象附加标签 ark backup create labeled-backup --labels env=prod,team=platform # 7. 设置较短保留期（如 24 小时） ark backup create short-ttl-backup --ttl 24h0m0s # 8. 基于已有调度模板创建备份（现代版本能力，命令省略 NAME 时会自动生成带时间戳的名称） ark backup create --from-schedule daily-backup

关于-o/--output：文档明确说明「For create commands, display the object but do not send it to the server」，即这是一种**预演（dry-run）**能力——在真正提交前先以table、json或yaml格式查看将要创建的Backup对象内容。对应实现中，output.PrintWithFormat会先判断是否需要打印并返回（create.go 中Run方法）。

命令执行流程与源码实现

从源码可以还原ark backup create的完整执行链路（create.go）：

1. Complete：将位置参数args[0]赋给o.Name，并通过f.KubebuilderWatchClient()建立与 API Server 的 controller-runtime 客户端连接；
2. Validate：依次校验输出格式 flag、selector 与 or-selector 互斥、from-schedule非空、备份名称合法性（DNS-1123）、include/exclude 命名空间合法性、storage-location与volume-snapshot-locations指向的存储位置是否存在、backup-type取值（Full/Incremental，见validateBackupType）；
3. BuildBackup：使用 builder 模式组装*velerov1api.Backup对象。若指定了--from-schedule，则读取对应Schedule并以schedule.TimestampedName(time.Now().UTC())生成带时间戳的名称、复制其模板 spec（源码见BuildBackup，对应测试TestCreateOptions_BuildBackupFromSchedule）；否则逐项写入 include/exclude namespaces、include/exclude resources、selector、TTL、storage location、snapshot locations、快照与集群资源三态布尔等字段；
4. Run：若指定了-o先打印对象不提交；否则调用o.client.Create将BackupCR 提交到集群，随后输出Backup request "xxx" submitted successfully.，并提示可用ark backup describe/ark backup logs查看详情。

值得一提的是Validate中有一处重要的兼容性约束：旧版过滤参数（--include-resources、--exclude-resources、--include-cluster-resources）与新版过滤参数（--include-cluster-scoped-resources、--exclude-cluster-scoped-resources、--include-namespace-scoped-resources、--exclude-namespace-scoped-resources）不能混用，否则报错。oldAndNewFilterParametersUsedTogether方法实现了这一判断，相关场景在TestCreateCommand中也有覆盖（create_test.go）。

CLI 参数与 Backup API 字段的映射关系

ark backup create本质上是一个「把命令行参数翻译成BackupCR 的spec」的客户端命令。对照 Backup API 类型文档，核心映射如下：

备份创建后的状态变化记录在status字段：phase的合法取值包括New、FailedValidation、InProgress、Completed、Failed（现代版本还引入了PartiallyFailed等状态）；status.validationErrors记录校验错误；status.expiration为可被垃圾回收的时间点。备份完成后，status.volumeBackups会记录每个 PV 的快照 ID、类型、可用区与 IOPS 等信息，便于在云厂商控制台人工核对。

备份产物与验证

按同版本 输出文件格式文档，ark backup create NAME创建的备份会以NAME为子目录存入对象存储 bucket，结构如下：

rootBucket/ backup1234/ ark-backup.json backup1234.tar.gz

• ark-backup.json完整记录 Backup 资源的全部信息（含默认值落库后的结果）与status.version，相当于备份配置的历史档案；
• backup1234.tar.gz是 gzip 压缩的 tar 归档，解压后resources/下按资源类型/cluster 或 namespaces/命名空间/的目录树组织，persistentvolumes存放于cluster/子目录，而configmaps、pods、deployments等命名空间作用域资源则存放于各自的namespaces/<ns>/子目录。

这意味着执行ark backup create后，可以用ark backup get查看备份列表、用ark backup describe查看详情、用ark backup logs查看日志，并可通过对象存储确认归档产物是否落盘。

关联命令

ark backup create是ark backup子命令组的一员，该组完整命令如下（均为 v0.8.1 文档中的相对链接，已转换为仓库根目录相对路径）：

• ark — 备份与恢复 Kubernetes 集群资源的总入口
• ark backup create — 创建备份
• ark backup delete — 删除备份
• ark backup describe — 查看备份详情
• ark backup download — 下载备份文件
• ark backup get — 列出备份
• ark backup logs — 获取备份日志

日常使用中，「创建（create）→ 查看（get/describe）→ 校验（logs）」是一个完整闭环：创建命令提交Backup请求后，立即用get观察phase是否从New进入InProgress再到Completed（或Failed），用describe检查status.validationErrors与快照明细，用logs定位失败原因。

小结

ark backup create是 Velero（原 Ark）按需备份能力的入口命令：通过--include-*/--exclude-*系列选项精确划定备份范围，通过--snapshot-volumes三态布尔控制卷快照，通过--ttl控制保留期，通过-o实现提交前预演。本文从官方 CLI 参考文档出发，结合 pkg/cmd/cli/backup/create.go 与 create_test.go 还原了其参数解析、校验与对象构建逻辑，并对照 Backup API 类型文档 与 输出文件格式文档 说明了 CLI 参数与 CR 字段、存储产物的对应关系，帮助你在理解原理的基础上把每次备份都配置得精确、可控、可验证。

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