Installing the Controller
The controller is installed once per cluster from a single manifest, which holds the Runner custom resource definition, the controller and its permissions. Runners are then added by creating Runner resources, which is described on the page of each backend.
Installing the manifest needs cluster administrator rights, as it creates a CustomResourceDefinition and ClusterRoles. Check the requirements first.
Download and verify
Section titled “Download and verify”The manifests are published at dl.gitea.com/runner-controller, one directory per version. Set VERSION to the latest version listed there. This documentation applies to version 0.7.10 and later. If you upgrade to 0.7.10 from an earlier version, first check your Runner manifests carefully against this documentation, so that the Actions Runner Controller keeps working after the upgrade. See Upgrading for the steps.
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"
# on macOS use: shasum -a 256 -c "$FILE.sha256"sha256sum -c "$FILE.sha256"Install
Section titled “Install”kubectl apply -f "$FILE"kubectl -n runner-controller-system rollout status deploy/runner-controller-controller-managerThe manifest creates:
| Resource | Purpose |
|---|---|
Namespace runner-controller-system |
Holds the controller |
CustomResourceDefinition runners.gitea.com |
The Runner resource |
Deployment runner-controller-controller-manager and ServiceAccount of the same name |
The controller, one replica with leader election |
ClusterRole runner-controller-manager-role, bound to the controller for the whole cluster |
What the controller does in any namespace, see Permissions of the controller |
Role runner-controller-leader-election-role and its binding |
Leader election, in runner-controller-system |
ClusterRole runner-controller-worker-role |
What a runner of the Kubernetes backend needs to run jobs as pods. The controller binds it per namespace |
ClusterRoles runner-controller-runner-editor-role and runner-controller-runner-viewer-role |
Ready-made roles to let users manage or view Runner resources, bind them as needed |
Service runner-controller-controller-manager-metrics-service, ClusterRoles runner-controller-metrics-auth-role and runner-controller-metrics-reader |
The controller’s metrics endpoint and the permissions around it |
The controller image commitgo/runner-controller:v<version> is public on Docker Hub, and the controller pod meets the restricted Pod Security Standard. For clusters without internet access see Air-gapped clusters.
Runner resources can be created in any namespace, and their runner pods run in the same namespace as the Runner, not in runner-controller-system.
Permissions of the controller
Section titled “Permissions of the controller”The controller runs as the ServiceAccount runner-controller-controller-manager in runner-controller-system. It watches the Runner resources, and the objects it creates for them, in all namespaces, so its permissions are granted for the whole cluster and cannot be limited to some namespaces.
The ClusterRole runner-controller-manager-role, bound for the whole cluster:
| API group | Resource | Verbs | Used for |
|---|---|---|---|
gitea.com |
runners |
create, delete, get, list, patch, update, watch |
Reading Runner resources |
gitea.com |
runners/status |
get, patch, update |
Updating status.targetSize |
gitea.com |
runners/finalizers |
update |
Not used yet, reserved for later versions |
| core | pods |
create, delete, get, list, patch, update, watch |
Runner pods and the cache server pod |
| core | configmaps |
create, delete, get, list, patch, update, watch |
Runner configurations, and reading the ConfigMaps a Runner refers to, such as your own runner configuration |
| core | secrets |
create, delete, get, list, patch, update, watch |
Registration Secrets and the key of the cache server, and reading the Secrets a Runner refers to, such as the registration token |
| core | services |
create, delete, get, list, patch, update, watch |
The Service of the cache server |
| core | persistentvolumeclaims |
create, delete, get, list, patch, update, watch |
The cache volumes of runner pods and of the cache server |
| core | persistentvolumes |
create, delete, get, list, patch, update, watch |
Reading the volumes bound to those claims, and setting their reclaim policy |
| core | events |
create, delete, get, list, patch, update, watch |
Events on Runner resources |
storage.k8s.io |
storageclasses |
get, list, watch |
Checking whether a StorageClass allows volume expansion, when a volume size is increased |
| core | serviceaccounts |
create, delete, get, list, watch |
Kubernetes backend: the ServiceAccount <name>-worker |
rbac.authorization.k8s.io |
rolebindings |
create, delete, get, list, watch |
Kubernetes backend: the RoleBinding <name>-worker |
rbac.authorization.k8s.io |
clusterroles, only runner-controller-worker-role |
bind |
Kubernetes backend: granting runner-controller-worker-role through that RoleBinding |
The Role runner-controller-leader-election-role, in runner-controller-system only:
| API group | Resource | Verbs | Used for |
|---|---|---|---|
coordination.k8s.io |
leases |
create, delete, get, list, patch, update, watch |
Leader election |
| core | events |
create, patch |
Events about leader election |
| core | configmaps |
create, delete, get, list, patch, update, watch |
Not used, to be removed in a later version |
The metrics endpoint checks each request with the ClusterRole runner-controller-metrics-auth-role, bound to the controller for the whole cluster: it creates tokenreviews (authentication.k8s.io) to verify the token of the request, and subjectaccessreviews (authorization.k8s.io) to check whether the sender may read the metrics. The ClusterRole runner-controller-metrics-reader allows get on /metrics and is not bound: bind it to the ServiceAccount of whatever collects the metrics.
Missing permissions
Section titled “Missing permissions”When a permission is missing, for example because the ClusterRole was edited, the work that needs it does not happen, and the controller log shows forbidden errors that name the resource and the verb, such as User "system:serviceaccount:runner-controller-system:runner-controller-controller-manager" cannot create resource "pods". Failures to create, change or delete objects are also reported as warning events on the Runner, such as ApplyRunnerWorkerFailed and CleanupRunnerWorkerFailed.
To check a permission:
kubectl auth can-i <verb> <resource> -n <namespace> \ --as=system:serviceaccount:runner-controller-system:runner-controller-controller-managerTo see the permissions of the version you installed:
kubectl describe clusterrole runner-controller-manager-rolekubectl -n runner-controller-system describe role runner-controller-leader-election-roleNext steps
Section titled “Next steps”Create a Runner for the backend you chose:
Upgrading and uninstalling are described in Operations.