安装 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 不可用。升级步骤见升级。
VERSION=<version>BASE=https://dl.gitea.com/runner-controller/${VERSION}FILE=runner-controller-v${VERSION}-install.yamlcurl -LO "$BASE/$FILE"curl -LO "$BASE/$FILE.sha256"
# macOS 上使用:shasum -a 256 -c "$FILE.sha256"sha256sum -c "$FILE.sha256"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 的权限
Section titled “controller 的权限”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 等警告事件。
检查某项权限:
kubectl auth can-i <verb> <resource> -n <namespace> \ --as=system:serviceaccount:runner-controller-system:runner-controller-controller-manager查看所安装版本的权限:
kubectl describe clusterrole runner-controller-manager-rolekubectl -n runner-controller-system describe role runner-controller-leader-election-role为所选后端创建 Runner:
升级与卸载见运维。