Kubernetes 后端
使用 Kubernetes 后端时,runner Pod 中不运行 Docker daemon,而是由 runner 通过 Kubernetes API,在 Runner 所在的命名空间中为每个任务创建一个 Pod(job Pod),任务结束后将其删除。runner Pod 与 job Pod 都不需要特权模式,每个 runner Pod 可以同时执行多个任务。
设置了 spec.kubernetesRuntime 的 Runner 使用该后端。spec.runtime 与 spec.kubernetesRuntime 须设置且只能设置其一。
- 集群不允许特权 Pod。
- 希望每个任务隔离在单独的 Pod 中,例如使用 Kata Containers 等沙箱运行时。
需要 Docker 的工作流,应由 Docker-in-Docker 后端的 Runner 执行,两者可以并用。
使用以下任一功能的任务会失败:
| 工作流功能 | 报错 |
|---|---|
Docker 类 action(action.yml 中 runs.using: docker),包括 composite action 中的 |
docker actions and docker:// steps are not supported on Kubernetes |
uses: docker://... 形式的步骤 |
同上 |
任务 container 的 options、volumes 或 credentials |
container options, volumes and credentials are not supported on Kubernetes |
服务的 volumes 或 credentials |
service <id>: volumes and credentials are not supported on Kubernetes |
服务的 options 中除 --health-cmd、--health-interval、--health-timeout、--health-retries 与 --health-start-period 以外的选项 |
only --health-* options are supported on Kubernetes |
两个服务的 id 映射到同一个容器名,例如 my_db 与 my-db,或服务名为 job |
service <id> maps to container "<name>", which is empty or named like another container of the pod |
此外任务中没有 Docker daemon 可以使用,docker build、docker run、docker compose 以及 Testcontainers 等会启动容器的工具都无法使用。
以下功能的行为与 Docker 不同:
- 私有镜像的拉取凭证写在 job Pod 模板的
imagePullSecrets中,卷写在其volumes中,而不是工作流的credentials与volumes。 - 服务作为 job Pod 中的容器运行,共享其网络。步骤通过服务的 id 或
localhost访问服务。两个服务不能监听同一端口,ports映射中的宿主机端口不生效:服务通过其容器端口访问。不是合法主机名的 id 会被改写,例如my_db要通过my-db访问。 - 服务的
command会出现在 Pod spec 中,因此请通过env向服务传递密钥。 - label 只能对应镜像,因此任务不能以 host 方式运行,即不能直接在 runner 容器内运行。
- 任务镜像由节点拉取和缓存。在按需增加节点的集群中,任务被调度到新节点上时会重新拉取镜像。
- 没有 tool cache 卷:
setup-*类 action 安装的工具随 job Pod 一起丢弃。 - 无法调度的 job Pod 会持续等待直至任务超时,并在任务日志中记录
Waiting for pod <pod> to be scheduled。
runner 如何以 Pod 运行任务,见其文档 Install on Kubernetes: Job pods。
- runner 镜像 5.3.0 及以上,不带
-dind后缀;建议 6.0.0 及以上。 默认镜像为gitea/runner:nightly,生产环境请固定版本号。 - Kubernetes 1.30 及以上。
- 任务镜像须包含
sh、tar、tail与env,运行actions/checkout等 JavaScript 类 action 还须包含node。docker.gitea.com/runner-images系列镜像均满足。
Pod Security 级别
Section titled “Pod Security 级别”- runner Pod 与内置缓存服务器满足 Pod Security 的
restricted级别,runner Pod 的 init container 也须满足。 - job Pod 在默认设置下满足
baseline,但不满足restricted,因为任务镜像中的进程通常以 root 运行。
因此命名空间设为 baseline 即可:
kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=baseline若命名空间须为 restricted,须在 job Pod 模板中设置 job Pod 的安全上下文,且任务镜像须能以非 root 用户运行。以下设置满足 restricted,但任务能否以该用户正常运行,取决于镜像和工作流。kubernetesRuntime.runnerRunAsUser 设置的是 runner Pod 与内置缓存服务器的用户,而不是 job Pod 的。
kubernetesRuntime: jobPodTemplate: spec: securityContext: runAsNonRoot: true runAsUser: 1001 seccompProfile: type: RuntimeDefault containers: - name: job securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"] - name: $services securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"]- 每个 runner Pod 只有一个持久卷,即 action 缓存。没有 Docker 数据目录的存储卷,因此
storage.cacheVolumeSize、dockerStorageClassName与dockerStorageMountPath不生效。 - StorageClass 须支持
fsGroup。 runner Pod 与内置缓存服务器以非 root 用户运行(默认 UID 1000),依靠fsGroup获得存储卷的写权限。部分供应器(常见于 NFS 类)会忽略fsGroup,此时 runner 下载 action 会失败。检查集群会测试这一点。 - job Pod 使用所在节点的磁盘。 节点拉取并缓存任务镜像,任务工作区默认是节点上的
emptyDir。请为可同时运行的任务在节点上留出足够的磁盘空间(任务镜像常有数 GB),否则 job Pod 会被驱逐,任务失败。也可以通过 job Pod 模板把工作区放到存储卷上。
- 任务使用其 job Pod 的资源。
scalability.cpuRequest与memoryRequest(以及设置了的cpuLimit与memoryLimit)作用于每个 job Pod 的job容器,默认 2 CPU 与 4Gi。请按可同时运行的任务数规划集群,最多为maxSize × capacity。服务容器默认不设置资源,除非 job Pod 模板为$services设置。 - runner Pod 使用
kubernetesRuntime.runnerResources,默认请求 100m CPU 与 256Mi,不设上限。runner 主要负责管理 job Pod,自身所需资源不多;但每个任务的日志、action 源码与缓存流量都经过 runner,因此capacity较大、日志量大或缓存读写频繁时请相应提高。若命名空间的 LimitRange 会添加默认上限,请确认其足够大,否则 runner 可能因内存不足被终止。 - 将 runner Pod 固定在稳定的节点上,例如通过
nodeSelector或affinity将其调度到不常被回收的节点池。runner Pod 因节点故障或驱逐被意外终止时,它正在执行的任务(最多capacity个)会失败,其 job Pod 被删除。缩容或应用配置变更时正常删除的 runner Pod,会先完成当前的任务,见排空与关闭。 Runner的nodeSelector、affinity、tolerations与imagePullSecrets不作用于 job Pod,job Pod 的这些设置写在 job Pod 模板中。
须放行:
- job Pod 访问 Gitea 自身配置的地址(其
ROOT_URL,用于检出代码和上传产物)、其镜像仓库、工作流使用的包仓库或其他服务,以及所属 runner Pod 的 8088 端口(为其提供工作流缓存服务); - runner Pod 访问 Gitea、任务所用 action 的来源(默认为
https://github.com,见 Actions)、Kubernetes API Server,以及缓存服务器或 S3 存储桶。
job Pod 带有 Kubernetes 标签 app.kubernetes.io/managed-by: gitea-runner,NetworkPolicy 可以据此选择它们。runner Pod 与缓存服务器的标签见 controller 创建的资源。
任务镜像由节点的容器运行时拉取,使用的是节点的代理设置,而不是 Runner 的 runnerEnv。
使用该后端时,内置缓存服务器以非 root 用户运行,默认监听 8080 端口。使用内置缓存服务器时,显式设置的 cacheServer.port 须不低于 1024,否则 Runner 会被拒绝。
controller 不会创建 NetworkPolicy。
runner 以 ClusterRole runner-controller-worker-role 的权限创建 job Pod,该 ClusterRole 包含在安装清单中:
| 资源 | 操作 |
|---|---|
pods |
create、get、list、delete |
pods/exec |
create、get |
pods/log |
get |
secrets |
create、delete |
对每个使用该后端的 Runner,controller 在其命名空间中创建 ServiceAccount <name>-worker,以及一个仅在该命名空间内授予此 ClusterRole 的 RoleBinding。
- 若要使用自己的 ServiceAccount,设置
kubernetesRuntime.runnerServiceAccountName。此时 controller 既不创建 ServiceAccount 也不创建 RoleBinding,须由您授予上述权限。 - 对于不是由它创建的同名 ServiceAccount 或 RoleBinding,controller 不会接管,而是不创建 runner Pod,并报告
ApplyRunnerWorkerFailed警告事件。请删除该对象,或改用runnerServiceAccountName。 - job Pod 不挂载 ServiceAccount 令牌。若 job Pod 模板开启了
automountServiceAccountToken,任务获得的是该命名空间defaultServiceAccount 的令牌,而不是 runner 的。 - 能在某个命名空间中创建
Runner的用户,可以借助其 runner Pod 在该命名空间中创建 Pod 并在其中执行命令。授予该权限时,应视同授予该命名空间的管理权限。
以下清单检查 StorageClass 能否供应存储卷、非 root 的 Pod 能否通过 fsGroup 写入存储卷,以及命名空间在 restricted 级别下能否接受 runner Pod 的安全设置。请将其中的 <storage class> 替换为 Runner 将使用的 StorageClass:className 默认为 standard,而不是集群的默认 StorageClass。Runner 的各存储卷使用不同的 StorageClass 时,对每个都检查一次。
kubectl create namespace rc-preflightkubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=restricted
cat <<'EOF' | kubectl -n rc-preflight apply -f -apiVersion: v1kind: PersistentVolumeClaimmetadata: name: preflightspec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 1Gi storageClassName: <storage class> # 要检查的 StorageClass---apiVersion: v1kind: Podmetadata: name: preflightspec: securityContext: runAsNonRoot: true runAsUser: 1000 runAsGroup: 1000 fsGroup: 1000 seccompProfile: type: RuntimeDefault containers: - name: test image: busybox command: ["sh", "-c", "touch /data/ok && sleep 3600"] securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"] volumeMounts: - name: data mountPath: /data volumes: - name: data persistentVolumeClaim: claimName: preflightEOF
kubectl -n rc-preflight wait --for=condition=Ready pod/preflight --timeout=3mkubectl -n rc-preflight exec preflight -- ls /data/ok两条命令都成功即表示通过。若 Pod 反复重启,且 kubectl -n rc-preflight logs preflight 显示 Permission denied,说明该 StorageClass 不支持 fsGroup;其他情况用 kubectl -n rc-preflight describe pod preflight 查看原因。用 kubectl delete namespace rc-preflight 清理。
创建 Runner
Section titled “创建 Runner”kubectl create namespace gitea-k8s-runnerskubectl label namespace gitea-k8s-runners pod-security.kubernetes.io/enforce=baselinekubectl -n gitea-k8s-runners create secret generic runner-registration-token \ --from-literal=token=<registration token>将以下内容保存为 runner.yaml,替换其中的 Gitea 地址与 StorageClass:
apiVersion: gitea.com/v1kind: Runnermetadata: name: k8s-runner namespace: gitea-k8s-runnersspec: gitea: instanceUrl: "https://<gitea host>" registrationTokenSecretRef: name: runner-registration-token key: token
kubernetesRuntime: image: gitea/runner:6.0.0 # 不带 -dind capacity: 4 # 每个 runner Pod 同时执行的任务数 labels: # runs-on 名称: 任务镜像,不带 docker:// ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest
scalability: minSize: 1 # runner Pod 数 maxSize: 5 # runner Pod 数:最多同时执行 5 × 4 个任务 cpuRequest: "2" # 每个任务的 job 容器 memoryRequest: 4Gi
storage: # 试用规模 className: "<storage class>" actionCacheVolumeSize: 10Gi cacheServerVolumeSize: 20Gi以上存储卷容量适合试用。生产环境请按容量规划设定,并推荐将缓存存放在 S3 兼容存储中。
kubectl apply -f runner.yamlkubectl -n gitea-k8s-runners get runner,pod,serviceaccount,rolebinding会出现 runner Pod k8s-runner-0001、缓存服务器 Pod k8s-runner-cache-server、ServiceAccount k8s-runner-worker 以及同名的 RoleBinding,名为 k8s-runner-0001 的 runner 会在 Gitea 中上线。kubectl -n gitea-k8s-runners describe runner k8s-runner 在成功时显示 RegisterRunner 与 Create... 事件,否则显示警告事件。
在令牌覆盖范围内的仓库中添加一个 runs-on: ubuntu-latest 的工作流,例如 Docker-in-Docker 后端创建 Runner 中的那个。任务运行期间,命名空间中会出现名为 gitea-actions-task-<id>-... 的 job Pod。
其他选项见配置与存储与缓存,字段参考列出了所有字段。本页其余部分只介绍该后端特有的选项。
label 与 job Pod 模板
Section titled “label 与 job Pod 模板”kubernetesRuntime: labels: ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest sandboxed: docker.gitea.com/runner-images:ubuntu-latest jobPodTemplate: # 作用于所有任务 spec: nodeSelector: node-pool: ci-jobs containers: - name: job resources: limits: memory: 8Gi jobPodTemplates: # 以 label 为键,作用于 runs-on 含该 label 的任务 sandboxed: spec: runtimeClassName: katalabels的键是任务在runs-on中使用的名称,值是任务镜像,不带docker://等前缀。名称不能包含:、,或空白字符。jobPodTemplate是所有 job Pod 的基础,只能包含metadata与spec。runner 在其上叠加自己生成的内容:-
名为
job的容器合并到执行步骤的容器中,名为$services的容器合并到每个服务容器中。其他名称的容器作为附加容器加入 job Pod。 -
名为
workspace的卷会替换存放任务工作区的emptyDir,例如为任务提供更大的存储卷空间:jobPodTemplate:spec:volumes:- name: workspaceephemeral:volumeClaimTemplate:spec:accessModes: ["ReadWriteOnce"]storageClassName: <storage class>resources:requests:storage: 50Gi -
私有任务镜像的拉取凭证写在其
spec.imagePullSecrets中。
-
jobPodTemplates叠加在jobPodTemplate之上,每项作用于runs-on含其键的任务;多项匹配时按runs-on中的顺序叠加。每个键都须是labels中的名称,否则Runner会被拒绝,因此删除 label 时须一并删除其模板。上例中runs-on: sandboxed的任务运行在 Kata Containers 中,这需要集群中有名为kata的 RuntimeClass。- 模板中的字面量
${NAME}(例如命令中的)须写作$${NAME}:sh -c 'echo $${HOME}'。未转义的${NAME}会被拒绝,见下文。 - 除非模板已设置,controller 会添加注解
karpenter.sh/do-not-disrupt: "true"(避免 Karpenter 在任务运行期间回收节点),以及取自scalability的job容器资源。
模板无效时。 controller 会检查 jobPodTemplate 以及 jobPodTemplates 中的每一项是否满足以下条件:
- 顶层只有
metadata与spec。 spec.containers是一个容器列表,且每个容器都有name。- 没有未转义的
${NAME}。 - 计入取自
scalability的资源后,job容器的请求不超过其上限。
模板未通过检查期间,controller 会报告 InvalidJobPodTemplate 警告事件,消息中会指明出错的模板,例如 kubernetesRuntime.jobPodTemplates["sandboxed"],并暂停处理该 Runner,直到模板修正:不伸缩、不应用变更、不重建消失的 runner Pod,也不删除过期的存储卷。已在运行的 runner Pod 不受影响,继续按原有配置执行任务。常见错误:
| 写法 | 问题 |
|---|---|
jobPodTemplate: {runtimeClassName: kata} |
缺少 spec: |
jobPodTemplate: {template: {spec: ...}} |
多出一层 template: |
containers: {job: {...}} |
containers 须为列表 |
containers: [{resources: ...}] |
容器缺少 name |
command: ["sh", "-c", "echo ${FOO}"] |
应写作 $${FOO} |
jobPodTemplates 中的某项只为 job 设置了 limits: {memory: 2Gi} |
请求仍取自 jobPodTemplate 或 scalability(默认 4Gi),超过了上限:须同时设置 requests |
scalability 只设置了 memoryLimit: 2Gi |
模板中未设置内存时,请求为 memoryRequest(默认 4Gi),超过了上限:须同时调低 memoryRequest |
spec 内部的字段不做检查。字段类型错误、数量格式错误或 RuntimeClass 不存在等问题,会在 runner 创建 job Pod 时被 API Server 拒绝,任务以 create pod: ... 失败。
kubernetesRuntime: capacity: 4 # 每个 runner Pod 的任务数,默认 4scalability: minSize: 1 # runner Pod 数 maxSize: 5 # runner Pod 数minSize与maxSize按 runner Pod 计数,因此最多同时运行maxSize × capacity个任务。- 排队的任务先占用正在运行的 runner Pod 的空闲位置,其余的由 controller 新增 runner Pod 承接。例如
capacity: 4,两个 runner Pod 共运行 3 个任务,有 9 个任务排队:其中 5 个可放在现有 Pod 上,controller 为剩下的 4 个新增一个 runner Pod。 - 缩容时一次回收一个 runner Pod,从编号最大的开始,且只回收没有在执行任务的,见伸缩。
需要对正在执行任务的 runner Pod 应用变更时,该 Pod 会被排空:不再接取新任务,完成当前的任务后再重建。同一 Runner 同一时间只排空一个 runner Pod。见配置变更如何生效。
kubernetesRuntime: shutdownTimeout: 3h # 默认 3h # terminationGracePeriodSeconds: 11100 # 默认为 shutdownTimeout + 5mshutdownTimeout 默认为 3 小时,与 runner 的任务超时时间一致,因此排空不会取消任务。相应地,节点维护(如 kubectl drain)可能需要等待 runner Pod 最长 3 小时 5 分钟。需要更快完成维护时可以适当减小:超时时仍在运行的任务会被取消。
使用自定义 runner 配置文件
Section titled “使用自定义 runner 配置文件”kubernetesRuntime.runnerConfigMapName 的用法见使用自定义 runner 配置文件,此外:
runner.labels须为<name>:kubernetes://<image>的形式,名称与kubernetesRuntime.labels相同。runner.capacity须与kubernetesRuntime.capacity相同,controller 按后者规划伸缩。- 设置
host.workdir_parent: /cache/act_workdir,启用缓存时还须将cache.dir设在/cache下。否则两者默认位于 runner 的主目录,其用户没有写权限,任务下载 action 会失败。 - 不要设置
kubernetes.namespace或kubernetes.kubeconfig:job Pod 须创建在Runner所在的命名空间中。不设置时,runner 使用自己的 ServiceAccount 与命名空间。 jobPodTemplate与jobPodTemplates不生效,controller 也不会为 job Pod 添加scalability中的资源和karpenter.sh/do-not-disrupt注解。请改在配置文件的kubernetes.pod_template中设置。- 若要通过 NetworkPolicy 放行缓存流量,请设置固定的
cache.port。controller 生成的配置文件使用 8088。
ServiceAccount、RoleBinding 以及 runner Pod 的安全上下文仍由 controller 管理。
两种后端并用
Section titled “两种后端并用”需要 Docker 的工作流可以由另一个使用 Docker-in-Docker 后端的 Runner 执行。由于它需要特权 Pod,请将它放在单独的、允许特权 Pod 的命名空间中,使 Kubernetes 后端所在的命名空间保持更严格的级别。注册令牌的 Secret 也须放在该命名空间中:
kubectl create namespace gitea-docker-runnerskubectl label namespace gitea-docker-runners pod-security.kubernetes.io/enforce=privilegedkubectl -n gitea-docker-runners create secret generic runner-registration-token \ --from-literal=token=<registration token>apiVersion: gitea.com/v1kind: Runnermetadata: name: docker-runner namespace: gitea-docker-runnersspec: gitea: instanceUrl: "https://<gitea host>" registrationTokenSecretRef: name: runner-registration-token key: token runtime: image: gitea/runner:6.0.0-dind labels: ubuntu-latest-docker: docker://docker.gitea.com/runner-images:ubuntu-latest storage: className: "<storage class>"需要 Docker 的工作流使用 runs-on: ubuntu-latest-docker。两个 Runner 须使用不同的 label:label 相同时,一个排队的任务会让两者同时扩容。
从 Docker-in-Docker 迁移
Section titled “从 Docker-in-Docker 迁移”要把工作流从 Docker-in-Docker 后端迁移到该后端,请在单独的命名空间中新建一个使用该后端的 Runner,与现有的并行运行。确认工作流在新 Runner 上运行正常后,再删除原有的。
两种后端的选项并不相同:label 的值不再带 docker:// 前缀,scalability 中的资源作用于 job 容器,pvcMounts、jobTmpfs 等选项没有对应项。请参照字段参考编写新的 Runner,而不是复制原有的。