跳转到内容
免费试用 Gitea Cloud ☁️ 30 天,加速你的开发与部署!
技术支持

运维

controller 以 Runner 上的事件报告问题,因此请从以下命令开始:

Terminal window
kubectl -n <namespace> describe runner <name>
kubectl -n <namespace> get runner,pod,pvc
kubectl -n <namespace> describe pod <pod>
kubectl -n runner-controller-system logs deploy/runner-controller-controller-manager

runner 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 启动至少 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 中的方法下载并校验:

Terminal window
kubectl apply -f runner-controller-v<version>-install.yaml
  • 该清单会同时更新自定义资源定义与 controller。
  • 您对清单做过的修改,如替换为镜像仓库中的 controller 镜像或提高内存上限,须在新版本的清单中重新应用。
  • 新版本生成的 runner Pod 有变化时,会按配置变更的方式重建它们,不会中断任务。

升级 runner 镜像只需修改各 Runner 中的 image。

请先删除 Runner 资源。其 runner Pod、job Pod、存储卷、Secret 等对象会一并删除:

Terminal window
kubectl -n <namespace> delete runner <name>
kubectl -n <namespace> get pvc # 等待存储卷全部删除

然后用已安装版本的清单删除 controller:

Terminal window
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 列表中,可以在那里删除。

将以下镜像同步到内部镜像仓库:

  1. controller,commitgo/runner-controller:v<version>:应用安装清单前,修改其中 Deployment 的 image。

  2. 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
  3. 任务镜像,即 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/checkout@v4 等 action 默认从 https://github.com 下载,无法访问互联网时会失败。请将工作流使用的 action 同步到 Gitea 实例,并按 Gitea 文档使用 actions/checkout@v4 等 Actions 时,Job 容器会从何处下载脚本中的方法让它们从实例解析。这是 Gitea 与工作流的设置,而不是 Runner 的设置。