运维
controller 以 Runner 上的事件报告问题,因此请从以下命令开始:
kubectl -n <namespace> describe runner <name>kubectl -n <namespace> get runner,pod,pvckubectl -n <namespace> describe pod <pod>kubectl -n runner-controller-system logs deploy/runner-controller-controller-managerrunner Pod 中运行 runner 的容器名为 runner:kubectl -n <namespace> logs <pod> -c runner 可以查看 runner 的运行情况。
Runner 持续出错时,controller 会以逐渐增大的间隔重试。编辑该 Runner 会触发立即重试。
| 事件 | 原因与处理 |
|---|---|
RuntimeNotSet |
Runner 既未设置 runtime 也未设置 kubernetesRuntime,只会出现在升级到 0.7.10 之前创建的 Runner 上。controller 暂停处理该 Runner。请设置其中之一及其 labels。 |
InspectGiteaFailed,状态码 403 |
Gitea Enterprise 的许可证缺失或无效。修复之前,controller 不会创建 runner Pod。 |
InspectGiteaFailed,状态码 401 |
注册令牌已在 Gitea 中重置或删除。请用当前的令牌更新 registrationTokenSecretRef 引用的 Secret(或 registrationToken)。 |
InspectGiteaFailed,状态码 404 |
instanceUrl 指向的不是有效 Gitea Enterprise 实例,见 Gitea 地址。 |
InspectGiteaFailed,没有状态码 |
controller 无法访问 Gitea:请检查 instanceUrl、controller 与 Gitea 之间的网络,以及证书,见自签名证书。 |
RegistrationTokenUnavailable |
registrationTokenSecretRef 引用的 Secret 或其键不存在或为空,或值带有首尾空白,见注册令牌。 |
RegisterRunnerFailed |
controller 无法向 Gitea 注册 runner。请检查 instanceUrl、令牌,以及 controller 与 Gitea 之间的网络。 |
BuildRunnerWorkerFailed |
Runner 引用的内容缺失或无效,消息中会指明:runnerEnv 或 runnerEnvFrom 的 Secret 或 ConfigMap(runner environment)、S3 密钥(cache S3 credentials)、外部缓存服务器的密钥(cache server external secret)、重复或与 controller 自带卷同名的 volumeName(is taken、is the controller's)、init container(runnerInitContainers),或自定义配置文件中设置了不应设置的 runner.file。修复之前,controller 暂停调整该 Runner 的 runner Pod:不伸缩、不应用变更,已在运行的 runner Pod 继续运行。仅在需要运行 runner Pod 时才会检查。 |
ApplyRunnerWorkerFailed,提到 violates PodSecurity |
命名空间不允许这些 runner Pod:Docker-in-Docker 后端的特权 Pod,或 Kubernetes 后端中不满足 restricted 的 init container。 |
ApplyRunnerWorkerFailed,提到 exists but is not managed by this Runner |
Kubernetes 后端:已存在同名的 ServiceAccount 或 RoleBinding,见权限。 |
InvalidJobPodTemplate |
Kubernetes 后端:job Pod 模板无效,修正之前 controller 暂停处理该 Runner,见模板无效时。 |
RunnerInitContainerFailed |
某个 init container 失败或无法启动。事件中附有退出码与日志末尾,kubectl -n <namespace> logs <pod> -c <init container> 可查看完整日志。 |
RunnerRegisteredItself |
runner 没有使用 controller 提供的注册信息,或同一范围内另有同名 runner 在线。请检查 runner 容器的日志。 |
RunnerNotOnline |
runner 已运行 3 分钟仍未在 Gitea 上线。请查看 runner 容器的日志。若日志显示它在尝试注册,例如出现 token is empty,说明该镜像版本与 controller 不兼容。 |
DestroyWorker |
某个 runner Pod 未能上线,已重新创建,缓存被清空,见下文。 |
GracePeriodTooSmall |
terminationGracePeriodSeconds 小于 shutdownTimeout,任务可能在完成前被终止。 |
JobTmpfsMemoryTooSmall |
内存请求或上限容纳不下 jobTmpfs,见 tmpfs 的内存。 |
CachePVCClassChangeIgnored、CachePVCShrinkIgnored、CachePVCExpandUnsupported |
某项存储变更需要新建存储卷,而 allowDeleteCachePVC 不允许,见更换 StorageClass 或调整容量。 |
| 现象 | 原因与处理 |
|---|---|
创建或修改 Runner 时报错 one of runtime and kubernetesRuntime must be set 或 labels: Required value |
请设置 runtime 或 kubernetesRuntime 之一,并写出工作流在 runs-on 中使用的 labels,见 label。 |
存储卷一直处于 Pending |
不存在该名称的 StorageClass,或它不支持动态供应。className 默认为 standard,见 runner Pod 的存储卷。kubectl describe pvc 会显示原因。 |
Pod 处于 Pending,提示 volume node affinity conflict |
没有节点能在其存储卷所在的位置运行该 Pod,见存储要求。若存储卷绑定的节点已不存在,请删除存储卷与 Pod:先执行 kubectl -n <namespace> delete pvc <runner pod>-action-cache <runner pod>-cache --wait=false(-cache 仅 Docker-in-Docker 有),再执行 kubectl -n <namespace> delete pod <runner pod>。controller 会用新的空存储卷重新创建该 Pod。 |
Pod 处于 Pending,提示没有匹配的节点 |
nodeSelector 没有匹配的节点、某个 taint 未被容忍,或集群资源不足。 |
| 扩容需要几分钟 | 从零扩容时属于正常现象:冷启动包括新建节点(如需要)和拉取镜像。可用 minSize 保留常驻的 runner。 |
配置变更后 runner Pod 没有重建,并出现 RollDeferred 事件 |
这些 runner Pod 正在执行任务,任务完成后会重建,见配置变更如何生效。 |
| 任务连接 Docker 失败 | Docker-in-Docker 后端:runner 镜像不是 -dind 版本。 |
| 配置代理后 runner 无法上线、工作流缓存失效,或无法创建 job Pod | NO_PROXY 遗漏了某个地址,见代理。 |
| 使用 S3 时工作流缓存始终未命中 | runner 容器的日志中有 sync S3 cache 或 upload cache to S3 相关的错误:请检查 endpoint、region、密钥与权限(包括存储桶策略)。 |
| 使用内置缓存服务器时工作流缓存始终未命中 | 集群域名不是 cluster.local:请设置 cacheServer.host,见内置缓存服务器。 |
controller 日志或警告事件中出现 system:serviceaccount:runner-controller-system:runner-controller-controller-manager 的 forbidden 错误 |
controller 缺少权限,见缺少权限。 |
Kubernetes 后端:任务失败,提示 pods is forbidden |
runner 的 ServiceAccount 缺少权限,见权限。 |
Kubernetes 后端:任务失败,提示 violates PodSecurity |
job Pod 不满足命名空间的级别,见 Pod Security 级别。 |
Kubernetes 后端:任务下载 action 失败,runner 容器的日志中出现 permission denied |
StorageClass 不支持 fsGroup,见存储。使用自定义配置文件时,可能是缺少 host.workdir_parent,见使用自定义 runner 配置文件。 |
Kubernetes 后端:job Pod 因磁盘压力或 ephemeral-storage 被驱逐 |
节点磁盘容纳不下任务镜像与工作区,见存储。 |
Kubernetes 后端:任务持续等待,日志显示 Waiting for pod ... to be scheduled |
没有节点能满足 job 容器的资源或 job Pod 模板的调度条件。 |
| Kubernetes 后端:工作流缓存超时 | job Pod 无法访问其 runner Pod 的 8088 端口,请检查 NetworkPolicy。 |
未能上线的 runner Pod
Section titled “未能上线的 runner Pod”runner Pod 启动至少 15 分钟(计入拉取镜像与 init container 的时间)、且其 runner 已有 5 分钟未在 Gitea 上线时,controller 会删除该 Pod 及其配置文件和缓存卷,报告 DestroyWorker 警告事件,然后重新创建它。注册信息会保留,除非 Gitea 中已不再列出该 runner,此时会重新注册。尚未启动的 Pod,例如处于 Pending 的,不受影响。
上线后又离线的 runner 也适用此规则。在此之前,controller 会在 3 分钟后报告 RunnerNotOnline,此时应查看 runner 容器的日志。
kubectl get runner只显示名称与创建时间。status.targetSize记录 controller 期望的 runner Pod 数量,每次变化都会产生ScaleUp或ScaleDown事件。Runner的一般事件包括RegisterRunner、RollWorker、RollDeferred、DrainWorker、CachePVCExpired、CachePVCExpand、RollCacheServer,以及 controller 创建或删除每个对象时的Create...与Delete...。- controller 的 Deployment 内存上限为 128Mi。其内存用量随集群中 Pod、Secret、ConfigMap 与存储卷的数量增长,因此在大型集群中,若 controller 因内存不足被终止,请提高该上限。
升级前,请确认您的 Runner 满足本文档各页的要求,尤其是后端中列出的 runner 镜像最低版本:镜像低于该版本的 runner Pod 在升级后可能无法正常工作。
应用新版本的清单,按安装 controller 中的方法下载并校验:
kubectl apply -f runner-controller-v<version>-install.yaml- 该清单会同时更新自定义资源定义与 controller。
- 您对清单做过的修改,如替换为镜像仓库中的 controller 镜像或提高内存上限,须在新版本的清单中重新应用。
- 新版本生成的 runner Pod 有变化时,会按配置变更的方式重建它们,不会中断任务。
升级 runner 镜像只需修改各 Runner 中的 image。
请先删除 Runner 资源。其 runner Pod、job Pod、存储卷、Secret 等对象会一并删除:
kubectl -n <namespace> delete runner <name>kubectl -n <namespace> get pvc # 等待存储卷全部删除然后用已安装版本的清单删除 controller:
kubectl delete -f runner-controller-v<version>-install.yaml先删除 Runner 资源,可以确认它们创建的对象都已删除。请在 Runner 没有执行任务时删除它:Docker-in-Docker 后端的 runner Pod 有 shutdownTimeout 的时间完成任务,但 Kubernetes 后端的 runner 会随 Runner 一起失去权限,其任务会失败。
删除存储卷后其存储是否释放,取决于 StorageClass 的回收策略。回收策略为 Retain 时,PersistentVolume 会以 Released 状态保留,须手动删除。从一开始就设置 storage.reclaimPolicy: Delete 可以避免这种情况。
runner 会以离线状态保留在 Gitea 的 runner 列表中,可以在那里删除。
将以下镜像同步到内部镜像仓库:
-
controller,
commitgo/runner-controller:v<version>:应用安装清单前,修改其中 Deployment 的image。 -
runner,例如
gitea/runner:6.0.0-dind,它同时用于运行内置缓存服务器。在image中设置,凭证写在imagePullSecrets中。注意imagePullSecrets位于spec顶层,而不是runtime下:imagePullSecrets:- name: <registry credentials>runtime:image: <internal registry>/runner:6.0.0-dind -
任务镜像,即 label 指向的镜像:
runtime:labels:ubuntu-latest: docker://<internal registry>/runner-images:ubuntu-latest使用 Docker-in-Docker 后端时,runner Pod 中的 Docker daemon 用私有任务镜像中所述的凭证拉取它们。使用 Kubernetes 后端时,job Pod 用 job Pod 模板中的
imagePullSecrets拉取它们。
Actions
Section titled “Actions”actions/checkout@v4 等 action 默认从 https://github.com 下载,无法访问互联网时会失败。请将工作流使用的 action 同步到 Gitea 实例,并按 Gitea 文档使用 actions/checkout@v4 等 Actions 时,Job 容器会从何处下载脚本中的方法让它们从实例解析。这是 Gitea 与工作流的设置,而不是 Runner 的设置。