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
This [Terraform](https://www.terraform.io/) module creates the required infrastructure needed to host [GitHub Actions](https://github.com/features/actions) self hosted, auto scaling runners on [AWS spot instances](https://aws.amazon.com/ec2/spot/). It provides the required logic to handle the life cycle for scaling up and down using a set of AWS Lambda functions. Runners are scaled down to zero to avoid costs when no workflows are active.
7
6
8
7
-[Motivation](#motivation)
@@ -75,32 +74,50 @@ Examples are provided in [the example directory](examples/). Please ensure you h
75
74
- AWS cli (optional)
76
75
- Node and yarn (for lambda development).
77
76
78
-
The module supports two main scenarios for creating runners. On repository level a runner will be dedicated to only one repository, no other repository can use the runner. On organization level you can use the runner(s) for all the repositories within the organization. See https://help.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners for more information. Before starting the deployment you have to choose one option.
77
+
The module supports two main scenarios for creating runners. On repository level a runner will be dedicated to only one repository, no other repository can use the runner. On organization level you can use the runner(s) for all the repositories within the organization. See [GitHub instructions](https://help.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) for more information. Before starting the deployment you have to choose one option.
78
+
79
+
GitHub workflows fail immediately if there is no action runner available for your builds. Since this module supports scaling down to zero, builds will fail in case there is no active runner available. We recommend to create an offline runner with matching labels to the configuration. Create this runner manually by following the [GitHub instructions](https://help.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) for adding a new runner on your local machine. If you stop the process after the step of running the `config.sh` script the runner will remain offline. This offline runner ensures that builds will not fail immediately and stay queued until there is an EC2 runner to pick it up.
80
+
81
+
Another convenient way of deploying this temporary required runner is using following approach. This automates all the manual labor.
GitHub workflows fail immediately if there is no action runner available for your builds. Since this module supports scaling down to zero, builds will fail in case there is no active runner available. We recommend to create an offline runner with matching labels to the configuration. Create this runner manually by following the GitHub instructions for adding a new runner on your local machine. If you stop the process after the step of running the `config.sh` script the runner will remain offline. This offline runner ensures that builds will not fail immediately and stay queued until there is an EC2 runner to pick it up.
97
+
You should stop and remove the container once the runner is registered as the builds would otherwise go to your local Docker container.
81
98
82
99
The setup consists of running Terraform to create all AWS resources and manually configuring the GitHub App. The Terraform module requires configuration from the GitHub App and the GitHub app requires output from Terraform. Therefore you first create the GitHub App and configure the basics, then run Terraform, and afterwards finalize the configuration of the GitHub App.
83
100
84
101
### Setup GitHub App (part 1)
85
102
86
-
Go to GitHub and create a new app. Beware you can create apps your organization or for a user. For now we support only organization level apps.
103
+
Go to GitHub and [create a new app](https://docs.github.com/en/developers/apps/creating-a-github-app). Beware you can create apps your organization or for a user. For now we support only organization level apps.
87
104
88
105
1. Create app in Github
89
106
2. Choose a name
90
107
3. Choose a website (mandatory, not required for the module).
91
108
4. Disable the webhook for now (we will configure this later).
92
109
5. Permissions for all runners:
93
-
- Repository:
94
-
-`Actions`: Read-only (check for queued jobs)
95
-
-`Checks`: Read-only (receive events for new builds)
96
-
-`Metadata`: Read-only (default/required)
110
+
- Repository:
111
+
-`Actions`: Read-only (check for queued jobs)
112
+
-`Checks`: Read-only (receive events for new builds)
9. On the General page, make a note of the "App ID" and "Client ID" parameters.
106
123
10. Create a new client secret and also write it down.
@@ -120,7 +137,7 @@ For local development you can build all the lambdas at once using `.ci/build.sh`
120
137
121
138
#### Service-linked role <!-- omit in toc -->
122
139
123
-
To create spot instances the `AWSServiceRoleForEC2Spot` role needs to be added to your account. You can do that manually by following the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html#service-linked-roles-spot-instance-requests). To use terraform for creating the role, either add the following resource or let the module manage the the service linked role by setting `create_service_linked_role` to `true`. Be aware this is an account global role, so maybe you don't want to mange it via a specific deployment.
140
+
To create spot instances the `AWSServiceRoleForEC2Spot` role needs to be added to your account. You can do that manually by following the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html#service-linked-roles-spot-instance-requests). To use terraform for creating the role, either add the following resource or let the module manage the the service linked role by setting `create_service_linked_role` to `true`. Be aware this is an account global role, so maybe you don't want to manage it via a specific deployment.
124
141
125
142
```hcl
126
143
resource "aws_iam_service_linked_role" "spot" {
@@ -197,7 +214,7 @@ This is the default, no additional configuration is required.
197
214
198
215
You have to create an configure you KMS key. The module will use the context with key: `Environment` and value `var.environment` as encryption context.
199
216
200
-
```HCL
217
+
```hcl
201
218
resource "aws_kms_key" "github" {
202
219
is_enabled = true
203
220
}
@@ -231,7 +248,7 @@ idle_config = [{
231
248
232
249
Cron expressions are parsed by [cron-parser](https://github.com/harrisiirak/cron-parser#readme). The supported syntax.
233
250
234
-
```
251
+
```bash
235
252
******
236
253
┬ ┬ ┬ ┬ ┬ ┬
237
254
│ │ │ │ │ |
@@ -379,7 +396,7 @@ We welcome contribution, please checkout the [contribution guide](CONTRIBUTING.m
379
396
380
397
This module is part of the Philips Forest.
381
398
382
-
```
399
+
```bash
383
400
384
401
___ _
385
402
/ __\__ _ __ ___ ___||_
@@ -394,7 +411,3 @@ This module is part of the Philips Forest.
394
411
Talk to the forestkeepers in the `forest`-channel on Slack.
0 commit comments