如何在GitLab Web UI中自动移除因Kubernetes Pod失效而不可用的Runner

问题场景 #

在笔记本VM的私有Kubernetes集群中部署了GitLab代理与GitLab Runner Pod，用于测试CI/CD流水线。由于每天关机后重启集群，系统会自动部署新的GitLab Runner Pod并同步至GitLab实例，但旧Pod对应的Runner会留在GitLab列表中成为失效条目，多次重启后会堆积大量不可用的Runner。

示例说明：GitLab Runner列表中，下方条目为已销毁Pod对应的失效Runner，上方为集群重启后新生成的活跃Runner。

优化解决方案 #

1. 配置临时（Ephemeral）Runner模式 #

在GitLab Runner的Kubernetes部署配置中启用临时模式，让Runner Pod在销毁时自动向GitLab注销自身，避免留下失效记录：

• 在values.yaml中添加配置：

runner:
  kubernetes:
    ephemeral: true

该模式下，Runner Pod生命周期结束时会主动调用GitLab API注销，不会在GitLab中残留失效条目。

2. 利用GitLab API定期清理失效Runner #

编写脚本调用GitLab API，定期清理状态为not_connected的失效Runner，并将脚本部署为Kubernetes CronJob，实现自动清理：

1. 脚本示例（使用curl）：

#!/bin/bash
GITLAB_URL="https://your-gitlab-instance.com"
PROJECT_ID="your-project-id"
PRIVATE_TOKEN="your-access-token"

# 获取所有失效Runner的ID
RUNNER_IDS=$(curl -s --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" "$GITLAB_URL/api/v4/projects/$PROJECT_ID/runners" | jq -r '.[] | select(.status == "not_connected") | .id')

# 逐个删除失效Runner
for ID in $RUNNER_IDS; do
  curl -s --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" -X DELETE "$GITLAB_URL/api/v4/projects/$PROJECT_ID/runners/$ID"
done

2. 将脚本打包成镜像，创建CronJob定期执行（例如每天凌晨执行一次）。

3. 固定Runner注册标识 #

针对单Pod的测试场景，配置GitLab Runner使用固定的注册令牌与名称，这样每次重启Pod时会覆盖旧的Runner记录，不会生成新的条目：

• 在GitLab Runner配置文件中指定固定的token和name：

[[runners]]
  name = "fixed-k8s-runner"
  token = "your-fixed-runner-token"
  executor = "kubernetes"
  # 其他配置...

注意：该方案仅适合单Runner Pod的场景，多Pod会导致注册冲突。

4. 优化集群关机流程 #

在关闭VM前，先主动清理Runner并注销：

1. 执行kubectl delete deployment gitlab-runner删除Runner部署
2. 调用GitLab API注销当前活跃的Runner
   下次启动集群时重新部署Runner，不会留下旧的失效条目。

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