Ark（Velero 前身）v0.8.1 快速上手：基于 Minio 与 nginx 示例的 Kubernetes 备份/恢复实战指南

Ark（Velero 前身）v0.8.1 快速上手：基于 Minio 与 nginx 示例的 Kubernetes 备份/恢复实战指南

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

本指南以仓库中保留的历史文档 site/content/docs/v0.8.1/_index.md 为骨架，完整讲解 Heptio Ark（Velero 的前身）v0.8.1 的快速上手指南：如何在一个本地 Minio（S3 兼容对象存储）之上部署 Ark 服务端与命令行客户端，备份一个 nginx 示例应用，模拟灾难后完成恢复，并在最后安全清理环境。读完本文，你将掌握 Ark/Velero 核心工作流（部署 → 备份 → 灾难演练 → 恢复 → 清理）的每一步操作，并理解ark backup create、ark restore create等命令的关键参数与背后的实现原理。

项目背景：Ark 是什么，与 Velero 的关系

文档开篇即以 "Heptio Ark" 命名：Ark 提供了备份与恢复 Kubernetes 集群资源（cluster resources）和持久化卷（persistent volumes）的工具。它是 Velero 的前身，当前仓库即 Velero 项目，而site/content/docs/v0.8.1/目录则完整保留了 v0.8.1 时代以ark为命令前缀的官方文档。理解这段历史有助于你阅读旧教程、迁移到新版本命令（ark→velero、命名空间heptio-ark→velero）时快速对照。

按原文档，Ark 允许你：

• 对集群进行备份，并在集群丢失（loss）时恢复；
• 跨云厂商复制集群资源（注意：云卷迁移 Cloud volume migrations 尚未支持）；
• 复制生产环境到开发与测试环境。

Ark 由两部分组成：

• 一个运行在集群上的服务端（server）：负责编排备份与恢复流程；
• 一个运行在本地的工作站客户端（command-line client）：即ark命令行工具。

从当前仓库源码结构可以印证这一架构：命令行入口位于 cmd/velero/velero.go，服务端控制器（backup/restore controller）位于 pkg/controller/，而 Backup、Restore 等自定义资源（CRD）定义位于 pkg/apis/velero/。备份恢复的完整流程正是以"客户端创建自定义资源对象 → 服务端控制器 watch 并执行"的方式实现的。

环境准备（Prerequisites）

原文档列出的前提条件如下：

• 可访问一个Kubernetes 集群，版本 1.7 或更高；其中要运行ark backup delete命令需要1.7.5 或更高版本（该命令依赖较新的 CRD 删除机制，旧版本存在兼容性问题）；
• 集群内配置DNS 服务（Ark 服务端与 Minio 之间的服务发现依赖集群 DNS）；
• 本地已安装kubectl。

获取源码与版本选择

原文档推荐克隆或 fork Ark 仓库：

git clone [e-mail]:heptio/ark.git

注意：务必 checkout 到合适的版本。官方建议 checkout 最新的 tagged release，因为 main 分支处于活跃开发中，可能不稳定。

当前仓库对应的示例资源位于 examples/ 目录：examples/minio/用于快速搭建本地对象存储，examples/nginx-app/提供用于演练备份/恢复的示例应用，二者与本文主题一一对应。

部署服务端与本地对象存储

为了快速演示，Ark 需要对象存储作为备份的存放后端。原文档使用Minio——一个运行在集群内部的 S3 兼容存储服务，因此无需绑定任何云厂商账号即可完成全流程演练。

原文档在 Ark 仓库根目录下执行：

kubectl apply -f examples/common/00-prereqs.yaml kubectl apply -f examples/minio/

提示：如果遇到 "Config creation" 相关的报错，等待一分钟后再重新执行上述命令（这是 Kubernetes API 配置传播存在短暂延迟所致）。

需要说明的是，v0.8.1 时代的示例使用heptio-ark命名空间，而当前仓库中的 Minio 示例文件已演进为 examples/minio/00-minio-deployment.yaml，其中创建的资源如下：

资源	类型	说明
Namespacevelero	v1/Namespace	部署命名空间（旧版本为heptio-ark）
Deploymentminio	apps/v1	Minio 服务端，镜像minio/minio:latest，监听 9000 端口
Serviceminio	v1/Service	ClusterIP 类型，暴露 9000 端口供集群内部访问
Jobminio-setup	batch/v1	用minio/mc客户端创建名为velero的 bucket

该文件中的关键配置片段：

# examples/minio/00-minio-deployment.yaml（节选） apiVersion: v1 kind: Namespace metadata: name: velero --- apiVersion: apps/v1 kind: Deployment metadata: namespace: velero name: minio labels: component: minio spec: containers: - name: minio image: minio/minio:latest args: - server - /storage - --config-dir=/config env: - name: MINIO_ACCESS_KEY value: "minio" - name: MINIO_SECRET_KEY value: "minio123" ports: - containerPort: 9000

随后部署示例 nginx 应用：

kubectl apply -f examples/nginx-app/base.yaml

该文件（examples/nginx-app/base.yaml）定义了命名空间nginx-example（带标签app: nginx）、2 副本的 nginx Deployment（nginx:1.17.6）与一个 LoadBalancer 类型的 Servicemy-nginx，是演练备份/恢复的完美载体——因为整个命名空间的所有对象都带有app=nginx标签，可以直接用标签选择器做定向备份。

检查服务端与应用是否部署成功：

kubectl get deployments -l component=ark --namespace=heptio-ark kubectl get deployments --namespace=nginx-example

安装客户端

本例中，官方推荐下载预编译的 release 二进制，其中 ark.md 是命令总入口。

创建备份并模拟灾难

第一步：创建备份

为任何匹配app=nginx标签选择器的对象创建备份：

ark backup create nginx-backup --selector app=nginx

这里--selector app=nginx是标签选择器过滤，只有带app=nginx标签的对象才会被纳入备份。除标签选择器外，ark backup create还支持命名空间过滤、资源类型过滤、卷快照控制等参数，详见下文"CLI 参数详解"一节。

第二步：模拟灾难

删除整个示例命名空间：

kubectl delete namespace nginx-example

第三步：确认资源已消失

kubectl get deployments --namespace=nginx-example kubectl get services --namespace=nginx-example kubectl get namespace/nginx-example

此时应无任何输出结果。

提示：命名空间的彻底清理可能需要等待几分钟，删除过程是异步的。

恢复

执行恢复

ark restore create --from-backup nginx-backup

该命令从nginx-backup备份创建一次恢复。可选的RESTORE_NAME参数用于指定恢复名称，若不指定，将自动生成形如nginx-backup-<时间戳>的名称（见 site/content/docs/v0.8.1/cli-reference/ark_restore_create.md 中的示例说明）。

查看恢复状态

ark restore get

恢复完成后，输出形如：

NAME BACKUP STATUS WARNINGS ERRORS CREATED SELECTOR nginx-backup-20170727200524 nginx-backup Completed 0 0 2017-07-27 20:05:24 +0000 UTC <none>

各列含义：

• NAME：恢复对象的名称；
• BACKUP：本次恢复所依据的备份；
• STATUS：恢复阶段，执行期间为InProgress，完成后为Completed；
• WARNINGS/ERRORS：恢复过程中的告警与错误计数；
• CREATED：创建时间；
• SELECTOR：若恢复时指定了标签选择器则显示。

注意：恢复可能耗时片刻，期间STATUS列显示为InProgress。成功完成后STATUS为Completed，且WARNINGS与ERRORS均为 0。届时nginx-example命名空间中的所有对象都应恢复到删除前的状态。

排查恢复中的告警与错误

如果WARNINGS或ERRORS不为 0，可以查看详细内容：

ark restore describe <RESTORE_NAME>

关于告警与错误的详细结构，site/content/docs/v0.8.1/debugging-restores.md 给出了权威解释：

• STATUS 为Completed并不代表恢复过程零问题——只要恢复流程走完，状态就会置为Completed，而问题多少体现在WARNINGS/ERRORS计数中；
• Errors表示恢复不完整或部分失败的阻塞性问题；
• Warnings表示非阻塞性告警（例如备份中引用的资源已以某种形式存在，导致"已存在"类告警）。

告警与错误均按相同三级结构组织：

• Ark：Ark 服务端自身遇到的系统性问题（如无法读取目录）；
• Cluster：与集群级（cluster-scoped）资源恢复相关的问题；
• Namespaces：以"命名空间 → 该命名空间内资源恢复问题列表"形式组织的映射。

清理环境

删除备份数据

如果要删除已创建的备份（包括对象存储中的数据与持久化卷快照）：

ark backup delete BACKUP_NAME

该命令会请求 Ark 服务端删除与BACKUP_NAME关联的全部备份数据。每个备份都需要单独执行一次；原文档指出，未来的版本将支持按名称或标签选择器批量删除多个备份（这一能力在后继 Velero 版本中已实现）。当备份被彻底移除后，再执行：

ark backup get BACKUP_NAME

将不再看到该备份。

卸载 Ark 但保留数据

如果想卸载 Ark 但保留对象存储与持久化卷快照中的备份数据，可以安全地删除heptio-ark命名空间及本例创建的其他资源：

kubectl delete -f examples/common/ kubectl delete -f examples/minio/ kubectl delete -f examples/nginx-app/base.yaml

（在当前仓库布局下，对应的对象为examples/minio/00-minio-deployment.yaml与examples/nginx-app/base.yaml。）

进阶：接入云厂商对象存储与 PV 快照

快速上手示例用 Minio 屏蔽了云厂商差异。在真实环境中，需要将对象存储指向云厂商服务，具体见 site/content/docs/v0.8.1/cloud-common.md，该文档分场景提供了 AWS、GCP、Azure、IBM Cloud Object Store 的配置指引，并提到自 0.7.0 起 Ark 可运行在任意命名空间（需额外定制，见 namespace.md）。

云厂商场景下还支持PV 快照。文档中的快照示例使用 examples/nginx-app/with-pv.yaml：它额外定义了一个 50Mi 的 PVCnginx-logs，将其挂载到 nginx 容器的/var/log/nginx目录，并利用fsfreeze hooks（备份前冻结文件系统、备份后解冻）保证快照一致性：

# examples/nginx-app/with-pv.yaml（节选） metadata: annotations: pre.hook.backup.velero.io/container: fsfreeze pre.hook.backup.velero.io/command: '["/sbin/fsfreeze", "--freeze", "/var/log/nginx"]' post.hook.backup.velero.io/container: fsfreeze post.hook.backup.velero.io/command: '["/sbin/fsfreeze", "--unfreeze", "/var/log/nginx"]'

快照演练流程与基础示例几乎一致，区别在于：

1. 部署examples/nginx-app/with-pv.yaml而非base.yaml；
2. 备份命令同样使用ark backup create nginx-backup --include-namespaces nginx-example，但由于资源中带有 PVC，默认（--snapshot-volumes=true）会触发云厂商的卷快照；
3. 模拟灾难时需注意：动态制备的 PV 默认 reclaim policy 为Delete，删除命名空间会异步触发云厂商删除底层磁盘，务必在下一步恢复前到云厂商控制台确认磁盘已不存在；
4. 恢复命令相同：ark restore create --from-backup nginx-backup。

特别提示（Azure）：使用 Azure 托管磁盘做 PV 快照，集群版本需为 1.7.2+。

CLI 参数详解：backup create 与 restore create

原文档主页面只演示了最基本的用法，仓库中的 CLI 参考文档给出了完整参数清单。下表整理自 site/content/docs/v0.8.1/cli-reference/ark_backup_create.md：

ark backup create NAME [flags]主要参数：

参数	类型/默认值	说明
--include-namespaces	stringArray，默认*	备份包含的命名空间（*表示全部）
--exclude-namespaces	stringArray	备份排除的命名空间
--include-resources	stringArray	备份包含的资源，格式resource.group，如storageclasses.storage.k8s.io
--exclude-resources	stringArray	备份排除的资源，格式同上
--include-cluster-resources	optionalBool，默认true	是否包含集群级资源
-l, --selector	labelSelector，默认<none>	仅备份匹配该标签选择器的资源（本文示例即使用此参数）
--snapshot-volumes	optionalBool，默认true	备份时是否对 PersistentVolume 拍摄快照
--ttl	duration，默认720h0m0s（30 天）	备份可被垃圾回收前保留的时长
--labels	mapStringString	应用到备份对象上的标签
--label-columns/--show-labels	-	结果展示时的标签列控制
-o, --output	string	输出格式table/json/yaml；对 create 命令而言仅显示对象而不发送到服务端

ark restore create [RESTORE_NAME] --from-backup BACKUP_NAME [flags]主要参数（见 ark_restore_create.md）：

参数	类型/默认值	说明
--from-backup	string（必填）	恢复所依据的备份名称
--namespace-mappings	mapStringString	命名空间映射，格式src1:dst1,src2:dst2,...，可将备份中的命名空间恢复到新名称
--include-namespaces/--exclude-namespaces	stringArray	恢复包含/排除的命名空间
--include-resources/--exclude-resources	stringArray	恢复包含/排除的资源类型
--include-cluster-resources	optionalBool，默认true	是否包含集群级资源
--restore-volumes	optionalBool，默认true	是否从快照恢复卷
-l, --selector	labelSelector	仅恢复匹配该标签选择器的资源

两个命令都继承自父命令的通用参数，其中-n, --namespace（默认heptio-ark）用于指定 Ark 自身操作所在的命名空间，与部署时保持一致；--kubeconfig、--kubecontext控制与 Kubernetes API server 的连接方式。

排障指引

原文档将排障归纳为三类，分别对应仓库中的专题文档：

• 安装/配置问题：见 site/content/docs/v0.8.1/debugging-install.md；
• 命名空间与备份删除问题：见 site/content/docs/v0.8.1/debugging-deletes.md；
• 恢复问题：见 site/content/docs/v0.8.1/debugging-restores.md，重点理解上文所述的Ark/Cluster/Namespaces三级告警与错误结构。

综合排障入口为 site/content/docs/v0.8.1/troubleshooting.md，此外也可以向项目提交 issue 或加入官方 Slack 的#ark-dr频道讨论（外部链接此处不展开）。

小结

通过本指南，你已完整走通了一条 Ark v0.8.1 的本地演练链路：借助 Minio 在集群内搭建 S3 兼容对象存储 → 部署 Ark 服务端与 nginx 示例应用 → 用ark backup create --selector做标签定向备份 → 删除命名空间模拟灾难 → 用ark restore create --from-backup完成恢复并用ark restore get/describe校验结果 → 通过ark backup delete清理数据。这套"备份-灾难演练-恢复-清理"的闭环方法论与命令心智模型，在 Velero 后续版本中一脉相承（命令前缀ark演化为velero，命名空间heptio-ark演化为velero），是理解整个 Kubernetes 备份生态最扎实的起点。如需深入架构细节、扩展插件机制（hooks 与 plugins，见 hooks.md 与 plugins.md）或输出文件格式（output-file-format.md），仓库内的 v0.8.1 文档目录是完整的第一手资料。

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