Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support

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.

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.

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"
# on macOS use: 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

The 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.

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.

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:

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

To see the permissions of the version you installed:

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

Create a Runner for the backend you chose:

Upgrading and uninstalling are described in Operations.