Velero（Ark）备份描述命令完全指南：ark describe backups从用法到源码解析
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
导读
ark describe backups是 Velero 项目（v0.9.0 时代名为 Ark）中用于查看备份（Backup）资源详细信息的核心 CLI 命令，它把存储在后端对象存储与 Kubernetes API Server 中的备份状态、配置、快照与错误信息汇总为人类可读的文本输出。本文以 v0.9.0 文档 ark_describe_backups.md 为主体，结合当前仓库源码（pkg/cmd/cli/backup/describe.go、pkg/cmd/util/output/backup_describer.go）逐一拆解命令语法、全部参数、输出字段语义及底层实现，帮助你快速定位备份失败原因、排查卷备份问题。
命令概览：做什么，输出什么
ark describe backups用于展示一个或多个 Backup 资源的详细信息。与只输出名称、阶段等摘要信息的ark backup get不同，describe 的输出是多行分节式的详情视图，通常包含：
- 备份元数据（名称、命名空间、创建时间等）；
- 当前**阶段（Phase）**及附加提示（如失败时提示运行
ark backup logs）； - 命名空间 / 资源包含与排除规则、集群级资源策略、标签选择器；
- 存储位置（Storage Location）、TTL、快照相关配置；
- 备份进度（已备份条目数 / 总条目数）；
- 校验错误（Validation Errors）、备份期间的 Errors / Warnings；
- 卷备份详情（原生快照、CSI 快照、Pod 卷备份）；
- 相关的删除请求（DeleteBackupRequests）记录。
该命令是日常备份巡检、故障排查、验收备份结果时最常用的工具之一。
命令语法
根据原文档 ark_describe_backups.md 的 Synopsis 节，命令语法为：
ark describe backups [NAME1] [NAME2] [NAME...] [flags]- 可以一次传入一个或多个备份名称，命令会按传入顺序逐个输出每个备份的详情；
- 也可以不传名称，此时命令会列出当前命名空间下所有备份并逐一描述（可通过
-l标签选择器过滤）。
从当前源码 pkg/cmd/cli/backup/describe.go 可以看到这条命令的实际执行逻辑：当传入名称时，逐个通过 controller-runtime 客户端kbClient.Get拉取对应 Backup 对象；未传名称时则用kbClient.List一次性列出全部 Backup，再对列表中的每一项分别调用描述器生成输出。
选项详解
原文档列出的核心选项如下（源码对应 pkg/cmd/cli/backup/describe.go）：
| 选项 | 简写 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
--help | -h | - | - | 显示 backups 子命令的帮助信息 |
--selector | -l | string | 空 | 仅展示匹配该标签选择器的条目（Label Selector，语法与kubectl一致，如-l app=nginx,env!=prod） |
--volume-details | - | bool | false | 展示 restic（Pod 卷）备份的详细卷信息 |
关于--volume-details：当未指定时，输出中 Pod 卷备份部分通常只按阶段聚合显示数量；指定该标志后，会按"命名空间/Pod 名"逐卷列出备份结果与进度。当前仓库实现对应describePodVolumeBackupsInSF中的details分支逻辑（见 pkg/cmd/util/output/backup_structured_describer.go）。
注：v0.9.0 属于 Ark 时代，上述标志即原文档的全部专属选项；在后续 Velero 版本中，该命令（
velero backup describe）又增加了--details、--insecure-skip-tls-verify、--cacert、-o/--output（支持plaintext与json结构化输出）等选项，详见下文"源码视角"一节。
继承自父命令的全局选项
ark describe backups还继承自ark根命令以下全局参数（原文档 "Options inherited from parent commands" 节），它们控制客户端连接与日志行为：
| 选项 | 默认值 | 说明 |
|---|---|---|
--alsologtostderr | false | 同时将日志写入标准错误与日志文件 |
--kubeconfig | 空 | kubeconfig 文件路径；未设置时依次尝试KUBECONFIG环境变量与集群内配置 |
--kubecontext | 当前上下文 | 指定用于连接 Kubernetes apiserver 的 kube context |
--log_backtrace_at | :0 | 当日志命中file:N时输出堆栈跟踪 |
--log_dir | 空 | 指定日志文件输出目录 |
--logtostderr | false | 日志输出到标准错误而非文件 |
-n, --namespace | heptio-ark | Ark 运行的命名空间（即 Backup 等 CRD 资源所在命名空间） |
--stderrthreshold | 2 | 达到或超过该级别的日志写入 stderr |
-v, --v | 0 | V 级别日志的日志级别 |
--vmodule | 空 | 按pattern=N逗号分隔列表对指定文件做日志过滤 |
其中-n/--namespace是日常使用最频繁的参数：当你把 Ark/Velero 安装在非默认命名空间时，必须用-n指对位置，否则命令会因找不到 Backup 资源而报错。当前源码中，命名空间同样作用于查询 DeleteBackupRequests 与 PodVolumeBackups 的List调用（pkg/cmd/cli/backup/describe.go）。
典型使用示例
在默认命名空间heptio-ark下查看单个备份：
ark describe backups daily-backup-20230601同时查看多个备份：
ark describe backups daily-backup-20230601 daily-backup-20230602查看全部备份并过滤标签：
ark describe backups -l velero.io/schedule-name=daily查看备份中 restic 卷的详细备份情况（含各 Pod 卷的进度与结果）：
ark describe backups daily-backup-20230601 --volume-details若 Ark 安装在自定义命名空间velero：
ark describe backups daily-backup-20230601 -n velero命令在输出多个备份时会用空行分隔；对于状态为Failed或PartiallyFailed的备份，Phase 行会以红色显示，并追加提示(runark backup logsfor more information)，引导你进一步用日志定位失败原因——该逻辑定义于 pkg/cmd/util/output/backup_describer.go。
读懂输出：各分节语义
以当前仓库实现为准，describe输出按以下分节组织（见 pkg/cmd/util/output/backup_describer.go 的调用顺序）：
- 元数据与 Phase：备份名称、命名空间、UID、创建时间，以及阶段。阶段枚举定义于 pkg/apis/velero/v1/backup_types.go，包括
New、Queued、ReadyToStart、FailedValidation、InProgress、WaitingForPluginOperations、Finalizing、Completed、PartiallyFailed、Failed、Deleting等。 - 校验错误：当
Status.ValidationErrors非空时逐条以红色列出，说明备份参数未通过校验（如引用了不存在的存储位置）。 - Errors / Warnings：从对象存储下载 backup-results 文件并展开，按 velero / cluster / namespace 三个维度归类错误与警告（pkg/cmd/util/output/backup_structured_describer.go）。
- Spec 配置：Included/Excluded Namespaces、Included/Excluded Resources、集群级资源策略、标签选择器、存储位置、TTL、快照配置、Hooks（pre/post exec hook 及其命令、超时、出错策略）、有序资源（OrderedResources）等。
- Status 状态：FormatVersion、开始/完成时间、过期时间（默认 30 天 TTL）、进度（
TotalItems/ItemsBackedUp，进行中显示estimatedTotalItemsToBeBackedUp），以及卷信息、Hook 尝试/失败次数。 - 卷详情：分为原生快照（含
snapshotID、卷类型、可用区、IOPS）、CSI 快照（snapshotContentName、存储侧 snapshotID、大小、驱动）、Pod 卷备份（restic，按 Completed/Failed/Canceled/In Progress 等阶段分组，--volume-details下再按 Pod 展开）。 - 删除请求：若存在 DeleteBackupRequest，列出每次删除尝试的创建时间、阶段与错误（pkg/cmd/util/output/backup_structured_describer.go）。
源码视角：命令的完整调用链
虽然 v0.9.0 文档面向的是ark命令，但该命令在后继版本（velero backup describe）中持续演进。当前仓库中对应实现集中在两个文件：
- 命令入口：pkg/cmd/cli/backup/describe.go 中的
NewDescribeCommand定义了参数解析与数据获取逻辑。值得注意的细节：- 支持
-o json结构化输出，但代码注释明确：结构化输出只适用于单个备份（len(backups.Items) == 1），多备份场景会退化为 plaintext，以避免内存溢出（见 describe.go）； - 提供 shell 自动补全
c.ValidArgsFunction = cli.CompleteBackupNames(f)，可直接 Tab 补全备份名； - 支持
--cacert与--insecure-skip-tls-verify，用于从对象存储下载 results / volume-info 文件时的 TLS 校验配置。
- 支持
- 输出渲染：pkg/cmd/util/output/backup_describer.go（人类可读的 plaintext 版）与 pkg/cmd/util/output/backup_structured_describer.go（结构化 JSON 版）共同承担字段拼接。两者都通过
downloadrequest.StreamWithBSLCACert从备份存储桶拉取资源清单与卷信息文件，并对文件缺失（ErrNotFound）做了兼容处理——例如 v1.1 之前产生的备份可能没有资源清单文件，输出中会显示<backup resource list not found>而非直接报错。
测试用例见 pkg/cmd/util/output/backup_describer_test.go 与 pkg/cmd/util/output/backup_structured_describer_test.go，可作为期望输出格式的参考样例。
与其他命令的协作
ark describe backups通常不是孤立使用的，排查链路可参考：
ark backup get：先获取备份列表与状态概览（ark_get_backups.md）；ark backup describe（父命令 ark describe）：ark describe是顶层命令，其子命令还包括restores、schedules（见 ark_describe.md）；ark backup logs：备份 Failed/PartiallyFailed 时，describe 输出会直接提示使用该命令拉取完整日志定位根因；ark restic repo get/ark restic server：配合排查 restic 卷备份相关状态（相关命令见 ark_restic_repo_get.md）。
小结
ark describe backups（现velero backup describe）是 Velero 备份体系中"状态可视化"的关键入口：一条命令即可聚合 CRD 状态、对象存储中的结果文件、卷快照信息与删除记录。理解其参数（尤其是--selector、--volume-details与全局-n）和输出分节语义，能显著提升备份排查效率；而深入 describe.go 与output包源码，则能让你在面对异常输出（如资源清单缺失、JSON 结构化输出限制）时心中有数。
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
