配置
本页的选项对两种后端都适用。示例中写在 runtime 下的选项,使用 Kubernetes 后端时请改写在 kubernetesRuntime 下。仅属于某个后端的选项在其页面中介绍:Docker-in-Docker 与 Kubernetes。存储与缓存见存储与缓存。
Gitea 地址
Section titled “Gitea 地址”gitea: instanceUrl: "https://gitea.example.com"instanceUrl 是 controller 与 runner 访问 Gitea 所用的地址。它可以是集群内的地址,例如部署在集群中的 Gitea 的 Service;若 Gitea 部署在某个路径下,地址须包含该路径。任务检出代码、上传产物时使用的是 Gitea 自身配置的地址(其 ROOT_URL),因此任务容器也须能访问该地址。
将注册令牌保存在 Runner 所在命名空间的 Secret 中,并在 registrationTokenSecretRef 中引用它:
kubectl -n <namespace> create secret generic runner-registration-token \ --from-literal=token=<registration token>gitea: registrationTokenSecretRef: name: runner-registration-token key: token- 只有 controller 使用该令牌。runner Pod 获取的是自己 runner 的凭证,而不是令牌。
- 值不能带首尾空白,而文件以换行结尾时,
--from-file会将该换行一并写入。controller 会拒绝这样的值,并报告RegistrationTokenUnavailable警告事件。在 YAML 清单中,请在stringData下把令牌写在一行内。 - 不建议使用
gitea.registrationToken以明文将令牌写在Runner中:任何能读取该Runner的人都能读取到令牌。请改用registrationTokenSecretRef。两者只能设置其一。
轮换令牌:Secret 的值变更后,每个 runner 都会用新令牌重新注册,其 Pod 随之重建,见配置变更如何生效。缓存卷会保留。原有的注册在 Gitea 中会成为离线 runner,可在 Gitea 的 runner 页面删除。
若 Gitea 使用自签名证书或内部 CA 签发的证书,须关闭证书校验,否则 controller 与 runner 都无法连接:
gitea: skipTlsVerify: true # 默认 false目前还无法为 controller 提供 CA 证书,只能通过 skipTlsVerify: true 解决。后续版本将支持提供 CA。
skipTlsVerify 作用于 controller 与 runner,但不作用于任务。任务容器会自行校验证书,例如 actions/checkout 克隆仓库时,因此任务镜像须信任 Gitea 的证书,否则任务会失败。对于 runner 访问的其他服务,如内部镜像仓库或 action 仓库,若要信任其 CA 而不是跳过校验,见 init container 中的示例。
scalability: minSize: 1 # 没有任务排队时保留的 runner Pod 数,默认 0 maxSize: 10 # 默认 10 cpuRequest: "2" memoryRequest: 4Gi # cpuLimit: "4" # 不设置则没有上限 # memoryLimit: 8GiminSize是 runner Pod 数量的下限,不区分繁忙或空闲。minSize: 0时,空闲后所有 runner Pod 都会被回收,下一个任务需要等待完整的启动过程:可能包括新建节点、拉取镜像和注册,通常需要几分钟。若需避免这段等待,请至少保留一个 runner。所有 runner Pod 都在执行任务时,新任务仍需等待新的 runner Pod。- 资源设置在 Docker-in-Docker 后端中作用于每个 runner Pod,在 Kubernetes 后端中作用于每个 job Pod 的
job容器,见并发与伸缩。
runner Pod 数量随队列变化的方式:
- 扩容:有任务排队时,controller 一次性为空闲 runner 无法承接的任务增加 runner Pod。例如有 2 个空闲 runner、5 个排队任务时,增加 3 个 runner Pod。Kubernetes 后端见并发与伸缩。
- 缩容:没有任务排队时,从编号最大的开始,一次回收一个 runner Pod,前提是该 runner 已空闲约 5 分钟。因此从满负载回到
minSize需要一段时间。编号最大的 runner 繁忙时,即使其他 runner 空闲,也不会回收任何 runner Pod。 - 减小
maxSize会立即回收超出新上限的 runner Pod,无论它们是否在执行任务:其任务有 runner 的shutdownTimeout时长用于收尾。它们的存储卷与注册信息也会立即删除,而不是保留storage.cacheTTL。 - 修改
minSize或maxSize会立即生效,不会重建其他 runner Pod。
当前的目标数量记录在 Runner 的 status 中,每次变化都会产生 ScaleUp 或 ScaleDown 事件:
kubectl -n <namespace> get runner <name> -o jsonpath='{.status.targetSize}'kubectl -n <namespace> describe runner <name>Runner 的 label 是任务在 runs-on 中选择的名称,每个 label 对应任务运行所用的镜像。label 没有默认值:每个 Runner 至少要列出一个。
runtime: labels: ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest # Docker-in-DockerkubernetesRuntime: labels: ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest # Kubernetes,不带前缀使用 Docker-in-Docker 后端时,label 的值也可以是 host:其任务以 host 方式运行,即直接在 runner 容器内运行,而不是在 runner 为任务单独创建的任务容器中运行。但工作流为任务指定了 container 时,该任务仍在任务容器中运行。
只要任务 runs-on 中的任一 label 是 Runner 的 label,controller 就会将该排队任务计入,即使该任务还需要 Runner 没有的 label、因而无法运行它。因此,令牌覆盖相同仓库的两个 Runner 不应使用相同的 label:否则一个排队的任务会让两者都扩容,而只有其中一个能执行它。
controller 之外的 runner(例如手动注册的)使用相同的 label 时同理:controller 不把它们计为空闲容量,可能扩容出用不上的 runner Pod,且同一 label 的任务会落在不同的环境中。
任务环境变量
Section titled “任务环境变量”envs 为 Runner 的每个任务设置环境变量:
runtime: envs: - name: NPM_CONFIG_REGISTRY value: "https://npm.example.com/"这些变量不会设置在 runner 容器中。runner 和 Docker 需要的变量,如代理,请写在 runnerEnv 中。
这些变量由 controller 写入 runner 配置文件,runner 执行每个任务时将其设置到任务中。runner 启动时会先将其 value 中的 ${NAME} 替换为 runner 容器自身的环境变量 NAME(例如通过 runnerEnv 设置的变量),该变量未设置时 runner 无法启动。字面量 ${NAME} 须写作 $${NAME}。
runner 环境变量
Section titled “runner 环境变量”runnerEnv 与 runnerEnvFrom 设置 runner 容器自身的环境变量,写法与 Kubernetes 容器的 env 和 envFrom 相同。使用 Docker-in-Docker 后端时,Docker daemon 运行在同一容器中,也会获得这些变量。
runtime: runnerEnv: - name: HTTPS_PROXY value: "http://proxy.example.com:8080" - name: NO_PROXY value: "gitea.example.com,.svc.cluster.local" - name: NPM_TOKEN valueFrom: secretKeyRef: name: runner-secrets key: npm-token runnerEnvFrom: - configMapRef: name: runner-env- 引用的 Secret 与 ConfigMap 须位于
Runner所在的命名空间。其中某个对象或键不存在、且未标记optional: true时,controller 不创建 runner Pod,并报告BuildRunnerWorkerFailed警告事件。 - 被引用的 Secret 或 ConfigMap 有任何变更(包括只改了其标签或注解),都会重建 runner Pod,见配置变更如何生效。
- 同名变量以
runnerEnv中的为准。 GITEA_INSTANCE_URL、CONFIG_FILE、RUNNER_STATE_FILE、GITEA_RUNNER_LABELS与GITEA_RUNNER_ONCE,以及 Kubernetes 后端的POD_IP,均为保留变量:其中一些由 controller 自行设置,其余的会改变 runner 的注册或接取任务的方式。在runnerEnv中设置它们的Runner会被拒绝。runnerEnvFrom的来源中含有这些变量(计入prefix)时,controller 不创建 runner Pod。- 以 host 方式运行的任务可以读取这些变量。在单独的任务容器中运行的任务无法读取,代理变量除外,见下文。
在 runner 容器上设置 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY 后,以下流量经过代理:
- runner 到 Gitea、action 仓库,以及缓存服务器或 S3 存储桶的连接;
- 使用 Docker-in-Docker 后端时,Docker daemon 拉取镜像,除非其
daemon.json设置了proxies; - 任务、服务与镜像构建:runner 会把这些变量传给它们,并将缓存服务器和服务加入其
NO_PROXY。envs中设置的代理变量优先。
NO_PROXY 须列出 runner 直接访问的集群内与内网地址,否则这些请求也会发往代理:
| 地址 | NO_PROXY 中遗漏时 |
|---|---|
| Gitea | runner 无法上线 |
内置缓存服务器(.svc.cluster.local,或 cacheServer.host)、外部缓存服务器或 S3 endpoint |
工作流缓存失效,但任务不会失败 |
| 内部镜像仓库 | 无法拉取任务镜像 |
Kubernetes 后端:API Server,即 runner Pod 中 KUBERNETES_SERVICE_HOST 的 IP 或其所在网段 |
无法创建 job Pod,任务失败 |
向任务传递 Secret 中的值
Section titled “向任务传递 Secret 中的值”envs 中的 ${NAME} 可以把 runner 容器的变量传给任务,其值既不会出现在 Runner 中,也不会出现在生成的配置文件中:
runtime: runnerEnv: - name: NPM_TOKEN valueFrom: secretKeyRef: name: runner-secrets key: npm-token envs: - name: NPM_TOKEN value: "${NPM_TOKEN}"以这种方式传递的值不会在任务日志中被遮蔽。需要在日志中遮蔽,或只允许部分仓库使用的值,请使用 Gitea Actions 的密钥(secrets)。
init container
Section titled “init container”runnerInitContainers 为 runner Pod 添加 init container,它们在 runner 启动前依次运行,例如为 runner 准备文件。文件通过 emptyDirMounts 中的目录传递给 runner:runner 容器在其 mountPath 处挂载该目录,init container 按其 volumeName 挂载。
以下示例将 ConfigMap 中的内部 CA 证书与镜像自带的证书合并,使 runner 能访问使用该 CA 证书的服务,如内部的 action 仓库。runner 从 SSL_CERT_FILE 读取证书,它在部分下载中使用的 git 则从 GIT_SSL_CAINFO 读取:
runtime: configMapMounts: - volumeName: company-ca configMapName: company-ca # 证书以 *.crt 保存 mountPath: /etc/company-ca readOnly: true emptyDirMounts: - volumeName: ca-bundle mountPath: /etc/ca-bundle readOnly: true runnerInitContainers: - name: ca-bundle # 不写 image:使用 runner 镜像 command: ["sh", "-c", "cat /etc/ssl/certs/ca-certificates.crt /in/*.crt > /out/ca-certificates.crt"] volumeMounts: - name: company-ca mountPath: /in readOnly: true - name: ca-bundle mountPath: /out runnerEnv: - name: SSL_CERT_FILE value: /etc/ca-bundle/ca-certificates.crt - name: GIT_SSL_CAINFO value: /etc/ca-bundle/ca-certificates.crt- init container 的写法与 Kubernetes 容器相同,但只支持以下字段:
name、image、imagePullPolicy、command、args、workingDir、env、envFrom、resources、securityContext与volumeMounts。不支持 sidecar(restartPolicy)和探针。名称install-registration、chown-cache与runner已被 controller 占用。 - 它们在 controller 自身的 init container 之后运行。不写
image时使用 runner 镜像及其imagePullPolicy,不写resources时使用 runner 容器的资源设置。 - 它们可以挂载
configMapMounts、secretMounts与emptyDirMounts的卷,使用 Docker-in-Docker 后端时还可以挂载pvcMounts的卷。 - 它们不挂载 ServiceAccount 令牌,因此无法使用 Kubernetes API。
- 使用 Kubernetes 后端时,它们须满足 Pod Security 的
restricted级别:不能以 root 运行,不能使用特权模式或提权,capabilities 不能超出NET_BIND_SERVICE。未设置的allowPrivilegeEscalation与capabilities.drop默认为false与["ALL"]。不满足时,Runner会被拒绝,或 controller 不创建 runner Pod 并报告BuildRunnerWorkerFailed警告事件。Docker-in-Docker 后端没有这一限制。 - 某个 init container 以错误退出或无法启动(例如无法拉取其镜像)时,runner 不会启动,kubelet 会不断重试,controller 报告
RunnerInitContainerFailed警告事件,附带退出码与日志末尾。 - 它们须在 15 分钟内完成:runner Pod 启动 15 分钟后(计入拉取镜像与 init container 的时间),其 runner 仍未在 Gitea 上线时,该 Pod 会被删除并重新创建,见未能上线的 runner Pod。init container 持续失败时也是如此。
- 修改
runnerInitContainers,或其env、envFrom读取的 Secret 或 ConfigMap 发生变更,都会重建 runner Pod。挂载的 ConfigMap 或 Secret 的内容变更则不会。
除了 Docker-in-Docker 后端的 pvcMounts,还可以向 runner 容器挂载以下三类卷:
runtime: configMapMounts: - volumeName: extra-config configMapName: runner-extra-config mountPath: /etc/runner-extra readOnly: true secretMounts: - volumeName: extra-secret secretName: runner-extra-secret mountPath: /etc/runner-secret readOnly: true emptyDirMounts: - volumeName: prepared mountPath: /etc/prepared medium: Memory # 留空为节点磁盘;Memory 计入 Pod 的内存 sizeLimit: 64Mi # 超出时 Pod 会被驱逐-
configMapMounts与secretMounts还支持items、defaultMode与optional,与 Pod 的卷相同。 -
每个挂载的
volumeName须唯一,且不能使用以下名称。这些名称由 controller 为自己的卷保留,无论Runner当前是否用到这些卷:runner-configrunner-datarunner-registrationrunner-cacherunner-action-cachecache-server-secretcache-s3-credentialsrunner-job-tmpfsno-service-account-token
否则 controller 不创建 runner Pod,并报告指明该卷的
BuildRunnerWorkerFailed警告事件,正在运行的 runner Pod 保持不变。 -
configMapMounts、secretMounts与emptyDirMounts的卷挂载到 runner 容器中,而不是任务容器中。
配置变更如何生效
Section titled “配置变更如何生效”runner Pod 的配置变更时会重建,包括:镜像、label、环境变量、init container 等 runner Pod 的选项,runnerEnv、runnerEnvFrom 或 init container 环境变量读取的 Secret 或 ConfigMap,轮换注册令牌、缓存服务器密钥或 S3 密钥,以及缓存卷达到 storage.cacheMaxAge。重建不会中断任务:
- 没有在执行任务的 runner Pod 立即重建。
- Docker-in-Docker 后端:正在执行任务的 runner Pod 在任务结束后重建,期间会有
RollDeferred事件。 - Kubernetes 后端:正在执行任务的 runner Pod 会被排空:不再接取新任务,当前的任务完成后重建。同一
Runner同一时间只排空一个 runner Pod,其他 runner Pod 承接排队的任务,必要时扩容。等待期间的事件为RollDeferred,开始排空时为DrainWorker。
内置缓存服务器的配置变更时会立即重建,见内置缓存服务器。
nodeSelector: node-pool: runnerstolerations: - key: dedicated operator: Equal value: runner effect: NoScheduleaffinity: {} # 标准的 Kubernetes affinityimagePullSecrets: - name: <registry credentials>这些字段位于 spec 顶层,而不是 runtime 下。若要让一组节点专供 runner 使用,请为这些节点设置 taint,以阻止其他 Pod 调度到这些节点,并在 tolerations 中容忍该 taint:
tolerations与imagePullSecrets同样作用于内置缓存服务器。它不使用nodeSelector或affinity,可以运行在任何能访问其存储卷的节点上。- 这些节点上的 DaemonSet,尤其是存储驱动的节点插件,也须容忍该 taint,否则 runner Pod 的存储卷无法挂载。
- runner Pod 与内置缓存服务器带有注解
karpenter.sh/do-not-disrupt: "true",Karpenter 不会为整合节点而回收它们所在的节点。因此minSize保留的 runner 所在的节点会一直保留。 - 使用 Kubernetes 后端时,这些字段只作用于 runner Pod。job Pod 的这些设置来自 job Pod 模板。
- 修改这些字段会按配置变更如何生效重建 runner Pod,并立即重建内置缓存服务器。
使用自定义 runner 配置文件
Section titled “使用自定义 runner 配置文件”controller 根据 Runner 生成 runner 的配置文件(config.yaml)。若要自行编写,请将其放在 Runner 所在命名空间的 ConfigMap 中,键为 config.yaml,并在 runnerConfigMapName 中指定该 ConfigMap:
runtime: runnerConfigMapName: my-runner-config此时 controller 原样挂载该文件,并且:
-
不再向其中写入原本会写入的选项:
labels中的镜像、envs、jobTmpfs.tmpSize、缓存设置,以及pvcMounts的container.valid_volumes; -
不创建内置缓存服务器,请在文件中自行配置缓存;
-
仍会依据部分选项工作,因此文件须与它们保持一致:
controller 依据 用于 文件中须保持一致 labels的名称统计排队任务 runner.labels中相同的名称,runner 按它接取任务shutdownTimeout设置 terminationGracePeriodSecondsrunner.shutdown_timeout中相同的值gitea.skipTlsVerify连接 Gitea runner.insecure中相同的值每个 runner Pod 一个任务(Docker-in-Docker) 规划伸缩 runner.capacity: 1。Kubernetes 后端见该页
编写该文件时:
- 设置
host.workdir_parent: /cache/act_workdir,与生成的配置文件相同,使下载的 action 保存在 action 缓存卷上。 - 不要设置
runner.file:controller 会自行放置 runner 的注册信息。
使用 Kubernetes 后端时,另见该页的使用自定义 runner 配置文件。配置文件中各项的说明见 runner 的 config.example.yaml。