企业官网建设流程全解析

Ark/Veleroark restore describe命令深度解析：查看 Kubernetes 恢复任务详情的完整指南

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

导读

ark restore describe是 Ark（Velero 的前身，v0.7.0 时代的命令行工具）中用于查看恢复（Restore）任务详细信息的核心命令。通过它，你可以快速检查一次恢复任务的执行阶段（Phase）、进度、时间戳、验证错误、资源过滤范围以及卷恢复状态，从而定位恢复失败或部分失败的原因。本文以 ark_restore_describe.md 为骨架，结合当前仓库中的pkg/cmd/cli/restore/describe.go与pkg/cmd/util/output/restore_describer.go源码，逐项解析该命令的语法、全部参数、输出字段含义，并对照讲解它在现代 Velero 版本中的演进。

一、命令概览与定位

ark restore describe是ark restore命令组下的一个子命令，功能是“Describe restores”（描述恢复任务）。在 v0.7.0 版本中，Ark 采用与 kubectl 类似的命令模型，既支持ark restore describe，也支持等价的ark describe restores写法（参考 ark.md）。

它的完整语法为：

ark restore describe [NAME1] [NAME2] [NAME...] [flags]

从语法可以看出，该命令支持同时传入多个恢复任务名称（NAME1、NAME2……），一次性批量查看多个 Restore 的详情。这一点在当前仓库源码中得到了印证：pkg/cmd/cli/restore/describe.go#L52-L53 中命令的Use字段即定义为use + " [NAME1] [NAME2] [NAME...]"。

当不带任何 NAME 参数执行时，命令会列出当前命名空间下所有匹配标签选择器的 Restore 并逐一描述；当传入一个或多个 NAME 时，则只描述指定的 Restore（源码中通过kbClient.Get逐个获取，见 describe.go#L63-L69）。

二、命令参数详解（Options）

v0.7.0 文档明确列出了该命令自身的两个参数：

其中--selector是描述命令最常用的过滤参数，例如-l app=web可以只查看打有app=web标签的 Restore。在当前的 describe.go#L109 中，该参数被绑定到listOptions.LabelSelector，随后通过labels.Parse解析、并在kbClient.List时作为LabelSelector传入（见 describe.go#L71-L75），用于从 API Server 侧过滤待描述的 Restore 列表。

继承自父命令的全局参数

除自身参数外，该命令还继承 Ark 根命令ark的所有全局参数。v0.7.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 --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

其中最常使用的是-n, --namespace，它决定了 Ark 在哪个命名空间中查找 Restore。注意 v0.7.0 时代默认命名空间为heptio-ark；在现代 Velero 中，该默认值已迁移为velero。若你的 kubeconfig 不在默认位置，还需通过--kubeconfig或环境变量KUBECONFIG指定。

三、输出字段全解析：从源码看 describe 到底展示什么

ark restore describe的输出由 pkg/cmd/util/output/restore_describer.go 中的DescribeRestore函数生成（调用链为 describe 命令 →output.DescribeRestore）。理解输出字段，有助于你快速定位恢复任务的状态问题。核心字段如下：

1. 元数据与阶段（Phase）

输出首先展示 Restore 的名称、命名空间、标签、注解等元数据，随后是阶段（Phase）。DescribeRestore从restore.Status.Phase读取当前阶段（见 restore_describer.go#L57-L80）：

• 若阶段为空，按New（新建）处理；
• 若 Restore 正在被删除（DeletionTimestamp已设置），阶段后追加(Deleting)标记；
• Completed 阶段以绿色显示，FailedValidation / PartiallyFailed / Failed 阶段以红色显示，便于一眼识别异常；
• 当阶段为Failed或PartiallyFailed时，输出还会附带提示：(run 'velero restore logs <name>' for more information)，引导你去查看恢复日志。

2. 进度（Progress）与时间戳

当restore.Status.Progress存在时：

• 阶段为InProgress：显示Estimated total items to be restored（预计需恢复的项目总数）与Items restored so far（已恢复项目数）；
• 其他阶段：显示Total items to be restored与Items restored。

随后输出Started（开始时间）与Completed（完成时间）；若时间戳为空（典型场景是校验未通过，尚未真正开始），则显示<n/a>（见 restore_describer.go#L91-L103）。

3. 校验错误（Validation errors）

若restore.Status.ValidationErrors非空，会以红色逐条列出校验错误。这是排查“Restore 创建后被直接拒绝”的最快入口。

4. 结果统计（Warnings / Errors）

describeRestoreResults（见 restore_describer.go#L303-L337）会在Warnings或Errors计数大于 0 时，从对象存储（BackupStorageLocation）下载恢复结果文件并解码，按Velero、Cluster、Namespaces三个维度展开具体的告警与错误明细。

5. 恢复规格（Spec）信息

DescribeRestore后半部分完整呈现 Restore 的规格配置，包括：

• Backup：本次恢复所基于的备份名称（restore.Spec.BackupName）；
• Namespaces：Included（默认展示all namespaces found in the backup）与 Excluded 列表；
• Resources：Included（默认*）与 Excluded 资源列表；
• Cluster-scoped：集群级资源处理策略（excluded / included / auto）；
• Namespace mappings：命名空间映射关系；
• Label selector / Or label selector：恢复对象的选择条件；
• Restore PVs：是否恢复持久卷（false / true / auto）；
• Existing Resource Policy / Existing Volume Data Policy：既有资源与既有卷数据的处理策略；
• ItemOperationTimeout：恢复项操作超时时间；
• Preserve Service NodePorts：是否保留 Service 的 NodePort；
• Resource modifier / Skip Default Resource Modifier：资源修改器配置。

6. Pod Volume Restores 卷恢复明细

describe 命令会自动查找与该 Restore 关联的PodVolumeRestore列表（按RestoreNameLabel标签过滤，见 describe.go#L80-L87）。describePodVolumeRestores（见 restore_describer.go#L382-L436）按阶段（Completed / Canceled / Failed / In Progress / Prepared / Accepted / New）分组统计卷恢复数量，并可在--details模式下展开到具体 Pod（namespace/name）与卷名。

7. 钩子与恢复项操作统计

若restore.Status.HookStatus存在，会输出HooksAttempted（钩子尝试次数）与HooksFailed（失败次数）；若启用了恢复项操作（如异步数据移动），还会输出各操作的插件、Operation ID、阶段与进度。

四、源码验证：命令的底层执行流程

从 describe.go 可以看到ark restore describe的完整执行链路，这对理解命令行为很有帮助：

1. 加载客户端：调用client.LoadConfig()读取 Ark 配置文件（含 CA 证书路径），并通过f.KubebuilderClient()创建 controller-runtime 客户端；
2. 数据获取：传入了 NAME 参数则逐个Get，否则按--selector构造ListOptions并List出 Restore 列表；
3. 关联查询：为每个 Restore 按RestoreNameLabel查询其 PodVolumeRestore；
4. 渲染输出：调用output.DescribeRestore（纯文本）或output.DescribeRestoreInSF（结构化输出）打印结果；多条记录之间以空行分隔（见 describe.go#L96-L101）。

对应的单元测试位于 pkg/cmd/cli/restore/describe_test.go，测试通过 fake client 构造一个名为restore-describe-1的 Restore，执行velero restore describe后断言输出中包含Name: restore-describe-1，验证了命令“按名称获取并描述恢复任务”的核心行为。

五、现代 Velero 版本中的演进（补充参考）

v0.7.0 文档记录的是 Ark 时代最精简的参数集（仅--help与--selector）。当前仓库中的实现（即现代 Velero 的velero restore describe）在继承这两个参数的基础上，新增了以下能力（见 describe.go#L110-L113）：

其中--output json在源码中被限定为仅当列表中只有一个 Restore 时生效（见 describe.go#L89-L93），避免结构化输出海量数据导致内存问题；而--details则会触发describeRestoreResourceList，从对象存储下载并按 GVK 排序输出完整的恢复资源清单（见 restore_describer.go#L518-L555）。

六、实战示例

假设 Ark 部署在默认命名空间heptio-ark：

# 1. 描述单个恢复任务 ark restore describe my-restore # 2. 同时描述多个恢复任务 ark restore describe restore-a restore-b restore-c # 3. 按标签选择器过滤后描述（仅描述打有 env=prod 标签的 Restore） ark restore describe --selector env=prod # 4. 在非默认命名空间中描述 ark restore describe my-restore --namespace velero

在现代 Velero 中对应为（需将命令前缀ark替换为velero）：

# 5. 展示卷恢复等额外细节 velero restore describe my-restore --details # 6. 输出单个 Restore 的结构化 JSON 便于脚本解析 velero restore describe my-restore --output json

当描述结果中出现红色Failed/PartiallyFailed阶段并附带提示时，应立即执行velero restore logs <name>查看详细日志（对应命令文档见 ark_restore_logs.md）；若是校验失败，则重点查看输出中的Validation errors段落，逐条修正恢复参数后重新创建 Restore。

七、关联命令与延伸阅读

ark restore describe属于ark restore命令族，兄弟命令包括（见 ark_restore.md）：

• ark restore create：创建恢复任务；
• ark restore delete：删除恢复任务；
• ark restore get：列出恢复任务；
• ark restore logs：获取恢复日志（排查失败的核心工具）。

如果你想深入了解 Restore 资源本身的结构（阶段、进度、验证错误等字段的定义），可查阅仓库中的 pkg/apis/velero/v1/restore_types.go；若关心描述输出的完整字段顺序与格式化细节，可直接阅读 pkg/cmd/util/output/restore_describer.go。本文所有参数与输出行为均可在上述源码与测试用例中逐一验证。

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