Velero 备份输出文件格式深入解析：从 tar.gz 归档到目录结构与元数据文件

Velero 备份输出文件格式深入解析从 tar.gz 归档到目录结构与元数据文件【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本篇技术指南以 Velero前身 Heptio Ark官方文档 site/content/docs/v0.8.1/output-file-format.md 为主体完整讲解备份产物在对象存储中的组织方式、ark-backup.json/velero-backup.json元数据文件的字段含义以及 gzip 压缩 tar 包内部的目录结构约定并结合当前仓库源码说明该格式在当前版本中的落地实现与读取链路。读完本文你将掌握 Velero 备份文件的存放规律、格式版本status.version的含义以及如何手动查看和验证一个备份归档的内容。一、核心概念备份就是一个 gzip 压缩的 tar 包文档开篇即点明了 Velero 备份产物的本质A backup is a gzip-compressed tar file whose name matches the Backup API resourcesmetadata.name即ark backup create NAME/ 现在的velero backup create NAME时指定的名称。也就是说每次执行备份命令Velero 会遍历集群中被纳入备份范围的 Kubernetes 资源将其序列化后写入一个gzip 压缩的 tar 包。该 tar 包的文件名与 Backup 自定义资源的metadata.name完全一致例如velero backup create test-backup生成的归档文件就是test-backup.tar.gz。这个约定在当前仓库源码中依然成立。在 pkg/backup/backup.go 中kubernetesBackupper.Backup的注释明确写着 placing them in a gzip-compressed tar file实现上通过gzip.NewWriter(backupFile)包一层tar.NewWriter完成双重封装gzippedData : gzip.NewWriter(backupFile) defer gzippedData.Close() tw : NewTarWriter(tar.NewWriter(gzippedData))而在对象存储一侧pkg/persistence/object_store_layout.go 用getBackupContentsKey精确地构造了该文件的存储键func (l *ObjectStoreLayout) getBackupContentsKey(backup string) string { return path.Join(l.subdirs[backups], backup, fmt.Sprintf(%s.tar.gz, backup)) }二、对象存储中的归档结构每个备份一个独立子目录文档指出在云对象存储的 bucket 中每个备份文件都被存放在各自独立的子目录里子目录名即备份名并且该子目录还额外包含一个名为ark-backup.json的 JSON 文件。目录结构示例如下rootBucket/ backup1234/ ark-backup.json backup1234.tar.gz其中backup1234.tar.gz上文所述的 gzip 压缩 tar 包即备份本体ark-backup.json与 Backup 资源一一对应的元数据文件记录了该备份的完整历史配置。在当时的 Ark 时代v0.8.1元数据文件名为ark-backup.jsonAPI group 为ark.heptio.com/v1。随着项目更名为 Velero这一命名也发生了对应演变当前仓库中元数据文件名已是velero-backup.json见 pkg/persistence/object_store_layout.gofunc (l *ObjectStoreLayout) getBackupMetadataKey(backup string) string { return path.Join(l.subdirs[backups], backup, velero-backup.json) }对应的对象存储测试用例pkg/persistence/object_store_test.go也验证了backups/name/velero-backup.json这一布局例如backups/backup-1/velero-backup.json与velero-backups/backups/backup-1/velero-backup.json带自定义 prefix 的场景。元数据文件的两个关键作用文档特别强调了两点完整历史记录JSON 文件列出了关联 Backup 资源的全部信息包括所有默认值。即使某个字段在创建备份时未显式指定也会以默认值形式记录在案因此它是排查备份到底备份了什么的第一手依据格式版本标识JSON 中的status.version字段对应着输出文件格式的版本号。读取备份归档时首先需要依据该版本决定如何解析 tar 包内部结构。三、备份元数据 JSON 文件逐字段解读文档给出了一个完整的示例 JSON 文件。该文件是理解备份配置与执行结果的体检报告字段可划分为三大部分{ kind: Backup, apiVersion: ark.heptio.com/v1, metadata: { name: test-backup, namespace: heptio-ark, selfLink: /apis/ark.heptio.com/v1/namespaces/heptio-ark/backups/testtest, uid: a12345cb-75f5-11e7-b4c2-abcdef123456, resourceVersion: 337075, creationTimestamp: 2017-07-31T13:39:15Z }, spec: { includedNamespaces: [ * ], excludedNamespaces: null, includedResources: [ * ], excludedResources: null, labelSelector: null, snapshotVolumes: true, ttl: 24h0m0s }, status: { version: 1, expiration: 2017-08-01T13:39:15Z, phase: Completed, volumeBackups: { pvc-e1e2d345-7583-11e7-b4c2-abcdef123456: { snapshotID: snap-04b1a8e11dfb33ab0, type: gp2, iops: 100 } }, validationErrors: null } }字段说明如下字段含义本示例中的取值metadata.name备份名称与 tar 包文件名一致test-backupmetadata.namespace备份 CR 所在命名空间Ark 默认heptio-arkVelero 默认veleroheptio-arkspec.includedNamespaces纳入备份的命名空间列表*表示全部[*]spec.excludedNamespaces排除的命名空间列表nullspec.includedResources纳入备份的资源类型列表*表示全部[*]spec.excludedResources排除的资源类型列表nullspec.labelSelector按标签选择器过滤备份对象nullspec.snapshotVolumes是否对卷做持久化快照truespec.ttl备份的保留时长24h0m0sstatus.version输出文件格式版本1status.expiration过期时间由ttl推算creationTimestampttl2017-08-01T13:39:15Zstatus.phase备份当前阶段Completedstatus.volumeBackups卷快照明细PVC UID → 快照 ID/类型/IOPS见上status.validationErrors校验错误列表null表示无错误null值得注意的细节status.volumeBackups文档专门提示status.volumeBackups字段包含了每个被快照卷的详细信息如 AWS EBS 快照 IDsnap-04b1a8e11dfb33ab0、卷类型gp2、IOPS 等。当你需要在云厂商控制台中手动核对这些快照是否存在、规格是否一致时该字段非常有用——它把集群内的 PVC与云上的快照一一对应了起来。说明示例中的apiVersion为ark.heptio.com/v1、默认命名空间为heptio-ark这反映的是 Ark v0.8.1 时期的 API。当前 Velero 版本的 Backup CR 使用velero.io/v1默认命名空间为velero见 pkg/apis/velero/v1/constants.go 中DefaultNamespace velero但元数据 JSON 的整体结构与语义保持一致。四、输出文件格式版本 1tar 包内部的目录结构约定文档后半部分给出了格式版本 1status.version: 1下的 tar 包内部结构。将backup1234.tar.gz解压后典型目录如下resources/ persistentvolumes/ cluster/ pv01.json ... configmaps/ namespaces/ namespace1/ myconfigmap.json ... namespace2/ ... pods/ namespaces/ namespace1/ mypod.json ... namespace2/ ... jobs/ namespaces/ namespace1/ awesome-job.json ... namespace2/ ... deployments/ namespaces/ namespace1/ cool-deployment.json ... namespace2/ ... ...这个结构可以总结为一条清晰的路径规则resources/资源类型/作用域/[命名空间/]对象名.json具体约定包括顶层resources/目录存放所有被备份的 Kubernetes 资源按资源类型分子目录如persistentvolumes/、configmaps/、pods/、jobs/、deployments/等集群作用域与命名空间作用域分层集群级资源放在cluster/子目录下如 PV 这类无命名空间的资源命名空间级资源放在namespaces/namespace/子目录下每个命名空间一个目录每个对象一个 JSON 文件文件名即对象名如mypod.json内容是该对象序列化后的 Kubernetes manifestunstructured 形式。五、源码印证当前仓库如何落地这套目录约定5.1 目录名常量集中定义上述目录命名在代码中以常量形式固化见 pkg/apis/velero/v1/constants.goResourcesDir resources备份中存放各类资源的顶层目录MetadataDir metadata存放备份元数据如版本文件的目录ClusterScopedDir cluster集群级资源子目录NamespaceScopedDir namespaces命名空间级资源子目录PreferredVersionDir -preferredversionAPI group 首选版本目录后缀配合EnableAPIGroupVersions特性使用。5.2 版本文件metadata/version格式版本信息不仅存在于对象存储的 JSON 元数据中也写入了 tar 包本身。在 pkg/backup/backup.go 的writeBackupVersion函数中Velero 会向 tar 包写入一个metadata/version文件内容为当前格式版本号func (kb *kubernetesBackupper) writeBackupVersion(tw tarWriter) error { versionFile : filepath.Join(velerov1api.MetadataDir, version) versionString : fmt.Sprintf(%s\n, BackupFormatVersion) ... }而版本号常量定义在 pkg/backup/backup.goconst BackupFormatVersion 1.1.0可以看到自文档所述的 v1 之后格式版本已演进到1.1.0。对应地pkg/backup/backup_test.go 中的测试用例断言了归档内容同时包含metadata/version与resources/deployments.apps/namespaces/ns-1/deploy-1.json等文件印证了版本文件 资源目录并存的结构。5.3 解析侧pkg/archive/parser.go的目录遍历逻辑备份读取如 restore 时依赖 pkg/archive/parser.go 中的Parser.Parse方法其遍历逻辑与文档描述的目录结构一一对应先确认顶层resources/目录存在并读取其子目录每个子目录对应一个资源类型对每个资源目录检查是否存在cluster/子目录——存在则将其中的文件归入集群作用域ItemsByNamespace[]再检查namespaces/子目录——其中的每个子目录名即命名空间目录内的文件即该命名空间下的对象。此外getResourceItemsForScopepkg/archive/parser.go在列举对象时会去掉.json后缀说明归档中每个对象固定以.json结尾与文档示例完全一致。5.4 解压侧pkg/archive/extractor.go的安全解包备份归档的解压入口是 pkg/archive/extractor.go 的UnzipAndExtractBackup其实现与文档gzip 压缩 tar 文件的描述严格对应先用gzip.NewReader解 gzip再用tar.NewReader逐条读取 tar 条目并落盘。同时它还包含两个重要的安全防护可作为阅读文档时的补充知识解压大小上限默认maxExtractionSize 16 3016 GiB累计解压超过该值即中止防止 zip bombpkg/archive/extractor.go路径穿越防护sanitizeArchivePath校验每个条目路径都落在目标目录内杜绝 Zip Slip 类漏洞pkg/archive/extractor.go。六、实践如何下载并检查一个备份归档在当前仓库中查看备份归档内容的官方途径是velero backup download命令其 CLI 实现位于 pkg/cmd/cli/backup/download.govelero backup download BACKUP_NAME常用参数参数作用默认值--output, -o输出文件路径NAME-data.tar.gz当前目录--force目标文件已存在时强制覆盖否--timeout等待下载请求处理的最大时长1 分钟--insecure-skip-tls-verify跳过对象存储 TLS 证书校验仅测试环境使用否--cacert自定义 CA 证书包路径使用 BackupStorageLocation 配置的 CA拿到tar.gz后即可按第四节的结构手动验证归档内容tar -tzf BACKUP_NAME-data.tar.gz # 列出归档内全部条目 tar -xzf BACKUP_NAME-data.tar.gz # 解压到当前目录解压后对照resources/下的目录树检查metadata/version的格式版本号再结合对象存储中velero-backup.json的spec字段即可完整还原一次备份到底做了什么。文档还指出status.volumeBackups中的快照明细snapshotID、type、iops 等可以直接用于在云厂商控制台逐一核对快照是否创建成功——这是排查卷快照缺失类问题的常用手段。注意velero backup download仅下载 Kubernetes manifesttar.gz不包含持久卷快照的数据本体见 pkg/cmd/cli/backup/download.go 的 Long 描述。快照内容需通过云厂商侧的快照snapshot恢复。七、小结Velero 的备份输出文件格式是一套简洁而稳定的约定对象存储中每个备份一个目录目录内是元数据 JSON gzip tar 包的组合tar 包内部按resources/类型/cluster|namespaces/ns/对象.json的规则组织所有 Kubernetes 资源格式版本通过 JSON 中的status.version和 tar 内的metadata/version双重标识当前为1.1.0。理解这套格式不仅能帮助你手工验证、审计备份内容也是深入阅读 Velero 备份pkg/backup/backup.go与恢复pkg/archive/parser.go、pkg/archive/extractor.go核心链路的起点。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考