Linux环境下部署Gitlab Runner配合k8s实现自动发布（CI/CD）

Gitlab Runner注册失败主因是ServiceAccount权限不足或网络不通；CI中kubectl失败因缺少二进制或kubeconfig；DinD误用致Job Pending；发布后CrashLoopBackOff因CI不校验Pod就绪状态。

在Kubernetes上搭建GitLab CI/CD流水线，听起来很美好，但实际落地时，几个“坑”总是反复出现。Runner注册不上、流水线里的命令执行失败、Job一直卡着、或者明明CI显示成功了，应用却起不来。这些问题看似分散，其实背后都指向几个关键配置环节。下面就来逐一拆解这些高频故障点。

Gitlab Runner注册到Kubernetes集群失败的常见原因

当你执行gitlab-runner register命令后，如果注册失败，先别急着怀疑Runner安装有问题。十有八九，问题出在ServiceAccount的权限或者网络连通性上。

道理很简单：GitLab Runner在K8s里是以Pod形式运行的。这个Pod需要能跟API Server“对话”，地址就是https://kubernetes.default.svc。同时，它绑定的serviceaccount必须拥有足够的权限，去创建和管理后续CI Job所需的Pod、ConfigMap、Secret等资源。

所以，排查可以遵循以下路径：

首先，验证基础连通性。可以进入Runner Pod（如果它能起来的话），执行curl -k https://kubernetes.default.svc。如果返回403（Forbidden），那说明网络是通的，只是权限不够；如果出现timeout或connection refused，那就是网络层面的问题，需要检查集群内DNS和服务发现。

其次，聚焦权限。检查gitlab-runner这个ServiceAccount绑定的ClusterRole。很多人图省事直接绑view角色，这只能看，不能创建Pod，肯定不行。生产环境建议使用edit角色，或者根据最小权限原则自定义一个角色。

再者，注意命名空间的一致性。注册命令里--kubernetes-namespace参数指定的命名空间，必须和Runner实际部署的命名空间一致，并且确保该命名空间下已经创建了对应的ServiceAccount。张冠李戴是注册失败的常见原因。

最后，留意镜像拉取。如果注册时使用了--kubernetes-image指向私有仓库的镜像，却忘了在Pod Spec中配置对应的imagePullSecrets，那么Runner Pod自身就会卡在ImagePullBackOff状态，自然无法完成注册。

CI流水线中before_script里kubectl命令执行失败

流水线配置好了，第一个Job也触发了，结果在before_script阶段执行kubectl get pods就报错。这通常是因为环境不对。

默认情况下，GitLab Runner容器里跑的用户是gitlab-runner，这个用户环境里很可能根本没有安装kubectl这个命令行工具。即便你从宿主机把/root/.kube/config配置文件挂载进去了，也常常会因为文件权限（非root用户无法读取）或者上下文（Context）不对而失败。

解决思路很直接：

第一，显式安装kubectl。不要依赖任何预设环境。在.gitlab-ci.yml文件的before_script里，根据基础镜像类型安装。比如Alpine镜像用apk add --no-cache kubectl，Debian/Ubuntu系镜像用apt-get update && apt-get install -y kubectl。

第二，明确指定kubeconfig。使用kubectl --kubeconfig /path/to/config或者--context=your-context-name来明确告诉kubectl使用哪个配置，避免它去默认路径（$HOME/.kube）寻找。

第三，更推荐的方式：使用ServiceAccount认证。这是K8s集群内Pod访问API的标准方式。你需要在定义Job时，通过Runner的Kubernetes Executor配置指定service_account。例如：

job_name:
  kubernetes:
    namespace: my-namespace
    image: alpine:latest
    service_account: gitlab-runner-sa

这样，Pod启动后会自动挂载Token和CA证书到/var/run/secrets/kubernetes.io/serviceaccount/目录下，kubectl会自动使用这些凭证，无需手动管理config文件。当然，前提是你得提前创建好这个gitlab-runner-sa并绑定好RBAC权限。如果这个ServiceAccount在default命名空间不存在，那么kubectl get pods自然会返回Forbidden错误。

image字段写docker:stable-git但Job一直Pending

这个场景非常典型，属于Docker-in-Docker（DinD）的经典误用。很多人在CI Job里想构建Docker镜像，就顺手把image指定为docker:stable-git，结果Job一直处于Pending状态。

原因在于：GitLab Runner的Kubernetes Executor只是提供了一个Pod运行环境，它本身并不提供Docker守护进程（dockerd）。docker:stable-git这个镜像只包含了Docker客户端（CLI），没有服务端。它试图在容器内启动一个Docker守护进程，这在没有特权模式且未挂载Docker Socket的普通Pod里是不可能成功的。

那么，正确的做法是什么？

首选方案是使用Kaniko。这是一个专门用于在Kubernetes或容器化环境中构建镜像的工具，它不需要Docker守护进程，也不需要特权模式。在.gitlab-ci.yml中可以这样配置：

build:
  image: gcr.io/kaniko-project/executor:v1.22.0
  script:
    - /kaniko/executor
      --context $CI_PROJECT_DIR
      --dockerfile $CI_PROJECT_DIR/Dockerfile
      --destination $YOUR_REGISTRY/your-image:tag

如果因特殊原因必须使用Docker CLI（例如某些本地测试场景），则必须确保Runner的配置允许特权模式，并在Pod模板中挂载宿主机的Docker Socket：

[[runners.kubernetes.pod_security_context]]
  privileged = true
[[runners.kubernetes.volumes]]
  name = "docker-sock"
  mount_path = "/var/run/docker.sock"
  host_path = "/var/run/docker.sock"

需要注意的是，出于安全考虑，绝大多数生产环境的K8s集群会禁止这种特权挂载。

另外两个小贴士：一是docker:stable-git镜像本身不包含git命令，如果你的script里有git clone操作，需要先apk add git。二是国内环境可能遇到镜像拉取超时，可以在Runner的ConfigMap中配置镜像仓库地址，并确保配置了正确的image_pull_secrets。

发布后Pod始终CrashLoopBackOff，但CI显示Success

这是最让人困惑的情况之一：GitLab CI流水线一片绿色，显示部署成功，但跑到K8s集群里一看，新发布的Pod却在不断重启（CrashLoopBackOff）。

问题根源在于：CI/CD流水线里的部署任务（比如kubectl apply -f deploy.yaml）只负责把资源声明提交给K8s API Server。一旦提交成功，这个CI Job就认为任务完成，标记为Success。它不会去等待Pod真正启动完成，更不会去检查Pod内部容器的健康状态。后续的镜像拉取失败、应用启动报错、配置错误等，都和CI流水线“无关”了。

要解决这个问题，必须把健康检查的环节纳入CI流程：

第一，在CI脚本末尾增加主动等待和探测。在kubectl apply之后，加上一条等待命令：

kubectl wait --for=condition=ready pod -l app=myapp --timeout=120s -n my-namespace

这条命令会阻塞，直到指定标签的Pod状态变为Ready，或者超时。如果超时或失败，整个CI Job就会失败，从而在流水线上给出明确的红色错误信号。

第二，确保Deployment配置了完善的探针。在应用的deploy.yaml里，必须设置livenessProbe（存活探针）和readinessProbe（就绪探针）。没有这些探针，Kubernetes就无法判断你的应用何时才算真正启动成功、何时健康。

第三，注意镜像标签策略。如果CI构建的镜像标签是latest，而集群节点上已经存在同名的latest镜像，K8s可能会因为imagePullPolicy设置为IfNotPresent而跳过拉取，导致运行的还是旧版本代码。建议使用$CI_COMMIT_TAG或$CI_PIPELINE_ID这类唯一标识作为镜像标签。

当出现CrashLoopBackOff时，最快的排查方法是：

kubectl describe pod -n my-namespace 

重点看输出末尾的Events字段。这里通常会直接告诉你根本原因，比如“镜像拉取失败”、“OOMKilled（内存不足）”、“找不到ConfigMap”等，这比直接看容器日志（kubectl logs）更高效。

说到底，CI流水线的绿色只是一个开始。真正的考验在于K8s集群内部的细节：RBAC权限是否精细、镜像仓库的认证方式是否正确、探针的配置是否与应用的实际启动时间匹配……如果不把这些环节放到真实的Pod生命周期里去验证，那么CI流水线的一片绿色，反而可能掩盖了部署的失败。