Windows环境GitLab Runner使用kubernetes执行器报未提供K8s配置错误

问题详情 #

• 运行环境：Windows主机安装的GitLab Runner，关联Docker Desktop提供的本地Kubernetes集群
• 异常现象：Runner此前可正常作业，现在Pipeline准备阶段报错，日志提示ERROR: Preparation failed: getting Kubernetes config: invalid configuration: no configuration has been provided
• 已完成的排查动作：
  • 查阅多个公开的GitLab Runner相关issue、同类报错的技术方案，均未生效
  • GitLab控制台中Runner状态为正常在线（绿色运行标识）
  • 确认Kubernetes配置文件存在于用户主目录的.kube路径下，本地执行kubectl get pods可正常返回集群信息
• 当前Runner的config.toml核心配置：

concurrent = 5
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "kubernetes runner"
  url = "https://gitlab.com/"
  token = "My_Token"
  executor = "kubernetes"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.kubernetes]
    host = ""
    bearer_token_overwrite_allowed = false
    image = ""
    namespace = ""
    namespace_overwrite_allowed = ""
    privileged = false
    service_account_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.affinity]
    [runners.kubernetes.pod_security_context]
    [runners.kubernetes.volumes]
    [runners.kubernetes.dns_config]

• 存疑点：怀疑Windows环境下GitLab Runner无法正确识别Kubernetes配置路径，但该配置此前可正常运行，无其他配置变更。

排查与解决方案 #

1. 核心原因定位
   GitLab Runner在Windows环境下不会自动继承系统的Kubeconfig路径扫描规则，且当前config.toml的[runners.kubernetes]段所有字段为空，完全依赖自动路径发现逻辑；如果Runner以Windows服务形式运行，默认使用的本地系统账户无权访问当前登录用户目录下的.kube配置文件。
   此前可正常运行、现在报错的常见触发原因：之前是手动用当前用户身份前台启动的Runner，后来改为服务运行，或者服务的运行账户被系统默认重置为Local System，导致路径访问权限丢失。
2. 分步修复操作
   • 第一步：确认Runner运行身份
     • 打开Windows服务管理器，找到GitLab Runner对应的服务，查看“登录”标签页的运行账户：
       • 若使用默认的Local System账户，有两种修复路径可选：一是将服务运行账户修改为当前登录的Windows用户（需赋予对应服务本地登录权限）；二是直接在配置文件中显式指定Kubeconfig的绝对路径，完全不依赖自动路径发现。
   • 第二步：显式补全Kubernetes相关配置
     • 找到本地Kubeconfig的绝对路径，例如默认路径为C:\Users\你的用户名\.kube\config
     • 在config.toml的[runners.kubernetes]段中添加配置，注意Windows路径的反斜杠需要转义为双反斜杠：

       [runners.kubernetes]
         config_file = "C:\\Users\\你的用户名\\.kube\\config"
         # 补全原本为空的必填字段，否则加载配置后会触发其他权限或镜像拉取报错
         image = "alpine:latest"
         namespace = "gitlab-runner"
       

     • 提前在Kubernetes集群中创建gitlab-runner命名空间，并为关联的服务账户赋予创建、管理Pod的基础权限。
   • 第三步：重载配置生效
     • 修改完config.toml后，重启GitLab Runner服务，或停止前台运行的Runner进程后重新启动，修改的配置才会被加载。
3. 快速验证方案
   • 停止GitLab Runner的Windows服务，使用当前登录的Windows用户打开终端，手动执行gitlab-runner run启动前台进程：
     • 如果前台运行时不再报配置缺失的错误，即可100%确认是服务运行账户的路径访问权限问题。
4. 额外注意事项
   • Docker Desktop自带的Kubernetes集群重启后，可能会重置Kubeconfig的默认上下文，可通过执行kubectl config current-context确认当前上下文指向Docker Desktop集群，避免上下文偏移导致加载配置无效。

内容的提问来源于stack exchange，提问作者Sabir Moglad