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

存储与缓存

runner Pod 将缓存保存在持久卷上,这些存储卷的生命周期长于 Pod:runner Pod 被回收时,其存储卷会保留;runner Pod 重建时会重新挂载它们,之前下载的镜像和 action 仍然保留。本页介绍这些存储卷、它们的保留时长,以及工作流缓存。

  • 能动态供应 ReadWriteOnce 存储卷。 存储卷随 runner Pod 的增加而创建,因此须由 StorageClass 按需供应。不支持预先手工创建的存储卷。
  • 建议 StorageClass 开启 allowVolumeExpansion,以便日后原地扩容,见更换 StorageClass 或调整容量。
  • 建议使用 volumeBindingMode: WaitForFirstConsumer,使存储卷创建在其 Pod 被调度到的位置。
  • 存储卷能挂载到其他节点。 缩容后重建的 runner Pod 会挂载其原有的存储卷,而它可能被调度到任何节点。local-path-provisioner 等节点本地的供应器会把每个 runner 固定在一个节点上,该节点不存在后,runner 无法再启动。这类供应器只适合单节点试用。
  • 拓扑。 绑定到某个可用区或部分节点的存储卷,会把其 runner Pod 限制在那里。若集群会按需增加节点,负责扩容节点的组件须能识别存储卷的拓扑,并在存储卷所在的位置添加节点,否则 Pod 会一直处于 Pending 状态,并提示 volume node affinity conflict。若无法做到,请通过 nodeSelector 或 affinity 把 runner Pod 限制在一个可用区内。

各后端另有要求:Docker-in-Docker 后端的 Docker 数据目录须使用块存储,Kubernetes 后端的存储卷须支持 fsGroup。

检查 StorageClass:

Terminal window
kubectl get storageclass

ALLOWVOLUMEEXPANSION 最好为 true,VOLUMEBINDINGMODE 最好为 WaitForFirstConsumer。

存储卷 PVC 名称 挂载位置 内容 容量 StorageClass
Docker 数据目录(仅 Docker-in-Docker) <runner pod>-cache dockerStorageMountPath,默认 /var/lib/docker Docker 拉取的镜像与镜像层、任务工作区 cacheVolumeSize,100Gi dockerStorageClassName,否则 className
action 缓存 <runner pod>-action-cache /cache 任务所用 action 的代码,以及 S3 缓存的暂存区 actionCacheVolumeSize,10Gi actionCacheClassName,否则 className

action 缓存保存任务通过 uses: 使用的 action,避免每个任务重新下载。工作流缓存与它无关,见工作流缓存。

className 默认是名为 standard 的 StorageClass,而不是集群的默认 StorageClass。请将它或更具体的字段设为集群中存在的 StorageClass,否则存储卷声明会一直处于 Pending。

使用 Docker-in-Docker 后端时,任务容器写入的所有内容,如工作区和 setup-* 类 action 安装的工具,都写入 Docker 数据目录。action 缓存只保存 runner 自己下载的内容,I/O 压力小。因此 action 缓存可以放在网络存储上,而 Docker 数据目录应放在高速的块存储上。

请按峰值而非平均值规划存储:

总量 ≈ maxSize × (Docker 数据目录 + action 缓存) + 缓存服务器
  • 默认容量偏大。 每个 runner Pod 的 Docker 数据目录为 100Gi,缓存服务器为 500Gi。请按任务的实际需求设定。
  • 缩容不会释放存储卷。 runner 的存储卷在最后一次使用后保留 storage.cacheTTL,默认一周。曾扩容到 maxSize 的 Runner 会在一周内占用相应的存储。
  • 使用 S3 缓存时没有缓存服务器的存储卷,但 action 缓存还要在上传前暂存每份缓存。
storage:
cacheTTL: 168h # 最后一次使用后保留的时长,默认 168h
cacheMaxAge: 720h # 自创建起达到该时长后清空重建,默认 720h
  • runner 的存储卷在 cacheTTL 时长内未被使用就会被删除。其 runner Pod 运行期间,存储卷处于使用中,会一直保留。内置缓存服务器的存储卷同样遵循 cacheTTL:缓存服务器停用满该时长后删除,例如缩容到 0 或改用其他缓存之后。
  • cacheMaxAge 限定 runner Pod 存储卷的总寿命。达到该时长的存储卷会被删除并重新创建为空卷,即使 runner 一直在使用,如 minSize 保留的 runner。这样的 runner Pod 会在空闲时用新的存储卷重建,同一 Runner 同一时间只重建一个,并产生 CachePVCExpired 事件。因此增大 cacheTTL 也不能让缓存永久保留。缓存服务器的存储卷不受影响,因为缓存服务器会自行清理过期条目。
  • runner 的注册信息保存在不会过期的 Secret 中。
  • 有两种情况会立即删除 runner 的存储卷:减小 maxSize 时,超出部分的 runner 的存储卷连同其注册信息一起删除;未能上线的 runner Pod 会连同其存储卷一起被删除,见未能上线的 runner Pod。

存储卷的 StorageClass 无法修改,Kubernetes 也无法缩小存储卷。为避免意外清空缓存,只有在 storage.allowDeleteCachePVC 为 true 时,controller 才会应用这类变更:

变更 allowDeleteCachePVC: false(默认) allowDeleteCachePVC: true
扩大容量,StorageClass 支持扩容 原地扩容(CachePVCExpand) 原地扩容(CachePVCExpand)
扩大容量,StorageClass 不支持扩容 忽略,报告 CachePVCExpandUnsupported 警告事件 删除存储卷并重新创建为空卷(CachePVCRecreate)
缩小容量 忽略,报告 CachePVCShrinkIgnored 警告事件 删除存储卷并重新创建为空卷(CachePVCRecreate)
更换 StorageClass 忽略,报告 CachePVCClassChangeIgnored 警告事件 删除存储卷并重新创建为空卷(CachePVCRecreate)

runner Pod 的存储卷在其空闲时重建,与其他配置变更相同。内置缓存服务器的存储卷会连同其 Pod 立即重建。

存储卷被删除时,其背后的存储是否释放由 StorageClass 决定。回收策略为 Retain 时,删除的存储卷会留下 Released 状态的 PersistentVolume。若要释放它们,请设置:

storage:
reclaimPolicy: Delete # 或 Retain;不设置则沿用 StorageClass 的策略

controller 会把该策略设置到为该 Runner 动态供应的 PersistentVolume 上,但只在存储卷已绑定、且正被 runner Pod 或缓存服务器使用期间修改。所以已缩容的 runner 的存储卷不会被修改,删除 Runner 时仍按 StorageClass 原有的策略处理。建议在创建 Runner 时就设置该项,而不是等到删除 Runner 前才设置。静态供应的存储卷永远不会被修改。

工作流缓存(actions/cache 以及 setup-go、setup-node 等 action 使用)需要缓存服务器。有以下三种方式,生产环境推荐使用 S3 兼容存储:

  • 缓存保存在存储桶中,不需要运行内置缓存服务器的 Pod,也不需要它的存储卷(默认 500Gi)。
  • 容量随存储桶扩展,不必预先规划和调整缓存服务器存储卷的大小。
  • 多个 Runner 可以通过相同的前缀共享缓存,而内置缓存服务器只服务于一个 Runner。

使用前请阅读 S3 兼容存储一节中的注意事项。内置缓存服务器无需额外配置,适合试用。

S3 兼容存储(推荐) 内置缓存服务器(默认) 外部缓存服务器
配置方式 cacheServer.s3 无需配置 cacheServer.externalServerURL
缓存存放在 存储桶 controller 创建的 Pod 的存储卷上 您的缓存服务器

任务的缓存流量经由 runner 转发,因此缓存服务器只需对 runner Pod 可达。

缓存可以存放在 S3 兼容服务的存储桶中,如 AWS S3、MinIO 或 RustFS。此时 runner 直接读写存储桶,controller 不创建缓存服务器,使用相同存储桶和前缀的 runner 共享缓存。

创建保存访问密钥的 Secret:

Terminal window
kubectl -n <namespace> create secret generic runner-cache-s3 \
--from-literal=access-key=<access key ID> \
--from-literal=secret-key=<secret access key>
cacheServer:
s3:
endpoint: "https://s3.us-west-2.amazonaws.com" # 以 http:// 或 https:// 开头
region: "us-west-2" # 见下文
bucket: "runner-cache"
prefix: "" # 留空时为 Runner 的 <namespace>/<name>
# pathStyle: true
accessKeyRef:
name: runner-cache-s3
key: access-key
secretKeyRef:
name: runner-cache-s3
key: secret-key
  • region 必填,用于为每个请求签名。在 AWS 上为存储桶所在的区域;MinIO 与 RustFS 通常为 us-east-1,Cloudflare R2 为 auto。
  • pathStyle 通常无需设置:此时 runner 对 amazonaws.com 上的存储桶使用主机名寻址,对其他服务使用路径寻址。在 AWS 上存储桶名含有点时设为 true,服务只支持主机名寻址时设为 false。
  • 请为存储桶设置生命周期规则。 runner 从不删除缓存,storage.cacheTTL 对存储桶也不生效。至少添加两条规则:前缀下的对象在若干天后过期(例如 7 天),以及中止未完成的分段上传(例如 1 天后)。过期时间从对象创建时算起,因此正在使用的缓存也会过期,下次运行时重新生成。与内置缓存服务器不同,存储桶会保留过期时间内保存过的每一份缓存,包括已被新版本取代的,也不限制每个仓库的容量。过期时间不宜过长。
  • 按最大的单个缓存规划 action 缓存的容量。 runner 会先把每份缓存完整写入其 action 缓存卷,再上传;分段上传在合并各段时会短暂占用约两倍空间。action 缓存应能容纳最大单个缓存的两倍,再加上下载的 action。默认的 10Gi 可容纳约 4GiB 以内的单个缓存。空间不足时该缓存不会被保存,任务不受影响。action 缓存位于网络存储上时,保存缓存会明显变慢。
  • 只支持静态访问密钥,不支持 IRSA、EKS Pod Identity 或实例角色。密钥需要存储桶上的 s3:ListBucket(可用条件限定在前缀下),以及前缀下对象的 s3:GetObject、s3:PutObject 与 s3:DeleteObject。s3:AbortMultipartUpload 为可选:有了它 runner 可以清理失败的上传,否则由生命周期规则清理。修改该 Secret,例如轮换密钥,会重建 runner Pod,使其读取新密钥。
  • 使用 Docker-in-Docker 后端时(包括以 host 方式运行的任务),任务代码有可能读到访问密钥。 请只授予上述权限并限定在前缀下;若存储服务支持,将密钥限制为只能从集群网络使用。不同的信任域请使用不同的密钥,例如对接不同 Gitea 实例的 Runner。
  • runner 用其镜像自带的证书校验 endpoint 的证书,或使用 SSL_CERT_FILE 中的证书包,见 init container 的示例。gitea.skipTlsVerify 对其不生效。
  • 只有 runner 访问存储桶,任务容器不访问。
  • 默认前缀因 Runner 而异。使用相同前缀的 Runner 共享缓存。缓存只按仓库名区分,不区分 Gitea 实例,因此对接不同 Gitea 实例的 Runner 不应使用相同的前缀。
  • s3 不能与 externalServerURL 同时设置。host 与 port 对其不生效。
  • 从内置缓存服务器切换过来时,原有缓存不会迁移。在其存储卷于 storage.cacheTTL 后被删除之前,删除 s3 配置即可切回原来的缓存。

默认情况下,controller 为每个 Runner 创建一个缓存服务器:名为 <name>-cache-server 的 Pod,以及一个 Service、一个保存 runner 认证密钥的 Secret 和一个存储卷。缓存数据保存在存储卷 <name>-cache-server-data 中,容量为 storage.cacheServerVolumeSize(默认 500Gi),StorageClass 为 className,请按各仓库的缓存用量设定其容量。使用 S3、外部缓存服务器或自定义 runner 配置文件时,不创建缓存服务器及其存储卷。

cacheServer:
# host: cache.example.internal # 不设置时为 <name>-cache-server-svc.<namespace>.svc.cluster.local
# port: 8081 # 默认 80;Kubernetes 后端默认 8080,且须不低于 1024
  • runner 通过其 Service 的主机名访问它,该主机名假定集群域名为 cluster.local。集群使用其他域名时请设置 host,否则工作流缓存每次都会未命中,但任务不会失败。
  • Runner 没有 runner Pod 时,缓存服务器的 Pod 与 Service 会被移除,其存储卷保留 storage.cacheTTL。
  • 它运行 runner 镜像,不设置资源请求和上限。
  • runner 用一个密钥向它认证,该密钥由 controller 生成,保存在 Secret <name>-cache-server-secret 中,以文件形式挂载到 runner Pod。
  • 要更换该密钥,删除该 Secret 即可。controller 会生成新密钥,立即重建缓存服务器,随后按配置变更的方式重建 runner Pod。在 runner Pod 重建之前,其任务的缓存读写会失败,任务将其视为未命中缓存。
  • 其配置变更时,例如 runner 镜像或端口,缓存服务器 Pod 会立即重建,数据保留在存储卷上。进行中的缓存读写会失败一次,任务将其视为未命中缓存。
  • 其存储卷的 cacheServerVolumeSize 与 className 变更,按与 runner Pod 存储卷相同的方式处理。
  • 改用外部缓存服务器、S3 或 runnerConfigMapName 后,内置缓存服务器会保留到所有 runner Pod 都使用新配置为止,因此不影响正在运行的任务,之后再被删除。其存储卷在 storage.cacheTTL 后删除。

若要使用自己的缓存服务器,例如用 gitea-runner cache-server 启动的,请设置其地址与共享密钥。此时 controller 不再创建内置缓存服务器。

cacheServer:
externalServerURL: "http://cache.example.com/"
externalSecretRef:
name: cache-server-secret
key: secret

externalSecretRef 从 Runner 所在命名空间的 Secret 中读取密钥。已弃用的 externalSecret 则以明文提供密钥,它会写入生成的配置文件。两者只能设置其一。

  • 该 Secret 或其键不存在或为空时,controller 不创建 runner Pod,并报告提到 cache server external secret 的 BuildRunnerWorkerFailed 警告事件。
  • 修改该 Secret,例如轮换密钥,会重建 runner Pod,使其读取新密钥。