cloudsnorkel.cdk-github-runners 0.18.0__tar.gz → 0.18.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel.cdk_github_runners.egg-info → cloudsnorkel_cdk_github_runners-0.18.2}/PKG-INFO +26 -4
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/README.md +25 -3
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.py +2 -2
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/__init__.py +129 -31
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
- cloudsnorkel_cdk_github_runners-0.18.2/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2/src/cloudsnorkel.cdk_github_runners.egg-info}/PKG-INFO +26 -4
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/SOURCES.txt +1 -1
- cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/LICENSE +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/MANIFEST.in +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/pyproject.toml +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.cfg +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/dependency_links.txt +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/requires.txt +0 -0
- {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: cloudsnorkel.cdk-github-runners
|
|
3
|
-
Version: 0.18.
|
|
3
|
+
Version: 0.18.2
|
|
4
4
|
Summary: CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.
|
|
5
5
|
Home-page: https://github.com/CloudSnorkel/cdk-github-runners.git
|
|
6
6
|
Author: Amir Szekely<amir@cloudsnorkel.com>
|
|
@@ -59,6 +59,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
|
|
|
59
59
|
|
|
60
60
|
* [API](#api)
|
|
61
61
|
* [Providers](#providers)
|
|
62
|
+
|
|
63
|
+
* [Job Isolation](#job-isolation)
|
|
62
64
|
* [Installation](#installation)
|
|
63
65
|
* [Customizing](#customizing)
|
|
64
66
|
|
|
@@ -103,6 +105,24 @@ The best provider to use mostly depends on your current infrastructure. When in
|
|
|
103
105
|
* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups
|
|
104
106
|
* Lambda is useful for short jobs that can work within time, size and readonly system constraints
|
|
105
107
|
|
|
108
|
+
### Job Isolation
|
|
109
|
+
|
|
110
|
+
Every job gets a new runner, but not every provider gives every job its own machine. EC2, CodeBuild, and Fargate run each job on its own instance, build, or task. ECS and Lambda can run different jobs on the same machine, so jobs that can run on the same ECS cluster or Lambda function should be treated as one trust boundary.
|
|
111
|
+
|
|
112
|
+
* **ECS** runs jobs as containers on a shared cluster of long-lived instances. With `dockerInDocker` enabled, which is the default for Linux, runner containers are privileged. A job running in a privileged container can take over the instance. From there it can access other jobs running on the same instance, and leave processes behind that affect jobs that run on it later. If you bring your own `capacityProvider`, its launch template must also require IMDSv2 with a hop limit of 1, or even unprivileged jobs can take the instance role.
|
|
113
|
+
* **Lambda** reuses execution environments between jobs. A job can leave processes behind that can access or affect later jobs running on the same function. We do clear up `/tmp` between jobs which is the only writable filesystem available.
|
|
114
|
+
|
|
115
|
+
To keep jobs of different trust levels apart:
|
|
116
|
+
|
|
117
|
+
* Don't run untrusted code, like pull requests from forks of public repositories, on an ECS or Lambda provider that also runs jobs with access to secrets.
|
|
118
|
+
* Use separate providers for different trust levels. Labels alone don't keep untrusted workflows off a provider, as any workflow can request any label. Use [runner groups](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups) limited to specific repositories or workflows. For ECS, give each provider its own cluster.
|
|
119
|
+
* Disable `dockerInDocker` on ECS if your jobs don't need Docker.
|
|
120
|
+
* If jobs of different trust levels must share a provider, use EC2, CodeBuild, or Fargate. EC2 and CodeBuild also support Docker.
|
|
121
|
+
|
|
122
|
+
All jobs running on the same provider, regardless of the type, share the provider's IAM role, security groups, network access, and anything granted to `grantPrincipal`, so only grant what every job on the provider may use.
|
|
123
|
+
|
|
124
|
+
If you are using ECS or Lambda to maximize runner provisioning speed, you could also consider [warm runners](#warm-runners).
|
|
125
|
+
|
|
106
126
|
## Installation
|
|
107
127
|
|
|
108
128
|
1. Install and use the appropriate package
|
|
@@ -640,6 +660,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
|
|
|
640
660
|
2. If you see too many errors, make sure you're only sending `workflow_job` events
|
|
641
661
|
5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
|
|
642
662
|
6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
|
|
663
|
+
7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
|
|
643
664
|
|
|
644
665
|
All logs are saved in CloudWatch.
|
|
645
666
|
|
|
@@ -688,10 +709,11 @@ Other useful metrics to track:
|
|
|
688
709
|
1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
|
|
689
710
|
2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
|
|
690
711
|
3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
|
|
712
|
+
4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
|
|
691
713
|
|
|
692
|
-
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It
|
|
693
|
-
|
|
694
|
-
|
|
714
|
+
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
|
|
715
|
+
into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
|
|
716
|
+
mean and which ones to alarm on.
|
|
695
717
|
|
|
696
718
|
## Known Issues
|
|
697
719
|
|
|
@@ -31,6 +31,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
|
|
|
31
31
|
|
|
32
32
|
* [API](#api)
|
|
33
33
|
* [Providers](#providers)
|
|
34
|
+
|
|
35
|
+
* [Job Isolation](#job-isolation)
|
|
34
36
|
* [Installation](#installation)
|
|
35
37
|
* [Customizing](#customizing)
|
|
36
38
|
|
|
@@ -75,6 +77,24 @@ The best provider to use mostly depends on your current infrastructure. When in
|
|
|
75
77
|
* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups
|
|
76
78
|
* Lambda is useful for short jobs that can work within time, size and readonly system constraints
|
|
77
79
|
|
|
80
|
+
### Job Isolation
|
|
81
|
+
|
|
82
|
+
Every job gets a new runner, but not every provider gives every job its own machine. EC2, CodeBuild, and Fargate run each job on its own instance, build, or task. ECS and Lambda can run different jobs on the same machine, so jobs that can run on the same ECS cluster or Lambda function should be treated as one trust boundary.
|
|
83
|
+
|
|
84
|
+
* **ECS** runs jobs as containers on a shared cluster of long-lived instances. With `dockerInDocker` enabled, which is the default for Linux, runner containers are privileged. A job running in a privileged container can take over the instance. From there it can access other jobs running on the same instance, and leave processes behind that affect jobs that run on it later. If you bring your own `capacityProvider`, its launch template must also require IMDSv2 with a hop limit of 1, or even unprivileged jobs can take the instance role.
|
|
85
|
+
* **Lambda** reuses execution environments between jobs. A job can leave processes behind that can access or affect later jobs running on the same function. We do clear up `/tmp` between jobs which is the only writable filesystem available.
|
|
86
|
+
|
|
87
|
+
To keep jobs of different trust levels apart:
|
|
88
|
+
|
|
89
|
+
* Don't run untrusted code, like pull requests from forks of public repositories, on an ECS or Lambda provider that also runs jobs with access to secrets.
|
|
90
|
+
* Use separate providers for different trust levels. Labels alone don't keep untrusted workflows off a provider, as any workflow can request any label. Use [runner groups](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups) limited to specific repositories or workflows. For ECS, give each provider its own cluster.
|
|
91
|
+
* Disable `dockerInDocker` on ECS if your jobs don't need Docker.
|
|
92
|
+
* If jobs of different trust levels must share a provider, use EC2, CodeBuild, or Fargate. EC2 and CodeBuild also support Docker.
|
|
93
|
+
|
|
94
|
+
All jobs running on the same provider, regardless of the type, share the provider's IAM role, security groups, network access, and anything granted to `grantPrincipal`, so only grant what every job on the provider may use.
|
|
95
|
+
|
|
96
|
+
If you are using ECS or Lambda to maximize runner provisioning speed, you could also consider [warm runners](#warm-runners).
|
|
97
|
+
|
|
78
98
|
## Installation
|
|
79
99
|
|
|
80
100
|
1. Install and use the appropriate package
|
|
@@ -612,6 +632,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
|
|
|
612
632
|
2. If you see too many errors, make sure you're only sending `workflow_job` events
|
|
613
633
|
5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
|
|
614
634
|
6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
|
|
635
|
+
7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
|
|
615
636
|
|
|
616
637
|
All logs are saved in CloudWatch.
|
|
617
638
|
|
|
@@ -660,10 +681,11 @@ Other useful metrics to track:
|
|
|
660
681
|
1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
|
|
661
682
|
2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
|
|
662
683
|
3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
|
|
684
|
+
4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
|
|
663
685
|
|
|
664
|
-
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It
|
|
665
|
-
|
|
666
|
-
|
|
686
|
+
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
|
|
687
|
+
into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
|
|
688
|
+
mean and which ones to alarm on.
|
|
667
689
|
|
|
668
690
|
## Known Issues
|
|
669
691
|
|
|
@@ -5,7 +5,7 @@ kwargs = json.loads(
|
|
|
5
5
|
"""
|
|
6
6
|
{
|
|
7
7
|
"name": "cloudsnorkel.cdk-github-runners",
|
|
8
|
-
"version": "0.18.
|
|
8
|
+
"version": "0.18.2",
|
|
9
9
|
"description": "CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.",
|
|
10
10
|
"license": "Apache-2.0",
|
|
11
11
|
"url": "https://github.com/CloudSnorkel/cdk-github-runners.git",
|
|
@@ -26,7 +26,7 @@ kwargs = json.loads(
|
|
|
26
26
|
],
|
|
27
27
|
"package_data": {
|
|
28
28
|
"cloudsnorkel.cdk_github_runners._jsii": [
|
|
29
|
-
"cdk-github-runners@0.18.
|
|
29
|
+
"cdk-github-runners@0.18.2.jsii.tgz"
|
|
30
30
|
],
|
|
31
31
|
"cloudsnorkel.cdk_github_runners": [
|
|
32
32
|
"py.typed"
|
|
@@ -32,6 +32,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
|
|
|
32
32
|
|
|
33
33
|
* [API](#api)
|
|
34
34
|
* [Providers](#providers)
|
|
35
|
+
|
|
36
|
+
* [Job Isolation](#job-isolation)
|
|
35
37
|
* [Installation](#installation)
|
|
36
38
|
* [Customizing](#customizing)
|
|
37
39
|
|
|
@@ -76,6 +78,24 @@ The best provider to use mostly depends on your current infrastructure. When in
|
|
|
76
78
|
* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups
|
|
77
79
|
* Lambda is useful for short jobs that can work within time, size and readonly system constraints
|
|
78
80
|
|
|
81
|
+
### Job Isolation
|
|
82
|
+
|
|
83
|
+
Every job gets a new runner, but not every provider gives every job its own machine. EC2, CodeBuild, and Fargate run each job on its own instance, build, or task. ECS and Lambda can run different jobs on the same machine, so jobs that can run on the same ECS cluster or Lambda function should be treated as one trust boundary.
|
|
84
|
+
|
|
85
|
+
* **ECS** runs jobs as containers on a shared cluster of long-lived instances. With `dockerInDocker` enabled, which is the default for Linux, runner containers are privileged. A job running in a privileged container can take over the instance. From there it can access other jobs running on the same instance, and leave processes behind that affect jobs that run on it later. If you bring your own `capacityProvider`, its launch template must also require IMDSv2 with a hop limit of 1, or even unprivileged jobs can take the instance role.
|
|
86
|
+
* **Lambda** reuses execution environments between jobs. A job can leave processes behind that can access or affect later jobs running on the same function. We do clear up `/tmp` between jobs which is the only writable filesystem available.
|
|
87
|
+
|
|
88
|
+
To keep jobs of different trust levels apart:
|
|
89
|
+
|
|
90
|
+
* Don't run untrusted code, like pull requests from forks of public repositories, on an ECS or Lambda provider that also runs jobs with access to secrets.
|
|
91
|
+
* Use separate providers for different trust levels. Labels alone don't keep untrusted workflows off a provider, as any workflow can request any label. Use [runner groups](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups) limited to specific repositories or workflows. For ECS, give each provider its own cluster.
|
|
92
|
+
* Disable `dockerInDocker` on ECS if your jobs don't need Docker.
|
|
93
|
+
* If jobs of different trust levels must share a provider, use EC2, CodeBuild, or Fargate. EC2 and CodeBuild also support Docker.
|
|
94
|
+
|
|
95
|
+
All jobs running on the same provider, regardless of the type, share the provider's IAM role, security groups, network access, and anything granted to `grantPrincipal`, so only grant what every job on the provider may use.
|
|
96
|
+
|
|
97
|
+
If you are using ECS or Lambda to maximize runner provisioning speed, you could also consider [warm runners](#warm-runners).
|
|
98
|
+
|
|
79
99
|
## Installation
|
|
80
100
|
|
|
81
101
|
1. Install and use the appropriate package
|
|
@@ -613,6 +633,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
|
|
|
613
633
|
2. If you see too many errors, make sure you're only sending `workflow_job` events
|
|
614
634
|
5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
|
|
615
635
|
6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
|
|
636
|
+
7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
|
|
616
637
|
|
|
617
638
|
All logs are saved in CloudWatch.
|
|
618
639
|
|
|
@@ -661,10 +682,11 @@ Other useful metrics to track:
|
|
|
661
682
|
1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
|
|
662
683
|
2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
|
|
663
684
|
3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
|
|
685
|
+
4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
|
|
664
686
|
|
|
665
|
-
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It
|
|
666
|
-
|
|
667
|
-
|
|
687
|
+
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
|
|
688
|
+
into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
|
|
689
|
+
mean and which ones to alarm on.
|
|
668
690
|
|
|
669
691
|
## Known Issues
|
|
670
692
|
|
|
@@ -2776,7 +2798,7 @@ class GitHubRunners(
|
|
|
2776
2798
|
:param idle_timeout: (experimental) Time to wait before stopping a runner that remains idle. If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources. Default: 5 minutes
|
|
2777
2799
|
:param log_options: (experimental) Logging options for the state machine that manages the runners. Default: no logs
|
|
2778
2800
|
:param providers: (experimental) List of runner providers to use. At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job. Default: CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
|
|
2779
|
-
:param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
|
|
2801
|
+
:param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider in the selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
|
|
2780
2802
|
:param require_self_hosted_label: (experimental) Whether to require the ``self-hosted`` label. If ``true``, the runner will only start if the workflow job explicitly requests the ``self-hosted`` label. Be careful when setting this to ``false``. Avoid setting up providers with generic label requirements like ``linux`` as they may match workflows that are not meant to run on self-hosted runners. Default: true
|
|
2781
2803
|
:param retry_options: (experimental) Options to retry operation in case of failure like missing capacity, or API quota issues. GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours. Retries use full jitter, so total time spent waiting is about half the sum of min(interval * backoffRate ^ attempt, maxDelay) over all attempts. Default: retry 210 times over a bit more than 24 hours
|
|
2782
2804
|
:param security_group: (deprecated) Security group attached to all management functions. Use this with to provide access to GitHub Enterprise Server hosted inside a VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
|
|
@@ -2820,20 +2842,16 @@ class GitHubRunners(
|
|
|
2820
2842
|
) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Dashboard":
|
|
2821
2843
|
'''(experimental) Creates a CloudWatch dashboard with the metrics you need to know if your runners are healthy.
|
|
2822
2844
|
|
|
2823
|
-
It
|
|
2845
|
+
It's split into sections, each with a short explanation of what its numbers mean and which ones to watch:
|
|
2824
2846
|
|
|
2825
|
-
-
|
|
2826
|
-
-
|
|
2827
|
-
-
|
|
2828
|
-
|
|
2829
|
-
-
|
|
2830
|
-
- How long do runners take (and therefore cost)? See "Runner time".
|
|
2831
|
-
- Is GitHub reaching the webhook at all? See "Webhook".
|
|
2832
|
-
- Is any of our code failing? See "Lambda errors".
|
|
2833
|
-
- What exactly went wrong? See "Recent errors".
|
|
2847
|
+
- **Jobs**: are jobs running and passing, and which runner is failing them?
|
|
2848
|
+
- **Runners**: do runners start, how long do they take (and therefore cost), and why do they fail to start?
|
|
2849
|
+
- **Runner assignment**: are runners taken by jobs they weren't started for, do jobs match more than one provider, and why
|
|
2850
|
+
were runners stopped before getting a job?
|
|
2851
|
+
- **Management functions (orchestration)**: is GitHub reaching the webhook, and is any of our code failing?
|
|
2834
2852
|
|
|
2835
|
-
**WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners}
|
|
2836
|
-
These resources may incur cost.
|
|
2853
|
+
**WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners}, {@link metricStoppedRunners} and
|
|
2854
|
+
{@link metricJobsMatchingMultipleProviders} which create metric filters. These resources may incur cost.
|
|
2837
2855
|
|
|
2838
2856
|
This dashboard is very basic. Pull requests and issues are welcome to improve it.
|
|
2839
2857
|
|
|
@@ -2857,6 +2875,7 @@ class GitHubRunners(
|
|
|
2857
2875
|
- "Ignored webhook" helps understand why runners aren't started
|
|
2858
2876
|
- "Ignored jobs based on labels" helps debug label matching issues
|
|
2859
2877
|
- "Webhook started runners" helps understand which runners were started
|
|
2878
|
+
- "Jobs matching multiple providers" lists jobs that need more labels so they match only one provider
|
|
2860
2879
|
- "Warm runner status" and "Warm runner errors" (when warm runners are configured)
|
|
2861
2880
|
|
|
2862
2881
|
:param prefix: Prefix for the query definitions. Defaults to "GitHub Runners".
|
|
@@ -2879,6 +2898,9 @@ class GitHubRunners(
|
|
|
2879
2898
|
|
|
2880
2899
|
If you want to be sure you are using the latest runner version, you can use this topic to be notified when a build fails.
|
|
2881
2900
|
|
|
2901
|
+
Email subscribers get a short summary with the failure reason and a link to the logs. Other subscribers get the original
|
|
2902
|
+
JSON notification from CodeBuild or EC2 Image Builder.
|
|
2903
|
+
|
|
2882
2904
|
When the image builder is defined in a separate stack (e.g. in a split-stacks setup), pass that stack or construct
|
|
2883
2905
|
as the optional scope so the topic and failure-notification aspects are created in the same stack as the image
|
|
2884
2906
|
builder. Otherwise the aspects may not find the image builder resources.
|
|
@@ -3000,6 +3022,66 @@ class GitHubRunners(
|
|
|
3000
3022
|
|
|
3001
3023
|
return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricJobCompleted", [props]))
|
|
3002
3024
|
|
|
3025
|
+
@jsii.member(jsii_name="metricJobsMatchingMultipleProviders")
|
|
3026
|
+
def metric_jobs_matching_multiple_providers(
|
|
3027
|
+
self,
|
|
3028
|
+
*,
|
|
3029
|
+
account: typing.Optional[builtins.str] = None,
|
|
3030
|
+
color: typing.Optional[builtins.str] = None,
|
|
3031
|
+
dimensions_map: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
|
|
3032
|
+
id: typing.Optional[builtins.str] = None,
|
|
3033
|
+
label: typing.Optional[builtins.str] = None,
|
|
3034
|
+
period: typing.Optional["_aws_cdk_ceddda9d.Duration"] = None,
|
|
3035
|
+
region: typing.Optional[builtins.str] = None,
|
|
3036
|
+
stack_account: typing.Optional[builtins.str] = None,
|
|
3037
|
+
stack_region: typing.Optional[builtins.str] = None,
|
|
3038
|
+
statistic: typing.Optional[builtins.str] = None,
|
|
3039
|
+
unit: typing.Optional["_aws_cdk_aws_cloudwatch_ceddda9d.Unit"] = None,
|
|
3040
|
+
visible: typing.Optional[builtins.bool] = None,
|
|
3041
|
+
) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Metric":
|
|
3042
|
+
'''(experimental) Metric for the number of jobs whose labels matched more than one provider.
|
|
3043
|
+
|
|
3044
|
+
We start a runner from the first matching provider, but GitHub may give such a job a runner from any of them, including one started for
|
|
3045
|
+
another job. Stolen runner detection starts another runner for the job left behind, but the job itself may run on a provider you didn't
|
|
3046
|
+
expect. Anything over zero means some workflows ask for too few labels. Add labels to those jobs so they match only one provider. Use the
|
|
3047
|
+
"Jobs matching multiple providers" CloudWatch Logs Insights query created by {@link createLogsInsightsQueries} to find them.
|
|
3048
|
+
|
|
3049
|
+
Jobs routed by a provider selector are not counted, as the selector picks the provider.
|
|
3050
|
+
|
|
3051
|
+
**WARNING:** this method creates a metric filter. This resource may incur cost.
|
|
3052
|
+
|
|
3053
|
+
:param account: Account which this metric comes from. Default: - Deployment account.
|
|
3054
|
+
:param color: The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. The ``Color`` class has a set of standard colors that can be used here. Default: - Automatic color
|
|
3055
|
+
:param dimensions_map: Dimensions of the metric. Default: - No dimensions.
|
|
3056
|
+
:param id: Unique identifier for this metric when used in dashboard widgets. The id can be used as a variable to represent this metric in math expressions. Valid characters are letters, numbers, and underscore. The first character must be a lowercase letter. Default: - No ID
|
|
3057
|
+
:param label: Label for this metric when added to a Graph in a Dashboard. You can use `dynamic labels <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html>`_ to show summary information about the entire displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph's legend. Default: - No label
|
|
3058
|
+
:param period: The period over which the specified statistic is applied. Default: Duration.minutes(5)
|
|
3059
|
+
:param region: Region which this metric comes from. Default: - Deployment region.
|
|
3060
|
+
:param stack_account: Account of the stack this metric is attached to. Default: - Deployment account.
|
|
3061
|
+
:param stack_region: Region of the stack this metric is attached to. Default: - Deployment region.
|
|
3062
|
+
:param statistic: What function to use for aggregating. Use the ``aws_cloudwatch.Stats`` helper class to construct valid input strings. Can be one of the following: - "Minimum" | "min" - "Maximum" | "max" - "Average" | "avg" - "Sum" | "sum" - "SampleCount | "n" - "pNN.NN" - "tmNN.NN" | "tm(NN.NN%:NN.NN%)" - "iqm" - "wmNN.NN" | "wm(NN.NN%:NN.NN%)" - "tcNN.NN" | "tc(NN.NN%:NN.NN%)" - "tsNN.NN" | "ts(NN.NN%:NN.NN%)" Default: Average
|
|
3063
|
+
:param unit: Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream
|
|
3064
|
+
:param visible: Whether this metric should be visible in dashboard graphs. Setting this to false is useful when you want to hide raw metrics that are used in math expressions, and show only the expression results. Default: true
|
|
3065
|
+
|
|
3066
|
+
:stability: experimental
|
|
3067
|
+
'''
|
|
3068
|
+
props = _aws_cdk_aws_cloudwatch_ceddda9d.MetricOptions(
|
|
3069
|
+
account=account,
|
|
3070
|
+
color=color,
|
|
3071
|
+
dimensions_map=dimensions_map,
|
|
3072
|
+
id=id,
|
|
3073
|
+
label=label,
|
|
3074
|
+
period=period,
|
|
3075
|
+
region=region,
|
|
3076
|
+
stack_account=stack_account,
|
|
3077
|
+
stack_region=stack_region,
|
|
3078
|
+
statistic=statistic,
|
|
3079
|
+
unit=unit,
|
|
3080
|
+
visible=visible,
|
|
3081
|
+
)
|
|
3082
|
+
|
|
3083
|
+
return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricJobsMatchingMultipleProviders", [props]))
|
|
3084
|
+
|
|
3003
3085
|
@jsii.member(jsii_name="metricLambdaErrors")
|
|
3004
3086
|
def metric_lambda_errors(
|
|
3005
3087
|
self,
|
|
@@ -3364,7 +3446,7 @@ class GitHubRunnersProps:
|
|
|
3364
3446
|
:param idle_timeout: (experimental) Time to wait before stopping a runner that remains idle. If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources. Default: 5 minutes
|
|
3365
3447
|
:param log_options: (experimental) Logging options for the state machine that manages the runners. Default: no logs
|
|
3366
3448
|
:param providers: (experimental) List of runner providers to use. At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job. Default: CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
|
|
3367
|
-
:param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
|
|
3449
|
+
:param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider in the selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
|
|
3368
3450
|
:param require_self_hosted_label: (experimental) Whether to require the ``self-hosted`` label. If ``true``, the runner will only start if the workflow job explicitly requests the ``self-hosted`` label. Be careful when setting this to ``false``. Avoid setting up providers with generic label requirements like ``linux`` as they may match workflows that are not meant to run on self-hosted runners. Default: true
|
|
3369
3451
|
:param retry_options: (experimental) Options to retry operation in case of failure like missing capacity, or API quota issues. GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours. Retries use full jitter, so total time spent waiting is about half the sum of min(interval * backoffRate ^ attempt, maxDelay) over all attempts. Default: retry 210 times over a bit more than 24 hours
|
|
3370
3452
|
:param security_group: (deprecated) Security group attached to all management functions. Use this with to provide access to GitHub Enterprise Server hosted inside a VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
|
|
@@ -3522,7 +3604,7 @@ class GitHubRunnersProps:
|
|
|
3522
3604
|
|
|
3523
3605
|
- The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput }
|
|
3524
3606
|
- The function returns a selected provider and its labels as {@link ProviderSelectorResult }
|
|
3525
|
-
- You can decline to provision a runner by returning undefined as the provider selector result
|
|
3607
|
+
- You can decline to provision a runner by returning undefined as the provider in the selector result
|
|
3526
3608
|
- You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.)
|
|
3527
3609
|
- Labels don't have to match the labels originally configured for the provider, but see warnings below
|
|
3528
3610
|
- This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total)
|
|
@@ -4700,6 +4782,9 @@ class LambdaRunnerProvider(
|
|
|
4700
4782
|
|
|
4701
4783
|
Creates a Docker-based function that gets executed for each job.
|
|
4702
4784
|
|
|
4785
|
+
Execution environments can be reused between jobs. All jobs that can run on the same function should be equally trusted. See
|
|
4786
|
+
https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
|
|
4787
|
+
|
|
4703
4788
|
This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.
|
|
4704
4789
|
|
|
4705
4790
|
:stability: experimental
|
|
@@ -5199,8 +5284,8 @@ class LogOptions:
|
|
|
5199
5284
|
) -> None:
|
|
5200
5285
|
'''(experimental) Defines what execution history events are logged and where they are logged.
|
|
5201
5286
|
|
|
5202
|
-
:param include_execution_data: (experimental) Determines whether execution data is included in your log. Default:
|
|
5203
|
-
:param level: (experimental) Defines which category of execution history events are logged. Default:
|
|
5287
|
+
:param include_execution_data: (experimental) Determines whether execution data is included in your log. Default: true
|
|
5288
|
+
:param level: (experimental) Defines which category of execution history events are logged. Default: ALL
|
|
5204
5289
|
:param log_group_name: (experimental) The log group where the execution history events will be logged.
|
|
5205
5290
|
:param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
|
|
5206
5291
|
|
|
@@ -5226,7 +5311,7 @@ class LogOptions:
|
|
|
5226
5311
|
def include_execution_data(self) -> typing.Optional[builtins.bool]:
|
|
5227
5312
|
'''(experimental) Determines whether execution data is included in your log.
|
|
5228
5313
|
|
|
5229
|
-
:default:
|
|
5314
|
+
:default: true
|
|
5230
5315
|
|
|
5231
5316
|
:stability: experimental
|
|
5232
5317
|
'''
|
|
@@ -5237,7 +5322,7 @@ class LogOptions:
|
|
|
5237
5322
|
def level(self) -> typing.Optional["_aws_cdk_aws_stepfunctions_ceddda9d.LogLevel"]:
|
|
5238
5323
|
'''(experimental) Defines which category of execution history events are logged.
|
|
5239
5324
|
|
|
5240
|
-
:default:
|
|
5325
|
+
:default: ALL
|
|
5241
5326
|
|
|
5242
5327
|
:stability: experimental
|
|
5243
5328
|
'''
|
|
@@ -9927,6 +10012,9 @@ class EcsRunnerProvider(
|
|
|
9927
10012
|
group to scale down to zero during the night and scale up during work hours. This way you can still save money, but have to wait less for
|
|
9928
10013
|
infrastructure to spin up.
|
|
9929
10014
|
|
|
10015
|
+
Jobs share instances, and by default run in privileged containers on Linux that can take over the instance. All jobs that can run on the same
|
|
10016
|
+
cluster should be equally trusted. See https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
|
|
10017
|
+
|
|
9930
10018
|
This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.
|
|
9931
10019
|
|
|
9932
10020
|
:stability: experimental
|
|
@@ -9969,10 +10057,10 @@ class EcsRunnerProvider(
|
|
|
9969
10057
|
:param scope: -
|
|
9970
10058
|
:param id: -
|
|
9971
10059
|
:param assign_public_ip: (deprecated) Assign public IP to the runner task. Default: - ignored
|
|
9972
|
-
:param capacity_provider: (experimental) Existing capacity provider to use. Make sure the AMI used by the capacity provider is compatible with ECS. Default: new capacity provider
|
|
9973
|
-
:param cluster: (experimental) Existing ECS cluster to use. Default: a new cluster
|
|
10060
|
+
:param capacity_provider: (experimental) Existing capacity provider to use. Make sure the AMI used by the capacity provider is compatible with ECS. Runner containers use bridge networking and share the instance with other jobs. Its launch template must require IMDSv2 and set the metadata hop limit to 1 (``requireImdsv2: true`` and ``httpPutResponseHopLimit: 1``), or jobs can take the instance role. A warning is added when we can't confirm both. Default: new capacity provider
|
|
10061
|
+
:param cluster: (experimental) Existing ECS cluster to use. Jobs from all providers using the same cluster can share instances. Only share a cluster between providers whose jobs are equally trusted. Default: a new cluster
|
|
9974
10062
|
:param cpu: (experimental) The number of cpu units used by the task. 1024 units is 1 vCPU. Fractions of a vCPU are supported. Default: 1024
|
|
9975
|
-
:param docker_in_docker: (experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required
|
|
10063
|
+
:param docker_in_docker: (experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container. A job running in a privileged container can take over the instance, access other jobs running on it, and affect jobs that run on it later. All jobs that can run on the same cluster should be equally trusted. Disable this if your jobs don't need Docker. Disabling Docker-in-Docker can also speed up runner provisioning as the runner doesn't have to wait for Docker to boot. Default: true
|
|
9976
10064
|
:param gpu: (experimental) Number of GPUs to request for the runner task. When set, the task will be scheduled on GPU-capable instances. Requires a GPU-capable instance type (e.g., g4dn.xlarge for 1 GPU, g4dn.12xlarge for 4 GPUs) and GPU AMI. When creating a new cluster, instanceType defaults to g4dn.xlarge and the ECS Optimized GPU AMI is used. You must ensure that the task's container image includes the CUDA runtime. Provide a CUDA-enabled base image via ``baseDockerImage``, use an image builder that starts from a GPU-capable image (such as nvidia/cuda), or add an image component that installs the CUDA runtime into the image. Default: undefined (no GPU)
|
|
9977
10065
|
:param group: (experimental) GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. Default: undefined
|
|
9978
10066
|
:param image_builder: (experimental) Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder determines the OS and architecture of the runner. Default: EcsRunnerProvider.imageBuilder()
|
|
@@ -10267,10 +10355,10 @@ class EcsRunnerProviderProps(RunnerProviderProps):
|
|
|
10267
10355
|
:param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
|
|
10268
10356
|
:param retry_options:
|
|
10269
10357
|
:param assign_public_ip: (deprecated) Assign public IP to the runner task. Default: - ignored
|
|
10270
|
-
:param capacity_provider: (experimental) Existing capacity provider to use. Make sure the AMI used by the capacity provider is compatible with ECS. Default: new capacity provider
|
|
10271
|
-
:param cluster: (experimental) Existing ECS cluster to use. Default: a new cluster
|
|
10358
|
+
:param capacity_provider: (experimental) Existing capacity provider to use. Make sure the AMI used by the capacity provider is compatible with ECS. Runner containers use bridge networking and share the instance with other jobs. Its launch template must require IMDSv2 and set the metadata hop limit to 1 (``requireImdsv2: true`` and ``httpPutResponseHopLimit: 1``), or jobs can take the instance role. A warning is added when we can't confirm both. Default: new capacity provider
|
|
10359
|
+
:param cluster: (experimental) Existing ECS cluster to use. Jobs from all providers using the same cluster can share instances. Only share a cluster between providers whose jobs are equally trusted. Default: a new cluster
|
|
10272
10360
|
:param cpu: (experimental) The number of cpu units used by the task. 1024 units is 1 vCPU. Fractions of a vCPU are supported. Default: 1024
|
|
10273
|
-
:param docker_in_docker: (experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required
|
|
10361
|
+
:param docker_in_docker: (experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container. A job running in a privileged container can take over the instance, access other jobs running on it, and affect jobs that run on it later. All jobs that can run on the same cluster should be equally trusted. Disable this if your jobs don't need Docker. Disabling Docker-in-Docker can also speed up runner provisioning as the runner doesn't have to wait for Docker to boot. Default: true
|
|
10274
10362
|
:param gpu: (experimental) Number of GPUs to request for the runner task. When set, the task will be scheduled on GPU-capable instances. Requires a GPU-capable instance type (e.g., g4dn.xlarge for 1 GPU, g4dn.12xlarge for 4 GPUs) and GPU AMI. When creating a new cluster, instanceType defaults to g4dn.xlarge and the ECS Optimized GPU AMI is used. You must ensure that the task's container image includes the CUDA runtime. Provide a CUDA-enabled base image via ``baseDockerImage``, use an image builder that starts from a GPU-capable image (such as nvidia/cuda), or add an image component that installs the CUDA runtime into the image. Default: undefined (no GPU)
|
|
10275
10363
|
:param group: (experimental) GitHub Actions runner group name. If specified, the runner will be registered with this group name. Setting a runner group can help managing access to self-hosted runners. It requires a paid GitHub account and organization level runner registration. The group must exist or the runner will not start. Users will still be able to trigger this runner with the correct labels. But the runner will only be able to run jobs from repos allowed to use the group. Default: undefined
|
|
10276
10364
|
:param image_builder: (experimental) Runner image builder used to build Docker images containing GitHub Runner and all requirements. The image builder determines the OS and architecture of the runner. Default: EcsRunnerProvider.imageBuilder()
|
|
@@ -10449,6 +10537,10 @@ class EcsRunnerProviderProps(RunnerProviderProps):
|
|
|
10449
10537
|
|
|
10450
10538
|
Make sure the AMI used by the capacity provider is compatible with ECS.
|
|
10451
10539
|
|
|
10540
|
+
Runner containers use bridge networking and share the instance with other jobs. Its launch template must require IMDSv2 and set the
|
|
10541
|
+
metadata hop limit to 1 (``requireImdsv2: true`` and ``httpPutResponseHopLimit: 1``), or jobs can take the instance role. A warning is
|
|
10542
|
+
added when we can't confirm both.
|
|
10543
|
+
|
|
10452
10544
|
:default: new capacity provider
|
|
10453
10545
|
|
|
10454
10546
|
:stability: experimental
|
|
@@ -10460,8 +10552,11 @@ class EcsRunnerProviderProps(RunnerProviderProps):
|
|
|
10460
10552
|
def cluster(self) -> typing.Optional["_aws_cdk_aws_ecs_ceddda9d.Cluster"]:
|
|
10461
10553
|
'''(experimental) Existing ECS cluster to use.
|
|
10462
10554
|
|
|
10555
|
+
Jobs from all providers using the same cluster can share instances. Only share a cluster between providers whose jobs are equally trusted.
|
|
10556
|
+
|
|
10463
10557
|
:default: a new cluster
|
|
10464
10558
|
|
|
10559
|
+
:see: https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
|
|
10465
10560
|
:stability: experimental
|
|
10466
10561
|
'''
|
|
10467
10562
|
result = self._values.get("cluster")
|
|
@@ -10482,13 +10577,16 @@ class EcsRunnerProviderProps(RunnerProviderProps):
|
|
|
10482
10577
|
|
|
10483
10578
|
@builtins.property
|
|
10484
10579
|
def docker_in_docker(self) -> typing.Optional[builtins.bool]:
|
|
10485
|
-
'''(experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required
|
|
10580
|
+
'''(experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container.
|
|
10486
10581
|
|
|
10487
|
-
|
|
10488
|
-
|
|
10582
|
+
A job running in a privileged container can take over the instance, access other jobs running on it, and affect jobs that run on it
|
|
10583
|
+
later. All jobs that can run on the same cluster should be equally trusted. Disable this if your jobs don't need Docker.
|
|
10584
|
+
|
|
10585
|
+
Disabling Docker-in-Docker can also speed up runner provisioning as the runner doesn't have to wait for Docker to boot.
|
|
10489
10586
|
|
|
10490
10587
|
:default: true
|
|
10491
10588
|
|
|
10589
|
+
:see: https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
|
|
10492
10590
|
:stability: experimental
|
|
10493
10591
|
'''
|
|
10494
10592
|
result = self._values.get("docker_in_docker")
|
|
@@ -19,9 +19,9 @@ import constructs._jsii
|
|
|
19
19
|
|
|
20
20
|
__jsii_assembly__ = jsii.JSIIAssembly.load(
|
|
21
21
|
"@cloudsnorkel/cdk-github-runners",
|
|
22
|
-
"0.18.
|
|
22
|
+
"0.18.2",
|
|
23
23
|
__name__[0:-6],
|
|
24
|
-
"cdk-github-runners@0.18.
|
|
24
|
+
"cdk-github-runners@0.18.2.jsii.tgz",
|
|
25
25
|
)
|
|
26
26
|
|
|
27
27
|
__all__ = [
|
|
Binary file
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: cloudsnorkel.cdk-github-runners
|
|
3
|
-
Version: 0.18.
|
|
3
|
+
Version: 0.18.2
|
|
4
4
|
Summary: CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.
|
|
5
5
|
Home-page: https://github.com/CloudSnorkel/cdk-github-runners.git
|
|
6
6
|
Author: Amir Szekely<amir@cloudsnorkel.com>
|
|
@@ -59,6 +59,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
|
|
|
59
59
|
|
|
60
60
|
* [API](#api)
|
|
61
61
|
* [Providers](#providers)
|
|
62
|
+
|
|
63
|
+
* [Job Isolation](#job-isolation)
|
|
62
64
|
* [Installation](#installation)
|
|
63
65
|
* [Customizing](#customizing)
|
|
64
66
|
|
|
@@ -103,6 +105,24 @@ The best provider to use mostly depends on your current infrastructure. When in
|
|
|
103
105
|
* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups
|
|
104
106
|
* Lambda is useful for short jobs that can work within time, size and readonly system constraints
|
|
105
107
|
|
|
108
|
+
### Job Isolation
|
|
109
|
+
|
|
110
|
+
Every job gets a new runner, but not every provider gives every job its own machine. EC2, CodeBuild, and Fargate run each job on its own instance, build, or task. ECS and Lambda can run different jobs on the same machine, so jobs that can run on the same ECS cluster or Lambda function should be treated as one trust boundary.
|
|
111
|
+
|
|
112
|
+
* **ECS** runs jobs as containers on a shared cluster of long-lived instances. With `dockerInDocker` enabled, which is the default for Linux, runner containers are privileged. A job running in a privileged container can take over the instance. From there it can access other jobs running on the same instance, and leave processes behind that affect jobs that run on it later. If you bring your own `capacityProvider`, its launch template must also require IMDSv2 with a hop limit of 1, or even unprivileged jobs can take the instance role.
|
|
113
|
+
* **Lambda** reuses execution environments between jobs. A job can leave processes behind that can access or affect later jobs running on the same function. We do clear up `/tmp` between jobs which is the only writable filesystem available.
|
|
114
|
+
|
|
115
|
+
To keep jobs of different trust levels apart:
|
|
116
|
+
|
|
117
|
+
* Don't run untrusted code, like pull requests from forks of public repositories, on an ECS or Lambda provider that also runs jobs with access to secrets.
|
|
118
|
+
* Use separate providers for different trust levels. Labels alone don't keep untrusted workflows off a provider, as any workflow can request any label. Use [runner groups](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups) limited to specific repositories or workflows. For ECS, give each provider its own cluster.
|
|
119
|
+
* Disable `dockerInDocker` on ECS if your jobs don't need Docker.
|
|
120
|
+
* If jobs of different trust levels must share a provider, use EC2, CodeBuild, or Fargate. EC2 and CodeBuild also support Docker.
|
|
121
|
+
|
|
122
|
+
All jobs running on the same provider, regardless of the type, share the provider's IAM role, security groups, network access, and anything granted to `grantPrincipal`, so only grant what every job on the provider may use.
|
|
123
|
+
|
|
124
|
+
If you are using ECS or Lambda to maximize runner provisioning speed, you could also consider [warm runners](#warm-runners).
|
|
125
|
+
|
|
106
126
|
## Installation
|
|
107
127
|
|
|
108
128
|
1. Install and use the appropriate package
|
|
@@ -640,6 +660,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
|
|
|
640
660
|
2. If you see too many errors, make sure you're only sending `workflow_job` events
|
|
641
661
|
5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
|
|
642
662
|
6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
|
|
663
|
+
7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
|
|
643
664
|
|
|
644
665
|
All logs are saved in CloudWatch.
|
|
645
666
|
|
|
@@ -688,10 +709,11 @@ Other useful metrics to track:
|
|
|
688
709
|
1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
|
|
689
710
|
2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
|
|
690
711
|
3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
|
|
712
|
+
4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
|
|
691
713
|
|
|
692
|
-
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It
|
|
693
|
-
|
|
694
|
-
|
|
714
|
+
Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
|
|
715
|
+
into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
|
|
716
|
+
mean and which ones to alarm on.
|
|
695
717
|
|
|
696
718
|
## Known Issues
|
|
697
719
|
|
|
@@ -11,4 +11,4 @@ src/cloudsnorkel.cdk_github_runners.egg-info/top_level.txt
|
|
|
11
11
|
src/cloudsnorkel/cdk_github_runners/__init__.py
|
|
12
12
|
src/cloudsnorkel/cdk_github_runners/py.typed
|
|
13
13
|
src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py
|
|
14
|
-
src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.
|
|
14
|
+
src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz
|
|
Binary file
|
|
File without changes
|
{cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/MANIFEST.in
RENAMED
|
File without changes
|
{cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/pyproject.toml
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|