企业官网建设流程全解析

Velero 旧版 CLI 参考：ark get命令详解与源码实现剖析

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

ark get是 Velero（前身 Heptio Ark）CLI 中用于获取集群备份/恢复资源的核心查询命令，它采用与kubectl相似的操作模型，让用户可以像查看 Kubernetes 资源一样查看 Ark 的backups、restores、schedules等自定义资源。本文以 ark_get.md 文档为主体，结合当前仓库中该命令的实际源码实现，完整讲解命令语法、全部全局选项与子命令选项、输出格式机制，以及命令背后的源码调用链，帮助读者彻底掌握这一命令族的用法与原理。

背景说明：v0.8.0 时代的 CLI 二进制名称为ark，其默认命名空间为heptio-ark；项目随后更名为 Velero，命令相应变为velero，默认命名空间也演进为velero（见 pkg/apis/velero/v1/constants.go）。本文以 v0.8.0 文档中的ark命令为准描述历史行为，并在涉及当前仓库源码时以velero为准说明其演进。

命令概述（Synopsis）

ark get的 Synopsis 只有一句简单描述："Get ark resources"——即获取 Ark 管理的资源。所谓 Ark 资源，本质上就是 Velero 项目定义的一组 Kubernetes 自定义资源（CRD），包括：

• backups：备份对象，记录一次备份请求及其执行状态；
• restores：恢复对象，记录一次恢复请求及其执行状态；
• schedules：定时调度对象，按 Cron 表达式周期性触发备份；
• 以及（在当前仓库的 get 命令源码 中）backup-locations（备份存储位置）、snapshot-locations（快照存储位置）、plugins（已注册插件）。

ark get自身是一个聚合命令，本身没有具体的查询逻辑，它的职责是把上述各类资源的获取子命令挂载到同一命令树下。从 pkg/cmd/cli/get/get.go 的NewCommand实现可以看到这一点：get命令用 cobra 框架创建，然后通过c.AddCommand(...)注册了backups、schedules、restores、backup-locations、snapshot-locations、plugins六个子命令，并全部提供了单数形式的别名（如backup、schedule），方便用户按ark get backup的方式书写。

语法格式

ark get本身不带资源参数，实际查询需指定子命令。完整语法为：

ark get backups [flags] ark get restores [flags] ark get schedules [flags] ark get backup-locations [flags] ark get snapshot-locations [flags] ark get plugins [flags]

与kubectl的交互习惯一致，v0.8.0 文档明确说明 Ark 支持两种等价书写形式（见 ark.md）：

• ark get backup形式：资源类型位于get之后；
• ark backup get形式：命令动词位于资源类型之后（backup子命令树下的get）。

这两种形式底层都解析到同一组实现函数，用户可按习惯选用。

全局选项（Options inherited from parent commands）

ark get自身只有一个-h, --help选项用于查看帮助，其余选项全部继承自父命令（ark根命令）。这些全局选项在 v0.8.0 文档中给出了完整清单，现逐一说明其作用：

--alsologtostderr log to standard error as well as files --kubeconfig string Path to the kubeconfig file to use to talk to the Kubernetes apiserver. If unset, try the environment variable KUBECONFIG, as well as in-cluster configuration --kubecontext string The context to use to talk to the Kubernetes apiserver. If unset defaults to whatever your current-context is (kubectl config current-context) --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) --log_dir string If non-empty, write log files in this directory --logtostderr log to standard error instead of files -n, --namespace string The namespace in which Ark should operate (default "heptio-ark") --stderrthreshold severity logs at or above this threshold go to stderr (default 2) -v, --v Level log level for V logs --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging

这些选项分为两类：

连接配置类

命名空间选项对ark get的查询结果有决定性影响：get子命令实际查询的是指定命名空间下的 CRD 实例，如果服务器端 Ark 部署在别的命名空间，就必须通过-n显式指定，否则查不到任何数据。

日志输出类

这些是 Go 标准k8s.io/klog/ glog 风格的日志参数，属于 Ark CLI 全命令共享的标准配置，与具体查询逻辑无关。

子命令选项详解

v0.8.0 文档中ark get的三个主要子命令——backups、restores、schedules——拥有完全一致的选项集合（见 ark_get_backups.md、ark_get_restores.md、ark_get_schedules.md）：

-h, --help help for backups --label-columns stringArray a comma-separated list of labels to be displayed as columns -o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. (default "table") -l, --selector string only show items matching this label selector --show-labels show labels in the last column

-o, --output string：输出格式

指定查询结果的展示格式，可选值为table、json、yaml，默认table。该选项的实际行为由 pkg/cmd/util/output/output.go 的BindFlags绑定，并通过PrintWithFormat（同文件 L113-L127）分派：

• table：走printTable路径，按资源类型查表渲染人类可读的表格（默认格式）；
• json/yaml：走printEncoded路径，将对象序列化后输出。值得注意的是，当查询结果是列表且列表中只有一个元素时，会直接输出该元素而非列表包裹（见 output.go L129-L149）。

选项的合法性校验在ValidateFlags/validateOutputFlag中完成（output.go L90-L108）：除table、json、yaml（及空值）外，其余值都会报错invalid output format ... - valid values are 'table', 'json', and 'yaml'。这也是各get子命令在Run回调中最先执行output.ValidateFlags(c)的原因。

-l, --selector string：标签选择器

只显示匹配该标签选择器的对象。在backup get的实现（pkg/cmd/cli/backup/get.go）中，该值通过labels.Parse解析为 Kubernetes 标签选择器，并以kbClient.List(..., &kbclient.ListOptions{LabelSelector: parsedSelector, ...})的方式传给 controller-runtime 客户端，由 API Server 侧完成过滤。这保证了ark get backups -l app=nginx这类查询语义与kubectl get ... -l app=nginx完全一致。

--label-columns stringArray：标签列

接受逗号分隔的标签键列表，将这些标签作为额外的列展示在表格中。源码层面（output.go L47-L48）使用flag.NewStringArray()实现，支持重复使用，如-L label1 -L label2。注意标签键名是大小写敏感的。

--show-labels：显示标签列

在表格最后一列输出对象的完整标签集合（格式为key1=value1,key2=value2）。这三个展示类选项最终汇入NewPrinter构造的printers.PrintOptions{ShowLabels, ColumnLabels}（output.go L241-L250），交给 Kubernetes 的printers.NewTablePrinter完成列渲染。

按名称查询与列表查询

虽然 v0.8.0 文档只给出ark get backups [flags]的语法占位，但从当前仓库的backup get实现（pkg/cmd/cli/backup/get.go）可以推断出该子命令支持两类查询方式：

• 不传名称：列出命名空间下所有资源。走kbClient.List分支，配合--selector进行标签过滤；
• 传一个或多个名称：逐个执行kbClient.Get，按名称精确获取指定对象，例如ark get backups daily-backup-20260101。若指定名称不存在，命令会报错退出。

此外，get.go 中 L70 设置了ValidArgsFunction = cli.CompleteBackupNames(f)，为交互式 shell 提供备份名称的自动补全能力。

表格输出列的构成

ark get backups默认表格的列定义在 pkg/cmd/util/output/backup_printer.go 中：

其中有两处值得注意的细节实现：

• 排序：sortBackupsByPrefixAndTimestamp（backup_printer.go L64-L82）对列表排序——默认按名称字母序，但如果备份名带有 14 位时间戳后缀（如 schedule 自动生成的备份），则在相同前缀分组内按时间戳倒序排列，让最新生成的备份排在最前。
• 过期时间推算：printBackup（backup_printer.go L84-L122）优先使用Status.Expiration；若未设置且Spec.TTL大于 0、备份已开始（StartTimestamp非空），则用StartTimestamp + TTL估算，避免把停留在 New 阶段的备份误判为已过期（对应 issue #3555 的修复）。

restores、schedules等其他资源类型同样在 pkg/cmd/util/output 包中有各自的列定义与行渲染函数，printTable通过类型断言（output.go L155-L223）统一分发。

完整使用示例

综合文档与源码，ark get的典型用法如下：

# 列出全部备份（表格形式） ark get backups # 按名称查看单个备份 ark get backups daily-backup-20260101 # 按标签过滤备份 ark get backups -l app=nginx # 以 YAML 格式输出备份对象（便于与 kubectl apply / git 配合） ark get backups -o yaml # 以 JSON 格式输出 ark get backups -o json # 在表格中展示自定义标签列，并显示完整标签 ark get backups --label-columns app --show-labels # 列出所有恢复与定时调度 ark get restores ark get schedules

相关命令速查

• ark —— Ark 根命令，Back up and restore Kubernetes cluster resources.
• ark get backups —— Get backups
• ark get restores —— Get restores
• ark get schedules —— Get schedules

小结

ark get命令族以kubectl式交互模型为设计蓝本，通过聚合backups、restores、schedules、backup-locations、snapshot-locations、plugins六个子命令，配合-o、-l、--label-columns、--show-labels等展示与过滤选项，提供了对 Velero 核心资源完整且灵活的查询能力。其源码实现（pkg/cmd/cli/get/get.go）清晰展示了 cobra 命令树的组织方式，而输出层（pkg/cmd/util/output）则体现了基于metav1.Table与 Kubernetes printer 的统一渲染机制。理解这一命令的选项体系与实现原理，对日常使用 Velero 排查备份/恢复状态、编写自动化运维脚本，以及深入理解 CLI 插件式扩展都很有帮助。

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