VeleroArk安装故障排查实战指南kubeconfig、cloud-credentials 与三大云厂商凭证问题全解析【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文以 Velero 项目其前身为 Heptio Arkv0.9.0 时期文档以 Ark 命名官方安装排错文档为主体系统梳理 Kubernetes 备份工具安装过程中最常见的四类报错kubeconfig 缺失导致的客户端启动失败、备份/恢复任务卡在New阶段、以及 AWS / Azure / GCE 三大云平台凭证 Secret 未正确创建或挂载引发的云厂商报错。读完本文你将掌握 Ark/Velero 客户端 kubeconfig 的查找规则、cloud-credentialsSecret 的创建与挂载规范、各云厂商凭证的格式要求以及一套可复制的先看 Pod 描述、再看日志、最后核对 Secret的分层排查思路。文中所有结论均可对照仓库内 v0.9.0 版安装排错原文 debugging-install.md 与当前版本 main 版 debugging-install.md 验证。排查总览安装问题的三个分层Ark/Velero 采用客户端CLI 服务端Deployment 内的控制器架构CLI 负责发起备份/恢复请求服务端控制器backup controller、restore controller 等负责真正执行任务。因此安装阶段的问题通常落在三个层面客户端层CLI 无法访问 Kubernetes API Server典型症状是invalid configuration: no configuration has been provided服务端层服务端 Pod 未运行或异常典型症状是备份/恢复长时间停留在New阶段没有任何控制器消费它们云凭证层对象存储S3 / Azure Blob / GCS或卷快照 API 的凭证未正确注入 Pod典型症状是 AWS / Azure / GCP 各自特有的凭证报错。下面按通用问题 → 各云厂商问题的顺序逐一展开每类问题都给出症状、原因、检查清单和修复手段。通用问题排查invalid configuration: no configuration has been providedkubeconfig 找不到症状运行 Ark CLI 命令如ark backup create时直接报错invalid configuration: no configuration has been provided原因CLI 在启动时找不到可用的 kubeconfig 文件无法建立与 Kubernetes API Server 的连接。注意 v0.9.0 时期 Ark 客户端并非使用client-go的默认加载逻辑而是按下面的固定优先级查找 kubeconfig优先级查找位置说明1--kubeconfig标志指定的路径CLI 全局标志显式优先级最高2$KUBECONFIG环境变量指定的路径未传--kubeconfig时生效3~/.kube/config前两者均未指定时的兜底默认路径这一查找规则在 v0.9.0 与当前 main 版本的排错文档中完全一致分别见 v0.9.0 文档 与 main 文档。检查与修复步骤确认当前 kubeconfig 文件是否存在且内容合法ls -la ~/.kube/config并用kubectl cluster-info验证集群连通性若 kubeconfig 不在默认位置通过环境变量导出export KUBECONFIG/path/to/your/kubeconfig或者在使用 Ark CLI 时显式指定ark --kubeconfig /path/to/your/kubeconfig ...。原理补充从当前仓库源码看Velero 客户端配置已演进为独立的配置文件机制——pkg/client/config.go 中configFileName()返回$HOME/.config/velero/config.json用于存放命名空间、feature flags 等客户端偏好而 kubeconfig 的解析仍由 Kubernetes 客户端库完成。这解释了为何排查顺序是先查 kubeconfig、再查客户端配置文件。备份或恢复卡在New阶段症状ark backup get或ark restore get看到的任务长期停留在New状态没有任何推进。原因备份/恢复任务卡在New阶段说明控制器根本没有处理这些对象——通常意味着Ark 服务端没有运行。服务端控制器通过 watch 监听 Backup / Restore 自定义资源服务端不可用时新提交的任务就会一直停留在New。检查与修复步骤按以下两条命令查看服务端 Pod 描述与日志定位异常v0.9.0 默认命名空间为heptio-ark当前版本为velero# 查看服务端 Pod 的状态、事件与容器状态 kubectl -n heptio-ark describe pods # 查看 Ark 服务端 Deployment 的日志 kubectl -n heptio-ark logs deployment/ark修复方向视 describe/logs 结果而定镜像拉取失败ImagePullBackOff、凭证挂载失败详见下文云厂商部分、RBAC 权限不足、资源配额不足等都可能导致服务端无法就绪。修复后重新观察备份/恢复状态正常情况下任务应离开New阶段进入后续处理流程。原理补充当前版本的 pkg/install/install.go 中Install()会先创建 CRD 并轮询等待其就绪再创建其余资源而 DeploymentIsReady() 会持续轮询名为velero的 Deployment 的可用状态要求DeploymentAvailable条件为 True 且持续约 10 秒连续观测 5 次。这段实现印证了服务端 Deployment 必须真正可用、任务才会被消费的排错逻辑——若你采用velero install方式部署输出末尾的Velero is available提示就来自这类就绪探测。AWSNoCredentialProviders: no valid providers in chain症状Ark 服务端日志中出现NoCredentialProviders: no valid providers in chain原因存放 AWS IAM 用户凭证的 Secret 没有正确创建或没有正确挂载进 Ark 服务端 Pod。AWS SDK 在凭证提供者链环境变量、共享凭证文件、IAM 角色等中找不到任何有效凭证时即抛出该错误。检查清单逐项核对缺一不可cloud-credentialsSecret 存在于 Ark 服务端所在命名空间v0.9.0 为heptio-arkSecret 中只有一个键cloud其值必须是本地credentials-ark文件的完整内容credentials-ark文件格式正确、值无误——这是 AWS 共享凭证文件的标准 INI 格式[default] aws_access_key_idyour AWS access key ID aws_secret_access_keyyour AWS secret access keycloud-credentialsSecret 被定义为 Ark Deployment 的一个 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials目录。正确创建方式按 aws-config.md 中的安装流程先创建 IAM 用户heptio-ark并附加 S3 EC2 权限策略生成访问密钥后写入本地credentials-ark文件再创建 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_NAMESPACE \ --from-file cloudcredentials-ark注意--from-file cloud...这一写法cloud就是 Secret 中的键名值取自credentials-ark文件——这正是检查清单第 2 条单键cloud的来历。若改用其他键名服务端将无法读取凭证。挂载的源码级验证当前仓库的安装代码 pkg/install/deployment.go 明确生成了这样的挂载结构cloud-credentialsSecret 作为 volumeMountPath为/credentials随后多个环境变量如 AWS 相关的凭证文件路径的值指向/credentials/cloud。也就是说Secret 单键cloud 挂载到/credentials是 Ark/Velero 服务端的硬性约定pkg/install/resources.go 中的默认资源模板也定义了名为cloud-credentials的 Secret。任何一环缺失Secret 不存在、键名不对、volume 未定义、挂载路径不对都会导致 AWS SDK 在容器内找不到凭证文件。kube2iam 场景v0.9.0 文档附带说明若改用 kube2iam 通过 Pod 注解注入 IAM 角色则无需 API 密钥。此时报NoCredentialProviders往往意味着角色信任策略Trust Policy或 S3 权限配置不完整。AWS 侧需要准备 aws-config.md 中的策略文档并在 Ark Deployment 上添加iam.amazonaws.com/role: arn:aws:iam::AWS_ACCOUNT_ID:role/heptio-ark注解。main 版本的 debugging-install.md 对 kube2iam 场景单列了检查项一是确认存在允许 kube2iam 所用角色承担 Ark 角色的信任策略文档二是确认 Ark 角色拥有文档列出的全部 S3 权限。AzureFailed to refresh the Token或adal: Refresh request failed症状Ark 服务端日志出现 Azure AD 令牌刷新失败类错误Failed to refresh the Token或adal: Refresh request failed原因存放 Azure 服务主体Service Principal凭证的 Secret 未正确创建或未正确挂载进 Ark 服务端 Pod。Azure SDK 使用 ADAL 库获取/刷新访问令牌服务主体凭证缺失或错误时即抛出此类错误。检查清单cloud-credentialsSecret 存在于 Ark 服务端所在命名空间Secret有全部七个键且每个键的值都正确七个键的定义见下方cloud-credentialsSecret 被定义为 Ark Deployment 的 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials。七个键的完整定义与 AWS/GCP 的单键cloud不同Azure 场景下 Secret 以环境变量方式承载凭证必须包含 azure-config.md 中配置的全部七个键Secret 键对应环境变量含义AZURE_SUBSCRIPTION_ID${AZURE_SUBSCRIPTION_ID}Azure 订阅 IDAZURE_TENANT_ID${AZURE_TENANT_ID}Azure 租户 IDAZURE_RESOURCE_GROUP${AZURE_RESOURCE_GROUP}存放集群磁盘的资源组注意是创建集群时的第二个资源组AZURE_CLIENT_ID${AZURE_CLIENT_ID}服务主体的应用客户端IDAZURE_CLIENT_SECRET${AZURE_CLIENT_SECRET}服务主体密码AZURE_STORAGE_ACCOUNT_ID${AZURE_STORAGE_ACCOUNT_ID}备份存储账号 IDAZURE_STORAGE_KEY${AZURE_STORAGE_KEY}存储账号访问密钥正确创建方式先完成 azure-config.md 中的准备工作——创建存储账号与 blob 容器、创建带Contributor角色的服务主体再一次性把七个环境变量写入 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_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}排查要点排错时最容易遗漏的是AZURE_RESOURCE_GROUP——它必须指向创建 AKS 集群时自动生成的第二个资源组磁盘所在组而非你手动指定的集群资源组详见 azure-config.md 中的 WARNING 说明。若令牌刷新失败且 Secret 键值齐全优先用kubectl -n heptio-ark get secret cloud-credentials -o yaml检查七个键的值是否与az命令输出一致。GCE/GKEopen credentials/cloud: no such file or directory症状Ark 服务端日志中出现open credentials/cloud: no such file or directory原因存放 GCE 服务账号凭证的 Secret 未正确创建或未正确挂载进 Ark 服务端 Pod。Ark 服务端在启动时按/credentials/cloud路径读取 GCP 服务账号 JSON 文件路径不存在即报此错。检查清单cloud-credentialsSecret 存在于 Ark 服务端所在命名空间Secret 中只有一个键cloud其值是本地credentials-ark文件即 GCP 服务账号 JSON key的完整内容cloud-credentialsSecret 被定义为 Ark Deployment 的 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials。正确创建方式按 gcp-config.md 的流程先创建服务账号并授权compute.disks.*、compute.snapshots.*等权限并通过gsutil iam ch授予 GCS 存储桶的objectAdmin再用gcloud iam service-accounts keys create credentials-ark生成 JSON 密钥文件最后创建 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_NAMESPACE \ --from-file cloudcredentials-ark与 AWS 的异同GCP 的 Secret 结构和 AWS 完全一致单键cloud、挂载/credentials报错信息open credentials/cloud: no such file or directory恰好印证了服务端读取的正是/credentials/cloud这个路径。若报错持续存在按上述四条清单逐一核对最常见的两个原因是 Secret 根本没创建以及--from-file执行时不在credentials-ark文件所在目录导致键cloud的值为空或文件路径错误。三朵云排错对照速查表排查项AWSAzureGCE/GKE典型报错NoCredentialProvidersFailed to refresh the Token/adal: Refresh request failedopen credentials/cloud: no such file or directorySecret 键结构单键cloud七键环境变量单键cloud凭证载体credentials-arkINI 格式访问密钥七个 Azure 环境变量credentials-ark服务账号 JSON凭证来源文档aws-config.mdazure-config.mdgcp-config.mdSecret 挂载位置/credentialsvolume 挂载/credentialsvolume 挂载/credentialsvolume 挂载挂载实现源码pkg/install/deployment.go同上同上三类问题的公共根因完全一致cloud-credentialsSecret 未创建、键结构不对、未定义为 volume或未挂载到/credentials。因此三者的修复流程可以统一为四步kubectl get secret确认存在 → 校验键名与值 → 检查 Deployment 的 volumes 定义 → 检查容器的mountPath是否为/credentials。从 Ark 到 Velero排错文档的版本演进本文依据的 v0.9.0 文档属于项目早期Heptio Ark 时代其排查方法论沿用至今但有三点版本差异值得注意命名变化v0.9.0 文档中的命令与命名空间是ark/heptio-ark如kubectl -n heptio-ark logs deployment/arkmain 版本文档已改为velero/velerokubectl -n velero logs deployment/velero凭证文件名也从credentials-ark变为credentials-velero排查框架一致main 版 debugging-install.md 保留了通用 → AWS → Azure → GCE/GKE的完整框架和全部检查项仅增加了 kube2iam 场景的细分说明安装方式演进v0.9.0 采用编辑示例 YAML kubectl apply的手工安装如 aws-config.md 中的examples/aws/目录当前版本则推荐velero install命令由 pkg/install 包自动生成 Secret、Deployment 等资源并等待就绪——这也让凭证挂载由程序保证手工配置错误率大幅降低。无论使用哪个版本排错时请始终从官方文档的检查清单出发先确认客户端 kubeconfig 可连通集群再确认服务端 Pod 运行正常最后逐项核对cloud-credentialsSecret 的存在性、键结构与挂载路径。这四类报错的 90% 场景都能通过这一流程定位并解决。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Velero（Ark）安装故障排查实战指南：kubeconfig、cloud-credentials 与三大云厂商凭证问题全解析
VeleroArk安装故障排查实战指南kubeconfig、cloud-credentials 与三大云厂商凭证问题全解析【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文以 Velero 项目其前身为 Heptio Arkv0.9.0 时期文档以 Ark 命名官方安装排错文档为主体系统梳理 Kubernetes 备份工具安装过程中最常见的四类报错kubeconfig 缺失导致的客户端启动失败、备份/恢复任务卡在New阶段、以及 AWS / Azure / GCE 三大云平台凭证 Secret 未正确创建或挂载引发的云厂商报错。读完本文你将掌握 Ark/Velero 客户端 kubeconfig 的查找规则、cloud-credentialsSecret 的创建与挂载规范、各云厂商凭证的格式要求以及一套可复制的先看 Pod 描述、再看日志、最后核对 Secret的分层排查思路。文中所有结论均可对照仓库内 v0.9.0 版安装排错原文 debugging-install.md 与当前版本 main 版 debugging-install.md 验证。排查总览安装问题的三个分层Ark/Velero 采用客户端CLI 服务端Deployment 内的控制器架构CLI 负责发起备份/恢复请求服务端控制器backup controller、restore controller 等负责真正执行任务。因此安装阶段的问题通常落在三个层面客户端层CLI 无法访问 Kubernetes API Server典型症状是invalid configuration: no configuration has been provided服务端层服务端 Pod 未运行或异常典型症状是备份/恢复长时间停留在New阶段没有任何控制器消费它们云凭证层对象存储S3 / Azure Blob / GCS或卷快照 API 的凭证未正确注入 Pod典型症状是 AWS / Azure / GCP 各自特有的凭证报错。下面按通用问题 → 各云厂商问题的顺序逐一展开每类问题都给出症状、原因、检查清单和修复手段。通用问题排查invalid configuration: no configuration has been providedkubeconfig 找不到症状运行 Ark CLI 命令如ark backup create时直接报错invalid configuration: no configuration has been provided原因CLI 在启动时找不到可用的 kubeconfig 文件无法建立与 Kubernetes API Server 的连接。注意 v0.9.0 时期 Ark 客户端并非使用client-go的默认加载逻辑而是按下面的固定优先级查找 kubeconfig优先级查找位置说明1--kubeconfig标志指定的路径CLI 全局标志显式优先级最高2$KUBECONFIG环境变量指定的路径未传--kubeconfig时生效3~/.kube/config前两者均未指定时的兜底默认路径这一查找规则在 v0.9.0 与当前 main 版本的排错文档中完全一致分别见 v0.9.0 文档 与 main 文档。检查与修复步骤确认当前 kubeconfig 文件是否存在且内容合法ls -la ~/.kube/config并用kubectl cluster-info验证集群连通性若 kubeconfig 不在默认位置通过环境变量导出export KUBECONFIG/path/to/your/kubeconfig或者在使用 Ark CLI 时显式指定ark --kubeconfig /path/to/your/kubeconfig ...。原理补充从当前仓库源码看Velero 客户端配置已演进为独立的配置文件机制——pkg/client/config.go 中configFileName()返回$HOME/.config/velero/config.json用于存放命名空间、feature flags 等客户端偏好而 kubeconfig 的解析仍由 Kubernetes 客户端库完成。这解释了为何排查顺序是先查 kubeconfig、再查客户端配置文件。备份或恢复卡在New阶段症状ark backup get或ark restore get看到的任务长期停留在New状态没有任何推进。原因备份/恢复任务卡在New阶段说明控制器根本没有处理这些对象——通常意味着Ark 服务端没有运行。服务端控制器通过 watch 监听 Backup / Restore 自定义资源服务端不可用时新提交的任务就会一直停留在New。检查与修复步骤按以下两条命令查看服务端 Pod 描述与日志定位异常v0.9.0 默认命名空间为heptio-ark当前版本为velero# 查看服务端 Pod 的状态、事件与容器状态 kubectl -n heptio-ark describe pods # 查看 Ark 服务端 Deployment 的日志 kubectl -n heptio-ark logs deployment/ark修复方向视 describe/logs 结果而定镜像拉取失败ImagePullBackOff、凭证挂载失败详见下文云厂商部分、RBAC 权限不足、资源配额不足等都可能导致服务端无法就绪。修复后重新观察备份/恢复状态正常情况下任务应离开New阶段进入后续处理流程。原理补充当前版本的 pkg/install/install.go 中Install()会先创建 CRD 并轮询等待其就绪再创建其余资源而 DeploymentIsReady() 会持续轮询名为velero的 Deployment 的可用状态要求DeploymentAvailable条件为 True 且持续约 10 秒连续观测 5 次。这段实现印证了服务端 Deployment 必须真正可用、任务才会被消费的排错逻辑——若你采用velero install方式部署输出末尾的Velero is available提示就来自这类就绪探测。AWSNoCredentialProviders: no valid providers in chain症状Ark 服务端日志中出现NoCredentialProviders: no valid providers in chain原因存放 AWS IAM 用户凭证的 Secret 没有正确创建或没有正确挂载进 Ark 服务端 Pod。AWS SDK 在凭证提供者链环境变量、共享凭证文件、IAM 角色等中找不到任何有效凭证时即抛出该错误。检查清单逐项核对缺一不可cloud-credentialsSecret 存在于 Ark 服务端所在命名空间v0.9.0 为heptio-arkSecret 中只有一个键cloud其值必须是本地credentials-ark文件的完整内容credentials-ark文件格式正确、值无误——这是 AWS 共享凭证文件的标准 INI 格式[default] aws_access_key_idyour AWS access key ID aws_secret_access_keyyour AWS secret access keycloud-credentialsSecret 被定义为 Ark Deployment 的一个 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials目录。正确创建方式按 aws-config.md 中的安装流程先创建 IAM 用户heptio-ark并附加 S3 EC2 权限策略生成访问密钥后写入本地credentials-ark文件再创建 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_NAMESPACE \ --from-file cloudcredentials-ark注意--from-file cloud...这一写法cloud就是 Secret 中的键名值取自credentials-ark文件——这正是检查清单第 2 条单键cloud的来历。若改用其他键名服务端将无法读取凭证。挂载的源码级验证当前仓库的安装代码 pkg/install/deployment.go 明确生成了这样的挂载结构cloud-credentialsSecret 作为 volumeMountPath为/credentials随后多个环境变量如 AWS 相关的凭证文件路径的值指向/credentials/cloud。也就是说Secret 单键cloud 挂载到/credentials是 Ark/Velero 服务端的硬性约定pkg/install/resources.go 中的默认资源模板也定义了名为cloud-credentials的 Secret。任何一环缺失Secret 不存在、键名不对、volume 未定义、挂载路径不对都会导致 AWS SDK 在容器内找不到凭证文件。kube2iam 场景v0.9.0 文档附带说明若改用 kube2iam 通过 Pod 注解注入 IAM 角色则无需 API 密钥。此时报NoCredentialProviders往往意味着角色信任策略Trust Policy或 S3 权限配置不完整。AWS 侧需要准备 aws-config.md 中的策略文档并在 Ark Deployment 上添加iam.amazonaws.com/role: arn:aws:iam::AWS_ACCOUNT_ID:role/heptio-ark注解。main 版本的 debugging-install.md 对 kube2iam 场景单列了检查项一是确认存在允许 kube2iam 所用角色承担 Ark 角色的信任策略文档二是确认 Ark 角色拥有文档列出的全部 S3 权限。AzureFailed to refresh the Token或adal: Refresh request failed症状Ark 服务端日志出现 Azure AD 令牌刷新失败类错误Failed to refresh the Token或adal: Refresh request failed原因存放 Azure 服务主体Service Principal凭证的 Secret 未正确创建或未正确挂载进 Ark 服务端 Pod。Azure SDK 使用 ADAL 库获取/刷新访问令牌服务主体凭证缺失或错误时即抛出此类错误。检查清单cloud-credentialsSecret 存在于 Ark 服务端所在命名空间Secret有全部七个键且每个键的值都正确七个键的定义见下方cloud-credentialsSecret 被定义为 Ark Deployment 的 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials。七个键的完整定义与 AWS/GCP 的单键cloud不同Azure 场景下 Secret 以环境变量方式承载凭证必须包含 azure-config.md 中配置的全部七个键Secret 键对应环境变量含义AZURE_SUBSCRIPTION_ID${AZURE_SUBSCRIPTION_ID}Azure 订阅 IDAZURE_TENANT_ID${AZURE_TENANT_ID}Azure 租户 IDAZURE_RESOURCE_GROUP${AZURE_RESOURCE_GROUP}存放集群磁盘的资源组注意是创建集群时的第二个资源组AZURE_CLIENT_ID${AZURE_CLIENT_ID}服务主体的应用客户端IDAZURE_CLIENT_SECRET${AZURE_CLIENT_SECRET}服务主体密码AZURE_STORAGE_ACCOUNT_ID${AZURE_STORAGE_ACCOUNT_ID}备份存储账号 IDAZURE_STORAGE_KEY${AZURE_STORAGE_KEY}存储账号访问密钥正确创建方式先完成 azure-config.md 中的准备工作——创建存储账号与 blob 容器、创建带Contributor角色的服务主体再一次性把七个环境变量写入 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_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}排查要点排错时最容易遗漏的是AZURE_RESOURCE_GROUP——它必须指向创建 AKS 集群时自动生成的第二个资源组磁盘所在组而非你手动指定的集群资源组详见 azure-config.md 中的 WARNING 说明。若令牌刷新失败且 Secret 键值齐全优先用kubectl -n heptio-ark get secret cloud-credentials -o yaml检查七个键的值是否与az命令输出一致。GCE/GKEopen credentials/cloud: no such file or directory症状Ark 服务端日志中出现open credentials/cloud: no such file or directory原因存放 GCE 服务账号凭证的 Secret 未正确创建或未正确挂载进 Ark 服务端 Pod。Ark 服务端在启动时按/credentials/cloud路径读取 GCP 服务账号 JSON 文件路径不存在即报此错。检查清单cloud-credentialsSecret 存在于 Ark 服务端所在命名空间Secret 中只有一个键cloud其值是本地credentials-ark文件即 GCP 服务账号 JSON key的完整内容cloud-credentialsSecret 被定义为 Ark Deployment 的 volume该 Secret 被挂载到 Ark 服务端 Pod 的/credentials。正确创建方式按 gcp-config.md 的流程先创建服务账号并授权compute.disks.*、compute.snapshots.*等权限并通过gsutil iam ch授予 GCS 存储桶的objectAdmin再用gcloud iam service-accounts keys create credentials-ark生成 JSON 密钥文件最后创建 Secretkubectl create secret generic cloud-credentials \ --namespace ARK_NAMESPACE \ --from-file cloudcredentials-ark与 AWS 的异同GCP 的 Secret 结构和 AWS 完全一致单键cloud、挂载/credentials报错信息open credentials/cloud: no such file or directory恰好印证了服务端读取的正是/credentials/cloud这个路径。若报错持续存在按上述四条清单逐一核对最常见的两个原因是 Secret 根本没创建以及--from-file执行时不在credentials-ark文件所在目录导致键cloud的值为空或文件路径错误。三朵云排错对照速查表排查项AWSAzureGCE/GKE典型报错NoCredentialProvidersFailed to refresh the Token/adal: Refresh request failedopen credentials/cloud: no such file or directorySecret 键结构单键cloud七键环境变量单键cloud凭证载体credentials-arkINI 格式访问密钥七个 Azure 环境变量credentials-ark服务账号 JSON凭证来源文档aws-config.mdazure-config.mdgcp-config.mdSecret 挂载位置/credentialsvolume 挂载/credentialsvolume 挂载/credentialsvolume 挂载挂载实现源码pkg/install/deployment.go同上同上三类问题的公共根因完全一致cloud-credentialsSecret 未创建、键结构不对、未定义为 volume或未挂载到/credentials。因此三者的修复流程可以统一为四步kubectl get secret确认存在 → 校验键名与值 → 检查 Deployment 的 volumes 定义 → 检查容器的mountPath是否为/credentials。从 Ark 到 Velero排错文档的版本演进本文依据的 v0.9.0 文档属于项目早期Heptio Ark 时代其排查方法论沿用至今但有三点版本差异值得注意命名变化v0.9.0 文档中的命令与命名空间是ark/heptio-ark如kubectl -n heptio-ark logs deployment/arkmain 版本文档已改为velero/velerokubectl -n velero logs deployment/velero凭证文件名也从credentials-ark变为credentials-velero排查框架一致main 版 debugging-install.md 保留了通用 → AWS → Azure → GCE/GKE的完整框架和全部检查项仅增加了 kube2iam 场景的细分说明安装方式演进v0.9.0 采用编辑示例 YAML kubectl apply的手工安装如 aws-config.md 中的examples/aws/目录当前版本则推荐velero install命令由 pkg/install 包自动生成 Secret、Deployment 等资源并等待就绪——这也让凭证挂载由程序保证手工配置错误率大幅降低。无论使用哪个版本排错时请始终从官方文档的检查清单出发先确认客户端 kubeconfig 可连通集群再确认服务端 Pod 运行正常最后逐项核对cloud-credentialsSecret 的存在性、键结构与挂载路径。这四类报错的 90% 场景都能通过这一流程定位并解决。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考