This controller operates self-hosted runners for GitHub Actions on your Kubernetes cluster.
GitHub Actions is very useful as a tool for automating development. GitHub Actions job is run in the cloud by default, but you may want to run your jobs in your environment. Self-hosted runner can be used for such use cases, but requires the provision of a virtual machine instance and configuration. If you already have a Kubernetes cluster, you'll want to run the self-hosted runner on top of it.
actions-runner-controller makes that possible. Just create a Runner resource on your Kubernetes, and it will run and operate the self-hosted runner of the specified repository. Combined with Kubernetes RBAC, you can also build simple Self-hosted runners as a Service.
First, install actions-runner-controller with a manifest file. This will create a actions-runner-system namespace in your Kubernetes and deploy the required resources.
$ kubectl apply -f https://github.com/chenrui333/actions-runner-controller/releases/latest/download/actions-runner-controller.yaml
Next, set up a GitHub App or personal access token for actions-runner-controller to access the GitHub API.
You can create a GitHub App for either your account or any organization. If you want to create a GitHub App for your account, open the following link to the creation page, enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page.
If you want to create a GitHub App for your organization, replace the :org
part of the following URL with your organization name before opening it. Then enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page to create a GitHub App.
You will see an App ID on the page of the GitHub App you created as follows, the value of this App ID will be used later.
Download the private key file by pushing the "Generate a private key" button at the bottom of the GitHub App page. This file will also be used later.
Go to the "Install App" tab on the left side of the page and install the GitHub App that you created for your account or organization.
When the installation is complete, you will be taken to a URL in one of the following formats, the last number of the URL will be used as the Installation ID later (For example, if the URL ends in settings/installations/12345
, then the Installation ID is 12345
).
https://github.com/settings/installations/${INSTALLATION_ID}
https://github.com/organizations/eventreactor/settings/installations/${INSTALLATION_ID}
Finally, register the App ID (APP_ID
), Installation ID (INSTALLATION_ID
), and downloaded private key file (PRIVATE_KEY_FILE_PATH
) to Kubernetes as Secret.
$ kubectl create secret generic controller-manager \
-n actions-runner-system \
--from-literal=github_app_id=${APP_ID} \
--from-literal=github_app_installation_id=${INSTALLATION_ID} \
--from-file=github_app_private_key=${PRIVATE_KEY_FILE_PATH}
Next, from an account that has admin
privileges for the repository, create a personal access token with repo
scope. This token is used to register a self-hosted runner by actions-runner-controller.
To use a Personal Access Token, you must issue the token with an account that has admin
privileges.
Open the Create Token page from the following link, grant the repo
scope, and press the "Generate Token" button at the bottom of the page to create the token.
Register the created token (GITHUB_TOKEN
) as a Kubernetes secret.
$ kubectl create secret generic controller-manager \
-n actions-runner-system \
--from-literal=github_token=${GITHUB_TOKEN}
There's generally two ways to use this controller:
- Manage runners one by one with
Runner
- Manage a set of runners with
RunnerDeployment
To launch a single Self-hosted runner, you need to create a manifest file includes Runner resource as follows. This example launches a self-hosted runner with name example-runner for the chenrui333/actions-runner-controller repository.
# runner.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: Runner
metadata:
name: example-runner
spec:
repository: chenrui333/actions-runner-controller
env: []
Apply the created manifest file to your Kubernetes.
$ kubectl apply -f runner.yaml
runner.actions.summerwind.dev/example-runner created
You can see that the Runner resource has been created.
$ kubectl get runners
NAME REPOSITORY STATUS
example-runner summerwind/actions-runner-controller Running
You can also see that the runner pod has been running.
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
example-runner 2/2 Running 0 1m
The runner you created has been registered to your repository.
Now your can use your self-hosted runner. See the official documentation on how to run a job with it.
There's also RunnerReplicaSet
and RunnerDeployment
that corresponds to ReplicaSet
and Deployment
but for Runner
.
You usually need only RunnerDeployment
rather than RunnerReplicaSet
as the former is for managing the latter.
# runnerdeployment.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
name: example-runnerdeploy
spec:
replicas: 2
template:
spec:
repository: chenrui333/actions-runner-controller
env: []
Apply the manifest file to your cluster:
$ kubectl apply -f runner.yaml
runnerdeployment.actions.summerwind.dev/example-runnerdeploy created
You can see that 2 runners has been created as specified by replicas: 2
:
$ kubectl get runners
NAME REPOSITORY STATUS
NAME REPOSITORY STATUS
example-runnerdeploy2475h595fr mumoshu/actions-runner-controller-ci Running
example-runnerdeploy2475ht2qbr mumoshu/actions-runner-controller-ci Running