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

安装 controller

controller 在每个集群中安装一次,使用同一份清单,其中包含 Runner 的自定义资源定义、controller 本身及其权限。之后通过创建 Runner 资源来添加 runner,具体见各后端的页面。

安装该清单需要集群管理员权限,因为它会创建 CustomResourceDefinition 与 ClusterRole。请先确认要求。

清单发布在 dl.gitea.com/runner-controller,每个版本一个目录。将 VERSION 设为其中列出的最新版本。本文档适用于 0.7.10 及以上版本。如果您需要从低于 0.7.10 的版本升级至 0.7.10,请仔细对照本文档检查您的 Runner 清单,避免升级后导致 Actions Runner Controller 不可用。升级步骤见升级。

Terminal window
VERSION=<version>
BASE=https://dl.gitea.com/runner-controller/${VERSION}
FILE=runner-controller-v${VERSION}-install.yaml
curl -LO "$BASE/$FILE"
curl -LO "$BASE/$FILE.sha256"
# macOS 上使用:shasum -a 256 -c "$FILE.sha256"
sha256sum -c "$FILE.sha256"
Terminal window
kubectl apply -f "$FILE"
kubectl -n runner-controller-system rollout status deploy/runner-controller-controller-manager

该清单会创建:

资源 用途
Namespace runner-controller-system 存放 controller
CustomResourceDefinition runners.gitea.com Runner 资源
Deployment runner-controller-controller-manager 及同名 ServiceAccount controller,一个副本,启用 leader election
ClusterRole runner-controller-manager-role,在整个集群范围绑定给 controller controller 在任意命名空间中的操作,见 controller 的权限
Role runner-controller-leader-election-role 及其绑定 leader election,位于 runner-controller-system
ClusterRole runner-controller-worker-role Kubernetes 后端的 runner 以 Pod 形式运行任务所需的权限。由 controller 按命名空间绑定
ClusterRole runner-controller-runner-editor-role 与 runner-controller-runner-viewer-role 预置的角色,用于授予用户管理或查看 Runner 资源的权限,按需绑定
Service runner-controller-controller-manager-metrics-service,ClusterRole runner-controller-metrics-auth-role 与 runner-controller-metrics-reader controller 的 metrics 端点及相关权限

controller 镜像 commitgo/runner-controller:v<version> 是 Docker Hub 上的公开镜像,controller Pod 满足 Pod Security 的 restricted 级别。无法访问互联网的集群见离线集群。

Runner 资源可以创建在任意命名空间中,其 runner Pod 运行在 Runner 所在的命名空间,而不是 runner-controller-system。

controller 以 runner-controller-system 中的 ServiceAccount runner-controller-controller-manager 运行。它监听所有命名空间中的 Runner 资源及其为之创建的对象,因此其权限在整个集群范围授予,无法限定在部分命名空间内。

ClusterRole runner-controller-manager-role,在整个集群范围绑定:

API 组 资源 操作 用途
gitea.com runners create、delete、get、list、patch、update、watch 读取 Runner 资源
gitea.com runners/status get、patch、update 更新 status.targetSize
gitea.com runners/finalizers update 目前未使用,为后续版本预留
core pods create、delete、get、list、patch、update、watch runner Pod 与缓存服务器 Pod
core configmaps create、delete、get、list、patch、update、watch runner 配置文件,以及读取 Runner 引用的 ConfigMap,例如自定义 runner 配置文件
core secrets create、delete、get、list、patch、update、watch 保存注册信息的 Secret 与缓存服务器的密钥,以及读取 Runner 引用的 Secret,例如注册令牌
core services create、delete、get、list、patch、update、watch 缓存服务器的 Service
core persistentvolumeclaims create、delete、get、list、patch、update、watch runner Pod 与缓存服务器的缓存卷
core persistentvolumes create、delete、get、list、patch、update、watch 读取上述 PVC 绑定的存储卷,并设置其回收策略
core events create、delete、get、list、patch、update、watch Runner 上的事件
storage.k8s.io storageclasses get、list、watch 增大存储卷容量时,检查 StorageClass 是否允许扩容
core serviceaccounts create、delete、get、list、watch Kubernetes 后端:ServiceAccount <name>-worker
rbac.authorization.k8s.io rolebindings create、delete、get、list、watch Kubernetes 后端:RoleBinding <name>-worker
rbac.authorization.k8s.io clusterroles,仅限 runner-controller-worker-role bind Kubernetes 后端:通过上述 RoleBinding 授予 runner-controller-worker-role

Role runner-controller-leader-election-role,仅在 runner-controller-system 中:

API 组 资源 操作 用途
coordination.k8s.io leases create、delete、get、list、patch、update、watch leader election
core events create、patch 与 leader election 相关的事件
core configmaps create、delete、get、list、patch、update、watch 未使用,将在后续版本中移除

metrics 端点通过 ClusterRole runner-controller-metrics-auth-role(在整个集群范围绑定给 controller)检查每个请求:创建 tokenreviews(authentication.k8s.io)以验证请求中的令牌,创建 subjectaccessreviews(authorization.k8s.io)以确认请求方是否有权读取 metrics。ClusterRole runner-controller-metrics-reader 允许对 /metrics 执行 get,默认未绑定:请将其绑定到采集 metrics 的组件所使用的 ServiceAccount。

缺少某项权限时(例如 ClusterRole 被修改过),依赖该权限的操作无法完成,controller 日志中会出现指明资源与操作的 forbidden 错误,例如 User "system:serviceaccount:runner-controller-system:runner-controller-controller-manager" cannot create resource "pods"。创建、修改或删除对象失败时,Runner 上还会出现 ApplyRunnerWorkerFailed、CleanupRunnerWorkerFailed 等警告事件。

检查某项权限:

Terminal window
kubectl auth can-i <verb> <resource> -n <namespace> \
--as=system:serviceaccount:runner-controller-system:runner-controller-controller-manager

查看所安装版本的权限:

Terminal window
kubectl describe clusterrole runner-controller-manager-role
kubectl -n runner-controller-system describe role runner-controller-leader-election-role

为所选后端创建 Runner:

升级与卸载见运维。