Improve readme
This commit is contained in:
Varun Priolkar
GitHub
parent
427cc506e1
commit
6997cc97c6
64
README.md
64
README.md
|
|
@ -4,19 +4,26 @@ This controller operates self-hosted runners for GitHub Actions on your Kubernet
|
||||||
|
|
||||||
## Motivation
|
## Motivation
|
||||||
|
|
||||||
[GitHub Actions](https://github.com/features/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](https://github.com/actions/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.
|
[GitHub Actions](https://github.com/features/actions) is a very useful tool for automating development. GitHub Actions jobs are run in the cloud by default, but you may want to run your jobs in your environment. [Self-hosted runner](https://github.com/actions/runner) can be used for such use cases, but requires the provisioning and configuration of a virtual machine instance. Instead if you already have a Kubernetes cluster, it makes more sense 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.
|
*actions-runner-controller* makes that possible. Just create a *Runner* resource on your Kubernetes, and it will run and operate the self-hosted runner for the specified repository. Combined with Kubernetes RBAC, you can also build simple Self-hosted runners as a Service.
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
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.
|
First, install *actions-runner-controller* with a manifest file. This will create *actions-runner-system* namespace in your Kubernetes and deploy the required resources.
|
||||||
|
|
||||||
```
|
```
|
||||||
$ kubectl apply -f https://github.com/summerwind/actions-runner-controller/releases/latest/download/actions-runner-controller.yaml
|
$ kubectl apply -f https://github.com/summerwind/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.
|
## Setting up authentication with GitHub API
|
||||||
|
|
||||||
|
There are two ways for _actions-runner-controller_ to authenticate with the the GitHub API:
|
||||||
|
|
||||||
|
1. Using GitHub App.
|
||||||
|
2. Using Personal Access Token.
|
||||||
|
|
||||||
|
**NOTE: It is extremely important to only follow one of the sections below and not both.**
|
||||||
|
|
||||||
### Using GitHub App
|
### Using GitHub App
|
||||||
|
|
||||||
|
|
@ -55,9 +62,9 @@ $ kubectl create secret generic controller-manager \
|
||||||
--from-file=github_app_private_key=${PRIVATE_KEY_FILE_PATH}
|
--from-file=github_app_private_key=${PRIVATE_KEY_FILE_PATH}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using personal access token
|
### Using Personal Access Token
|
||||||
|
|
||||||
Next, from an account that has `admin` privileges for the repository, create a [personal access token](https://github.com/settings/tokens) with `repo` scope. This token is used to register a self-hosted runner by *actions-runner-controller*.
|
From an account that has `admin` privileges for the repository, create a [personal access token](https://github.com/settings/tokens) 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.
|
To use a Personal Access Token, you must issue the token with an account that has `admin` privileges.
|
||||||
|
|
||||||
|
|
@ -75,14 +82,14 @@ $ kubectl create secret generic controller-manager \
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
There's generally two ways to use this controller:
|
There are two ways to use this controller:
|
||||||
|
|
||||||
- Manage runners one by one with `Runner`
|
- Manage runners one by one with `Runner`.
|
||||||
- Manage a set of runners with `RunnerDeployment`
|
- Manage a set of runners with `RunnerDeployment`.
|
||||||
|
|
||||||
### Runners
|
### Runners
|
||||||
|
|
||||||
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 *summerwind/actions-runner-controller* repository.
|
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 *summerwind/actions-runner-controller* repository.
|
||||||
|
|
||||||
```
|
```
|
||||||
# runner.yaml
|
# runner.yaml
|
||||||
|
|
@ -126,7 +133,7 @@ Now your can use your self-hosted runner. See the [official documentation](https
|
||||||
|
|
||||||
### RunnerDeployments
|
### RunnerDeployments
|
||||||
|
|
||||||
There's also `RunnerReplicaSet` and `RunnerDeployment` that corresponds to `ReplicaSet` and `Deployment` but for `Runner`.
|
There are `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.
|
You usually need only `RunnerDeployment` rather than `RunnerReplicaSet` as the former is for managing the latter.
|
||||||
|
|
||||||
|
|
@ -151,7 +158,7 @@ $ kubectl apply -f runner.yaml
|
||||||
runnerdeployment.actions.summerwind.dev/example-runnerdeploy created
|
runnerdeployment.actions.summerwind.dev/example-runnerdeploy created
|
||||||
```
|
```
|
||||||
|
|
||||||
You can see that 2 runners has been created as specified by `replicas: 2`:
|
You can see that 2 runners have been created as specified by `replicas: 2`:
|
||||||
|
|
||||||
```
|
```
|
||||||
$ kubectl get runners
|
$ kubectl get runners
|
||||||
|
|
@ -160,3 +167,36 @@ NAME REPOSITORY STATUS
|
||||||
example-runnerdeploy2475h595fr mumoshu/actions-runner-controller-ci Running
|
example-runnerdeploy2475h595fr mumoshu/actions-runner-controller-ci Running
|
||||||
example-runnerdeploy2475ht2qbr mumoshu/actions-runner-controller-ci Running
|
example-runnerdeploy2475ht2qbr mumoshu/actions-runner-controller-ci Running
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Additional tweaks
|
||||||
|
|
||||||
|
You can pass details through the spec selector. Here's an eg. of what you may like to do:
|
||||||
|
|
||||||
|
```
|
||||||
|
nodeSelector:
|
||||||
|
node-role.kubernetes.io/test: ""
|
||||||
|
|
||||||
|
tolerations:
|
||||||
|
- effect: NoSchedule
|
||||||
|
key: node-role.kubernetes.io/test
|
||||||
|
operator: Exists
|
||||||
|
|
||||||
|
repository: mumoshu/actions-runner-controller-ci
|
||||||
|
ImagePullPolicy: Always
|
||||||
|
image: custom-image/actions-runner:latest
|
||||||
|
resources:
|
||||||
|
limits:
|
||||||
|
cpu: "4.0"
|
||||||
|
memory: "8Gi"
|
||||||
|
requests:
|
||||||
|
cpu: "2.0"
|
||||||
|
memory: "4Gi"
|
||||||
|
sidecarContainers:
|
||||||
|
- name: mysql
|
||||||
|
image: mysql:5.7
|
||||||
|
env:
|
||||||
|
- name: MYSQL_ROOT_PASSWORD
|
||||||
|
value: abcd1234
|
||||||
|
securityContext:
|
||||||
|
runAsUser: 0
|
||||||
|
```
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue