Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation confuses Runner Scale Set Controller with Actions Runner Controller #35714

Open
1 task done
Nuru opened this issue Dec 19, 2024 · 4 comments
Open
1 task done
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team needs SME This proposal needs review from a subject matter expert waiting for review Issue/PR is waiting for a writer's review

Comments

@Nuru
Copy link

Nuru commented Dec 19, 2024

Code of Conduct

What article on docs.github.com is affected?

Pretty much everything under actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller.

What part(s) of the article would you like to see updated?

There are numerous references to "Actions Runner Controller" (e.g. About Actions Runner Controller). These references are frequently paired with information that does not apply to the ARC or the runners it controls, leading to massive confusion.

The statement "Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions" is true and correct. However, there is, additionally, a GHA Runner Scale Set Controller (RSSC) which, while it also is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions, operates differently and on a different kind of runner configuration, a Runner Scale Set.

Much of the documentation purportedly about ARC is actually about RSSC and the Runner Scale Sets they control. The RSSC manages Runner Scale Sets, while the ARC manages Runner Deployments and Runner Replica Sets. See About ARC, which is correct, versus About ARC, which is actually about RSSC.

Articles like Using self-hosted runners in a workflow (permalink to source for historical reference after the article is corrected) are ridiculously confusing when they start by saying "Actions Runner Controller does not support multiple labels, only the name of the runner can be used in place of a label" and then go on to explain how to use multiple labels to route jobs. The correct admonition is that RSSCs do not support multiple labels. ARC does continue to support multiple labels.

I would like to see articles that are about the RSSC retitled, and references to ARC that are actually references to RSSC corrected. Since adoption of RSSC is facing stiff resistance, both ARC and RSSC are likely to be actively used for the foreseeable future, and both should be correctly and distinctly documented.

Additional information

This confusion is likely the cause of #34526

@Nuru Nuru added the content This issue or pull request belongs to the Docs Content team label Dec 19, 2024
Copy link

welcome bot commented Dec 19, 2024

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Dec 19, 2024
@Nuru Nuru changed the title Documentation confuses Runner Scale Sets with Actions Runner Controller Documentation confuses Runner Scale Set Controller with Actions Runner Controller Dec 19, 2024
@nguyenalex836 nguyenalex836 added actions This issue or pull request should be reviewed by the docs actions team waiting for review Issue/PR is waiting for a writer's review and removed triage Do not begin working on this issue until triaged by the team labels Dec 19, 2024
@nguyenalex836
Copy link
Contributor

@Nuru Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

@jc-clark jc-clark added the needs SME This proposal needs review from a subject matter expert label Dec 23, 2024
Copy link
Contributor

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

@jc-clark
Copy link
Contributor

Thanks for all this context @Nuru! I just approved the changes you suggested over in #35715. But it sounds like this is also a bigger issue with the rest of the ARC/runner scale set docs.

So we'll surface this for our engineering team to help chime in on the best path forward.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team needs SME This proposal needs review from a subject matter expert waiting for review Issue/PR is waiting for a writer's review
Projects
None yet
Development

No branches or pull requests

4 participants
@Nuru @jc-clark @nguyenalex836 and others