企业官网建设流程全解析

Ark（Velero）backup describe命令详解：从集群状态到卷快照的备份全景视图

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

ark backup describe是 Ark（Velero 的前身，当前仓库中命令已演进为velero backup describe）中用于以人类可读格式描述一个或多个备份的核心诊断命令。它把一个 Backup 自定义资源（CR）的完整配置（Spec）与执行结果（Status）——包括命名空间/资源过滤、存储位置、卷快照、Pod 卷备份、校验错误和删除记录——统一呈现在终端中，是备份创建后检查配置、故障排查时核对执行情况的首选工具。读完本文，你将掌握该命令的完整语法、全部参数语义、输出字段的底层含义，以及它如何与当前仓库中pkg/cmd/cli/backup的源码实现一一对应。

一、命令定位与总体语法

在 Ark v0.8.1 的 CLI 参考文档（site/content/docs/v0.8.1/cli-reference/ark_backup_describe.md）中，该命令被定义为ark backup下的一个子命令，功能描述为"Describe backups"（描述备份）。

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

与ark backup get（仅列出备份名称与概要状态）不同，describe会针对指定名称的备份，输出一个结构化但面向人阅读的多段式报告。其最突出的能力是支持一次传入多个备份名称，逐个生成报告：

# 描述单个备份 ark backup describe my-backup # 同时描述多个备份 ark backup describe my-backup-1 my-backup-2 my-backup-3

从当前仓库源码看，这一"多名称"能力在 describe.go 中依然保留：Use: use + " [NAME1] [NAME2] [NAME...]"，命令运行时会对args中的每个名称逐一执行kbClient.Get拉取 Backup 对象，再调用输出层描述；同时为每个备份收集关联的DeleteBackupRequest与PodVolumeBackup列表，用于后续的输出（describe.go）。

二、核心选项：--selector/-l

-h, --help help for describe -l, --selector string only show items matching this label selector

这是该命令唯一的功能性自有选项：

• --selector（简写-l）：只展示**匹配该标签选择器（label selector）**的备份。当describe不带任何备份名称时，它不会报错，而是退化为"按标签筛选后列出所有备份"；选择器语法遵循 Kubernetes 标准，例如-l 'env=production'、-l 'app in (nginx, redis)'。

其底层实现在当前仓库中依然可查：当args为空时，命令使用labels.Parse(listOptions.LabelSelector)解析选择器，再以LabelSelector作为条件执行kbClient.List拉取备份列表（describe.go）：

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

注意两个分支的行为差异：

对应地，在测试用例 describe_test.go 中，命令输出被断言为包含Name:、Backup Volumes:以及Or label selector: <none>等字段，验证了按名称描述时的输出格式。

三、继承自父命令的全局参数

除自有选项外，ark backup describe还继承了 Ark 根命令的整套全局参数（文档中"Options inherited from parent commands"一节）。这些参数直接决定了 CLI 如何与 Kubernetes API Server 建立连接、如何输出日志，是实际运行时的"隐藏依赖"：

一个典型的完整调用示例：

ark backup describe my-backup \ --kubeconfig /path/to/kubeconfig \ -n heptio-ark \ --logtostderr \ -v 4

四、输出内容的构成：与源码逐段对应

describe之所以比get信息量大得多，是因为它渲染的是 Backup 对象的完整 Spec + Status。当前仓库中负责纯文本渲染的函数是DescribeBackup（pkg/cmd/util/output/backup_describer.go），其输出段落与 Ark 时代的报告结构一脉相承，主要包括：

4.1 元数据与执行阶段（Phase）

报告首先输出备份的元数据与当前所处阶段：

Phase: Completed

阶段值直接取自backup.Status.Phase，且会做彩色渲染以突出状态：Completed显示为绿色，FailedValidation/PartiallyFailed/Failed显示为红色；若阶段为空则按New（新建未处理）处理（backup_describer.go）。如果备份失败或部分失败，报告还会追加提示：

Phase: Failed (run `velero backup logs <name>` for more information)

当阶段为Queued时，还会额外输出Queue position，反映备份在并发队列中的等待位次。

4.2 备份规格（Spec）段

接下来是对备份配置的完整回顾，字段与 Backup API 的 Spec 一一对应（DescribeBackupSpec）：

Namespaces: Included: * Excluded: <none> Resources: Included: * Excluded: <none> Cluster-scoped: auto Label selector: <none> Or label selector: <none> Storage Location: default Velero-Native Snapshot PVs: auto Snapshot Move Data: auto Data Mover: velero TTL: 720h0m0s CSISnapshotTimeout: 10m0s ItemOperationTimeout: 240h0m0s Hooks: <none>

其中几个关键字段的语义：

• Namespaces/Resources的Included/Excluded：对应spec.includedNamespaces、spec.excludedNamespaces、spec.includedResources、spec.excludedResources，空列表按*（全部）展示；
• Label selector：备份创建时--selector指定的资源筛选标签；Or label selector对应多选择器取并集的筛选方式；
• Storage Location：备份写入的对象存储位置，对应spec.storageLocation（默认为default）；
• Velero-Native Snapshot PVs：是否对 PV 做原生云快照（true/false/auto）；
• TTL：备份过期时间，过期后由 GC 控制器回收；
• Hooks：备份前后执行的资源 Hook 列表，含Pre Exec Hook/Post Exec Hook的容器、命令、错误策略与超时（backup_describer.go）。

4.3 备份状态（Status）段

状态段（DescribeBackupStatus）呈现执行结果的时间线与进度：

Backup Format Version: 1.1.0 Started: 2026-09-16 02:10:33 +0000 UTC Completed: 2026-09-16 02:11:02 +0000 UTC Expiration: 2026-10-16 02:10:33 +0000 UTC Total items to be backed up: 128 Items backed up: 128 HooksAttempted: 2 HooksFailed: 0

• Started/Completed：备份开始与完成时间戳；校验失败未开始的备份显示为<n/a>；
• Expiration：过期时间（TTL 之外不可为 0，控制器处理前可能临时显示<nil>）；
• Total items to be backed up/Items backed up：资源项总量与已备份数量；备份进行中时前缀变为Estimated total items（估算值）；
• HooksAttempted/HooksFailed：Hook 执行统计。

若备份存在校验错误，会在状态段之前单独输出红色Validation errors:列表（backup_describer.go）。

4.4 卷快照与 Pod 卷备份段

Backup Volumes:段是排查"卷有没有备上"的核心区域，由describeBackupVolumes渲染（backup_describer.go），分成三类分别展示：

Backup Volumes: Velero-Native Snapshots: <none included> CSI Snapshots: <none included> Pod Volume Backups - kopia: Completed: 3

• Velero-Native Snapshots：云厂商原生快照（如 AWS EBS snapshot），按 PV 名称列出 Snapshot ID、卷类型、可用区、IOPS 与结果；
• CSI Snapshots：CSI 驱动创建的卷快照，按namespace/pvcname列出 Snapshot Content Name、Storage Snapshot ID、快照大小（字节）与 CSI 驱动；
• Pod Volume Backups：文件系统级卷备份（Pod 卷上传），按阶段分组（Completed/Failed/In Progress 等）展示每个 Pod 的卷清单。这里有一个实用设计：未加--details时，上述信息只显示"包含与否"的摘要（如<none included>、specify --details for more information）；加上--details后才会展开每个卷的 Snapshot ID、类型、IOPS、大小等明细，避免默认输出过于冗长。

4.5 删除记录段

如果该备份关联过删除请求，报告末尾会追加Deletion Attempts:段（DescribeDeleteBackupRequests），列出每次删除尝试的创建时间、处理阶段（Phase）以及失败时的错误明细；存在失败删除时标题会标注失败次数，例如Deletion Attempts (1 failed):。这一信息在"备份删不掉"的排障场景中尤为关键，其数据来源正是命令启动时为该备份查询的DeleteBackupRequest列表（describe.go）。

五、命令的演进：从ark backup describe到velero backup describe

本仓库文档目录（site/content/docs/v0.8.1/cli-reference/ark_backup_describe.md）记录的是 Ark 更名 Velero 之前的 v0.8.1 形态：CLI 名为ark、默认命名空间为heptio-ark、API 组为ark.heptio.com。对照当前仓库源码（pkg/cmd/cli/backup），该命令已经历如下演进，理解这些差异有助于跨版本排障：

1. 命令名变化：ark backup describe→velero backup describe，默认命名空间heptio-ark→velero（backup.go 中以NewCommand(f client.Factory)注册子命令）；
2. 新增--details：控制卷快照、Pod 卷备份、Backup Item Operations 等明细的展开（describe.go）；
3. 新增--output/-o：支持plaintext（默认）与json两种格式；json结构化输出仅对单个备份生效（多备份场景下为避免内存溢出仍走纯文本，describe.go），结构化渲染实现在 pkg/cmd/util/output/backup_structured_describer.go；
4. 新增--cacert与--insecure-skip-tls-verify：控制对象存储 TLS 证书校验，--cacert指定证书 bundle，未指定时优先使用 BackupStorageLocation 中的 CA 证书（describe.go）；
5. 数据来源从对象存储文件补充：卷快照明细等信息需要从对象存储下载backup-volume-info等文件（经 DownloadRequest 机制），下载失败时输出区显示<error getting backup volume info: ...>而非静默跳过（backup_describer.go）。

六、实战排障示例：一次完整的 describe 排查流程

假设一次备份prod-backup结束后状态异常，可以按如下节奏使用该命令：

# 1. 先看整体阶段与校验错误 ark backup describe prod-backup # 2. 若存在卷相关疑问，展开明细 ark backup describe prod-backup --details # 3. 查看失败阶段的详细日志 ark backup logs prod-backup # 4. 批量检查某环境的所有备份 ark backup describe -l 'env=prod' # 5. 当前版本下以 JSON 格式获取机器可读结果（仅单备份） velero backup describe prod-backup -o json

排查时重点关注输出中的三类信号：

• Phase颜色：红色表示Failed/PartiallyFailed/FailedValidation，绿色表示Completed；
• Validation errors段：非空即说明备份在创建阶段被拒绝，属于配置问题而非执行问题；
• Backup Volumes段：核对期望备份的卷是否出现在对应快照/上传分组中，未出现通常意味着 PVC 在备份启动时未挂载或未匹配到卷策略。

七、相关资源与延伸阅读

• 命令参考：ark backup describe（v0.8.1）、ark backup（父命令）
• 命令实现：pkg/cmd/cli/backup/describe.go、pkg/cmd/cli/backup/backup.go
• 输出渲染：pkg/cmd/util/output/backup_describer.go（纯文本）、pkg/cmd/util/output/backup_structured_describer.go（JSON）
• 测试用例：pkg/cmd/cli/backup/describe_test.go
• 备份产物格式：site/content/docs/v0.8.1/output-file-format.md（说明对象存储中的ark-backup.json与备份 tar 包结构，describe中Backup Format Version字段即与之对应）

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