VeleroArk备份输出文件格式深度解析tar.gz 归档、ark-backup.json 与目录结构全指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读备份文件的组织方式决定了数据能否被可靠地恢复与审计。本文以 Velero前身 Arkv0.6.0 的官方文档 output-file-format.md 为骨架完整讲解备份归档gzip 压缩的 tar 文件的命名规则、云端存储目录布局、ark-backup.json清单文件的字段含义以及归档内部的resources/目录层级并结合当前仓库源码pkg/backup、pkg/archive、pkg/apis/velero/v1补充格式版本号、元数据目录、API 组版本目录等演进细节。读完你将能手动解包备份、核对快照信息、定位特定资源的 JSON 文件并对 Velero 备份格式的历史与现状建立完整认知。备份文件是什么一个 gzip 压缩的 tar 归档在 Velerov0.6.0 时代名为 Ark中一次备份最终落盘的产物是一个 gzip 压缩的 tar 文件其文件名与 Backup API 资源对象Backup CR的metadata.name完全一致——即执行ark backup create NAME现在为velero backup create NAME时指定的名称。也就是说velero backup create backup1234会在对象存储中生成名为backup1234.tar.gz的归档文件。这种命名约定保证了备份名字与存储文件的一一对应你通过命令行创建的每个备份都能在对象存储的固定位置找到同名文件。从当前仓库源码看这一gzip 压缩 tar 归档的写入逻辑至今依然成立。在 pkg/backup/backup.go 的BackupWithResolvers函数中备份文件首先经过gzip.NewWriter压缩再交给tar.NewWriter写入gzippedData : gzip.NewWriter(backupFile) defer gzippedData.Close() tw : NewTarWriter(tar.NewWriter(gzippedData)) defer tw.Close()对应的解包逻辑则在 pkg/archive/extractor.goUnzipAndExtractBackup先用gzip.NewReader解压再通过tar.NewReader逐个读出归档条目并解包到本地临时目录。两处代码共同印证.tar.gz既是备份的物理格式也是 Velero 恢复时解析备份的标准入口。对象存储中的目录布局每个备份一个子目录备份文件在云端对象存储中并非散落平铺而是每个备份文件存放于桶bucket下的独立子目录中。子目录位于 Ark/Velero 服务端配置所指定的 bucket 之下其中除了.tar.gz归档外还额外包含一个名为ark-backup.json早期版本或velero-backup.json的清单文件。整体目录结构形如rootBucket/ backup1234/ ark-backup.json backup1234.tar.gz这一布局的含义是所有与某次备份相关的元数据与数据本体被放在同一目录下便于统一管理、清理与审计。ark-backup.json备份的完整历史档案ark-backup.json明确列出了与本次备份关联的 Backup 资源的全部信息——包括所有被显式或隐式默认值使用的配置项从而形成一份完整的历史记录。它还包含status.version字段该字段对应备份输出文件的格式版本下文详述。之所以强调包括默认值是因为用户创建备份时可能只指定了少量参数而服务端会填充大量默认值例如snapshotVolumes: true、ttl: 24h0m0s。这份 JSON 将这些最终生效的配置快照下来日后无论是排查问题、审计合规还是理解当初到底备份了什么都有一份权威依据。从实现角度看这与当前仓库中BackupAPI 类型的序列化逻辑一脉相承。完整字段定义可查阅 pkg/apis/velero/v1/backup.goBackupSpec、BackupStatus结构体归档被写入对象存储的流程见 pkg/controller/backup_controller.go。一个真实的ark-backup.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 } }对关键字段的逐项说明字段含义与说明kind/apiVersionKubernetes API 对象的类型与版本。示例中为 Ark 时代的ark.heptio.com/v1在后续版本中演进为velero.io/v1metadata.name备份名称与ark backup create指定的名称一致同时也是.tar.gz文件名metadata.uid/resourceVersion/creationTimestampKubernetes 为对象生成的标准标识与时间戳用于唯一标识本次备份spec.includedNamespaces纳入备份的命名空间列表*表示全部spec.excludedNamespaces排除的命名空间列表null表示不排除spec.includedResources/excludedResources纳入/排除的资源类型列表*表示全部资源spec.labelSelector按标签选择器过滤备份对象null表示不过滤spec.snapshotVolumes是否对持久卷创建云快照true表示启用spec.ttl备份保留时长如24h0m0s超过后会被垃圾回收status.version输出文件格式版本号本示例为1status.expiration由ttl计算出的过期时间点status.phase备份所处阶段如Completedstatus.volumeBackups卷快照明细详见下文status.validationErrors校验错误列表null表示无错误status.volumeBackups云控制台核对快照的利器示例中最值得注意的字段是status.volumeBackups——它以PVC 名称为键列出每个持久卷对应的云快照信息volumeBackups: { pvc-e1e2d345-7583-11e7-b4c2-abcdef123456: { snapshotID: snap-04b1a8e11dfb33ab0, type: gp2, iops: 100 } }snapshotID云厂商侧的快照 ID示例为 AWS 的snap-...格式type卷类型示例为 AWS 的gp2iops预置 IOPS 值。原文档特别提示如果你想在云厂商的 GUI 控制台中手动核对这些快照这份文件会非常有用。通过snapshotID可以直接在控制台搜索到对应快照从而确认快照是否按预期创建、是否与备份一一对应。文件格式版本status.version的语义status.version示例中为1对应的就是备份输出文件的格式版本。格式版本的意义在于当 Velero 未来改变归档内部布局如新增目录、调整文件名时通过版本号可以在不破坏旧备份的前提下安全演进恢复程序可以依据版本号选择正确的解析路径。从当前仓库源码看格式版本机制已经进一步细化。在 pkg/backup/backup.go 中定义了两个版本常量// BackupVersion is the current backup major version for Velero. // Deprecated, use BackupFormatVersion const BackupVersion 1 // BackupFormatVersion is the current backup version for Velero, including major, minor, and patch. const BackupFormatVersion 1.1.0BackupVersion旧的大版本号当前为1已被标记为 DeprecatedBackupFormatVersion新的带主版本.次版本.补丁的完整版本号当前为1.1.0用于标识备份归档的格式演进。归档内部还专门有一个版本标记文件。在 pkg/backup/backup.go 的writeBackupVersion函数中备份开始写入时会先向 tar 中写入metadata/version文件内容即BackupFormatVersionfunc (kb *kubernetesBackupper) writeBackupVersion(tw tarWriter) error { versionFile : filepath.Join(velerov1api.MetadataDir, version) versionString : fmt.Sprintf(%s\n, BackupFormatVersion) ... }这说明格式版本不仅记录在ark-backup.json的status.version中还以独立文件的形式存在于 tar 归档内部metadata/version双保险地标注了归档格式。metadata目录常量定义于 pkg/apis/velero/v1/constants.go。解包后的归档内部结构格式版本 1当.tar.gz归档被解压后典型的结构如下示例文件backup1234.tar.gzresources/ 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/ ... ...目录层级规则这一结构的组织规律非常清晰可以归纳为**资源类型 → 作用域 → 命名空间 → 单个对象 JSON**四层顶层固定为resources/目录其下每个子目录对应一种资源类型如persistentvolumes、configmaps、pods、jobs、deployments目录名采用资源复数名资源类型小写复数形式每种资源下再按作用域分为两类cluster/存放**集群级别cluster-scoped**的资源实例如PersistentVolume这类不隶属于任何命名空间的资源namespaces/存放命名空间级资源其下再按命名空间分子目录namespace1/、namespace2/最底层是每个 Kubernetes 对象序列化后的 JSON 文件文件名即对象名如pv01.json、mypod.json、awesome-job.json。这套资源按类型分目录、集群与命名空间分作用域、命名空间内按对象逐个 JSON 落盘的设计使备份内容高度结构化既可被恢复程序逐对象精准解析也方便人工用tar -tzf或find快速定位某个对象。源码与测试的印证从当前仓库源码看这套目录常量与解析逻辑被完整保留并演进目录名常量定义于 pkg/apis/velero/v1/constants.goResourcesDir resourcesClusterScopedDir clusterNamespaceScopedDir namespacesPreferredVersionDir -preferredversionAPI 组首选版本目录后缀见下文解析器 pkg/archive/parser.go 的Parse函数正是按上述规则遍历归档先检查顶层resources目录再为每个资源子目录读取cluster与namespaces两类子目录最终组装出ResourceItems结构GroupResourceItemsByNamespace其中集群级资源以空字符串作为 namespace 键。测试用例 pkg/archive/parser_test.go 给出了真实风格的归档文件列表例如root-dir/resources/widgets.foo/cluster/item-1.json root-dir/resources/widgets.foo/namespaces/ns-1/item-1.json root-dir/resources/widgets.foo/namespaces/ns-2/item-1.json root-dir/resources/dongles.bar/namespaces/ns-3/item-4.json注意这里的widgets.foo这种目录名资源目录名采用resource.group格式即资源复数名 点号 API 组名对于核心coreAPI 组则省略.group后缀如pods、configmaps。这一格式在 pkg/archive/parser.go 的extractGroupName中通过SplitN(resourceGroupDir, ., 2)解析。版本 1 之后的格式演进以仓库源码为准原文档所述的是文件格式版本 1对应 Ark v0.6.0。以当前仓库源码为据格式已经做了若干演进了解这些有助于你阅读新旧不一的备份归档新增metadata/version文件归档顶层除resources/外还包含metadata/目录见 pkg/apis/velero/v1/constants.go 的MetadataDir metadata内部写入格式版本号pkg/backup/backup.go。资源目录下出现 API 组版本子目录当启用EnableAPIGroupVersions特性时resources/resource.group/下会出现v1-preferredversion、v2beta1等按 API 版本划分的子目录其中-preferredversion后缀标记服务端首选版本。解析逻辑见 pkg/archive/parser.go 的ParseGroupVersions函数——它从目录名提取 API 组与版本构造metav1.APIGroup结构。解包防护机制新版解包器 pkg/archive/extractor.go 加入了解压体积上限默认 16 GiB见maxExtractionSize与路径穿越防护Zip Slip 防护sanitizeArchivePath防止恶意或损坏的归档在解包时耗尽磁盘或逃逸临时目录——这也是在处理不受信任的备份文件时需要了解的安全边界。实际排查与使用场景速查基于以上格式知识你可以通过以下方式直接操作备份产物列出归档内容快速确认某对象是否在备份中# 下载备份归档后列出顶层目录与关键对象 tar -tzf backup1234.tar.gz | head -50 tar -tzf backup1234.tar.gz | grep pods/namespaces/nginx-example/解包并查看某个对象的完整 JSONmkdir -p extracted tar -xzf backup1234.tar.gz -C extracted cat extracted/resources/deployments/namespaces/default/cool-deployment.json核对卷快照读取同目录下的ark-backup.json或新版本的velero-backup.json依据status.volumeBackups.pvc-name.snapshotID到云厂商控制台检索对应快照。判断归档格式版本查看ark-backup.json的status.version或直接读取归档内metadata/version文件tar -xOf backup1234.tar.gz metadata/version总结备份输出文件格式是 Velero 可靠性与可审计性的基石name.tar.gz以一备份一子目录的方式组织于对象存储配套的ark-backup.json完整记录了 Backup 资源的最终配置含默认值、格式版本号status.version与卷快照明细status.volumeBackups解包后则呈现为resources/resource.group/{cluster,namespaces/ns}/object.json的高度结构化层级。当前仓库源码pkg/backup/backup.go、pkg/archive/parser.go、pkg/archive/extractor.go在保留这套核心结构的同时已演进出版本号文件metadata/version、API 组版本目录与安全防护机制。理解这套格式无论对于备份排障、手工审计还是二次开发都是扎实的起点。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考