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 按以下优先级顺序查找--kubeconfig命令行标志指定的路径如有$KUBECONFIG环境变量指定的路径如有默认路径~/.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.gofunc 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 regionus-east-2 \ --snapshot-location-config regionus-east-23.2 挂载与环境变量注入创建 Secret 后pkg/install/deployment.go 会向 Velero Deployment 追加以下内容Node Agent DaemonSet 同理见 pkg/install/daemonset.go一个名为cloud-credentials的 VolumeDefaultMode: 0444只读挂载到 Pod 的/credentials路径四个环境变量均指向/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。四、AWSNoCredentialProviders: no valid providers in chain使用静态凭据IAM 用户密钥时的排查清单该报错意味着存放 AWS IAM 用户凭据的 Secret 未正确创建/挂载。请逐项确认cloud-credentialsSecret 存在于 Velero Server 所在命名空间默认veleroSecret 只有单个键cloud其值为credentials-velero文件的完整内容credentials-velero文件格式正确、取值正确[default] aws_access_key_id你的 AWS Access Key ID aws_secret_access_key你的 AWS Secret Access Keycloud-credentials已作为 Volume 定义在 Velero Deployment 中该 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使用 kube2iamPod 角色注入时的排查清单该报错意味着 Velero 无法读取 S3 桶。请确认存在信任策略Trust Policy允许 kube2iam 使用的角色 assume Velero 的 IAM 角色按 AWS 配置文档操作Velero 新角色拥有文档中列出的全部 S3 相关权限此方式无需静态密钥凭据由节点侧代理注入因此不再依赖cloud-credentials的 AWS 键值正确性但对 IAM 角色链的配置要求更高。五、AzureFailed to refresh the Token/adal: Refresh request failed该报错意味着存放 Azure 服务主体Service Principal凭据的 Secret 未正确创建/挂载到 Velero Server Pod。请确认cloud-credentialsSecret 存在于 Velero Server 命名空间Secret 包含全部预期键且取值正确按 Azure 安装文档创建服务主体后生成凭据文件velero install对该文件采用AZURE_CREDENTIALS_FILE方式注入见 3.2 节环境变量列表cloud-credentials已作为 Volume 定义在 Velero Deployment 中Secret 已挂载到 Pod 的/credentials路径Token 刷新失败除 Secret 缺失外也常源于服务主体缺少桶对应资源组/存储账户的访问权限可对照 Azure 安装文档核对权限范围。六、GCE/GKEopen credentials/cloud: no such file or directory注意这条报错直接暴露了挂载路径/credentials/cloud是Secret 未创建或未挂载最直白的信号。该报错意味着存放 GCE 服务账户凭据的 Secret 未正确创建/挂载。请确认cloud-credentialsSecret 存在于 Velero Server 命名空间Secret 只有单个键cloud其值为credentials-velero文件GCP 服务账户 JSON的完整内容cloud-credentials已作为 Volume 定义在 Velero Deployment 中Secret 已挂载到 Pod 的/credentials路径GCP SDK 通过环境变量GOOGLE_APPLICATION_CREDENTIALS/credentials/cloud定位该文件见 pkg/install/deployment.go因此若 Pod 中该环境变量缺失即使 Secret 存在也会报同样错误。七、故障排查路径总结报错故障层首个检查动作invalid configuration: no configuration has been provided客户端检查--kubeconfig/$KUBECONFIG/~/.kube/config备份/恢复卡在New服务端kubectl -n velero describe pods与kubectl -n velero logs deployment/veleroNoCredentialProvidersAWS凭据 Secret检查cloud-credentials键cloud的内容与挂载Failed to refresh the TokenAzure凭据 Secret检查服务主体凭据文件键值与挂载open credentials/cloud: no such file or directoryGCE凭据 Secret/挂载检查/credentials挂载与环境变量核心排查思路可归纳为三问客户端能否连接集群Server Pod 是否在运行并处理任务cloud-credentialsSecret 的存在 → 键值 → Volume → 挂载 → 环境变量五个环节是否全部就位按照 3.2 节列出的挂载机制逐项核对即可覆盖绝大多数安装期凭据故障。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考