Velero 安装问题调试指南：kubeconfig、cloud-credentials 凭据 Secret 与备份卡住故障排查

Velero 安装问题调试指南：kubeconfig、cloud-credentials 凭据 Secret 与备份卡住故障排查

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

本文基于 Velero 官方文档（site/content/docs/v1.10/debugging-install.md）整理并结合仓库源码，系统讲解 Velero 安装阶段最常见的四类故障：客户端找不到 kubeconfig、备份/恢复任务卡在New阶段、以及 AWS/Azure/GCE 三大云厂商的凭据 Secret 配置错误。读完本文，你将能够依据报错信息快速定位到具体故障环节，并通过源码级机制（凭据 Secret 的创建、挂载与环境变量注入）理解 Velero 插件获取云凭据的完整链路。

一、通用故障：客户端找不到 kubeconfig

报错信息

invalid configuration: no configuration has been provided

该错误表示 Velero 客户端找不到任何可用的kubeconfig文件。Velero 按以下优先级顺序查找：

1. --kubeconfig命令行标志指定的路径（如有）
2. $KUBECONFIG环境变量指定的路径（如有）
3. 默认路径~/.kube/config

源码印证：查找顺序的实现

这条查找链直接来自 Kubernetes 官方 client-go 库的加载规则。在 pkg/client/client.go 中，Config()函数的核心逻辑为：

func Config(kubeconfig, kubecontext, baseName string, qps float32, burst int) (*rest.Config, error) { loadingRules := clientcmd.NewDefaultClientConfigLoadingRules() loadingRules.ExplicitPath = kubeconfig // 对应 --kubeconfig 标志 ... clientConfig, err := kubeConfig.ClientConfig() if err != nil { return nil, errors.Wrap(err, "error finding Kubernetes API server config in --kubeconfig, $KUBECONFIG, or in-cluster configuration") } ... }

从源码结构看：NewDefaultClientConfigLoadingRules()先取ExplicitPath（即--kubeconfig），再回落到$KUBECONFIG与~/.kube/config；当三级都落空时，client-go 返回invalid configuration: no configuration has been provided，外层再包装为上文所述的错误信息。

排查步骤

• 检查--kubeconfig路径是否正确、文件是否存在
• 检查echo $KUBECONFIG是否指向有效文件
• 确认~/.kube/config存在且包含目标集群的 context
• 注意区分：Velero 客户端还有一份自身配置 pkg/client/config.go，即~/.config/velero/config.json（存储namespace、namespace-mode、features、cacert等选项，缺失时仅返回空 map 不会报错）。文档中这条invalid configuration错误与 kubeconfig 相关，而非该客户端配置文件，两者不要混淆

二、通用故障：备份/恢复卡在New阶段

报错现象

创建备份或恢复后，velero backup describe显示任务长时间停留在New阶段。

原因分析

New意味着 Velero 的控制器（controllers）还没有开始处理该备份/恢复对象，通常原因是 Velero Server 根本没有在运行（Pod 启动失败、崩溃重启、或 Deployment 被误删）。

排查命令

# 查看 Pod 描述，重点看 Events、重启次数与失败原因 kubectl -n velero describe pods # 查看 Velero 服务端日志，搜索 ERROR 关键字 kubectl -n velero logs deployment/velero

若日志中反复出现凭据相关报错（见下文各云厂商小节），说明 Server 起来了但对象存储访问失败；若 Deployment 本身不存在或 Pod 处于CrashLoopBackOff，则回到安装环节检查velero install输出与集群 RBAC 配置（可参考 RBAC 文档 与 基础安装文档）。

三、凭据 Secret 机制：理解各云报错的共同根因

三大云厂商的凭据报错（下文第四、五、六节）本质都是同一个问题：cloud-credentialsSecret 没有正确创建或挂载到 Velero Server Pod。先理解其机制，排查才有方向。

3.1 Secret 的创建

velero install时传入的--secret-file文件内容，会被原样写入名为cloud-credentials的 Secret 的单个键cloud。这一点在 pkg/cmd/cli/install/install.go 的命令说明中明确写道：

The provided secret data will be created in a Secret named 'cloud-credentials'.

实现层面见 pkg/install/resources.go：

func Secret(namespace string, data []byte) *corev1api.Secret { return &corev1api.Secret{ ObjectMeta: objectMeta(namespace, "cloud-credentials"), ... Data: map[string][]byte{ "cloud": data, // 凭据文件内容整体存入 cloud 键 }, Type: corev1api.SecretTypeOpaque, } }

安装命令示例（AWS 场景）：

velero install --provider aws \ --plugins velero/velero-plugin-for-aws:v1.0.0 \ --bucket backups \ --secret-file ./aws-iam-creds \ --backup-location-config region=us-east-2 \ --snapshot-location-config region=us-east-2

3.2 挂载与环境变量注入

创建 Secret 后，pkg/install/deployment.go 会向 Velero Deployment 追加以下内容（Node Agent DaemonSet 同理，见 pkg/install/daemonset.go）：

1. 一个名为cloud-credentials的 Volume（DefaultMode: 0444只读）
2. 挂载到 Pod 的/credentials路径
3. 四个环境变量，均指向/credentials/cloud，供各云 SDK 自动发现凭据文件：

GOOGLE_APPLICATION_CREDENTIALS: /credentials/cloud # GCP AWS_SHARED_CREDENTIALS_FILE: /credentials/cloud # AWS AZURE_CREDENTIALS_FILE: /credentials/cloud # Azure ALIBABA_CLOUD_CREDENTIALS_FILE: /credentials/cloud # 阿里云

也就是说：SDK 读到的是 Secretcloud键挂载后的文件，文件格式必须由对应云插件/SDK 能解析。设计细节可进一步参阅 Secret 设计文档 与早期安装清单示例 aws-plugin.yaml。

四、AWS：NoCredentialProviders: no valid providers in chain

使用静态凭据（IAM 用户密钥）时的排查清单

该报错意味着存放 AWS IAM 用户凭据的 Secret 未正确创建/挂载。请逐项确认：

1. cloud-credentialsSecret 存在于 Velero Server 所在命名空间（默认velero）
2. Secret 只有单个键cloud，其值为credentials-velero文件的完整内容
3. credentials-velero文件格式正确、取值正确：

[default] aws_access_key_id=<你的 AWS Access Key ID> aws_secret_access_key=<你的 AWS Secret Access Key>

4. cloud-credentials已作为 Volume 定义在 Velero Deployment 中
5. 该 Secret 已挂载到 Velero Server Pod 的/credentials路径

可结合 3.2 节确认环境变量AWS_SHARED_CREDENTIALS_FILE=/credentials/cloud是否存在于 Pod 中：

kubectl -n velero get deployment velero -o yaml | grep -A2 "AWS_SHARED_CREDENTIALS_FILE" kubectl -n velero exec deployment/velero -- cat /credentials/cloud

使用 kube2iam（Pod 角色注入）时的排查清单

该报错意味着 Velero 无法读取 S3 桶。请确认：

1. 存在信任策略（Trust Policy），允许 kube2iam 使用的角色 assume Velero 的 IAM 角色（按 AWS 配置文档操作）
2. Velero 新角色拥有文档中列出的全部 S3 相关权限

此方式无需静态密钥，凭据由节点侧代理注入，因此不再依赖cloud-credentials的 AWS 键值正确性，但对 IAM 角色链的配置要求更高。

五、Azure：Failed to refresh the Token/adal: Refresh request failed

该报错意味着存放 Azure 服务主体（Service Principal）凭据的 Secret 未正确创建/挂载到 Velero Server Pod。请确认：

1. cloud-credentialsSecret 存在于 Velero Server 命名空间
2. Secret 包含全部预期键且取值正确（按 Azure 安装文档创建服务主体后生成凭据文件，velero install对该文件采用AZURE_CREDENTIALS_FILE方式注入，见 3.2 节环境变量列表）
3. cloud-credentials已作为 Volume 定义在 Velero Deployment 中
4. Secret 已挂载到 Pod 的/credentials路径

Token 刷新失败除 Secret 缺失外，也常源于服务主体缺少桶对应资源组/存储账户的访问权限，可对照 Azure 安装文档核对权限范围。

六、GCE/GKE：open credentials/cloud: no such file or directory

注意这条报错直接暴露了挂载路径/credentials/cloud，是"Secret 未创建或未挂载"最直白的信号。该报错意味着存放 GCE 服务账户凭据的 Secret 未正确创建/挂载。请确认：

1. cloud-credentialsSecret 存在于 Velero Server 命名空间
2. Secret 只有单个键cloud，其值为credentials-velero文件（GCP 服务账户 JSON）的完整内容
3. cloud-credentials已作为 Volume 定义在 Velero Deployment 中
4. Secret 已挂载到 Pod 的/credentials路径

GCP SDK 通过环境变量GOOGLE_APPLICATION_CREDENTIALS=/credentials/cloud定位该文件（见 pkg/install/deployment.go），因此若 Pod 中该环境变量缺失，即使 Secret 存在也会报同样错误。

七、故障排查路径总结

核心排查思路可归纳为三问：客户端能否连接集群？Server Pod 是否在运行并处理任务？cloud-credentialsSecret 的"存在 → 键值 → Volume → 挂载 → 环境变量"五个环节是否全部就位？按照 3.2 节列出的挂载机制逐项核对，即可覆盖绝大多数安装期凭据故障。

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