企业官网建设流程全解析

Heptio Ark v0.7.0 快速上手：Kubernetes 集群备份与持久卷恢复实战指南

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

Heptio Ark（即 Velero 的前身）是面向 Kubernetes 的集群备份与恢复工具，本指南以其 v0.7.0 版本文档（site/content/docs/v0.7.0/_index.md）为主体，完整演示如何在一套集群上部署 Ark 服务端与命令行客户端，使用 Minio 本地对象存储完成一次真实的"备份—模拟灾难—恢复"演练，并结合仓库中的源码与示例文件深入讲解架构、Config 配置、Backup API 类型、备份钩子与排障方法。读完本文，你将能够独立完成 Ark 的安装、配置、备份、恢复全流程，并理解其底层工作原理。

背景说明：Heptio Ark 在后续演进中更名为 Velero（即本仓库当前项目名），CLI 从ark变为velero，API 组从ark.heptio.com/v1变为velero.io/v1，默认命名空间从heptio-ark变为velero。本文严格以 v0.7.0 时代文档为准，同时标注与现代仓库的对应关系，便于对照学习。

Ark 是什么：能做什么，由什么组成

Ark 提供了一整套工具，用于备份和恢复 Kubernetes 集群资源以及持久卷（Persistent Volumes），核心能力包括：

• 对集群进行备份，并在发生丢失时进行恢复（灾备场景）；
• 将集群资源复制到其他云提供商（注意：v0.7.0 尚不支持跨云提供商的卷迁移）；
• 复制生产环境用于开发与测试环境。

从组成上看，Ark 由两部分构成（site/content/docs/v0.7.0/about.md）：

• 运行在集群上的服务端（server）：以 Deployment 形式运行，内部由一组自定义控制器组成；
• 运行在本地的工作站客户端（command-line client）：即ark命令行工具，向 Kubernetes API Server 提交备份/恢复请求。

操作模型：一切都是自定义资源

Ark 的每一次操作（按需备份、定时备份、恢复）都是一个 Kubernetes 自定义资源（CRD），存储在 etcd 中；另有一个名为Config的自定义资源用来指定云提供商等必要配置。这些资源由对应的自定义控制器（custom controllers）负责处理：控制器监听自定义资源的 API 请求，执行校验，并负责与云提供商 API 交互——例如管理对象存储和持久卷快照。

备份工作流（Backup workflow）

以ark backup create test-backup为例，完整流程如下（site/content/docs/v0.7.0/about.md）：

1. Ark 客户端向 Kubernetes API Server 发起请求，创建一个Backup对象；
2. BackupController发现新的Backup对象并执行校验；
3. BackupController开始备份过程，通过查询 API Server 收集要备份的资源数据；
4. BackupController调用对象存储服务（如 AWS S3）上传备份文件。

默认情况下ark backup create会为持久卷创建磁盘快照，可通过--snapshot-volumes=false关闭，或使用其他参数精确控制（详见 ark backup create 命令参考）。

需要注意：集群备份不是严格原子的。如果备份执行期间 Kubernetes 对象正在被创建或编辑，它们可能不会被包含在备份中；捕获到不一致信息的概率较低，但确实存在这种可能。

备份过期机制与对象存储同步

创建备份时可使用--ttl <DURATION>指定过期时间（默认 30 天/720 小时）。当 Ark 发现某个 Backup 资源已过期，会删除：Backup 资源本身、云端对象存储中的备份文件、所有持久卷快照以及所有关联的 Restore。

Ark 将对象存储视为唯一事实来源（source of truth）：它会持续检查对象存储与 Backup 资源的对应关系。如果存储桶中存在格式正确的备份文件，但 Kubernetes API 中缺少对应的 Backup 资源，Ark 会反向将信息从对象存储同步到 Kubernetes——这正是集群迁移场景下恢复功能得以工作的基础。

快速开始：用 Minio 完成一次完整演练

为简单起见，v0.7.0 官方文档使用Minio（一个运行在集群内部的 S3 兼容对象存储服务）作为演练环境；在真实云环境中，参考 在云提供商上运行 Ark 分别设置 AWS/GCP/Azure。

前置条件（Prerequisites）

• 可访问的 Kubernetes 集群，版本1.7 或更高；要使用ark backup delete需要1.7.5 或更高；
• 集群上有 DNS 服务；
• 已安装kubectl。

获取源码（Download）

克隆或 Fork Ark 仓库：

git clone git@github.com:heptio/ark.git

重要：务必检出合适的版本。官方建议检出最新的 tagged 版本，main 分支处于活跃开发状态，可能不稳定。

在当前仓库中，v0.7.0 时代的文档保留在 site/content/docs/v0.7.0/ 目录下，可直接对照阅读。

部署服务端（Set up server）

在 Ark 仓库根目录下依次执行以下命令，启动服务端与本地存储服务：

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

注意：如果出现关于 Config 创建的报错，等一分钟后再重新执行这些命令。

路径说明：v0.7.0 时代的examples/common/与examples/aws/等目录在当前仓库快照中已不存在；当前仓库保留了 examples/minio/00-minio-deployment.yaml 与 examples/nginx-app/base.yaml 等示例，Minio 部署文件的整体结构（Namespace + Minio Deployment + Service + 初始化 Job）与 v0.7.0 一致，可直接对照学习。

部署 Minio 的 YAML 文件包含了四个关键部分，展示了 Ark 本地存储的搭建方式：

• Namespace：velero（v0.7.0 时代为heptio-ark），所有组件共用；
• Minio Deployment：镜像minio/minio:latest，启动参数server /storage --config-dir=/config，通过环境变量MINIO_ACCESS_KEY=minio、MINIO_SECRET_KEY=minio123配置访问凭据，暴露 9000 端口；
• Service：ClusterIP类型，将 9000 端口暴露给集群内部（生产环境建议 ClusterIP；仅测试/试用环境可改为 NodePort）；
• minio-setup Job：使用minio/mc客户端执行两条命令——先用mc alias set velero http://minio:9000 minio minio123建立别名，再用mc mb -p velero/velero创建名为velero的存储桶。

接下来部署示例 nginx 应用：

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

检查 Ark 与 nginx 两个 Deployment 是否创建成功：

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

安装客户端（Install client）

v0.7.0 时代官方推荐直接下载预编译的 release 二进制，也可以从源码构建；确保将其安装到$PATH中的某个目录。

执行备份（Back up）

1. 创建备份，只包含匹配app=nginx标签选择器的对象：

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

2. 模拟灾难：

   kubectl delete namespace nginx-example

3. 确认 nginx 的 Deployment 与 Service 已消失：

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

   此时应该没有任何输出。命名空间彻底清理可能需要等待几分钟。

执行恢复（Restore）

1. 从nginx-backup创建恢复：

   ark restore create nginx-backup

2. 查看恢复状态：

   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>

   注意：恢复过程可能需要片刻，期间STATUS列为InProgress。成功恢复后STATUS变为Completed，WARNINGS和ERRORS为 0，nginx-example命名空间中的所有对象应恢复到删除前的状态。

如果存在错误或警告，可用以下命令查看详细信息：

ark restore describe <RESTORE_NAME>

清理（Clean up）

演练结束后，移除本示例创建的所有 Kubernetes 对象：

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

云环境下的两种典型演练场景

在真实云提供商环境中，cloud-common.md 给出了两种演练模式：不涉及持久卷的基础示例，以及涉及持久卷快照的示例。

基础示例（无持久卷）

# 1. 启动示例 nginx 应用 kubectl apply -f examples/nginx-app/base.yaml # 2. 按命名空间创建备份 ark backup create nginx-backup --include-namespaces nginx-example # 3. 模拟灾难 kubectl delete namespaces nginx-example # 4. 恢复丢失的资源 ark restore create nginx-backup

快照示例（含持久卷）

注意：对于 Azure，集群需要 1.7.2+ 才能支持托管磁盘的 PV 快照。

# 1. 启动带持久卷的示例应用 kubectl apply -f examples/nginx-app/with-pv.yaml # 2. 创建带 PV 快照的备份 ark backup create nginx-backup --include-namespaces nginx-example # 3. 模拟灾难 kubectl delete namespaces nginx-example

由于动态制备的 PV 默认回收策略（reclaim policy）是 "Delete"，上述命令会触发云提供商删除 PV 底层的磁盘。删除过程是异步的，可能耗时较长。继续下一步之前，务必到云提供商控制台确认磁盘确实已不存在。

# 4. 恢复丢失的资源 ark restore create nginx-backup

with-pv.yaml示例（当前仓库中的 examples/nginx-app/with-pv.yaml）展示了两个关键细节：

• PVC 声明：nginx-logsPVC 申请 50Mi 的ReadWriteOnce存储，可注释storageClassName以使用默认存储类；
• 备份钩子注解：Pod 上标注了pre.hook.backup.velero.io/...与post.hook.backup.velero.io/...，通过fsfreeze冻结/解冻文件系统，保证日志目录在快照前完成磁盘 I/O 落盘（详见下文"备份钩子"章节）。

深入理解 Ark Config：配置参数全解析

Ark 通过自定义资源Config指定备份与云提供商设置。服务端首次部署后会等待你在heptio-ark命名空间中创建名为default的 Config。一个典型的 Config 示例如下（config-definition.md）：

apiVersion: ark.heptio.com/v1 kind: Config metadata: namespace: heptio-ark name: default persistentVolumeProvider: name: aws config: region: us-west-2 backupStorageProvider: name: aws bucket: ark config: region: us-west-2 backupSyncPeriod: 60m gcSyncPeriod: 60m scheduleSyncPeriod: 1m restoreOnlyMode: false

注意：v0.7.0 假设 Ark 服务端以 Kubernetes Deployment 形式运行。如果修改defaultConfig，服务端会优雅退出；当 kubelet 重启 Ark 服务端 Pod 后，服务端将使用更新后的配置值。

主配置参数（Main config parameters）

AWS（及其他 S3 兼容存储）配置

backupStorageProvider/config：

persistentVolumeProvider/config（仅 AWS）：region（string，必填），例如 "us-east-1"。

GCP 配置

• backupStorageProvider/config：无需参数。
• persistentVolumeProvider/config：project（string，必填），例如 "project-example-3jsn23"。

Azure 配置

• backupStorageProvider/config：无需参数。
• persistentVolumeProvider/config：
  • location（string，必填）：例如 "Canada East"（Azure 文档中称为 Regions）；
  • apiTimeout（metav1.Duration，默认2m0s）：等待 Azure API 请求完成的最长时间。

用 Backup API 类型精确控制备份

Backup属于 API 组ark.heptio.com/v1，创建后 Ark 服务端立即开始备份流程。以下是一个包含全部字段说明的示例（api-types/backup.md）：

apiVersion: ark.heptio.com/v1 kind: Backup metadata: name: a # v0.7.0 起可以是任意字符串，但必须是 Ark 服务端所在的命名空间 namespace: heptio-ark spec: # 要包含的命名空间数组；未指定则包含所有命名空间 includedNamespaces: - '*' # 要排除的命名空间数组 excludedNamespaces: - some-namespace # 要包含的资源数组；可使用缩写（如 'po' 代表 'pods'）或全限定名 includedResources: - '*' # 要排除的资源数组 excludedResources: - storageclasses.storage.k8s.io # 是否包含集群级资源。true=全部包含；false=不包含；null/未设置=仅当包含所有命名空间且无排除时才全部包含， # 否则仅备份与命名空间级资源关联的集群级资源（如 PVC 关联的 PV） includeClusterResources: null # 对象必须匹配该标签选择器才会被纳入备份 labelSelector: matchLabels: app: ark component: server # 是否对卷做快照。仅适用于 Azure、GCE、AWS 的 PV。 # 未设置时，只要配置了持久卷提供商就执行快照 snapshotVolumes: null # 备份可被垃圾回收前的时间 ttl: 24h0m0s # 备份期间不同阶段要执行的动作；目前唯一支持的钩子是使用 pod exec API 在容器内执行命令 hooks: resources: - name: my-hook includedNamespaces: - '*' excludedNamespaces: - some-namespace includedResources: - pods excludedResources: [] labelSelector: matchLabels: app: ark component: server # 已废弃，改用 pre hooks: [] # 自定义 action 执行前运行的钩子；目前仅支持 "exec" pre: - exec: container: my-container command: - /bin/uname - -a onError: Fail timeout: 10s # 所有自定义 action 及附加项处理完成后运行的钩子；内容同 pre post: - exec: container: my-container command: - /bin/uname - -a onError: Fail timeout: 10s status: expiration: null phase: "" validationErrors: null version: 1 volumeBackups: some-pv-name: snapshotID: snap-1234 type: io1 availabilityZone: my-zone iops: 10000

其中includeClusterResources的逻辑值得特别注意：如果includedNamespaces或excludedNamespaces中指定了至少一个命名空间，则备份的集群级资源仅限于与已包含的命名空间级资源关联的部分（例如 PVC 被包含时，其关联的集群级 PV 也会被备份）。status.volumeBackups记录了恢复所需的 PV 信息（快照 ID、卷类型、可用区、IOPS），由系统填充，用户不应手动设置。

备份钩子（Hooks）：文件系统冻结实战

备份钩子是保证数据一致性的关键机制。v0.7.0 起 Ark 同时支持pre 钩子（在任何自定义 action 处理之前执行）与post 钩子（在所有自定义 action 完成、且自定义 action 指定的附加项都已备份之后执行）。经典场景是文件系统冻结：用 pre 钩子执行fsfreeze --freeze确保待处理的磁盘 I/O 全部落盘，随后 Ark 对磁盘做快照，最后用 post 钩子执行fsfreeze --unfreeze解冻（hooks.md）。

指定钩子有两种方式：Pod 注解与Backup spec（上文 Backup API 示例中的spec.hooks即第二种方式）。

通过 Pod 注解指定钩子

Pre 钩子注解（v0.7.0 起支持不带pre.前缀的旧写法，如hook.backup.ark.heptio.com/container，但已废弃）：

Post 钩子注解（v0.7.0+）：

在当前仓库的源码中，钩子注解键已迁移为velero.io后缀，定义于 internal/hook/item_hook_handler.go：

• 备份钩子：hook.backup.velero.io/container、hook.backup.velero.io/command、hook.backup.velero.io/on-error、hook.backup.velero.io/timeout；
• 恢复钩子：post.hook.restore.velero.io/container、post.hook.restore.velero.io/command、post.hook.restore.velero.io/on-error、post.hook.restore.velero.io/exec-timeout、post.hook.restore.velero.io/wait-timeout等。

同时，源码中的ItemHookHandler接口（internal/hook/item_hook_handler.go）明确了钩子执行的核心逻辑：当被处理对象是 Pod 且存在相应注解时执行注解钩子；否则依据 Backup 上下文中的钩子定义，结合钩子 spec 的命名空间、资源与标签选择器决定是否对该对象执行钩子，并区分pre与post两个阶段。这与 v0.7.0 文档描述的执行时机完全一致，可作为理解钩子内部机制的入口。

with-pv.yaml中 fsfreeze 钩子的实际写法（当前仓库版本，注解键为velero.io）：

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"]'

对应的 Pod 中需要有一个特权容器（securityContext.privileged: true）挂载同一卷来执行冻结命令，保证日志卷在快照瞬间数据一致。

恢复排障：理解 WARNINGS 与 ERRORS

无论恢复过程中是否有问题，Ark 完成 Restore 后状态都会变为 "Completed"，问题数量体现在ark restore get输出的WARNINGS与ERRORS列中。v0.7.0 文档给出了真实输出示例（debugging-restores.md）：

NAME BACKUP STATUS WARNINGS ERRORS CREATED SELECTOR backup-test-20170726180512 backup-test Completed 155 76 2017-07-26 11:41:14 -0400 EDT <none> backup-test-20170726180513 backup-test Completed 121 14 2017-07-26 11:48:24 -0400 EDT <none> backup-test-2-20170726180514 backup-test-2 Completed 0 0 2017-07-26 13:31:21 -0400 EDT <none> backup-test-2-20170726180515 backup-test-2 Completed 0 1 2017-07-26 13:32:59 -0400 EDT <none>

用ark restore describe深入查看：

ark restore describe backup-test-20170726180512

输出中先展示恢复配置（Backup、Included/Excluded 命名空间与资源、命名空间映射、标签选择器、Restore PVs、Phase、Validation errors），随后按 Warnings 与 Errors 分段展示明细。典型示例如下：

Warnings: Ark: <none> Cluster: <none> Namespaces: heptio-ark: serviceaccounts "ark" already exists serviceaccounts "default" already exists kube-system: serviceaccounts "attachdetach-controller" already exists ... Errors: Ark: <none> Cluster: <none> Namespaces: <none>

错误与警告的语义区分：Errors 针对不完整或部分完成的恢复；Warnings 针对非阻塞性问题——恢复看起来"正常"，备份中引用的资源都以某种形式存在，只是其中一些可能已经预先存在（例如上例中大量serviceaccounts "xxx" already exists）。

两者的结构完全一致，均分三级：

• Ark：Ark 服务端遇到的系统相关问题（如无法读取目录）；
• Cluster：与集群级资源恢复相关的问题；
• Namespaces：命名空间到问题列表的映射，记录各命名空间资源恢复时遇到的问题。

进阶使用场景：灾备与集群迁移

场景一：灾难恢复（Disaster recovery）——定时备份 + 只读恢复模式

利用 Schedule 定时备份，可在意外事故（如服务中断）后恢复到先前状态（use-cases.md）：

1. 在集群上首次运行 Ark 服务端后，创建每日备份（按需替换<SCHEDULE NAME>）：

   ark schedule create <SCHEDULE NAME> --schedule "0 7 * * *"

   这会创建一个名为<SCHEDULE NAME>-<TIMESTAMP>的 Backup 对象，其中<TIMESTAMP>格式为YYYYMMDDhhmmss。Schedule 本质上是 Backup 的包装器：被触发时在后台创建 Backup。

2. 灾难发生，需要重建资源。

3. 更新 Ark 服务端的 Config，将restoreOnlyMode设为true，防止恢复期间创建或删除 Backup 对象。

4. 用最近的备份执行恢复：

   ark restore create <SCHEDULE NAME>-<TIMESTAMP>

恢复成功后，被恢复的 Kubernetes 对象带有ark-restore=<BACKUP NAME>-<TIMESTAMP>标签，可用于识别来源。

场景二：集群迁移（Cluster migration）——共享对象存储

只要两个集群的 Ark Config 指向同一个云对象存储桶，Ark 就能将资源从一个集群迁移到另一个集群（前提是同一云提供商；Ark 不支持跨云提供商的持久卷迁移）：

1. (集群 1)如果此前没有通过 schedule 做检查点备份，先备份整个集群：

   ark backup create <BACKUP-NAME>

   默认 TTL 为 30 天（720 小时），可用--ttl修改。

2. (集群 2)确保新集群 Ark Config 中的persistentVolumeProvider和backupStorageProvider字段与集群 1 一致，使新的 Ark 服务端指向同一存储桶。

3. (集群 2)确认 Ark Backup 对象已创建——Ark 资源会与云存储中可用的备份文件自动同步（即前文所述"对象存储同步"机制）。

4. (集群 2)确认正确的 Backup（<BACKUP-NAME>）存在后，恢复一切：

   ark restore create <BACKUP-NAME>

ark backup create命令参考

创建备份是最高频的操作，v0.7.0 版本支持以下参数（ark_backup_create.md）：

ark backup create NAME [flags]

小结

Heptio Ark v0.7.0 确立的架构与工作流——服务端 + CLI 客户端、CRD 驱动操作、对象存储作为事实来源、控制器处理备份/恢复/定时任务——至今仍是 Velero 的核心设计。通过本文的 Minio 本地演练，你已经掌握了从部署、备份、模拟灾难到恢复的完整闭环；结合 Config 参数、Backup API 类型、备份钩子与恢复排障章节，可以进一步将这套方案迁移到 AWS/GCP/Azure 生产环境，并借助 Schedule 与 restoreOnlyMode 落地真正的灾备体系。

继续深入学习可参考本仓库保留的 v0.7.0 文档目录（site/content/docs/v0.7.0/），其中包含构建源码、输出文件格式、插件机制、命名空间自定义等更详细的资料。

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