docs: adding docs for the chart values (#608)
* docs: adding docs for the chart values * docs: updating the main docs * docs: grammar fixes * docs: updating proxy default Co-authored-by: Callum James Tait <callum.tait@photobox.com>
This commit is contained in:
toast-gear
GitHub
parent
552ee28072
commit
aa7d4c5ecc
28
README.md
28
README.md
|
|
@ -31,8 +31,6 @@ ToC:
|
||||||
- [Common Errors](#common-errors)
|
- [Common Errors](#common-errors)
|
||||||
- [Contributing](#contributing)
|
- [Contributing](#contributing)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Motivation
|
## Motivation
|
||||||
|
|
||||||
[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.
|
[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.
|
||||||
|
|
@ -47,14 +45,16 @@ actions-runner-controller uses [cert-manager](https://cert-manager.io/docs/insta
|
||||||
|
|
||||||
Install the custom resource and actions-runner-controller with `kubectl` or `helm`. This will create actions-runner-system namespace in your Kubernetes and deploy the required resources.
|
Install the custom resource and actions-runner-controller with `kubectl` or `helm`. This will create actions-runner-system namespace in your Kubernetes and deploy the required resources.
|
||||||
|
|
||||||
`kubectl`:
|
**Kubectl Deployment:**
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
# REPLACE "v0.18.2" with the version you wish to deploy
|
# REPLACE "v0.18.2" with the version you wish to deploy
|
||||||
kubectl apply -f https://github.com/actions-runner-controller/actions-runner-controller/releases/download/v0.18.2/actions-runner-controller.yaml
|
kubectl apply -f https://github.com/actions-runner-controller/actions-runner-controller/releases/download/v0.18.2/actions-runner-controller.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
`helm`:
|
**Helm Deployment:**
|
||||||
|
|
||||||
|
__**Note: For all configuration options for the Helm chart see the chart's [README](./charts/actions-runner-controller/README.md)
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
|
helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
|
||||||
|
|
@ -93,14 +93,14 @@ You can create a GitHub App for either your user account or any organization, be
|
||||||
|
|
||||||
_Note: Links are provided further down to create an app for your logged in user account or an organisation with the permissions for all runner types set in each link's query string_
|
_Note: Links are provided further down to create an app for your logged in user account or an organisation with the permissions for all runner types set in each link's query string_
|
||||||
|
|
||||||
**Required Permissions for Repository Runners**<br />
|
**Required Permissions for Repository Runners:**<br />
|
||||||
**Repository Permissions**
|
**Repository Permissions**
|
||||||
|
|
||||||
* Actions (read)
|
* Actions (read)
|
||||||
* Administration (read / write)
|
* Administration (read / write)
|
||||||
* Metadata (read)
|
* Metadata (read)
|
||||||
|
|
||||||
**Required Permissions for Organisation Runners**<br />
|
**Required Permissions for Organisation Runners:**<br />
|
||||||
**Repository Permissions**
|
**Repository Permissions**
|
||||||
|
|
||||||
* Actions (read)
|
* Actions (read)
|
||||||
|
|
@ -143,6 +143,8 @@ When the installation is complete, you will be taken to a URL in one of the foll
|
||||||
|
|
||||||
Finally, register the App ID (`APP_ID`), Installation ID (`INSTALLATION_ID`), and downloaded private key file (`PRIVATE_KEY_FILE_PATH`) to Kubernetes as Secret.
|
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 Deployment:**
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
$ kubectl create secret generic controller-manager \
|
$ kubectl create secret generic controller-manager \
|
||||||
-n actions-runner-system \
|
-n actions-runner-system \
|
||||||
|
|
@ -151,6 +153,10 @@ $ 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}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Helm Deployment:**
|
||||||
|
|
||||||
|
Configure your values.yaml, see the chart's [README](./charts/actions-runner-controller/README.md) for deploying the secret via Helm
|
||||||
|
|
||||||
### Deploying Using PAT Authentication
|
### Deploying Using PAT Authentication
|
||||||
|
|
||||||
Personal Access Tokens can be used to register a self-hosted runner by *actions-runner-controller*.
|
Personal Access Tokens can be used to register a self-hosted runner by *actions-runner-controller*.
|
||||||
|
|
@ -175,18 +181,24 @@ Log-in to a GitHub account that has `admin` privileges for the repository, and [
|
||||||
|
|
||||||
* enterprise:admin (Full control)
|
* enterprise:admin (Full control)
|
||||||
|
|
||||||
_Note: when you deploy enterprise runners they will get access to organisations, however, access to the repositories themselves is **NOT** allowed by default. Each GitHub organisation must allow enterprise runner groups to be used in repositories as an initial one time configuration step, this only needs to be done once after which it is permanent for that runner group._
|
_Note: When you deploy enterprise runners they will get access to organisations, however, access to the repositories themselves is **NOT** allowed by default. Each GitHub organisation must allow enterprise runner groups to be used in repositories as an initial one time configuration step, this only needs to be done once after which it is permanent for that runner group._
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Once you have created the appropriate token, deploy it as a secret to your Kubernetes cluster that you are going to deploy the solution on:
|
Once you have created the appropriate token, deploy it as a secret to your Kubernetes cluster that you are going to deploy the solution on:
|
||||||
|
|
||||||
|
**Kubectl Deployment:**
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
kubectl create secret generic controller-manager \
|
kubectl create secret generic controller-manager \
|
||||||
-n actions-runner-system \
|
-n actions-runner-system \
|
||||||
--from-literal=github_token=${GITHUB_TOKEN}
|
--from-literal=github_token=${GITHUB_TOKEN}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Helm Deployment:**
|
||||||
|
|
||||||
|
Configure your values.yaml, see the chart's [README](./charts/actions-runner-controller/README.md) for deploying the secret via Helm
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
[GitHub self-hosted runners can be deployed at various levels in a management hierarchy](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#about-self-hosted-runners):
|
[GitHub self-hosted runners can be deployed at various levels in a management hierarchy](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#about-self-hosted-runners):
|
||||||
|
|
@ -353,7 +365,6 @@ With this scaling metric we are required to define a list of repositories within
|
||||||
The scale out performance is controlled via the manager containers startup `--sync-period` argument. The default value is set to 10 minutes to prevent default deployments rate limiting themselves from the GitHub API.
|
The scale out performance is controlled via the manager containers startup `--sync-period` argument. The default value is set to 10 minutes to prevent default deployments rate limiting themselves from the GitHub API.
|
||||||
|
|
||||||
**Kustomize Config :** The period can be customised in the `config/default/manager_auth_proxy_patch.yaml` patch<br />
|
**Kustomize Config :** The period can be customised in the `config/default/manager_auth_proxy_patch.yaml` patch<br />
|
||||||
**Helm Config :** `syncPeriod`
|
|
||||||
|
|
||||||
**Benefits of this metric**
|
**Benefits of this metric**
|
||||||
1. Supports named repositories allowing you to restrict the runner to a specified set of repositories server side.
|
1. Supports named repositories allowing you to restrict the runner to a specified set of repositories server side.
|
||||||
|
|
@ -409,7 +420,6 @@ spec:
|
||||||
The `HorizontalRunnerAutoscaler` will poll GitHub based on the configuration sync period for the number of busy runners which live in the RunnerDeployment's namespace and scale based on the settings
|
The `HorizontalRunnerAutoscaler` will poll GitHub based on the configuration sync period for the number of busy runners which live in the RunnerDeployment's namespace and scale based on the settings
|
||||||
|
|
||||||
**Kustomize Config :** The period can be customised in the `config/default/manager_auth_proxy_patch.yaml` patch<br />
|
**Kustomize Config :** The period can be customised in the `config/default/manager_auth_proxy_patch.yaml` patch<br />
|
||||||
**Helm Config :** `syncPeriod`
|
|
||||||
|
|
||||||
**Benefits of this metric**
|
**Benefits of this metric**
|
||||||
1. Supports named repositories server side the same as the `TotalNumberOfQueuedAndInProgressWorkflowRuns` metric [#313](https://github.com/actions-runner-controller/actions-runner-controller/pull/313)
|
1. Supports named repositories server side the same as the `TotalNumberOfQueuedAndInProgressWorkflowRuns` metric [#313](https://github.com/actions-runner-controller/actions-runner-controller/pull/313)
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
## Docs
|
||||||
|
|
||||||
|
All additional docs are kept in the `docs/` folder, this README is solely for documenting the values.yaml keys and values
|
||||||
|
|
||||||
|
## Values
|
||||||
|
|
||||||
|
_The values are documented as of HEAD_
|
||||||
|
|
||||||
|
_Default values are the defaults set in the charts values.yaml, some properties have default configurations in the code for when the property is omitted or invalid_
|
||||||
|
|
||||||
|
| Key | Description | Default |
|
||||||
|
|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
|
||||||
|
| `labels` | Set labels to apply to all resources in the chart | |
|
||||||
|
| `replicaCount` | Set the number of controller pods | 1 |
|
||||||
|
| `syncPeriod` | Set the period in which the controler reconciles the desired runners count | 10m |
|
||||||
|
| `githubAPICacheDuration` | Set the cache period for API calls | |
|
||||||
|
| `logLevel` | Set the log level of the controller container | |
|
||||||
|
| `authSecret.create` | Deploy the controller auth secret | true |
|
||||||
|
| `authSecret.name` | Set the name of the auth secret | controller-manager |
|
||||||
|
| `authSecret.github_app_id` | The ID of your GitHub App. **This can't be set at the same time as `authSecret.github_token`** | |
|
||||||
|
| `authSecret.github_app_installation_id` | The ID of your GitHub App installation. **This can't be set at the same time as `authSecret.github_token`** | |
|
||||||
|
| `authSecret.github_app_private_key` | The multiline string of your GitHub App's private key. **This can't be set at the same time as `authSecret.github_token`** | |
|
||||||
|
| `authSecret.github_token` | Your chosen GitHub PAT token. **This can't be set at the same time as the `authSecret.github_app_*`** | |
|
||||||
|
| `image.repository` | The "repository/image" of the controller container | summerwind/actions-runner-controller |
|
||||||
|
| `image.tag` | The tag of the controller container | |
|
||||||
|
| `image.dindSidecarRepositoryAndTag` | The "repository/image" of the dind sidecar container | docker:dind |
|
||||||
|
| `image.pullPolicy` | The pull policy of the controller image | IfNotPresent |
|
||||||
|
| `metrics.serviceMonitor` | Deploy serviceMonitor kind for for use with prometheus-operator CRDs | false |
|
||||||
|
| `metrics.port` | Set port of metrics service | 8443 |
|
||||||
|
| `metrics.proxy.enabled` | Deploy kube-rbac-proxy container in controller pod | true |
|
||||||
|
| `metrics.proxy.image.repository` | The "repository/image" of the kube-proxy container | quay.io/brancz/kube-rbac-proxy |
|
||||||
|
| `metrics.proxy.image.tag` | The tag of the kube-proxy image to use when pulling the container | v0.10.0 |
|
||||||
|
| `imagePullSecrets` | Specifies the secret to be used when pulling the controller pod containers | |
|
||||||
|
| `fullNameOverride` | Override the full resource names | |
|
||||||
|
| `nameOverride` | Override the resource name prefix | |
|
||||||
|
| `serviceAccont.annotations` | Set annotations to the service account | |
|
||||||
|
| `serviceAccount.create` | Deploy the controller pod under a service account | true |
|
||||||
|
| `podAnnotations` | Set annotations for the controller pod | |
|
||||||
|
| `podLabels` | Set labels for the controller pod | |
|
||||||
|
| `serviceAccount.name` | Set the name of the service account | |
|
||||||
|
| `securityContext` | Set the security context for each container in the controller pod | |
|
||||||
|
| `podSecurityContext` | Set the security context to controller pod | |
|
||||||
|
| `service.port` | Set controller service type | |
|
||||||
|
| `service.type` | Set controller service ports | |
|
||||||
|
| `topologySpreadConstraints` | Set the controller pod topologySpreadConstraints | |
|
||||||
|
| `nodeSelector` | Set the controller pod nodeSelector | |
|
||||||
|
| `resources` | Set the controller pod resources | |
|
||||||
|
| `affinity` | Set the controller pod affinity rules | |
|
||||||
|
| `tolerations` | Set the controller pod tolerations | |
|
||||||
|
| `env` | Set environment variables for the controller container | |
|
||||||
|
| `priorityClassName` | Set the controller pod priorityClassName | |
|
||||||
|
| `scope.watchNamespace` | Tells the controller which namespace to watch if `scope.singleNamespace` is true | |
|
||||||
|
| `scope.singleNamespace` | Limit the controller to watch a single namespace | false |
|
||||||
|
| `githubWebhookServer.logLevel` | Set the log level of the githubWebhookServer container | |
|
||||||
|
| `githubWebhookServer.replicaCount` | Set the number of webhook server pods | 1 |
|
||||||
|
| `githubWebhookServer.enabled` | Deploy the webhook server pod | false |
|
||||||
|
| `githubWebhookServer.secret.create` | Deploy the webhook hook secret | true |
|
||||||
|
| `githubWebhookServer.secret.name` | Set the name of the webhook hook secret | github-webhook-server |
|
||||||
|
| `githubWebhookServer.secret.github_webhook_secret_token` | Set the webhook secret token value | |
|
||||||
|
| `githubWebhookServer.imagePullSecrets` | Specifies the secret to be used when pulling the githubWebhookServer pod containers | |
|
||||||
|
| `githubWebhookServer.nameOveride` | Override the resource name prefix | |
|
||||||
|
| `githubWebhookServer.fullNameOveride` | Override the full resource names | |
|
||||||
|
| `githubWebhookServer.serviceAccount.create` | Deploy the githubWebhookServer under a service account | true |
|
||||||
|
| `githubWebhookServer.serviceAccount.annotations` | Set annotations for the service account | |
|
||||||
|
| `githubWebhookServer.serviceAccount.name` | Set the service account name | |
|
||||||
|
| `githubWebhookServer.podAnnotations` | Set annotations for the githubWebhookServer pod | |
|
||||||
|
| `githubWebhookServer.podLabels` | Set labels for the githubWebhookServer pod | |
|
||||||
|
| `githubWebhookServer.podSecurityContext` | Set the security context to githubWebhookServer pod | |
|
||||||
|
| `githubWebhookServer.securityContext` | Set the security context for each container in the githubWebhookServer pod | |
|
||||||
|
| `githubWebhookServer.resources` | Set the githubWebhookServer pod resources | |
|
||||||
|
| `githubWebhookServer.topologySpreadConstraints` | Set the githubWebhookServer pod topologySpreadConstraints | |
|
||||||
|
| `githubWebhookServer.nodeSelector` | Set the githubWebhookServer pod nodeSelector | |
|
||||||
|
| `githubWebhookServer.tolerations` | Set the githubWebhookServer pod tolerations | |
|
||||||
|
| `githubWebhookServer.affinity` | Set the githubWebhookServer pod affinity rules | |
|
||||||
|
| `githubWebhookServer.priorityClassName` | Set the githubWebhookServer pod priorityClassName | |
|
||||||
|
| `githubWebhookServer.service.type` | Set githubWebhookServer service type | |
|
||||||
|
| `githubWebhookServer.service.ports` | Set githubWebhookServer service ports | `[{"port":80, "targetPort:"http", "protocol":"TCP", "name":"http"}]` |
|
||||||
|
| `githubWebhookServer.ingress.enabled` | Deploy an ingress kind for the githubWebhookServer | false |
|
||||||
|
| `githubWebhookServer.ingress.annotations` | Set annotations for the ingress kind | |
|
||||||
|
| `githubWebhookServer.ingress.hosts` | Set hosts configuration for ingress | `[{"host": "chart-example.local", "paths": []}]` |
|
||||||
|
| `githubWebhookServer.ingress.tls` | Set tls configuration for ingress | |
|
||||||
Loading…
Reference in New Issue