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”To change the manifest before installing it, see Customizing the manifest.
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.
Customizing the manifest
Section titled “Customizing the manifest”To change the manifest, for example to pull the controller image from an internal registry or to raise the memory limit of the controller, keep the changes in a Kustomize overlay rather than editing the downloaded file. An upgrade then only replaces the manifest, and the changes carry over to the new version. Kustomize is built into kubectl.
Put the downloaded manifest in a directory, together with these two files:
runner-controller/├── kustomization.yaml├── manager-patch.yaml└── runner-controller-v<version>-install.yamlapiVersion: kustomize.config.k8s.io/v1beta1kind: Kustomizationresources: - runner-controller-v<version>-install.yamlimages: - name: commitgo/runner-controller newName: <internal registry>/runner-controller # without a tagpatches: - path: manager-patch.yamlapiVersion: apps/v1kind: Deploymentmetadata: name: runner-controller-controller-manager namespace: runner-controller-systemspec: template: spec: imagePullSecrets: - name: registry-credentials containers: - name: manager resources: limits: memory: 512MiThe Secret with the registry credentials must be in the namespace runner-controller-system, with the name given in imagePullSecrets of the patch. If the registry needs no credentials, leave imagePullSecrets out of the patch and skip the step below. Otherwise, create the namespace and the Secret before the first install:
# --save-config lets kubectl apply take over the namespace without a warningkubectl create namespace runner-controller-system --save-configkubectl -n runner-controller-system create secret docker-registry registry-credentials \ --docker-server=<internal registry> \ --docker-username=<user name> \ --docker-password=<password>Then apply the directory instead of the file:
kubectl apply -k runner-controller/kubectl -n runner-controller-system rollout status deploy/runner-controller-controller-managerimagesreplaces the name of the controller image and keeps the tag of the manifest, so the tag follows the version. Do not setnewTag, and mirror the image of a new version before upgrading to it.- The credentials in the patch only pull the controller image, and runner pods and job pods do not use them. Images of air-gapped clusters lists where the credentials of each image go.
- The patch is merged into the Deployment of the manifest. Fields it does not set, such as the CPU limit and the requests, keep the values of the manifest.
kubectl kustomize runner-controller/prints the result without applying it.- If a new version renames the Deployment,
kubectl apply -kfails withno resource matches strategic merge patchrather than skipping the patch. Update the patch to the new manifest.
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.