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.
Files changed (17) hide show
  1. {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
  2. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/README.md +25 -3
  3. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.py +2 -2
  4. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/__init__.py +129 -31
  5. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
  6. cloudsnorkel_cdk_github_runners-0.18.2/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz +0 -0
  7. {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
  8. {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
  9. cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz +0 -0
  10. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/LICENSE +0 -0
  11. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/MANIFEST.in +0 -0
  12. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/pyproject.toml +0 -0
  13. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.cfg +0 -0
  14. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
  15. {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
  16. {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
  17. {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.0
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 shows
693
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
694
- recent errors from the logs.
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 shows
665
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
666
- recent errors from the logs.
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.0",
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.0.jsii.tgz"
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 shows
666
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
667
- recent errors from the logs.
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 answers the questions you're most likely to ask:
2845
+ It's split into sections, each with a short explanation of what its numbers mean and which ones to watch:
2824
2846
 
2825
- - Are jobs running and passing? See "Jobs completed by status".
2826
- - Which runner is broken? See "Failed jobs by runner label".
2827
- - Are jobs stuck because runners fail to start? See "Runner executions".
2828
- - Why were runners stopped before getting a job? See "Stopped runners by reason".
2829
- - Why are runners failing to start? See "Recent failed attempts".
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} and {@link metricStoppedRunners} which create metric filters.
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: false
5203
- :param level: (experimental) Defines which category of execution history events are logged. Default: ERROR
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: false
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: ERROR
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 CodeBuild privileged mode. Disabling this can speed up provisioning of CodeBuild runners. If you don't intend on running or building Docker images, disable this for faster start-up times. Default: true
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 CodeBuild privileged mode. Disabling this can speed up provisioning of CodeBuild runners. If you don't intend on running or building Docker images, disable this for faster start-up times. Default: true
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 CodeBuild privileged mode.
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
- Disabling this can
10488
- speed up provisioning of CodeBuild runners. If you don't intend on running or building Docker images, disable this for faster start-up times.
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.0",
22
+ "0.18.2",
23
23
  __name__[0:-6],
24
- "cdk-github-runners@0.18.0.jsii.tgz",
24
+ "cdk-github-runners@0.18.2.jsii.tgz",
25
25
  )
26
26
 
27
27
  __all__ = [
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: cloudsnorkel.cdk-github-runners
3
- Version: 0.18.0
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 shows
693
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
694
- recent errors from the logs.
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.0.jsii.tgz
14
+ src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz