ArkVelero 前身在 Azure 上运行配置指南存储账户、服务主体与凭据管理全流程【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文基于仓库中的 v0.7.1 Azure 配置文档完整讲解如何在微软 Azure 云上部署并配置 Ark即 Velero 的前身仓库当前项目为 Velero的备份与恢复环境涵盖 Azure 存储账户与 Blob 容器的创建、用于权限集成的 Service Principal 创建、七项必需环境变量的获取以及将凭据封装为 Kubernetes Secret、定制 Ark Config 的完整步骤。读完本文你将能够在 Azure 上独立完成 Ark/Velero 服务端的环境搭建并理解这些配置项在 pkg/util/azure 源码中的底层实现逻辑。本文以 v0.7.1 时代文档为基线同时结合当前仓库源码说明其演进与继承关系。一、架构背景Ark 如何与 Azure 集成Heptio Ark后更名为 Velero在设计上通过两个Provider抽象完成与云厂商的对接persistentVolumeProviderPV 提供方负责对集群中的持久化卷做原生云盘快照Azure 场景下即对托管磁盘Managed Disks发起快照backupStorageProvider备份存储提供方负责将备份数据上传到对象存储Azure 场景下即 Blob 存储Azure Blob Storage。完整的配置流程分为四步创建存储账户与 Blob 容器 → 为 Ark 创建 Service Principal → 配置服务端Ark Config→ 为凭据创建 Secret。如果本机尚未安装 Azure CLI 2.0az命令需要先安装随后执行az login完成登录认证。需要说明v0.7.1 是 Ark 早期版本当时 API 组为ark.heptio.com/v1示例目录为examples/azure/当前仓库的主线版本已演进为 Velero资源对象更名为 BackupStorageLocationBSL。但凭证键名如AZURE_SUBSCRIPTION_ID与存储账号密钥的用法在 pkg/util/azure/util.go 中仍然保留下文会结合现状说明。二、Kubernetes 集群前置条件在开始之前需确认 Azure 上 Kubernetes 集群的 Agent Pool代理节点池虚拟机允许使用托管磁盘Managed Disks。若对 I/O 性能敏感建议选用 SSD 后端支撑的高级托管磁盘Premium Managed Disks。此外Azure 场景下若要支持 PV 原生快照集群版本需要不低于Kubernetes 1.7.2该约束同时记录在 v0.7.1 的 Config 定义文档 与 cloud-common.md 的 Snapshot 示例中。三、创建 Azure 存储账户与 Blob 容器Ark 需要一个存储账户Storage Account与一个 Blob 容器来存放备份数据。存储账户可以创建在 Kubernetes 集群所在的资源组中也可以独立划分资源组官方示例将存储账户放在独立的Ark_Backups资源组中便于隔离管理。存储账户的命名必须全局唯一因为会用于 DNS 名称因此示例利用系统随机数cat /proc/sys/kernel/random/uuid | cut -d - -f5生成唯一后缀。同时存储账户启用静态加密Microsoft 托管密钥并仅允许 HTTPS 访问。完整命令如下# 1. 创建用于存放备份存储账户的资源组按需调整 location AZURE_BACKUP_RESOURCE_GROUPArk_Backups az group create -n $AZURE_BACKUP_RESOURCE_GROUP --location WestUS # 2. 创建存储账户全局唯一名称 AZURE_STORAGE_ACCOUNT_IDarkcat /proc/sys/kernel/random/uuid | cut -d - -f5 az storage account create \ --name $AZURE_STORAGE_ACCOUNT_ID \ --resource-group $AZURE_BACKUP_RESOURCE_GROUP \ --sku Standard_GRS \ --encryption-services blob \ --https-only true \ --kind BlobStorage \ --access-tier Hot # 3. 创建名为 ark 的 blob 容器可自定义名称若改名需同步调整 Ark Config 中 # backupStorageProvider 下的 bucket 字段 az storage container create -n ark --public-access off --account-name $AZURE_STORAGE_ACCOUNT_ID # 4. 获取刚创建的存储账户的访问密钥 AZURE_STORAGE_KEYaz storage account keys list \ --account-name $AZURE_STORAGE_ACCOUNT_ID \ --resource-group $AZURE_BACKUP_RESOURCE_GROUP \ --query [0].value \ -o tsv各命令要点说明参数/命令说明--sku Standard_GRS使用标准异地冗余存储Geo-Redundant Storage提供跨区域容灾--encryption-services blob对 Blob 服务启用静态加密--https-only true仅允许 HTTPS 访问存储账户--kind BlobStorage存储账户类型为 BlobStorage对象存储--access-tier Hot访问层为热数据层适合备份写入场景--public-access off容器不开放公共访问备份数据私有从源码看存储密钥的用途上文取出的AZURE_STORAGE_KEY正是 Ark/Velero 访问 Blob 的凭据。在当前仓库 pkg/util/azure/storage.go 的NewStorageClient中若凭据中存在存储账户访问密钥AZURE_STORAGE_KEY将调用azblob.NewSharedKeyCredential以共享密钥方式创建 Blob 客户端否则回退到 Azure AD 认证NewCredential。而在 pkg/util/azure/credential.go 中NewCredential按「配置文件凭据 → Workload Identity → Managed Identity」的顺序尝试获取 TokenCredential——这体现了 Velero 在认证方式上的演进v0.7.1 时代仅支持 Service Principal客户端密钥一种方式。四、创建 Service Principal 与七项环境变量要让 Ark 具备调用 Azure API 的权限需要为其创建专用的Service Principal服务主体对应 Azure AD 中的应用对象。文档明确指出Ark 要正常工作必须设置七个环境变量。4.1 获取订阅 ID 与租户 IDAZURE_SUBSCRIPTION_IDaz account list --query [?isDefault].id -o tsv AZURE_TENANT_IDaz account list --query [?isDefault].tenantId -o tsv4.2 设置集群资源组名称易错点# 务必设置为第二个资源组的名称见下方警告 AZURE_RESOURCE_GROUPNAME_OF_RESOURCE_GROUP_2WARNINGAZURE_RESOURCE_GROUP必须设置为在 Azure 中预置集群时自动创建的第二个资源组的名称。你的集群本体创建在最初指定的资源组中但磁盘Disks实际放在第二个资源组中。若不确定名称可执行az group list --query [].{ ResourceGroup: name, Location:location }查看列表取集群对应的ResourceGroup值同时记下Location值——该区域信息稍后要填入 Ark Config 的 Azure 专属配置段。4.3 创建 Contributor 角色的 Service PrincipalService Principal 需要Contributor 角色具备订阅级访问权限因此务必妥善保护该凭据。密码可自行指定也可让az ad sp create-for-rbac自动生成# 方式一自定密码 AZURE_CLIENT_SECRETsuper_secret_and_high_entropy_password_replace_me_with_your_own az ad sp create-for-rbac --name heptio-ark --role Contributor --password $AZURE_CLIENT_SECRET # 方式二由 CLI 自动生成密码务必捕获输出中的 password AZURE_CLIENT_SECRETaz ad sp create-for-rbac --name heptio-ark --role Contributor --query password -o tsv # 创建完成后获取客户端 ID AZURE_CLIENT_IDaz ad sp list --display-name heptio-ark --query [0].appId -o tsv4.4 七项环境变量一览至此Ark 所需的七个环境变量已全部齐备#环境变量来源/含义1AZURE_SUBSCRIPTION_ID默认订阅 ID2AZURE_TENANT_IDAzure AD 租户 ID3AZURE_RESOURCE_GROUP存放磁盘的第二个资源组4AZURE_CLIENT_IDService Principal 的应用客户端ID5AZURE_CLIENT_SECRETService Principal 的客户端密钥6AZURE_STORAGE_ACCOUNT_ID存储账户名称7AZURE_STORAGE_KEY存储账户访问密钥这七个键名至今仍被 Velero 核心代码引用。在 pkg/util/azure/util.go 中它们被定义为常量CredentialKeySubscriptionID、CredentialKeyTenantID、CredentialKeyResourceGroup、CredentialKeyClientID、CredentialKeyClientSecret、CredentialKeyStorageAccountAccessKey等pkg/repository/config/azure.go 还会将存储账户名与密钥转换为 restic 所需的AZURE_ACCOUNT_NAME/AZURE_ACCOUNT_KEY环境变量此时强制useAADfalse因为 restic 不支持 Azure AD 认证。这印证了七项变量的分工前五项服务于 Azure 管理面 API快照、密钥交换后两项服务于数据面Blob 读写。五、创建凭据 Secret 并配置服务端5.1 部署基础脚手架在 Ark 根目录下先应用前置资源创建命名空间、RBAC 等脚手架。若要运行在自定义命名空间需事先编辑 YAML 指定命名空间参见 在自定义命名空间中运行kubectl apply -f examples/common/00-prereqs.yaml注意当前仓库主线的examples/目录如 examples/minio已不再包含azure/子目录此处的examples/common/00-prereqs.yaml与examples/azure/均为 v0.7.1 历史版本的文件布局按历史文档步骤操作时请使用 v0.7.1 对应发行包。5.2 创建凭据 Secret将上一步设置的七个环境变量写入 Kubernetes Secretkubectl create secret generic cloud-credentials \ --namespace ARK_SERVER_NAMESPACE \ --from-literal AZURE_SUBSCRIPTION_ID${AZURE_SUBSCRIPTION_ID} \ --from-literal AZURE_TENANT_ID${AZURE_TENANT_ID} \ --from-literal AZURE_RESOURCE_GROUP${AZURE_RESOURCE_GROUP} \ --from-literal AZURE_CLIENT_ID${AZURE_CLIENT_ID} \ --from-literal AZURE_CLIENT_SECRET${AZURE_CLIENT_SECRET} \ --from-literal AZURE_STORAGE_ACCOUNT_ID${AZURE_STORAGE_ACCOUNT_ID} \ --from-literal AZURE_STORAGE_KEY${AZURE_STORAGE_KEY}这里的 Secret 名称cloud-credentials与后续 Ark Config 中通过credentialsFile/cloud-credentials引用的凭据文件对应在 pkg/util/azure/util.go 的LoadCredentials中Velero 会优先读取 BSL 配置指定的凭据文件credentialsFile键否则回退到AZURE_CREDENTIALS_FILE环境变量最终以 dotenv 格式解析为键值映射。5.3 定制 Ark Config凭据就绪后需要替换模板文件examples/azure/10-ark-config.yaml中的占位值YOUR_BUCKET、YOUR_LOCATION、YOUR_TIMEOUT。完整的参数定义可参考 Config 定义文档。下面是填写完成的示例apiVersion: ark.heptio.com/v1 kind: Config metadata: namespace: heptio-ark name: default persistentVolumeProvider: name: azure config: location: West US apiTimeout: 15m backupStorageProvider: name: azure bucket: ark backupSyncPeriod: 30m gcSyncPeriod: 30m scheduleSyncPeriod: 1m restoreOnlyMode: false字段逐项解析含默认值均来自 config-definition.mdKey类型默认值含义persistentVolumeProviderCloudProviderConfig无可选集群 PV 快照所用云厂商未设置时请求 PV 快照/恢复的备份与恢复会被判定为无效persistentVolumeProvider/nameString无可选原生支持aws、gcp、azure其他厂商可通过外部插件接入persistentVolumeProvider/configmap[string]string无可选传递给 PV 云厂商的配置键值Azure 场景见下表backupStorageProviderCloudProviderConfig必填实际存放备份的云存储厂商backupStorageProvider/nameString必填备份存储厂商名原生支持aws/gcp/azurebackupStorageProvider/bucketString必填备份上传的存储桶即你创建的 Blob 容器名backupStorageProvider/configmap[string]string无可选传递给备份存储厂商的配置键值backupSyncPeriodmetav1.Duration60m0s查询对象存储以对齐已有备份文件与 Backup 资源的频率gcSyncPeriodmetav1.Duration60m0s查询对象存储、清理已超过 TTL 的备份文件的频率scheduleSyncPeriodmetav1.Duration1m0s检查 Schedule 资源、判断是否需要发起备份的频率resourcePriorities[]string[namespaces, persistentvolumes, persistentvolumeclaims, secrets, configmaps]恢复资源的顺序列表不在列表中的资源在其他资源之后恢复restoreOnlyModeboolfalse开启后关闭备份、调度与过期备份删除功能仅从已有备份文件执行恢复Azure 专属配置段backupStorageProvider/configAzure 无必填参数。persistentVolumeProvider/config则有两个键Key类型默认值含义locationstring必填Azure 区域名示例West US、Canada EastapiTimeoutmetav1.Duration2m0s单次 Azure API 请求的超时时间可使用以下命令获取完整的 Azure 区域列表az account list-locations --query sort([].displayName) -o tsv配置演进提示当前 Velero 主线已将Config拆分为 BackupStorageLocationBSL与 VolumeSnapshotLocationVSL。其中 Azure BSL 支持resourceGroup、storageAccount、subscriptionId、storageAccountURI、useAAD、activeDirectoryAuthorityURI等配置键见 pkg/util/azure/storage.go并可通过AZURE_CLOUD_NAME选择 AzurePublic/AzureChina/AzureGovernment 云环境见 pkg/util/azure/util.go。v0.7.1 的location/apiTimeout语义在 VSL 侧被resourceGroup等更细粒度的键取代。六、启动服务端完成以上所有步骤后在 Ark 根目录下应用 Azure 示例目录中的全部资源kubectl apply -f examples/azure/该目录包含 10-ark-config.yaml 等模板文件。Ark 服务端在首次部署后会等待用户在heptio-ark命名空间创建名为default的 Config 资源config-definition.md 的 Overview 部分明确此行为若后续修改defaultConfig服务端会优雅退出待 kubelet 重启 Ark Pod 后加载新配置。启动成功后即可参照 cloud-common.md 中的示例做端到端验证部署 examples/nginx-app/base.yaml 样例应用 → 执行ark backup create nginx-backup --include-namespaces nginx-example创建备份 → 删除命名空间模拟灾难 → 执行ark restore create nginx-backup完成恢复。若测试带 PV 快照的恢复流程则改用 examples/nginx-app/with-pv.yaml并注意动态供给 PV 的默认回收策略为 Delete磁盘删除是异步的恢复前务必到云控制台确认原磁盘已不存在。七、常见问题与故障排查要点AZURE_RESOURCE_GROUP设置错误导致快照失败这是 Azure 集成中最常见的配置错误。该变量必须指向存放集群节点磁盘的第二个资源组而非创建集群时指定的资源组。排查时用az group list核对两个资源组的实际名称与 Location。凭据缺失或键名不一致七个环境变量必须全部写入 Secret。当前仓库源码对凭据键名有严格校验例如 pkg/util/azure/credential.go 中若设置了客户端密钥/证书但缺少AZURE_TENANT_ID或AZURE_CLIENT_ID会直接报错仅设置租户与客户端 ID 而缺少密钥时也会返回 incomplete credential configuration 错误。存储账户访问权限不足Service Principal 需要 Contributor 角色否则在 pkg/util/azure/storage.go 的exchangeStorageAccountAccessKey中通过管理面 API 换取存储账户密钥时AccountsClientListKeys会因权限不足失败最终体现为备份上传失败。区域不匹配Config 中persistentVolumeProvider.config.location应使用实际部署集群的区域可用az account list-locations输出精确名称避免因区域名格式不一致如WestUSvsWest US导致快照定位失败。结语通过上述四步流程——创建存储账户与 Blob 容器、创建 Contributor 角色的 Service Principal、收集七项环境变量并封装为 Kubernetes Secret、填写并应用 Ark Config——即可在 Azure 上完整运行 ArkVelero的备份与恢复能力。虽然 v0.7.1 是历史版本但其凭证模型与存储模型在当今 Velero 的 pkg/util/azure 源码中依然可见其继承脉络理解这份配置对排查现代 Velero 的 Azure 备份问题同样具有直接的参考价值。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考