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

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 须设置且只能设置其一。

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

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 授予 privileged SecurityContextConstraints。

  • 部分加固型的 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 时,对每个都检查一次。

Terminal window
kubectl create namespace rc-preflight
kubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=privileged
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:
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: preflight
EOF
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 清理。

创建命名空间,以及保存注册令牌的 Secret:

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

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

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

Terminal window
kubectl apply -f runner.yaml
kubectl -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 check
on: [push]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: cat /etc/os-release

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

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 事件,见排查。

任务镜像由 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 + 5m
  • shutdownTimeout 是 runner 等待正在执行的任务的时长,超时后任务被取消。任务可能超过 10 分钟时请相应增大。
  • terminationGracePeriodSeconds 是 Kubernetes 强制终止 Pod 前的等待时长。其值不应小于 shutdownTimeout,否则 Pod 会在任务完成前被终止。出现这种设置时,controller 会报告 GracePeriodTooSmall 警告事件。

配置变更不会中断任务:正在执行任务的 runner Pod 会在任务结束后才重建,见配置变更如何生效。

任务写入的数据,如检出的代码和构建产物,存放在 Docker 数据目录所在的存储卷上。受磁盘 I/O 制约的任务,例如处理大量小文件的任务,可以改为把这些数据放在内存(tmpfs)中:

runtime:
jobTmpfs:
workspaceSize: 8Gi # 任务工作区
tmpSize: 2Gi # 可选:任务容器中的 /tmp
scalability:
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 + tmpSize
memoryLimit ≥ 任务所需内存 + workspaceSize + tmpSize × 2

tmpSize 在上限中计两次,因为 Docker 类 action 另有同样大小的 /tmp。按上面的设置,若任务需要 4Gi,请求至少为 14Gi,上限至少为 16Gi。请求过低会使节点内存超额分配;上限过低时,tmpfs 写满后任务会因内存耗尽被终止,而不是以 no space left on device 失败。内存设置明显容纳不下 tmpfs 时,controller 会报告 JobTmpfsMemoryTooSmall 警告事件。

-dind-rootless 版本以非 root 用户运行 Docker 及任务。它需要同时设置以下两项:

runtime:
image: gitea/runner:6.0.0-dind-rootless
runAsUser: 1000
storage:
dockerStorageMountPath: /home/rootless/.local/share/docker
  • 缺少 runAsUser:controller 不会将 Docker 数据目录存储卷的属主设为该用户,Docker 无法启动。
  • 缺少 dockerStorageMountPath:存储卷挂载到 rootless daemon 不使用的位置。初期不会报错,但每次 Pod 重建都会丢失已拉取的镜像,而且镜像会在节点磁盘上累积,直至耗尽磁盘空间。

runner Pod 仍然是特权的:Docker 需要内核权限来创建网络命名空间、挂载文件系统,这与它以哪个用户运行无关。rootless 镜像的作用在于任务代码不以 root 运行,在 CI 中运行不受信任的代码时(虽然这是极不建议的行为),这仍是有价值的纵深防御。

pvcMounts 将已有的 PersistentVolumeClaim 挂载到 runner Pod 中,供任务读写共享数据:

runtime:
pvcMounts:
- volumeName: shared-data
claimName: my-existing-pvc # 位于 Runner 所在的命名空间,不由 controller 创建
mountPath: /mnt/shared
readOnly: true # 默认 true

runner 只允许任务容器挂载 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。