在 AWS 上配置 Ark（Velero 前身）：S3 存储桶、IAM 用户与服务器部署完整指南

在 AWS 上配置 Ark（Velero 前身）：S3 存储桶、IAM 用户与服务器部署完整指南

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

本指南以 v0.7.1 版本文档中的 AWS 配置手册为核心，完整讲解如何在 AWS 上为 Ark（Velero 项目的前身，即当前仓库所演进的开源 Kubernetes 备份/迁移工具的早期版本）搭建运行环境：从创建 S3 存储桶、创建并授权 IAM 用户、生成访问凭证，到创建 Kubernetes Secret、编辑服务器配置并最终启动 Ark 服务器。读完本文，你将掌握在 AWS 上完整落地 Ark 的全部操作步骤，理解Config自定义资源中与 AWS 相关的每个配置参数（region、s3Url、s3ForcePathStyle、kmsKeyId）的作用，并能对照源码理解凭证加载的底层机制。

一、总体流程概览

在 AWS 上运行 Ark，需要依次完成以下四件事：

1. 创建 S3 存储桶：Ark 需要一个对象存储桶来存放备份文件；
2. 创建用于 Ark 的 AWS IAM 用户：授予该用户操作 S3 与 EC2（卷快照）所需的权限；
3. 配置服务器：通过示例 YAML 指定存储桶、区域等参数；
4. 创建存放凭证的 Secret：将 AWS 访问凭证以 Kubernetes Secret 形式提供给 Ark 服务器。

如果本地尚未安装aws命令行工具，请先按照 AWS 官方用户指南完成awsCLI 的安装与配置（aws configure），后续所有操作均依赖awsCLI。

二、创建 S3 存储桶

Ark 依赖对象存储桶保存备份数据。使用aws s3api create-bucket创建存储桶，并替换命令中的占位符：

aws s3api create-bucket \ --bucket <YOUR_BUCKET> \ --region <YOUR_REGION> \ --create-bucket-configuration LocationConstraint=<YOUR_REGION>

特别注意 us-east-1 区域的差异：us-east-1不支持LocationConstraint参数。如果你的区域恰好是us-east-1，必须省略该配置：

aws s3api create-bucket \ --bucket <YOUR_BUCKET> \ --region us-east-1

说明：LocationConstraint用于在非us-east-1区域指定存储桶所在位置，这是 S3 API 的行为约束，与 Ark 无关；但存储桶创建成功后，其区域必须与后续Config中配置的region保持一致，否则备份读写会失败。

三、创建 IAM 用户并授予权限

Ark 服务器需要通过 AWS API 上传备份文件到 S3，并在启用卷快照时操作 EC2 卷。因此需要为 Ark 创建一个专用的 IAM 用户，并按以下步骤操作（AWS IAM 用户的详细概念可参考 AWS 官方 IAM 用户文档）：

步骤 1：创建 IAM 用户

aws iam create-user --user-name heptio-ark

v0.7.1 文档约定使用用户名heptio-ark（Ark 早期名为 Heptio Ark，故以 heptio 为前缀）。

步骤 2：为heptio-ark附加策略

aws iam attach-user-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess \ --user-name heptio-ark aws iam attach-user-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess \ --user-name heptio-ark

这两条命令分别授予：

• AmazonS3FullAccess：读写 S3 对象，用于备份文件的存储与读取；
• AmazonEC2FullAccess：操作 EC2 资源，用于对持久卷（EBS 卷）创建/恢复快照。

实践提示：FullAccess策略是文档给出的最简可用方案，便于快速起步；在生产环境中，通常建议按最小权限原则收敛为仅包含s3:PutObject、s3:GetObject、s3:ListBucket、ec2:CreateSnapshot、ec2:DescribeVolumes、ec2:CreateVolume等操作的精细策略。

步骤 3：为用户创建访问密钥

aws iam create-access-key --user-name heptio-ark

命令返回结果形如：

{ "AccessKey": { "UserName": "heptio-ark", "Status": "Active", "CreateDate": "2017-07-31T22:24:41.576Z", "SecretAccessKey": <AWS_SECRET_ACCESS_KEY>, "AccessKeyId": <AWS_ACCESS_KEY_ID> } }

请妥善保存返回的AccessKeyId与SecretAccessKey，它们将用于下一步创建 Ark 专用的凭证文件。

步骤 4：创建 Ark 专用凭证文件

在本地目录创建一个名为credentials-ark的文件，内容为标准的 AWS 共享凭证（INI）格式：

[default] aws_access_key_id=<AWS_ACCESS_KEY_ID> aws_secret_access_key=<AWS_SECRET_ACCESS_KEY>

其中aws_access_key_id和aws_secret_access_key就是上一步create-access-key返回的 Access Key Id 与 Secret Access Key。

凭证加载的源码依据

从当前仓库源码 pkg/repository/config/aws.go 可以看到，Ark/Velero 的 AWS 凭证体系定义了AWS_SHARED_CREDENTIALS_FILE、AWS_PROFILE、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AWS_CONFIG_FILE等环境变量，并默认使用default作为 profile 名——这正是credentials-ark文件采用[default]段的原因。GetS3Credentials会优先读取Config中指定的凭证文件路径，其次回退到AWS_SHARED_CREDENTIALS_FILE环境变量，并支持通过profile配置项切换不同凭证段落（pkg/repository/config/aws.go）。这一机制保证了只要把凭证文件正确挂载进 Ark 服务器 Pod，即可被 SDK 自动加载。

四、创建 Kubernetes 前置资源与凭证 Secret

在 Ark 仓库根目录下，先执行以下命令创建命名空间、RBAC 以及其他前置脚手架资源：

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

该文件在 v0.7.1 时代定义了 Ark 各类对象（backups、schedules、restores、configs、downloadrequests）的 CustomResourceDefinition、Ark 服务器运行所在的命名空间、备份数据存储所在的命名空间、Ark 的 ServiceAccount 以及授予该 ServiceAccount 的 RBAC 规则。若要在自定义命名空间中运行，需要先编辑这些 YAML 文件以指定命名空间，详见 在自定义命名空间中运行。

版本说明：examples/common/00-prereqs.yaml属于 v0.7.1 文档时期的历史示例路径，随着项目演进，当前仓库的 examples 目录已精简为 nginx 示例与 MinIO 示例；作为对照，当前仓库仍以 config/crd（CRD 定义）和 config/rbac/role.yaml（RBAC 规则）等形式承载等价的前置资源定义，可据此理解 Ark 服务端启动所需的基础组件。

接下来创建存放 AWS 凭证的 Secret。在刚刚创建credentials-ark文件的目录中执行：

kubectl create secret generic cloud-credentials \ --namespace <ARK_SERVER_NAMESPACE> \ --from-file cloud=credentials-ark

这里的--from-file cloud=credentials-ark会将本地文件credentials-ark的内容以名为cloud的键写入 Secret，即 Secret 内部实际结构为cloud: <credentials-ark 文件内容>。<ARK_SERVER_NAMESPACE>需替换为 Ark 服务器实际运行的命名空间（默认场景下为heptio-ark）。

五、编辑服务器配置文件

需要按以下清单修改示例文件中的占位符：

1.examples/aws/00-ark-config.yaml

将文件中的<YOUR_BUCKET>和<YOUR_REGION>替换为实际值：<YOUR_BUCKET>替换为第一步创建的 S3 存储桶名称，<YOUR_REGION>替换为该存储桶所在的区域（如us-west-2）。该文件对应 Ark 的Config自定义资源，其完整字段含义见 Config 定义文档。

2.examples/common/10-deployment.yaml

确保spec.template.spec.containers[*].env.name的取值为AWS_SHARED_CREDENTIALS_FILE。该环境变量指向容器内共享凭证文件的路径，Ark 服务器即通过它定位之前创建的cloud-credentialsSecret 中挂载出的凭证文件。从 pkg/repository/config/aws.go 可以看到该环境变量名正是凭证加载逻辑显式声明的入口之一。

3.（可选）nginx 示例：examples/nginx-app/with-pv.yaml

如果后续要运行带持久卷（PV）的 nginx 备份/恢复示例，需要将examples/nginx-app/with-pv.yaml中的<YOUR_STORAGE_CLASS_NAME>替换为gp2——这是 AWS 的默认StorageClass名称。当前仓库中的 examples/nginx-app/with-pv.yaml 仍保留了这一可选的storageClassName注释占位，印证了该配置点的位置：在PersistentVolumeClaim的spec下通过storageClassName指定存储类。

六、AWS 相关 Config 参数详解

Config是 Ark 自定义的核心配置对象，其中与 AWS 相关的配置集中在backupStorageProvider/config与persistentVolumeProvider/config两个段落。以下是 Config 定义文档 中针对AWS（及其他 S3 兼容存储）的参数完整说明：

backupStorageProvider/config

persistentVolumeProvider/config（仅 AWS）

一个完整的 AWSConfig示例（Config资源名为default，位于heptio-ark命名空间）：

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

要点解读：

• persistentVolumeProvider用于指定集群持久卷所属的云提供商（用于卷快照），可选；若不指定，则请求 PV 快照/恢复的 Backup 与 Restore 将被视为无效。
• backupStorageProvider必填，指定实际存储备份的云提供商与存储桶。
• backupSyncPeriod（默认60m）控制 Ark 查询对象存储、为已有备份文件补齐 Backup 资源的频率；gcSyncPeriod（默认60m）控制清理超过 TTL 的备份文件的频率；scheduleSyncPeriod（默认1m）控制检查 Schedule 资源是否需要触发备份的频率；restoreOnlyMode（默认false）开启后仅保留恢复功能，备份、调度与过期备份删除功能将被关闭。
• Ark 服务器首次部署时会等待名为default的 Config 出现在heptio-ark命名空间；若defaultConfig 被修改，服务器会优雅退出，待 kubelet 重启 Pod 后以新配置生效。

与 S3 兼容存储（MinIO）的关联

s3ForcePathStyle与s3Url面向的正是 S3 兼容的本地对象存储场景。当前仓库的 examples/minio/00-minio-deployment.yaml 提供了完整的 MinIO 部署示例（Deployment + Service + 建桶 Job），其中 MinIO 以minio为访问密钥、监听 9000 端口。若将 Ark 的备份后端指向这样的本地 MinIO，则需要在backupStorageProvider/config中设置：

backupStorageProvider: name: aws bucket: velero config: region: minio s3Url: http://minio:9000 s3ForcePathStyle: true

aws作为 provider 名称同样适用于 S3 兼容存储——这是 Ark 将 AWS 与 S3 兼容服务统一处理的直接体现。

七、启动 Ark 服务器

完成上述配置后，在 Ark 仓库根目录执行以下命令启动服务器：

kubectl apply -f examples/aws/00-ark-config.yaml kubectl apply -f examples/common/10-deployment.yaml

第一条命令创建 AWS 相关的Config自定义资源（含存储桶与区域配置），第二条命令创建 Ark 服务器的 Deployment 并挂载凭证。服务器启动后即开始监听defaultConfig 并进入就绪状态。

八、验证与示例演练

服务器启动后，可参考 云提供商配置总览 中的示例验证备份与恢复能力：

基础示例（无持久卷）

# 启动示例 nginx 应用 kubectl apply -f examples/nginx-app/base.yaml # 创建备份 ark backup create nginx-backup --include-namespaces nginx-example # 模拟灾难：删除命名空间 kubectl delete namespaces nginx-example # 从备份恢复 ark restore create nginx-backup

带持久卷的快照示例

kubectl apply -f examples/nginx-app/with-pv.yaml ark backup create nginx-backup --include-namespaces nginx-example kubectl delete namespaces nginx-example ark restore create nginx-backup

注意：由于动态供应的 PV 默认回收策略为 Delete，删除命名空间会触发云提供商异步删除卷，因此在继续恢复之前，务必到云控制台确认底层磁盘确实已删除，再执行ark restore create。AWS 场景下，该流程依赖persistentVolumeProvider中的region定位 EBS 卷并完成快照创建与恢复。

此外，若希望 Ark 服务器运行在自定义命名空间（v0.7.0 及以后版本支持任意命名空间），需要编辑前置资源 YAML 中的命名空间字段，并通过ark client config set namespace=<NAMESPACE_VALUE>让所有客户端命令指向同一命名空间，详见 在自定义命名空间中运行。

九、小结

本文完整复现了 v0.7.1 版本文档定义的 AWS 部署路径：S3 存储桶 → IAM 用户与访问密钥 → 共享凭证文件 → Kubernetes Secret →Config配置 → 服务器启动。同时结合当前仓库源码（pkg/repository/config/aws.go）说明了AWS_SHARED_CREDENTIALS_FILE与defaultprofile 的加载机制，并结合 Config 定义文档 与 MinIO 示例 讲清了region、s3Url、s3ForcePathStyle、kmsKeyId等关键参数。按此流程操作，即可在 AWS（或任何 S3 兼容对象存储）上搭建起 Ark 的备份存储后端，并进一步通过 examples/nginx-app 示例完成备份/恢复的端到端验证。

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