Velero 备份查看命令完全指南：ark get backups 用法、参数与实现原理-平芜编程栈

Velero 备份查看命令完全指南：ark get backups 用法、参数与实现原理

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

导读

ark get backups是 Velero（v0.6.0 时代仍以 Heptio Ark 命名）提供的核心查询命令，用于以表格、JSON 或 YAML 形式列出集群中的 Backup 资源。本指南以 v0.6.0 的 CLI 参考文档为主体，结合当前仓库源码，完整讲解该命令的语法、全部参数、输出列语义、过滤器用法以及底层实现与测试验证，帮助你快速掌握备份列表的查看与筛选技巧。

命令概览：从`ark get backups`到`ark backup get`

在 Velero v0.6.0 中，CLI 支持两种等价的资源查看语法：

ark get backups [flags] ark backup get [flags]

根据 ark.md 的说明，这一设计与 kubectl 的模型保持一致，两种写法执行相同的操作。在当前仓库源码中，ark get命令通过 pkg/cmd/cli/get/get.go 聚合了 backups、schedules、restores、backup-locations、snapshot-locations、plugins 六类资源的 get 子命令，其中 backups 子命令即backup.NewGetCommand(f, "backups")，同时注册了backup别名：

backupCommand := backup.NewGetCommand(f, "backups") backupCommand.Aliases = []string{"backup"}

其余同类命令还包括ark get schedules、ark get restores、ark get backup-locations、ark get snapshot-locations与ark get plugins，可参见 ark_get.md。

命令语法与 Synopsis

ark get backups [flags]

backups为固定资源名，命令本身不接受位置参数来指定单个备份名称；
查看单个备份的详细信息应使用ark describe backup <name>或ark backup describe <name>（见 ark_backup_describe.md）；
查看全部备份的状态汇总，ark get backups是首选的入口。

在源码层面，该命令的创建逻辑位于 pkg/cmd/cli/backup/get.go：通过client.Factory获取 controller-runtime 客户端，再根据是否传入位置参数决定执行List（列出）或Get（按名称查询）操作，最终调用output.PrintWithFormat按指定格式输出。get命令默认支持名称补全（ValidArgsFunction注册了cli.CompleteBackupNames）。

参数详解

`ark get backups`专属参数

参数	简写	类型	默认值	说明
`--help`	`-h`	bool	—	显示 backups 命令的帮助信息
`--label-columns`	—	stringArray	—	逗号分隔的标签列表，将指定标签作为独立列展示；标签名区分大小写，可多次使用（如`-L label1 -L label2`）
`--output`	`-o`	string	`table`	输出格式，有效值为`table`、`json`、`yaml`
`--selector`	`-l`	string	—	标签选择器，仅显示匹配该选择器的备份
`--show-labels`	—	bool	`false`	在表格最后一列展示标签

以上参数中，--output、--label-columns、--show-labels由输出模块统一注册。见 pkg/cmd/util/output/output.go：

flags.StringP("output", "o", "table", "Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command.") labelColumns := flag.NewStringArray() flags.VarP(&labelColumns, "label-columns", "L", "Accepts a comma separated list of labels that are going to be presented as columns. Names are case-sensitive. You can also use multiple flag options like -L label1 -L label2...") flags.Bool("show-labels", false, "Show labels in the last column")

而--selector直接绑定到metav1.ListOptions.LabelSelector（见 pkg/cmd/cli/backup/get.go）：

c.Flags().StringVarP(&listOptions.LabelSelector, "selector", "l", listOptions.LabelSelector, "Only show items matching this label selector")

注意：文档中--label-columns的短参数未标出，但在当前源码中其短参数为-L，支持-L label1 -L label2的多次传参方式。

继承自父命令的参数

ark get backups还继承了一组父命令的全局参数（定义于ark根命令，见 ark.md）：

参数	类型	默认值	说明
`--alsologtostderr`	bool	—	同时将日志写入标准错误与日志文件
`--kubeconfig`	string	—	指定与 Kubernetes apiserver 通信所用的 kubeconfig 路径；未设置时依次尝试环境变量`KUBECONFIG`与集群内配置
`--log_backtrace_at`	string	`:0`	当日志命中`file:N`时输出堆栈跟踪
`--log_dir`	string	—	非空时指定日志文件输出目录
`--logtostderr`	bool	—	将日志写入标准错误而非日志文件
`--stderrthreshold`	severity	`2`	达到或超过该阈值的日志输出到 stderr
`-v, --v`	Level	—	V 日志的详细级别
`--vmodule`	moduleSpec	—	以`pattern=N`逗号分隔列表实现按文件过滤的日志级别

输出格式：`--output`的三种取值

--output默认值为table，可选json与yaml。在源码中，输出格式的合法性由validateOutputFlag校验，非法值会直接报错（见 pkg/cmd/util/output/output.go）：

switch output { case "", "json", "yaml": case "table": if cmd.Name() == "install" { return errors.New("'table' format is not supported with 'install' command") } default: return errors.Errorf("invalid output format %q - valid values are 'table', 'json', and 'yaml'", output) }

PrintWithFormat依据格式分发：table走printTable，json/yaml走printEncoded。一个值得注意的细节是：当列表只有一个对象时，json/yaml输出会退化为单个对象而不是对象数组（见 output.go 中meta.ExtractList与长度判断逻辑）。

表格输出列说明

表格模式由 pkg/cmd/util/output/backup_printer.go 中的backupColumns定义，ark get backups的表格将展示以下列：

列名	语义
`Name`	备份名称（`Type: string, Format: name`，支持终端装饰高亮）
`Status`	备份阶段（`New`、`InProgress`、`Completed`、`PartiallyFailed`、`Failed`、`Deleting`等；阶段为空时显示`New`，正在删除时显示`Deleting`）
`Errors`	错误计数（`backup.Status.Errors`）
`Warnings`	警告计数（`backup.Status.Warnings`）
`Created`	开始时间（`backup.Status.StartTimestamp`，未设置时显示`n/a`）
`Expires`	过期时间：优先取`backup.Status.Expiration`；若为空且 TTL 大于 0、备份已开始，则由`StartTimestamp + TTL`推算（见 backup_printer.go）
`Storage Location`	备份存储位置（`backup.Spec.StorageLocation`）
`Queue Position`	排队位置（`backup.Status.QueuePosition`）
`Selector`	备份的标签选择器（`backup.Spec.LabelSelector`）

排序规则

printBackupList调用sortBackupsByPrefixAndTimestamp进行排序（见 backup_printer.go）：

默认按名称字母序排列；
若名称带有-[0-9]{14}形式的 14 位时间戳后缀（典型于 schedule 自动生成的备份），则同一前缀分组内按后缀降序，即同一调度下的最新备份排在最前；
前缀不同的备份仍按字母序排列。

过滤器与标签列：`--selector`、`--label-columns`、`--show-labels`

--selector（-l）：按标签选择器过滤。源码中将该值解析为labels.Parse(listOptions.LabelSelector)，并作为 controller-runtimeListOptions.LabelSelector传给kbClient.List（见 get.go）。可组合使用-l "env=prod"、-l "env in (prod,staging)"、-l "app=web,backup=true"等 Kubernetes 标签选择器语法。
--label-columns（-L）：将指定标签渲染为表格的额外列，标签名区分大小写，可传逗号分隔列表，也可多次使用-L。
--show-labels：在表格最后追加一列展示对象全部标签（kubectl get同款交互）。

三者在输出端通过printers.NewTablePrinter的PrintOptions{ShowLabels, ColumnLabels}生效（见 output.go）。

实战示例

# 1. 以默认表格列出当前命名空间下全部备份 ark get backups # 2. 以 JSON 格式输出全部备份（便于脚本解析） ark get backups -o json # 3. 以 YAML 格式输出全部备份 ark get backups -o yaml # 4. 只显示标签匹配 app=web 的备份 ark get backups -l app=web # 5. 组合选择器：env 属于 (prod,staging) 且 backup=true ark get backups -l "env in (prod,staging),backup=true" # 6. 将 app 与 team 标签渲染为独立列 ark get backups --label-columns app,team # 或等价的多次传参写法 ark get backups -L app -L team # 7. 在最后一列展示全部标签 ark get backups --show-labels # 8. 使用别名形式（等价命令） ark backup get

底层调用链与测试验证

ark get backups的完整调用链可概括为：

ark → ark get（get.NewCommand，聚合子命令） → backups（backup.NewGetCommand，注册 alias "backup"） → f.KubebuilderClient() 获取客户端 → kbClient.List / kbClient.Get 查询 Backup/BackupList → output.ValidateFlags + output.PrintWithFormat → printTable（table 格式）或 printEncoded（json/yaml 格式）

相关测试位于 pkg/cmd/cli/backup/get_test.go：测试用 fake controller-runtime client 预置了b1、b2、b3三个带abc=abc标签的备份，分别验证了「按名称列表查询」与「-l abc=abc标签过滤」两条路径的表格输出行数，与文档描述的参数行为一一对应。输出列与排序行为另有 pkg/cmd/util/output/backup_printer_test.go 覆盖。

Velero 备份查看命令完全指南：ark get backups 用法、参数与实现原理