存储与缓存
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:
kubectl get storageclassALLOWVOLUMEEXPANSION 最好为 true,VOLUMEBINDINGMODE 最好为 WaitForFirstConsumer。
runner Pod 的存储卷
Section titled “runner Pod 的存储卷”| 存储卷 | 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 缓存还要在上传前暂存每份缓存。
存储卷的生命周期
Section titled “存储卷的生命周期”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 或调整容量
Section titled “更换 StorageClass 或调整容量”存储卷的 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 兼容存储
Section titled “S3 兼容存储”缓存可以存放在 S3 兼容服务的存储桶中,如 AWS S3、MinIO 或 RustFS。此时 runner 直接读写存储桶,controller 不创建缓存服务器,使用相同存储桶和前缀的 runner 共享缓存。
创建保存访问密钥的 Secret:
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-keyregion必填,用于为每个请求签名。在 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配置即可切回原来的缓存。
内置缓存服务器
Section titled “内置缓存服务器”默认情况下,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后删除。
外部缓存服务器
Section titled “外部缓存服务器”若要使用自己的缓存服务器,例如用 gitea-runner cache-server 启动的,请设置其地址与共享密钥。此时 controller 不再创建内置缓存服务器。
cacheServer: externalServerURL: "http://cache.example.com/" externalSecretRef: name: cache-server-secret key: secretexternalSecretRef 从 Runner 所在命名空间的 Secret 中读取密钥。已弃用的 externalSecret 则以明文提供密钥,它会写入生成的配置文件。两者只能设置其一。
- 该 Secret 或其键不存在或为空时,controller 不创建 runner Pod,并报告提到
cache server external secret的BuildRunnerWorkerFailed警告事件。 - 修改该 Secret,例如轮换密钥,会重建 runner Pod,使其读取新密钥。