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

Heptio Ark v0.7.0 快速上手Kubernetes 集群备份与持久卷恢复实战指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/veleroHeptio 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变为veleroAPI 组从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.mdArk 客户端向 Kubernetes API Server 发起请求创建一个Backup对象BackupController发现新的Backup对象并执行校验BackupController开始备份过程通过查询 API Server 收集要备份的资源数据BackupController调用对象存储服务如 AWS S3上传备份文件。默认情况下ark backup create会为持久卷创建磁盘快照可通过--snapshot-volumesfalse关闭或使用其他参数精确控制详见 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 gitgithub.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 本地存储的搭建方式Namespacevelerov0.7.0 时代为heptio-ark所有组件共用Minio Deployment镜像minio/minio:latest启动参数server /storage --config-dir/config通过环境变量MINIO_ACCESS_KEYminio、MINIO_SECRET_KEYminio123配置访问凭据暴露 9000 端口ServiceClusterIP类型将 9000 端口暴露给集群内部生产环境建议 ClusterIP仅测试/试用环境可改为 NodePortminio-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 componentark --namespaceheptio-ark kubectl get deployments --namespacenginx-example安装客户端Install clientv0.7.0 时代官方推荐直接下载预编译的 release 二进制也可以从源码构建确保将其安装到$PATH中的某个目录。执行备份Back up创建备份只包含匹配appnginx标签选择器的对象ark backup create nginx-backup --selector appnginx模拟灾难kubectl delete namespace nginx-example确认 nginx 的 Deployment 与 Service 已消失kubectl get deployments --namespacenginx-example kubectl get services --namespacenginx-example kubectl get namespace/nginx-example此时应该没有任何输出。命名空间彻底清理可能需要等待几分钟。执行恢复Restore从nginx-backup创建恢复ark restore create nginx-backup查看恢复状态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变为CompletedWARNINGS和ERRORS为 0nginx-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-backupwith-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.mdapiVersion: 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 parametersKeyTypeDefaultMeaningpersistentVolumeProviderCloudProviderConfigNone (Optional)集群持久卷所属的云提供商规格用于快照可选。若未指定请求 PV 快照/恢复的 Backup 与 Restore 会被视为无效。注意Azure 需要集群 1.7.2 才能快照其托管磁盘persistentVolumeProvider/nameStringNone (Optional)持久卷云提供商名称。Ark 原生支持aws、gcp、azure其他提供商可通过外部插件接入persistentVolumeProvider/configmap[string]stringNone (Optional)传给持久卷云提供商的配置键/值见各云提供商章节backupStorageProviderCloudProviderConfigRequired Field实际存储备份的云提供商规格必填backupStorageProvider/nameStringRequired Field存储备份的云提供商名称必填backupStorageProvider/bucketStringRequired Field备份上传的目标存储桶必填backupStorageProvider/configmap[string]stringNone (Optional)传给备份存储提供商的配置键/值backupSyncPeriodmetav1.Duration60m0sArk 查询对象存储以确认已有备份文件对应 Backup 资源的频率gcSyncPeriodmetav1.Duration60m0sArk 查询对象存储以删除已过 TTL 备份文件的频率scheduleSyncPeriodmetav1.Duration1m0sArk 检查 Schedule 资源对象以判断是否需要触发备份的频率resourcePriorities[]string[namespaces, persistentvolumes, persistentvolumeclaims, secrets, configmaps]恢复时资源对象的恢复顺序也支持RESOURCE.GROUP格式。不在列表中的资源在所有优先资源之后恢复restoreOnlyModeboolfalse开启后备份、定时备份、过期备份删除功能全部关闭仅从对象存储中的既有备份文件执行恢复AWS及其他 S3 兼容存储配置backupStorageProvider/configKeyTypeDefaultMeaningregionstringRequired Field例如 us-east-1完整列表见 AWS 文档s3ForcePathStyleboolfalse使用本地存储服务如 Minio时设为trues3Urlstring非 AWS 托管存储必填例如http://minio:9000。对 AWS S3 也可显式指定但 Ark 可从region和bucket自动生成该字段主要用于 Minio 等本地存储服务kmsKeyIdstringEmpty例如 502b409c-4da1-419f-a16e-eif453b3i49f 或 alias/KMS-Key-Alias-Name。指定 AWS KMS key id 或别名可为 S3 中的备份启用加密仅适用于 AWS S3且可能需要显式授予密钥使用权限persistentVolumeProvider/config仅 AWSregionstring必填例如 us-east-1。GCP 配置backupStorageProvider/config无需参数。persistentVolumeProvider/configprojectstring必填例如 project-example-3jsn23。Azure 配置backupStorageProvider/config无需参数。persistentVolumeProvider/configlocationstring必填例如 Canada EastAzure 文档中称为 RegionsapiTimeoutmetav1.Duration默认2m0s等待 Azure API 请求完成的最长时间。用 Backup API 类型精确控制备份Backup属于 API 组ark.heptio.com/v1创建后 Ark 服务端立即开始备份流程。以下是一个包含全部字段说明的示例api-types/backup.mdapiVersion: 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但已废弃Annotation NameDescriptionpre.hook.backup.ark.heptio.com/container命令执行的容器默认 Pod 内第一个容器。可选pre.hook.backup.ark.heptio.com/command要执行的命令多参数时以 JSON 数组形式给出如[/usr/bin/uname, -a]pre.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理方式默认Fail可选值为Fail和Continue。可选pre.hook.backup.ark.heptio.com/timeout命令执行等待时间超时视为钩子出错默认 30s。可选Post 钩子注解v0.7.0Annotation NameDescriptionpost.hook.backup.ark.heptio.com/container命令执行的容器默认 Pod 内第一个容器。可选post.hook.backup.ark.heptio.com/command要执行的命令多参数时以 JSON 数组形式给出post.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理方式默认Fail可选值为Fail和Continue。可选post.hook.backup.ark.heptio.com/timeout命令执行等待时间超时视为钩子出错默认 30s。可选在当前仓库的源码中钩子注解键已迁移为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.ioannotations: 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.mdNAME 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。两者的结构完全一致均分三级ArkArk 服务端遇到的系统相关问题如无法读取目录Cluster与集群级资源恢复相关的问题Namespaces命名空间到问题列表的映射记录各命名空间资源恢复时遇到的问题。进阶使用场景灾备与集群迁移场景一灾难恢复Disaster recovery——定时备份 只读恢复模式利用 Schedule 定时备份可在意外事故如服务中断后恢复到先前状态use-cases.md在集群上首次运行 Ark 服务端后创建每日备份按需替换SCHEDULE NAMEark schedule create SCHEDULE NAME --schedule 0 7 * * *这会创建一个名为SCHEDULE NAME-TIMESTAMP的 Backup 对象其中TIMESTAMP格式为YYYYMMDDhhmmss。Schedule 本质上是 Backup 的包装器被触发时在后台创建 Backup。灾难发生需要重建资源。更新 Ark 服务端的 Config将restoreOnlyMode设为true防止恢复期间创建或删除 Backup 对象。用最近的备份执行恢复ark restore create SCHEDULE NAME-TIMESTAMP恢复成功后被恢复的 Kubernetes 对象带有ark-restoreBACKUP NAME-TIMESTAMP标签可用于识别来源。场景二集群迁移Cluster migration——共享对象存储只要两个集群的 Ark Config 指向同一个云对象存储桶Ark 就能将资源从一个集群迁移到另一个集群前提是同一云提供商Ark 不支持跨云提供商的持久卷迁移(集群 1)如果此前没有通过 schedule 做检查点备份先备份整个集群ark backup create BACKUP-NAME默认 TTL 为 30 天720 小时可用--ttl修改。(集群 2)确保新集群 Ark Config 中的persistentVolumeProvider和backupStorageProvider字段与集群 1 一致使新的 Ark 服务端指向同一存储桶。(集群 2)确认 Ark Backup 对象已创建——Ark 资源会与云存储中可用的备份文件自动同步即前文所述对象存储同步机制。(集群 2)确认正确的 BackupBACKUP-NAME存在后恢复一切ark restore create BACKUP-NAMEark backup create命令参考创建备份是最高频的操作v0.7.0 版本支持以下参数ark_backup_create.mdark backup create NAME [flags]参数说明--exclude-namespaces stringArray从备份中排除的命名空间--exclude-resources stringArray从备份中排除的资源格式为 resource.group如storageclasses.storage.k8s.io--include-cluster-resources optionalBool[true]是否在备份中包含集群级资源--include-namespaces stringArray备份包含的命名空间*表示所有默认*--include-resources stringArray备份包含的资源格式为 resource.group*表示所有资源--label-columns stringArray作为输出列显示的标签列表逗号分隔--labels mapStringString应用于备份的标签-o, --output string输出格式。对 create 命令仅显示对象但不发送到服务端。有效值为table、json、yaml-l, --selector labelSelector仅备份匹配该标签选择器的资源默认none--show-labels在最后一列显示标签--snapshot-volumes optionalBool[true]是否在备份中为 PersistentVolume 创建快照--ttl duration备份可被垃圾回收前的时间默认720h0m0s小结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考