如何解决Kubernetes集群中GitLab Runner的KUBERNETES_MASTER配置错误

我搭建了两台Ubuntu 22.04 Server虚拟机用于学习CI/CD、GitLab、Kubernetes及云计算技术：

• VM1 - MicroK8s Kubernetes集群：默认配置，已部署PostGIS、GeoServer Pod及对应服务（通过内部IP和externalIp暴露）；安装了GitLab Runner（计划用Kubernetes执行器）和GitLab Kubernetes Agent，二者在VM2中均显示已连接。后续打算部署VM2中的Leaflet+Django地图应用Pod，与GeoServer交互。
• VM2 - GitLab：默认安装最新版GitLab，已在/etc/gitlab/gitlab.rb中启用agent server。

原本VM1的GitLab Runner用Docker执行器正常，切换到Kubernetes执行器后，运行GitLab默认伪CI/CD流水线（含build、test、deploy阶段，仅执行echo和等待）时出现以下错误：

Running with gitlab-runner 15.8.2 (4d1ca121)
  on testcluster-k8s-runner Hko2pDKZ, system ID: s_072d6d140cfe
Preparing the "kubernetes" executor
Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: getting Kubernetes config: invalid configuration: no configuration has been provided, try setting KUBERNETES_MASTER environment variable
Will be retried in 3s ...
Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: getting Kubernetes config: invalid configuration: no configuration has been provided, try setting KUBERNETES_MASTER environment variable
Will be retried in 3s ...
Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: getting Kubernetes config: invalid configuration: no configuration has been provided, try setting KUBERNETES_MASTER environment variable
Will be retried in 3s ...
ERROR: Job failed (system failure): getting Kubernetes config: invalid configuration: no configuration has been provided, try setting KUBERNETES_MASTER environment variable

我不清楚KUBERNETES_MASTER的定义和配置位置，尝试将使用microk8s kubectl的用户的.kube目录复制到/home/gitlab-runner/.kube，但问题未解决。

1. 理解KUBERNETES_MASTER #

KUBERNETES_MASTER是指定Kubernetes API服务器地址的环境变量，格式为https://<集群IP>:<API端口>（MicroK8s默认API端口是16443）。不过更推荐通过GitLab Runner配置文件或kubeconfig来管理集群访问，而非直接设置环境变量。

2. 正确获取MicroK8s的kubeconfig #

MicroK8s的kubeconfig默认存放在/var/snap/microk8s/current/credentials/client.config，而非普通用户的~/.kube/config。执行以下命令将其复制给gitlab-runner用户并调整权限：

# 创建gitlab-runner用户的.kube目录
sudo mkdir -p /home/gitlab-runner/.kube
# 复制MicroK8s的kubeconfig文件
sudo cp /var/snap/microk8s/current/credentials/client.config /home/gitlab-runner/.kube/config
# 修改文件所属用户和权限
sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner/.kube/config
sudo chmod 600 /home/gitlab-runner/.kube/config

3. 配置GitLab Runner的config.toml #

编辑GitLab Runner的配置文件/etc/gitlab-runner/config.toml，在对应的[[runners]]块下添加[kubernetes]配置段，指定kubeconfig路径：

[[runners]]
  name = "testcluster-k8s-runner"
  url = "https://<VM2-GitLab地址>/ci"
  token = "Hko2pDKZxxxxxxxxxx"
  executor = "kubernetes"
  [kubernetes]
    namespace = "gitlab-runner"
    kubeconfig = "/home/gitlab-runner/.kube/config"
    # 可选：如果kubeconfig里的地址是localhost，可手动指定master_url为VM1的IP
    # master_url = "https://<VM1-IP>:16443"

4. 重启GitLab Runner服务 #

使配置生效：

sudo gitlab-runner restart

5. 验证配置 #

执行以下命令测试gitlab-runner用户能否正常访问MicroK8s集群：

sudo -u gitlab-runner kubectl --kubeconfig=/home/gitlab-runner/.kube/config get nodes

如果能返回集群节点信息，说明配置正确，重新运行CI流水线即可。

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