企业官网建设流程全解析

Velerobackup get命令完全指南：查看 Kubernetes 备份列表与状态

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

本文基于仓库中 v0.8.0 时代的命令行参考文档（ark_backup_get.md）展开，结合当前 Velero 源码实现进行深度解读。你将从本文掌握velero backup get的完整用法：如何列出全部备份、按标签筛选、按名称精确查询、切换 table/json/yaml 输出格式，以及如何读懂每一列字段和备份阶段状态的真实含义，从而在日常备份管理中快速定位问题。

一、命令概述：从ark backup get到velero backup get

原文档记录的是 Velero 前身Ark时代的命令ark backup get（文档默认命名空间为heptio-ark）。Velero 项目在更名后，命令体系从ark迁移为velero，功能完全对应保留。因此，本文所有示例均以当前仓库的实际命令velero backup get为准，二者在用法上等价。

从当前仓库根命令注册代码（pkg/cmd/velero/velero.go）可以看到：

c.AddCommand( backup.NewCommand(f), ... )

而backup子命令组（pkg/cmd/cli/backup/backup.go）下挂载了create、get、logs、describe、download、delete六个子命令：

c.AddCommand( NewCreateCommand(f, "create"), NewGetCommand(f, "get"), NewLogsCommand(f), NewDescribeCommand(f, "describe"), NewDownloadCommand(f), NewDeleteCommand(f, "delete"), )

也就是说，get是backup命令族中负责查询与展示的核心子命令。

二、命令语法与快速上手

原文档给出的 Synopsis 为：

ark backup get [flags]

对应到当前版本即：

velero backup get [flags]

原文档仅支持[flags]无参形式（即列出全部备份）。而在当前仓库的实现中（pkg/cmd/cli/backup/get.go），命令还支持传入一个或多个备份名称来精确查询指定备份，这是源码层面的增强：

backups := new(api.BackupList) if len(args) > 0 { for _, name := range args { backup := new(api.Backup) err := kbClient.Get(context.TODO(), kbclient.ObjectKey{Namespace: f.Namespace(), Name: name}, backup) cmd.CheckError(err) backups.Items = append(backups.Items, *backup) } }

最常用示例

# 列出当前命名空间下所有备份（表格形式） velero backup get # 列出指定名称的备份 velero backup get my-backup-20260916 # 同时查看多个指定备份 velero backup get backup-a backup-b backup-c # 以 JSON 格式输出（便于脚本解析） velero backup get -o json # 以 YAML 格式输出 velero backup get -o yaml # 按标签选择器过滤 velero backup get -l app=nginx # 指定 kubeconfig 与命名空间 velero backup get --kubeconfig /path/to/kubeconfig -n velero

注意：默认查询命名空间为velero（源码常量见 pkg/install/resources.go 的DefaultVeleroNamespace = "velero"）；而 v0.8.0 时代 Ark 的默认命名空间为heptio-ark。如果你的集群是从旧版升级而来，备份 CRD 仍可能存在于旧命名空间中，查询时需用-n显式指定。

三、命令选项详解（继承原文档全部参数）

原文档列出了 5 个get专属选项，整理如下：

这些选项在当前源码中有完整对应。其中-o、--label-columns（短旗标为-L）、--show-labels三个选项由统一的输出参数绑定函数注册（pkg/cmd/util/output/output.go#L45-L50）：

func BindFlags(flags *pflag.FlagSet) { flags.StringP("output", "o", "table", "Output display format. ... Valid formats are 'table', 'json', and 'yaml'. ...") labelColumns := flag.NewStringArray() flags.VarP(&labelColumns, "label-columns", "L", "Accepts a comma separated list of labels that are going to be presented as columns. ...") flags.Bool("show-labels", false, "Show labels in the last column") }

而-l, --selector则在 get 命令内部单独绑定（pkg/cmd/cli/backup/get.go#L71）：

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

选项组合实战

# 只显示 app=nginx 的备份 velero backup get -l app=nginx # 同时显示多个标签列（等价写法） velero backup get --label-columns app,env velero backup get -L app -L env # 在表格最后一列展示全部标签 velero backup get --show-labels # 组合：按标签过滤 + 增加标签列 + JSON 输出 velero backup get -l app=nginx --label-columns env -o json

四、继承自父命令的全局选项

原文档同时列出了从父命令继承的 10 个全局选项，它们控制 Velero CLI 与 Kubernetes API Server 的连接方式及日志行为：

这些 klog 日志选项在当前根命令中被统一挂载（pkg/cmd/velero/velero.go#L133-L140）：

klog.InitFlags(flag.CommandLine) ... c.PersistentFlags().AddGoFlagSet(flag.CommandLine)

连接参数实战

# 使用特定 kubeconfig 和 context 查询 velero backup get --kubeconfig ~/.kube/prod-config --kubecontext prod # 查看调试日志 velero backup get -v 4 # 指定备份所在命名空间（从 heptio-ark 升级而来的集群） velero backup get -n heptio-ark

五、表格输出列含义与备份阶段状态

当使用默认的table格式时，输出由 backup_printer.go 中定义的 9 列构成：

backupColumns = []metav1.TableColumnDefinition{ {Name: "Name", Type: "string", Format: "name"}, {Name: "Status"}, {Name: "Errors"}, {Name: "Warnings"}, {Name: "Created"}, {Name: "Expires"}, {Name: "Storage Location"}, {Name: "Queue Position"}, {Name: "Selector"}, }

各列含义如下：

备份阶段（BackupPhase）状态对照表

Status列的取值定义在 pkg/apis/velero/v1/backup_types.go#L301-L365：

过期时间的计算逻辑

在 backup_printer.go 中，Expires列的计算规则是：优先取Status.Expiration；若未设置，则在备份已开始（StartTimestamp非空）且设置了 TTL 时，用StartTimestamp + TTL推算。这样避免了停滞在New阶段的备份被错误显示为已过期（对应 issue #3555 的修复）。

输出示例

NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION QUEUE POSITION SELECTOR nginx-backup-001 Completed 0 0 2026-09-16T02:30:00Z 24h default (empty) app=nginx nginx-backup-002 InProgress 0 0 2026-09-16T03:00:00Z n/a default app=nginx

六、输出格式详解：table / json / yaml

-o, --output支持三种格式，默认table。其校验与分发逻辑位于 pkg/cmd/util/output/output.go：

func validateOutputFlag(cmd *cobra.Command) error { output := GetOutputFlagValue(cmd) 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) } return nil }

• table：人类可读的表格，是默认格式，便于日常巡检；
• json / yaml：将备份对象的完整定义序列化输出（通过encode.Encode），适合接入脚本与自动化工具进行解析。当查询结果为列表且列表中仅有一个条目时，会直接输出该单个对象的 JSON/YAML 而非数组，更便于jq等工具处理（见 output.go#L129-L149）。

# 用 jq 提取第一个备份的名称与状态 velero backup get -o json | jq '.items[0] | {name: .metadata.name, phase: .status.phase}'

此外，table格式通过NewPrinter组装列定义与行数据（output.go#L151-L237），并应用--show-labels与--label-columns的列选项。

七、标签筛选与标签列：从查询到展示的完整链路

-l, --selector：按标签过滤备份

get 命令将--selector的值放入metav1.ListOptions.LabelSelector，在执行列表查询时先用labels.Parse解析为合法的标签选择器，再传给List调用（pkg/cmd/cli/backup/get.go#L55-L63）：

parsedSelector, err := labels.Parse(listOptions.LabelSelector) cmd.CheckError(err) err = kbClient.List(context.TODO(), backups, &kbclient.ListOptions{ LabelSelector: parsedSelector, Namespace: f.Namespace(), })

支持标准 Kubernetes 标签选择器语法，例如：

# 精确匹配 velero backup get -l app=nginx # 集合匹配（in / notin） velero backup get -l 'app in (nginx,redis)' # 存在性匹配 velero backup get -l backup-type # 排除特定标签 velero backup get -l 'env!=prod'

--label-columns/--show-labels：将标签变成列

这两个选项作用于表格输出层：--label-columns（短旗标-L）接受逗号分隔的标签键列表（可多次指定），将对应标签值渲染为额外列；--show-labels则在最后一列展示该对象的全部标签。二者最终传入 Kubernetes 表格打印器（output.go#L241-L250）：

func NewPrinter(cmd *cobra.Command) (printers.ResourcePrinter, error) { options := printers.PrintOptions{ ShowLabels: GetShowLabelsValue(cmd), ColumnLabels: GetLabelColumnsValues(cmd), } printer := printers.NewTablePrinter(options) return printer, nil }

八、源码视角：get 命令的执行流程

综合 pkg/cmd/cli/backup/get.go 的完整实现，velero backup get的执行流程如下：

1. 校验输出标志：调用output.ValidateFlags(c)，非法输出格式直接报错退出；
2. 建立客户端：通过f.KubebuilderClient()创建 controller-runtime 风格的客户端（kbClient）；
3. 按参数分支：
   • 若带有备份名称参数（args），逐个按namespace/name精确 Get，并聚合到BackupList；
   • 否则解析--selector后，在指定命名空间执行 List 查询；
4. 排序整理：列表模式下，backup_printer.go#L64-L82 的sortBackupsByPrefixAndTimestamp会先按名称字典序排序；对于名称以-14位时间戳结尾（即来自同一 Schedule 的定时备份）的条目组，则按时间戳倒序（新的在前）排列，方便快速查看最新备份；
5. 格式化输出：根据-o选择 table 或 json/yaml 渲染，最终写入 stdout。

命令还注册了备份名称的 shell 补全函数cli.CompleteBackupNames(f)（get.go#L70），在支持 cobra 补全的 shell 中按 Tab 可自动补全备份名。

九、测试验证：行为如何被保障

仓库中 pkg/cmd/cli/backup/get_test.go 的TestNewGetCommand覆盖了两种核心场景：

1. 按名称精确查询：创建b1、b2、b3三个带标签abc=abc的备份，执行velero backup get b1 b2 b3，断言输出中包含 3 条以 "New"（测试中备份尚未被处理，状态为New）开头的记录行；
2. 标签选择器过滤：执行velero backup get -l abc=abc，断言同样返回这 3 个备份。

测试通过 Fake Controller Runtime Client 模拟 API Server，直接验证了命令从参数解析、客户端查询到表格渲染的完整链路，可作为理解命令行为（尤其是传参与过滤语义）的可靠参考。

十、实战场景汇总

总结

velero backup get是 Velero 备份管理中最高频的查询命令。本文完整继承并扩展了 v0.8.0 参考文档的全部内容：从ark到velero的命令演化、专属选项与全局选项、table/json/yaml 三种输出格式、9 列表格字段、13 种备份阶段状态，并结合当前源码（get.go、output.go、backup_printer.go、backup_types.go）与测试用例（get_test.go）揭示了背后的执行链路、排序规则、过期时间计算与标签过滤原理，可帮助你在实际集群中精准、高效地定位备份状态与问题。

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