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

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 系列镜像均满足。

以下要求是在通用要求与存储要求之外的补充。

  • runner Pod 与内置缓存服务器满足 Pod Security 的 restricted 级别,runner Pod 的 init container 也须满足。
  • job Pod 在默认设置下满足 baseline,但不满足 restricted,因为任务镜像中的进程通常以 root 运行。

因此命名空间设为 baseline 即可:

Terminal window
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,任务获得的是该命名空间 default ServiceAccount 的令牌,而不是 runner 的。
  • 能在某个命名空间中创建 Runner 的用户,可以借助其 runner Pod 在该命名空间中创建 Pod 并在其中执行命令。授予该权限时,应视同授予该命名空间的管理权限。

以下清单检查 StorageClass 能否供应存储卷、非 root 的 Pod 能否通过 fsGroup 写入存储卷,以及命名空间在 restricted 级别下能否接受 runner Pod 的安全设置。请将其中的 <storage class> 替换为 Runner 将使用的 StorageClass:className 默认为 standard,而不是集群的默认 StorageClass。Runner 的各存储卷使用不同的 StorageClass 时,对每个都检查一次。

Terminal window
kubectl create namespace rc-preflight
kubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=restricted
cat <<'EOF' | kubectl -n rc-preflight apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: preflight
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 1Gi
storageClassName: <storage class> # 要检查的 StorageClass
---
apiVersion: v1
kind: Pod
metadata:
name: preflight
spec:
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: preflight
EOF
kubectl -n rc-preflight wait --for=condition=Ready pod/preflight --timeout=3m
kubectl -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 清理。

Terminal window
kubectl create namespace gitea-k8s-runners
kubectl label namespace gitea-k8s-runners pod-security.kubernetes.io/enforce=baseline
kubectl -n gitea-k8s-runners create secret generic runner-registration-token \
--from-literal=token=<registration token>

将以下内容保存为 runner.yaml,替换其中的 Gitea 地址与 StorageClass:

apiVersion: gitea.com/v1
kind: Runner
metadata:
name: k8s-runner
namespace: gitea-k8s-runners
spec:
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 兼容存储中。

Terminal window
kubectl apply -f runner.yaml
kubectl -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。

其他选项见配置与存储与缓存,字段参考列出了所有字段。本页其余部分只介绍该后端特有的选项。

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: kata
  • labels 的键是任务在 runs-on 中使用的名称,值是任务镜像,不带 docker:// 等前缀。名称不能包含 :、, 或空白字符。
  • jobPodTemplate 是所有 job Pod 的基础,只能包含 metadata 与 spec。runner 在其上叠加自己生成的内容:
    • 名为 job 的容器合并到执行步骤的容器中,名为 $services 的容器合并到每个服务容器中。其他名称的容器作为附加容器加入 job Pod。

    • 名为 workspace 的卷会替换存放任务工作区的 emptyDir,例如为任务提供更大的存储卷空间:

      jobPodTemplate:
      spec:
      volumes:
      - name: workspace
      ephemeral:
      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 的任务数,默认 4
scalability:
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 + 5m

shutdownTimeout 默认为 3 小时,与 runner 的任务超时时间一致,因此排空不会取消任务。相应地,节点维护(如 kubectl drain)可能需要等待 runner Pod 最长 3 小时 5 分钟。需要更快完成维护时可以适当减小:超时时仍在运行的任务会被取消。

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 管理。

需要 Docker 的工作流可以由另一个使用 Docker-in-Docker 后端的 Runner 执行。由于它需要特权 Pod,请将它放在单独的、允许特权 Pod 的命名空间中,使 Kubernetes 后端所在的命名空间保持更严格的级别。注册令牌的 Secret 也须放在该命名空间中:

Terminal window
kubectl create namespace gitea-docker-runners
kubectl label namespace gitea-docker-runners pod-security.kubernetes.io/enforce=privileged
kubectl -n gitea-docker-runners create secret generic runner-registration-token \
--from-literal=token=<registration token>
apiVersion: gitea.com/v1
kind: Runner
metadata:
name: docker-runner
namespace: gitea-docker-runners
spec:
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 后端迁移到该后端,请在单独的命名空间中新建一个使用该后端的 Runner,与现有的并行运行。确认工作流在新 Runner 上运行正常后,再删除原有的。

两种后端的选项并不相同:label 的值不再带 docker:// 前缀,scalability 中的资源作用于 job 容器,pvcMounts、jobTmpfs 等选项没有对应项。请参照字段参考编写新的 Runner,而不是复制原有的。