Ark/Veleroark restore describe命令深度解析查看 Kubernetes 恢复任务详情的完整指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读ark restore describe是 ArkVelero 的前身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。二、命令参数详解Optionsv0.7.0 文档明确列出了该命令自身的两个参数参数简写默认值说明--help-h—显示 describe 子命令的帮助信息--selector-l空仅显示匹配该标签选择器label selector的恢复任务其中--selector是描述命令最常用的过滤参数例如-l appweb可以只查看打有appweb标签的 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 patternN 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 / ErrorsdescribeRestoreResults见 restore_describer.go#L303-L337会在Warnings或Errors计数大于 0 时从对象存储BackupStorageLocation下载恢复结果文件并解码按Velero、Cluster、Namespaces三个维度展开具体的告警与错误明细。5. 恢复规格Spec信息DescribeRestore后半部分完整呈现 Restore 的规格配置包括Backup本次恢复所基于的备份名称restore.Spec.BackupNameNamespacesIncluded默认展示all namespaces found in the backup与 Excluded 列表ResourcesIncluded默认*与 Excluded 资源列表Cluster-scoped集群级资源处理策略excluded / included / autoNamespace mappings命名空间映射关系Label selector / Or label selector恢复对象的选择条件Restore PVs是否恢复持久卷false / true / autoExisting Resource Policy / Existing Volume Data Policy既有资源与既有卷数据的处理策略ItemOperationTimeout恢复项操作超时时间Preserve Service NodePorts是否保留 Service 的 NodePortResource 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模式下展开到具体 Podnamespace/name与卷名。7. 钩子与恢复项操作统计若restore.Status.HookStatus存在会输出HooksAttempted钩子尝试次数与HooksFailed失败次数若启用了恢复项操作如异步数据移动还会输出各操作的插件、Operation ID、阶段与进度。四、源码验证命令的底层执行流程从 describe.go 可以看到ark restore describe的完整执行链路这对理解命令行为很有帮助加载客户端调用client.LoadConfig()读取 Ark 配置文件含 CA 证书路径并通过f.KubebuilderClient()创建 controller-runtime 客户端数据获取传入了 NAME 参数则逐个Get否则按--selector构造ListOptions并List出 Restore 列表关联查询为每个 Restore 按RestoreNameLabel查询其 PodVolumeRestore渲染输出调用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参数说明--details展示额外细节如逐 Pod 的卷恢复明细、恢复资源清单Resource List--insecure-skip-tls-verify跳过对象存储 TLS 证书校验不安全不推荐生产环境使用--cacert指定用于验证 TLS 连接的 CA 证书包路径-o, --output输出格式支持plaintext默认与jsonjson仅适用于单个 Restore 的结构化描述其中--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. 按标签选择器过滤后描述仅描述打有 envprod 标签的 Restore ark restore describe --selector envprod # 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.mdark 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
