Docker-in-Docker 后端
使用 Docker-in-Docker 后端时,每个 runner Pod 运行 runner 镜像的 -dind 版本,其中同时包含 runner 和一个 Docker daemon。任务以该 daemon 中的容器运行,与在服务器上安装 runner 的方式相同,因此工作流可以自由使用 Docker:docker build、Docker 类 action、带卷的服务容器。每个 runner Pod 同一时间只执行一个任务。
设置了 spec.runtime 的 Runner 使用该后端。spec.runtime 与 spec.kubernetesRuntime 须设置且只能设置其一。
特权 Pod
Section titled “特权 Pod”Docker daemon 需要以特权模式运行,该要求无法通过配置取消。rootless 镜像同样不能免除该要求。
-
runner Pod 所在的命名空间须允许特权 Pod。使用 Pod Security Admission 时,将其级别设为
privileged:Terminal window kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=privileged -
在 OpenShift 上,为该命名空间的 default ServiceAccount 授予
privilegedSecurityContextConstraints。 -
部分加固型的 Kubernetes 产品完全禁止特权容器,这类环境请使用 Kubernetes 后端。
在不允许特权 Pod 的命名空间中,controller 会报告提到 violates PodSecurity 的 ApplyRunnerWorkerFailed 警告事件,Gitea 中的这些 runner 会显示为离线,直到其 Pod 能够启动。
每个 runner Pod 有两个持久卷:保存拉取的镜像与镜像层的 Docker 数据目录,以及 action 缓存。见 runner Pod 的存储卷。
Docker 数据目录所在的存储卷须使用块存储。Docker 无法在 NFS 上工作,数据目录位于 NFS 上时任务会失败。块存储容量有限时,可以只把该存储卷放在块存储上:
storage: className: "<block storage class>" # 以下存储卷未单独指定时使用 dockerStorageClassName: "<block storage class>" # Docker 数据目录:须为块存储 actionCacheClassName: "<any storage class>" # action 缓存:可用网络存储- 每个 runner Pod 默认请求 2 CPU 与 4Gi 内存(
scalability.cpuRequest与memoryRequest),集群须有能容纳它的节点。 - 默认不设置上限,runner Pod 可以使用超过请求值的资源。在任务中编译代码或构建镜像会出现内存尖峰:请为节点留出余量,或设置
memoryLimit。 - 使用将任务数据放在内存中时,须相应提高内存的请求与上限。
- 每个 runner Pod 挂载两个存储卷。多数平台限制单个节点可挂载的块设备数量,这会限制每个节点上的 runner Pod 数量。
- 节点自动伸缩并非必需。在节点数量固定的集群中,将
maxSize设为节点能容纳的数量,超出的 runner Pod 会保持Pending。
- runner Pod 需要访问 Gitea、任务所用 action 的来源(默认为
https://github.com,见 Actions),以及缓存服务器或 S3 存储桶。 - 任务镜像由 runner Pod 中的 Docker daemon 拉取,因此 runner Pod 须能访问这些镜像仓库,节点须能访问 runner 镜像所在的仓库。
- 任务容器的连接经由其 runner Pod 发出,因此 runner Pod 的出站规则也须涵盖任务访问的地址:Gitea 自身配置的地址(其
ROOT_URL),以及工作流使用的包仓库或其他服务。 - 使用默认拒绝的 NetworkPolicy 时,须放行上述出站流量。controller 不会创建 NetworkPolicy。用于选择这些 Pod 的标签见 controller 创建的资源。
以下清单检查 StorageClass 能否供应存储卷,以及命名空间是否允许特权 Pod。请将其中的 <storage class> 替换为 Runner 将使用的 StorageClass:className 默认为 standard,而不是集群的默认 StorageClass。Runner 的各存储卷使用不同的 StorageClass 时,对每个都检查一次。
kubectl create namespace rc-preflightkubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=privileged
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: containers: - name: test image: busybox command: ["sh", "-c", "touch /data/ok && sleep 3600"] securityContext: privileged: true volumeMounts: - name: data mountPath: /data volumes: - name: data persistentVolumeClaim: claimName: preflightEOF
kubectl -n rc-preflight wait --for=condition=Ready pod/preflight --timeout=3m输出 condition met 即表示通过:Pod 已运行,说明存储卷已供应并挂载,命名空间也允许特权 Pod。超时则用 kubectl -n rc-preflight describe pod preflight 查看原因。用 kubectl delete namespace rc-preflight 清理。
创建 Runner
Section titled “创建 Runner”创建命名空间,以及保存注册令牌的 Secret:
kubectl create namespace gitea-runnerskubectl label namespace gitea-runners pod-security.kubernetes.io/enforce=privilegedkubectl -n gitea-runners create secret generic runner-registration-token \ --from-literal=token=<registration token>将以下内容保存为 runner.yaml,替换其中的 Gitea 地址与 StorageClass:
apiVersion: gitea.com/v1kind: Runnermetadata: name: my-runner namespace: gitea-runnersspec: gitea: instanceUrl: "https://<gitea host>" registrationTokenSecretRef: name: runner-registration-token key: token
runtime: image: gitea/runner:6.0.0-dind # -dind 版本 labels: # runs-on 名称: 任务镜像 ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest ubuntu-24.04: docker://docker.gitea.com/runner-images:ubuntu-24.04
scalability: minSize: 1 # 没有任务排队时保留的 runner Pod 数 maxSize: 10 cpuRequest: "2" memoryRequest: 4Gi
storage: # 试用规模 className: "<storage class>" cacheVolumeSize: 30Gi # Docker 数据目录,默认 100Gi actionCacheVolumeSize: 5Gi # action 缓存,默认 10Gi cacheServerVolumeSize: 20Gi # 内置缓存服务器,默认 500Gi以上存储卷容量适合试用。生产环境请按容量规划设定,并推荐将缓存存放在 S3 兼容存储中。
kubectl apply -f runner.yamlkubectl -n gitea-runners get runner,pod,pvc由于 minSize: 1,runner Pod my-runner-0001 会与 my-runner-cache-server Pod 一同启动,通常在几分钟内完成,同名的 runner 会在 Gitea 的 runner 列表中上线,位于令牌所在的页面。kubectl -n gitea-runners describe runner my-runner 显示进展:成功时有 RegisterRunner 与 Create... 事件,否则有警告事件,见排查。
要观察 runner 的伸缩,在令牌覆盖范围内、已启用 Actions 的仓库中,添加一个使用上述 label 的工作流 .gitea/workflows/runner-check.yaml:
name: Runner checkon: [push]jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: cat /etc/os-release其他选项见配置与存储与缓存,字段参考列出了所有字段。本页其余部分只介绍该后端特有的选项。
runner 镜像
Section titled “runner 镜像”runtime: image: gitea/runner:6.0.0-dind- 须使用
-dind版本。同一版本不带该后缀的镜像不包含 Docker daemon,任务会失败。 - 须使用 runner 5.3.0 及以上版本,建议使用 6.0.0 及以上版本。
- 生产环境请固定版本号。默认的
gitea/runner:nightly-dind每天都会变化。 - 若镜像与 controller 不兼容,controller 会报告
RunnerRegisteredItself或RunnerNotOnline事件,见排查。
私有任务镜像
Section titled “私有任务镜像”任务镜像由 runner Pod 中的 Docker daemon 拉取,它不使用 Runner 的 imagePullSecrets:后者只用于 Kubernetes 拉取 runner 镜像。请改为以 Docker 配置文件的形式向 runner 提供镜像仓库凭证,来源是类型为 kubernetes.io/dockerconfigjson 的 Secret:
runtime: secretMounts: - volumeName: docker-config secretName: <registry credentials> mountPath: /etc/docker-config readOnly: true items: - key: .dockerconfigjson path: config.json runnerEnv: - name: DOCKER_CONFIG value: /etc/docker-config工作流也可以在 container.credentials 中提供其任务镜像的凭证。
runner Pod 在执行任务时被删除,例如节点被回收或减小了 maxSize,runner 会等待任务完成:
runtime: shutdownTimeout: 10m # 默认 10m # terminationGracePeriodSeconds: 900 # 默认为 shutdownTimeout + 5mshutdownTimeout是 runner 等待正在执行的任务的时长,超时后任务被取消。任务可能超过 10 分钟时请相应增大。terminationGracePeriodSeconds是 Kubernetes 强制终止 Pod 前的等待时长。其值不应小于shutdownTimeout,否则 Pod 会在任务完成前被终止。出现这种设置时,controller 会报告GracePeriodTooSmall警告事件。
配置变更不会中断任务:正在执行任务的 runner Pod 会在任务结束后才重建,见配置变更如何生效。
将任务数据放在内存中
Section titled “将任务数据放在内存中”任务写入的数据,如检出的代码和构建产物,存放在 Docker 数据目录所在的存储卷上。受磁盘 I/O 制约的任务,例如处理大量小文件的任务,可以改为把这些数据放在内存(tmpfs)中:
runtime: jobTmpfs: workspaceSize: 8Gi # 任务工作区 tmpSize: 2Gi # 可选:任务容器中的 /tmpscalability: memoryRequest: 14Gi # 须包含 tmpfs,见下文 memoryLimit: 16Gi| 字段 | 必填 | 说明 |
|---|---|---|
workspaceSize |
是 | 任务工作区的容量上限。工作区在任务结束时删除,所占内存随之释放。拉取的镜像仍在 Docker 数据目录的存储卷上。 |
tmpSize |
否 | 任务容器中 /tmp 的大小。Docker 类 action(runs.using: docker)各自拥有同样大小的 /tmp。使用 runnerConfigMapName 时不生效。 |
- 每个 runner Pod 同一时间只执行一个任务,因此按单个任务的峰值用量设定。写入超出容量时,任务以
no space left on device失败。 - 可与 rootless 镜像一起使用。以 host 方式运行的任务不使用它。
tmpfs 计入 runner Pod 的内存用量,而 controller 不会因此提高 memoryRequest 与 memoryLimit:
memoryRequest ≥ 任务所需内存 + workspaceSize + tmpSizememoryLimit ≥ 任务所需内存 + workspaceSize + tmpSize × 2tmpSize 在上限中计两次,因为 Docker 类 action 另有同样大小的 /tmp。按上面的设置,若任务需要 4Gi,请求至少为 14Gi,上限至少为 16Gi。请求过低会使节点内存超额分配;上限过低时,tmpfs 写满后任务会因内存耗尽被终止,而不是以 no space left on device 失败。内存设置明显容纳不下 tmpfs 时,controller 会报告 JobTmpfsMemoryTooSmall 警告事件。
以非 root 用户运行任务
Section titled “以非 root 用户运行任务”-dind-rootless 版本以非 root 用户运行 Docker 及任务。它需要同时设置以下两项:
runtime: image: gitea/runner:6.0.0-dind-rootless runAsUser: 1000storage: dockerStorageMountPath: /home/rootless/.local/share/docker- 缺少
runAsUser:controller 不会将 Docker 数据目录存储卷的属主设为该用户,Docker 无法启动。 - 缺少
dockerStorageMountPath:存储卷挂载到 rootless daemon 不使用的位置。初期不会报错,但每次 Pod 重建都会丢失已拉取的镜像,而且镜像会在节点磁盘上累积,直至耗尽磁盘空间。
runner Pod 仍然是特权的:Docker 需要内核权限来创建网络命名空间、挂载文件系统,这与它以哪个用户运行无关。rootless 镜像的作用在于任务代码不以 root 运行,在 CI 中运行不受信任的代码时(虽然这是极不建议的行为),这仍是有价值的纵深防御。
挂载已有存储卷
Section titled “挂载已有存储卷”pvcMounts 将已有的 PersistentVolumeClaim 挂载到 runner Pod 中,供任务读写共享数据:
runtime: pvcMounts: - volumeName: shared-data claimName: my-existing-pvc # 位于 Runner 所在的命名空间,不由 controller 创建 mountPath: /mnt/shared readOnly: true # 默认 truerunner 只允许任务容器挂载 runner 配置文件中 container.valid_volumes 所列的路径。controller 会把每个 mountPath 及其下的路径加入该列表,因此任务容器可以挂载它们:
jobs: example: runs-on: ubuntu-latest container: image: docker.gitea.com/runner-images:ubuntu-latest volumes: - /mnt/shared:/data steps: - run: ls /data使用自定义 runner 配置文件时,须自行在其 container.valid_volumes 中列出这些路径。被多个 runner Pod 同时挂载的存储卷声明,须使用允许这样做的访问模式,例如 ReadOnlyMany 或 ReadWriteMany。