actions/actions-runner-controller
1
0
Fork 0
mirror of https://github.com/actions/actions-runner-controller.git synced 2025-12-10 19:50:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Restructure documentation (#2114)

Browse Source 
Breaks up the ARC documentation into several smaller articles. 

`@vijay-train` and `@martin389` put together the plan for this update, and I've just followed it here. 

In these updates:

- The README has been updated to include more general project information, and link to each new article.
- The `detailed-docs.md` file has been broken up into multiple articles, and then deleted.
- The Actions Runner Controller Overview doc has been renamed to `about-arc.md`.

Any edits to content beyond generally renaming headers or fixing typos is out of scope for this PR, but will be made in the future. 

Co-authored-by: Bassem Dghaidi <568794+Link-@users.noreply.github.com>
This commit is contained in:
Siara
2023-01-05 01:47:52 -08:00
committed by GitHub
parent 84104de74b
commit 3ede9b5a01
17 changed files with 2059 additions and 2071 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/using-arc-across-organizations.md Normal file
View File

@@ -0,0 +1,61 @@
# Using ARC across organizations
## Multitenancy
> This feature requires controller version => [v0.26.0](https://github.com/actions/actions-runner-controller/releases/tag/v0.26.0)
In a large enterprise, there might be many GitHub organizations that requires self-hosted runners. Previously, the only way to provide ARC-managed self-hosted runners in such environment was [Deploying Multiple Controllers](#deploying-multiple-controllers), which incurs overhead due to it requires one ARC installation per GitHub organization.
With multitenancy, you can let ARC manage self-hosted runners across organizations. It's enabled by default and the only thing you need to start using it is to set the `spec.githubAPICredentialsFrom.secretRef.name` fields for the following resources:
- `HorizontalRunnerAutoscaler`
- `RunnerSet`
Or `spec.template.spec.githubAPICredentialsFrom.secretRef.name` field for the following resource:
- `RunnerDeployment`
> Although not explained above, `spec.githubAPICredentialsFrom` fields do exist in `Runner` and `RunnerReplicaSet`. A comparable pod annotation exists for the runner pod, too.
> However, note that `Runner`, `RunnerReplicaSet` and runner pods are implementation details and are managed by `RunnerDeployment` and ARC.
> Usually you don't need to manually set the fields for those resources.
`githubAPICredentialsFrom.secretRef.name` should refer to the name of the Kubernetes secret that contains either PAT or GitHub App credentials that is used for GitHub API calls for the said resource.
Usually, you should have a set of GitHub App credentials per a GitHub organization and you would have a RunnerDeployment and a HorizontalRunnerAutoscaler per an organization runner group. So, you might end up having the following resources for each organization:
- 1 Kubernetes secret that contains GitHub App credentials
- 1 RunnerDeployment/RunnerSet and 1 HorizontalRunnerAutoscaler per Runner Group
And the RunnerDeployment/RunnerSet and HorizontalRunnerAutoscaler should have the same value for `spec.githubAPICredentialsFrom.secretRef.name`, which refers to the name of the Kubernetes secret.
```yaml
kind: Secret
data:
github_app_id: ...
github_app_installation_id: ...
github_app_private_key: ...
---
kind: RunnerDeployment
metadata:
namespace: org1-runners
spec:
template:
spec:
githubAPICredentialsFrom:
secretRef:
name: org1-github-app
---
kind: HorizontalRunnerAutoscaler
metadata:
namespace: org1-runners
spec:
githubAPICredentialsFrom:
secretRef:
name: org1-github-app
```
> Do note that, as shown in the above example, you usually set the same secret name to `githubAPICredentialsFrom.secretRef.name` fields of both `RunnerDeployment` and `HorizontalRunnerAutoscaler`, so that GitHub API calls for the same set of runners shares the specified credentials, regardless of
when and which varying ARC component(`horizontalrunnerautoscaler-controller`, `runnerdeployment-controller`, `runnerreplicaset-controller`, `runner-controller` or `runnerpod-controller`) makes specific API calls.
> Just don't be surprised you have to repeat `githubAPICredentialsFrom.secretRef.name` settings among two resources!
Please refer to [Deploying Using GitHub App Authentication](#deploying-using-github-app-authentication) for how you could create the Kubernetes secret containing GitHub App credentials.