[Doc] Create ARC Overview doc #1707
Conversation
The purpose of this doc is a starting point overview to ARC, with links to Quick start guide within.
Fixed some formatting
Vijay-train
changed the title
Fixed links to include quotes, where missing. Added spaces after periods, where missing.
| ### The Runner container image | ||
| The GitHub hosted runners include a large amount of pre-installed software packages. For complete list, see "[Runner images](https://github.com/actions/virtual-environments/tree/main/images/linux)." | ||
|
|
||
| ARC maintains a few runner images with `latest` aligning with GitHub's Ubuntu version, these images do not contain all of the software installed on the GitHub runners. They contain subset of packages from the GitHub runners: Basic CLI packages, git, docker and build-essentials. |
There was a problem hiding this comment.
JFYI, it's true that our image is intended NOT to include anything that can be installed via setup-* actions. The use ofsetup-* actions for installing additional software on top of the runner container image backed runners is recommended. (Worth mentioning in this sentence? 🤔
There was a problem hiding this comment.
I did mention using the setup actions as the last sentence in this section, but I agree to make it more explicit. Will do so.
| 2) Scaling parameters - `minReplicas` and `maxReplicas` indicates the min and max number of replicas to scale to. | ||
| 3) Scaling metrics - ARC supports two types of scaling metrics. `TotalNumberOfQueuedAndInProgressWorkflowRuns` and `PercentageRunnersBusy`. These indicate the type of scaling to employ. | ||
|
|
||
| The `TotalNumberOfQueuedAndInProgressWorkflowRuns` metric polls GitHub for all pending workflow runs against a given set of repositories. The metric will scale the runner count up to the total number of pending jobs at the sync time up to the `maxReplicas` configuration. |
There was a problem hiding this comment.
The TotalNumberOfQueuedAndInProgressWorkflowRuns metric is half-baked. It doesn't support labels so it won't work correctly on a repository that uses both github-hosted and self-hosted runners. I've seen several folks had troubles due to that and eventually moved to the webhook-based scaling or PercentageRunnersBusy.
Would it still be a good idea to introduce this metric? 🤔
There was a problem hiding this comment.
in that case, it might be better to remove it for now. Will do so.
Updated the following based on PR feedback - `The Runner container image` now calls out more explicitly the recommended way to install additional software - `Scaling runners - dynamically with Pull Driven ScalingScaling runners - dynamically with Pull Driven Scaling` - Removed mentions of `TotalNumberOfQueuedAndInProgressWorkflowRuns` as its not fully implemented
There was a problem hiding this comment.
How are these changes meant to compliment what is in the repository README.md file?
Currently, the main README.md is massive as all features and functionality are documented with most this content is covered in some form or fashion. I could see reorganizing the existing content into smaller, digestible docs to be easier to read and navigate while maintaining linkage.
| ## ARC components | ||
| ARC basically consists of a set of custom resources. An ARC deployment is applying these custom resources onto a K8s cluster. Once applied, it creates a set of Pods, with the Github Actions runner running within them. Github is now able to treat these Pods as self hosted runners and allocate jobs to them. |
There was a problem hiding this comment.
How much about the underlying ARC components from the Helm chart are generally useful for adopters to understand? Are these covered elsewhere in more detail?
There was a problem hiding this comment.
I think some of it might be useful to document in their own sections. We should do so incrementally going forward. We can then link those in this article.
| ### Custom resources | ||
| ARC consists of several custom resource definitions (Runner, Runner Set, Runner Deployment, Runner Replica Set and Horizontal Runner AutoScaler). For more information on CRDs, refer "[Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)." | ||
|
|
||
| The helm command (in the QuickStart guide) installs the custom resources into the actions-runner-system namespace. | ||
| ```code | ||
| helm install -f custom-values.yaml --wait --namespace actions-runner-system \ | ||
| --create-namespace actions-runner-controller \ | ||
| actions-runner-controller/actions-runner-controller | ||
| ``` |
There was a problem hiding this comment.
What is the best way for adopters to review and reference the CRDs' schema?
- Browse the release-specific CRD definitions?
kubectl explainafter they are installed?
There was a problem hiding this comment.
Yes, that could be one way. As we incrementally add additional documentation, we could ( in future) have a section on CRDs and include these details there.
| You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. Your workflow contains one or more jobs which can run in sequential order or in parallel. Each job will run inside its own runner and has one or more steps that either run a script that you define or run an action, which is a reusable extension that can simplify your workflow. To learn more about about Actions - see "[Github Actions](https://docs.github.com/en/actions/learn-github-actions)." | ||
|
|
||
| ## Runners | ||
| Runners execute the job that is assigned to them by Github Actions workflow. There are two types of Runners.. |
There was a problem hiding this comment.
| Runners execute the job that is assigned to them by Github Actions workflow. There are two types of Runners.. | |
| Runners execute the job that is assigned to them by Github Actions workflow. There are two types of Runners. |
There was a problem hiding this comment.
Thanks for the suggestion. Actually fixed this in latest commit by replacing .. with ':`
Incorporated review feedback from @andyfeller, @sethrylan, @debuger24 and @mumoshu. Thank you all. Co-authored-by: Andy Feller <andyfeller@github.com> Co-authored-by: Rahul Kumar <rahulcomp24@gmail.com> Co-authored-by: Seth Rylan Gainey <sethrylan@github.com> Co-authored-by: Yusuke Kuoka <ykuoka@gmail.com>
@andyfeller - Yes, the intent is to incrementally update the README.md with links to the digestible articles (like this one). We will also remove any duplication then. |
Vijay-train
requested review from
mumoshu,
sethrylan and
andyfeller
and removed request for
sethrylan
Vijay-train
requested review from
debugger24
and removed request for
andyfeller
Add more detailed config for PercentageRunnersBusy metric Co-authored-by: Yusuke Kuoka <ykuoka@gmail.com>
There was a problem hiding this comment.
LGTM. Thanks a lot for your efforts and contribution @Vijay-train
|
✨ |
The purpose of this doc is a starting point overview to ARC, with links to Quick start guide within. Users can use this doc to get a high level understanding of ARC with a bit more details than the
QuickStartguide. Note - links toQuickStartguide will be updated once that PR gets merged.README.md will be updated( in a separate PR) with links to this doc post merge.