You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/index.md
+8-7
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ A pertinent question may arise: why not opt for Kubernetes? The current strategy
15
15
16
16
## Overview
17
17
18
-
The module is designed to be used in a GitHub organization. It can also be used in a GitHub repository, but this not supports all features. The module is receiving GitHub webhook events for the `workflow_job` event. The module will create a new runner if the event is for a workflow that requires a runner, and no runner is available. Alteratively the module can be configured as ephemeral runners. In this case the module will create a new runner for each workflow job event.
18
+
The module is designed to be used in a GitHub organization. It can also be used in a GitHub repository, but this does not supports all features. The module is receiving GitHub webhook events for the `workflow_job` event. The module will create a new runner if the event is for a workflow that requires a runner, and no runner is available. Alternatively the module can be configured as ephemeral runners. In this case the module will create a new runner for each workflow job event.
19
19
20
20
For ephemeral runners a pool is can be configured. The pool maintains a minimum number of runners based on a schedule. The pool works only for org level runners.
21
21
@@ -46,7 +46,7 @@ The "Scale Up Runner" Lambda actively monitors the SQS queue, processing incomin
46
46
47
47
The Lambda first requests a JIT configuration or registration token from GitHub, which is needed later by the runner to register itself. This avoids the case that the EC2 instance, which later in the process will install the agent, needs administration permissions to register the runner. Next, the EC2 spot instance is created via the launch template. The launch template defines the specifications of the required instance and contains a [`user_data`](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) script. This script will install the required software and configure it. The configuration for the runner is shared via EC2 tags and the parameter store (SSM), from which the user data script will fetch it and delete it once it has been retrieved. Once the user data script is finished, the action runner should be online, and the workflow will start in seconds.
48
48
49
-
The current method for scaling down runners employs a straightforward approach: at predefined intervals, the Lambda conducts a thorough examination of each runner (instance) to assess its activity. If a runner is found to be idle, it is deregistered from GitHub, and the associated AWS instance is terminated. For ephemeral runners the the instance is terminated immediately after the workflow is finished. Instances not registered in GitHub as a runner after a minimal boot time will be marked orphan and removed in a next cycle. To avoid orphaned runners the scale down lambda is active in this cae as well.
49
+
The current method for scaling down runners employs a straightforward approach: at predefined intervals, the Lambda conducts a thorough examination of each runner (instance) to assess its activity. If a runner is found to be idle, it is deregistered from GitHub, and the associated AWS instance is terminated. For ephemeral runners the instance is terminated immediately after the workflow is finished. Instances not registered in GitHub as a runner after a minimal boot time will be marked orphan and removed in a next cycle. To avoid orphaned runners the scale down lambda is active in this case as well.
50
50
51
51
### Pool
52
52
@@ -79,18 +79,19 @@ The Instance Termination Watcher is creating log and optional metrics for termin
79
79
80
80
This feature is Beta, changes will not trigger a major release as long in beta.
81
81
82
-
The Job Retry will allow you to retry scaling when a job is not started. When enabled the scale up lambda will send a retry message to the a SQS queue. The job retry lambda will check after a delay if the job is still queued. And if so it will send a retry command de the scale up lambda via SQS. The feature is designed to be used with ephemeral runners. The feature is opt in, it will not be created by default.
82
+
The Job Retry will allow you to retry scaling when a job is not started. When enabled the scale up lambda will send a retry message to the a SQS queue. The Job Retry lambda will check after a delay if the job is still queued, and if so, it will send a retry command to the scale up lambda via SQS. The feature is designed to be used with ephemeral runners. The feature is opt in, it will not be created by default.
83
83
84
84
Consequences of enabling the feature are:
85
+
85
86
- Increase of calls to the GitHub API, could cause reaching the rate limit.
86
-
- Could create new instance when job are not started caused by other failures, resulting in more costs and useless instance creation.
87
+
- Could create new instance when jobs are not started caused by other failures, resulting in more costs and useless instance creation.
87
88
88
89
89
90
### Security
90
91
91
-
Sensitive information such as secrets and private keys is stored securely in the SSM Parameter Store. These values undergo encryption using either the default KMS key for SSM or a custom KMS key, depending on the specified configuration.
92
+
Sensitive information such as secrets and private keys are stored securely in the SSM Parameter Store. These values undergo encryption using either the default KMS key for SSM or a custom KMS key, depending on the specified configuration.
92
93
93
-
Permission are managed in several places. Below are the most important ones. For details check the Terraform sources.
94
+
Permissions are managed in several places. Below are the most important ones. For details check the Terraform sources.
94
95
95
96
- The GitHub App requires access to actions and to publish `workflow_job` events to the AWS webhook (API gateway).
96
97
- The scale up lambda should have access to EC2 for creating and tagging instances.
@@ -112,5 +113,5 @@ Both modules are built on top of the same base modules. When using the multi-run
112
113
The module contains a lot of configuration options. The default values are a good starting point. But you may want to tweak some of the values. Below are some recommendations. We suggest the following configuration for the runners:
113
114
114
115
- Use the multi-runner module to create multiple runners in one go.
115
-
- Use the ephemeral runners for org level runners. To improve the security of your runners.
116
+
- Use the ephemeral runners for org level runners to improve the security of your runners.
116
117
- Use pre-built AMIs to speed up the startup of your runners.
| <aname="input_ami_name_filter"></a> [ami\_name\_filter](#input\_ami\_name\_filter)| AMI name filter for the action runner AMI. By default amazon linux 2 is used. |`string`|`"github-runner-al2023-x86_64-*"`| no |
95
-
| <aname="input_github_app"></a> [github\_app](#input\_github\_app)| GitHub for API usages. | <pre>object({<br> id = string<br> key_base64 = string<br> })</pre> | n/a | yes |
95
+
| <aname="input_github_app"></a> [github\_app](#input\_github\_app)| GitHub for API usages. | <pre>object({<br/> id = string<br/> key_base64 = string<br/> })</pre> | n/a | yes |
96
96
| <aname="input_runner_os"></a> [runner\_os](#input\_runner\_os)| The EC2 Operating System type to use for action runner instances (linux,windows). |`string`|`"linux"`| no |
0 commit comments