cloudsnorkel.cdk-github-runners 0.17.1__tar.gz → 0.18.0__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.17.1/src/cloudsnorkel.cdk_github_runners.egg-info → cloudsnorkel_cdk_github_runners-0.18.0}/PKG-INFO +30 -3
  2. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/README.md +28 -1
  3. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/pyproject.toml +1 -1
  4. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/setup.py +3 -3
  5. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/__init__.py +112 -5
  6. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
  7. cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz +0 -0
  8. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel.cdk_github_runners.egg-info}/PKG-INFO +30 -3
  9. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/SOURCES.txt +1 -1
  10. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/requires.txt +1 -1
  11. cloudsnorkel_cdk_github_runners-0.17.1/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.17.1.jsii.tgz +0 -0
  12. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/LICENSE +0 -0
  13. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/MANIFEST.in +0 -0
  14. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/setup.cfg +0 -0
  15. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
  16. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/dependency_links.txt +0 -0
  17. {cloudsnorkel_cdk_github_runners-0.17.1 → cloudsnorkel_cdk_github_runners-0.18.0}/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.17.1
3
+ Version: 0.18.0
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>
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
24
  Requires-Dist: aws-cdk-lib<3.0.0,>=2.239.0
25
25
  Requires-Dist: constructs<11.0.0,>=10.5.1
26
- Requires-Dist: jsii<2.0.0,>=1.139.0
26
+ Requires-Dist: jsii<2.0.0,>=1.142.0
27
27
  Requires-Dist: publication>=0.0.3
28
28
 
29
29
  # GitHub Self-Hosted Runners CDK Constructs
@@ -36,6 +36,7 @@ Requires-Dist: publication>=0.0.3
36
36
  [![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)
37
37
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
38
38
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
39
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
39
40
 
40
41
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
41
42
 
@@ -50,7 +51,7 @@ Self-hosted runners in AWS are useful when:
50
51
  * You need easy access to internal resources in your actions
51
52
  * You want to pre-install some software for your actions
52
53
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
53
- * You are using GitHub Enterprise Server
54
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
54
55
 
55
56
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
56
57
 
@@ -67,6 +68,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
67
68
  * [Examples](#examples)
68
69
  * [Architecture](#architecture)
69
70
  * [Troubleshooting](#troubleshooting)
71
+
72
+ * [Rebuilding runner images](#rebuilding-runner-images)
70
73
  * [Monitoring](#monitoring)
71
74
  * [Getting Help](#getting-help)
72
75
  * [Contributing](#contributing)
@@ -636,6 +639,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
636
639
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
637
640
  2. If you see too many errors, make sure you're only sending `workflow_job` events
638
641
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
642
+ 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
639
643
 
640
644
  All logs are saved in CloudWatch.
641
645
 
@@ -648,6 +652,29 @@ To get `status.json`, check out the CloudFormation stack output for a command th
648
652
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
649
653
  ```
650
654
 
655
+ ### Rebuilding runner images
656
+
657
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
658
+
659
+ ```sh
660
+ STACK=my-runners-stack
661
+ resources() {
662
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
663
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
664
+ }
665
+ for project in $(resources AWS::CodeBuild::Project); do
666
+ # skip runner projects of CodeBuild providers, we only want image builders
667
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
668
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
669
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
670
+ done
671
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
672
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
673
+ done
674
+ ```
675
+
676
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
677
+
651
678
  ## Monitoring
652
679
 
653
680
  There are three important ways to monitor your runners:
@@ -8,6 +8,7 @@
8
8
  [![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)
9
9
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
10
10
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
11
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
11
12
 
12
13
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
13
14
 
@@ -22,7 +23,7 @@ Self-hosted runners in AWS are useful when:
22
23
  * You need easy access to internal resources in your actions
23
24
  * You want to pre-install some software for your actions
24
25
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
25
- * You are using GitHub Enterprise Server
26
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
26
27
 
27
28
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
28
29
 
@@ -39,6 +40,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
39
40
  * [Examples](#examples)
40
41
  * [Architecture](#architecture)
41
42
  * [Troubleshooting](#troubleshooting)
43
+
44
+ * [Rebuilding runner images](#rebuilding-runner-images)
42
45
  * [Monitoring](#monitoring)
43
46
  * [Getting Help](#getting-help)
44
47
  * [Contributing](#contributing)
@@ -608,6 +611,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
608
611
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
609
612
  2. If you see too many errors, make sure you're only sending `workflow_job` events
610
613
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
614
+ 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
611
615
 
612
616
  All logs are saved in CloudWatch.
613
617
 
@@ -620,6 +624,29 @@ To get `status.json`, check out the CloudFormation stack output for a command th
620
624
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
621
625
  ```
622
626
 
627
+ ### Rebuilding runner images
628
+
629
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
630
+
631
+ ```sh
632
+ STACK=my-runners-stack
633
+ resources() {
634
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
635
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
636
+ }
637
+ for project in $(resources AWS::CodeBuild::Project); do
638
+ # skip runner projects of CodeBuild providers, we only want image builders
639
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
640
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
641
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
642
+ done
643
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
644
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
645
+ done
646
+ ```
647
+
648
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
649
+
623
650
  ## Monitoring
624
651
 
625
652
  There are three important ways to monitor your runners:
@@ -1,5 +1,5 @@
1
1
  [build-system]
2
- requires = ["setuptools~=75.3.2", "build~=1.5.0"]
2
+ requires = ["setuptools~=75.3.2", "build~=1.6.1"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [tool.pyright]
@@ -5,7 +5,7 @@ kwargs = json.loads(
5
5
  """
6
6
  {
7
7
  "name": "cloudsnorkel.cdk-github-runners",
8
- "version": "0.17.1",
8
+ "version": "0.18.0",
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.17.1.jsii.tgz"
29
+ "cdk-github-runners@0.18.0.jsii.tgz"
30
30
  ],
31
31
  "cloudsnorkel.cdk_github_runners": [
32
32
  "py.typed"
@@ -36,7 +36,7 @@ kwargs = json.loads(
36
36
  "install_requires": [
37
37
  "aws-cdk-lib>=2.239.0, <3.0.0",
38
38
  "constructs>=10.5.1, <11.0.0",
39
- "jsii>=1.139.0, <2.0.0",
39
+ "jsii>=1.142.0, <2.0.0",
40
40
  "publication>=0.0.3"
41
41
  ],
42
42
  "classifiers": [
@@ -9,6 +9,7 @@ r'''
9
9
  [![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)
10
10
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
11
11
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
12
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
12
13
 
13
14
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
14
15
 
@@ -23,7 +24,7 @@ Self-hosted runners in AWS are useful when:
23
24
  * You need easy access to internal resources in your actions
24
25
  * You want to pre-install some software for your actions
25
26
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
26
- * You are using GitHub Enterprise Server
27
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
27
28
 
28
29
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
29
30
 
@@ -40,6 +41,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
40
41
  * [Examples](#examples)
41
42
  * [Architecture](#architecture)
42
43
  * [Troubleshooting](#troubleshooting)
44
+
45
+ * [Rebuilding runner images](#rebuilding-runner-images)
43
46
  * [Monitoring](#monitoring)
44
47
  * [Getting Help](#getting-help)
45
48
  * [Contributing](#contributing)
@@ -609,6 +612,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
609
612
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
610
613
  2. If you see too many errors, make sure you're only sending `workflow_job` events
611
614
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
615
+ 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
612
616
 
613
617
  All logs are saved in CloudWatch.
614
618
 
@@ -621,6 +625,29 @@ To get `status.json`, check out the CloudFormation stack output for a command th
621
625
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
622
626
  ```
623
627
 
628
+ ### Rebuilding runner images
629
+
630
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
631
+
632
+ ```sh
633
+ STACK=my-runners-stack
634
+ resources() {
635
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
636
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
637
+ }
638
+ for project in $(resources AWS::CodeBuild::Project); do
639
+ # skip runner projects of CodeBuild providers, we only want image builders
640
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
641
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
642
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
643
+ done
644
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
645
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
646
+ done
647
+ ```
648
+
649
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
650
+
624
651
  ## Monitoring
625
652
 
626
653
  There are three important ways to monitor your runners:
@@ -1420,6 +1447,7 @@ class Architecture(
1420
1447
 
1421
1448
  @jsii.python.classproperty
1422
1449
  @jsii.member(jsii_name="ARM64")
1450
+ @builtins.classmethod
1423
1451
  def ARM64(cls) -> "Architecture":
1424
1452
  '''(experimental) ARM64.
1425
1453
 
@@ -1429,6 +1457,7 @@ class Architecture(
1429
1457
 
1430
1458
  @jsii.python.classproperty
1431
1459
  @jsii.member(jsii_name="X86_64")
1460
+ @builtins.classmethod
1432
1461
  def X86_64(cls) -> "Architecture":
1433
1462
  '''(experimental) X86_64.
1434
1463
 
@@ -2796,12 +2825,14 @@ class GitHubRunners(
2796
2825
  - Are jobs running and passing? See "Jobs completed by status".
2797
2826
  - Which runner is broken? See "Failed jobs by runner label".
2798
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".
2799
2830
  - How long do runners take (and therefore cost)? See "Runner time".
2800
2831
  - Is GitHub reaching the webhook at all? See "Webhook".
2801
2832
  - Is any of our code failing? See "Lambda errors".
2802
2833
  - What exactly went wrong? See "Recent errors".
2803
2834
 
2804
- **WARNING:** this method calls {@link metricJobCompleted} and {@link metricStolenRunners} which create metric filters.
2835
+ **WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners} and {@link metricStoppedRunners} which create metric filters.
2805
2836
  These resources may incur cost.
2806
2837
 
2807
2838
  This dashboard is very basic. Pull requests and issues are welcome to improve it.
@@ -3072,6 +3103,69 @@ class GitHubRunners(
3072
3103
 
3073
3104
  return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricStolenRunners", [props]))
3074
3105
 
3106
+ @jsii.member(jsii_name="metricStoppedRunners")
3107
+ def metric_stopped_runners(
3108
+ self,
3109
+ *,
3110
+ account: typing.Optional[builtins.str] = None,
3111
+ color: typing.Optional[builtins.str] = None,
3112
+ dimensions_map: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
3113
+ id: typing.Optional[builtins.str] = None,
3114
+ label: typing.Optional[builtins.str] = None,
3115
+ period: typing.Optional["_aws_cdk_ceddda9d.Duration"] = None,
3116
+ region: typing.Optional[builtins.str] = None,
3117
+ stack_account: typing.Optional[builtins.str] = None,
3118
+ stack_region: typing.Optional[builtins.str] = None,
3119
+ statistic: typing.Optional[builtins.str] = None,
3120
+ unit: typing.Optional["_aws_cdk_aws_cloudwatch_ceddda9d.Unit"] = None,
3121
+ visible: typing.Optional[builtins.bool] = None,
3122
+ ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Metric":
3123
+ '''(experimental) Metric for the number of runners we stopped on purpose before they got a job.
3124
+
3125
+ These step function executions end up as aborted and not failed, so they don't show up in {@link metricFailed}.
3126
+
3127
+ This metric has one dimension, ``Reason``, which is the error the step function was stopped with:
3128
+
3129
+ - ``IdleRunner``: the runner was idle for longer than its idle timeout and was reaped. This is usually a runner whose job was taken by
3130
+ another runner, or a job that was canceled before it started.
3131
+ - ``StaleWarmRunner``: a warm runner was replaced because its configuration changed.
3132
+ - ``WarmRunnerExpired``: a warm runner reached the end of its duration.
3133
+ - ``WarmRunnerBadDeadline``: a warm runner had an invalid deadline and was stopped.
3134
+
3135
+ **WARNING:** this method creates a metric filter. This resource may incur cost.
3136
+
3137
+ :param account: Account which this metric comes from. Default: - Deployment account.
3138
+ :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
3139
+ :param dimensions_map: Dimensions of the metric. Default: - No dimensions.
3140
+ :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
3141
+ :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
3142
+ :param period: The period over which the specified statistic is applied. Default: Duration.minutes(5)
3143
+ :param region: Region which this metric comes from. Default: - Deployment region.
3144
+ :param stack_account: Account of the stack this metric is attached to. Default: - Deployment account.
3145
+ :param stack_region: Region of the stack this metric is attached to. Default: - Deployment region.
3146
+ :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
3147
+ :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
3148
+ :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
3149
+
3150
+ :stability: experimental
3151
+ '''
3152
+ props = _aws_cdk_aws_cloudwatch_ceddda9d.MetricOptions(
3153
+ account=account,
3154
+ color=color,
3155
+ dimensions_map=dimensions_map,
3156
+ id=id,
3157
+ label=label,
3158
+ period=period,
3159
+ region=region,
3160
+ stack_account=stack_account,
3161
+ stack_region=stack_region,
3162
+ statistic=statistic,
3163
+ unit=unit,
3164
+ visible=visible,
3165
+ )
3166
+
3167
+ return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricStoppedRunners", [props]))
3168
+
3075
3169
  @jsii.member(jsii_name="metricSucceeded")
3076
3170
  def metric_succeeded(
3077
3171
  self,
@@ -4788,6 +4882,7 @@ class LambdaRunnerProvider(
4788
4882
 
4789
4883
  @jsii.python.classproperty
4790
4884
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
4885
+ @builtins.classmethod
4791
4886
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
4792
4887
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner.
4793
4888
 
@@ -4806,6 +4901,7 @@ class LambdaRunnerProvider(
4806
4901
 
4807
4902
  @jsii.python.classproperty
4808
4903
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
4904
+ @builtins.classmethod
4809
4905
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
4810
4906
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirement for Lambda runner.
4811
4907
 
@@ -5220,6 +5316,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5220
5316
 
5221
5317
  @jsii.python.classproperty
5222
5318
  @jsii.member(jsii_name="LINUX")
5319
+ @builtins.classmethod
5223
5320
  def LINUX(cls) -> "Os":
5224
5321
  '''(deprecated) Linux.
5225
5322
 
@@ -5231,6 +5328,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5231
5328
 
5232
5329
  @jsii.python.classproperty
5233
5330
  @jsii.member(jsii_name="LINUX_AMAZON_2")
5331
+ @builtins.classmethod
5234
5332
  def LINUX_AMAZON_2(cls) -> "Os":
5235
5333
  '''(experimental) Amazon Linux 2.
5236
5334
 
@@ -5240,6 +5338,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5240
5338
 
5241
5339
  @jsii.python.classproperty
5242
5340
  @jsii.member(jsii_name="LINUX_AMAZON_2023")
5341
+ @builtins.classmethod
5243
5342
  def LINUX_AMAZON_2023(cls) -> "Os":
5244
5343
  '''(experimental) Amazon Linux 2023.
5245
5344
 
@@ -5249,6 +5348,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5249
5348
 
5250
5349
  @jsii.python.classproperty
5251
5350
  @jsii.member(jsii_name="LINUX_UBUNTU")
5351
+ @builtins.classmethod
5252
5352
  def LINUX_UBUNTU(cls) -> "Os":
5253
5353
  '''(experimental) Ubuntu Linux.
5254
5354
 
@@ -5258,6 +5358,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5258
5358
 
5259
5359
  @jsii.python.classproperty
5260
5360
  @jsii.member(jsii_name="LINUX_UBUNTU_2204")
5361
+ @builtins.classmethod
5261
5362
  def LINUX_UBUNTU_2204(cls) -> "Os":
5262
5363
  '''(experimental) Ubuntu Linux 22.04.
5263
5364
 
@@ -5267,6 +5368,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5267
5368
 
5268
5369
  @jsii.python.classproperty
5269
5370
  @jsii.member(jsii_name="LINUX_UBUNTU_2404")
5371
+ @builtins.classmethod
5270
5372
  def LINUX_UBUNTU_2404(cls) -> "Os":
5271
5373
  '''(experimental) Ubuntu Linux 24.04.
5272
5374
 
@@ -5276,6 +5378,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5276
5378
 
5277
5379
  @jsii.python.classproperty
5278
5380
  @jsii.member(jsii_name="WINDOWS")
5381
+ @builtins.classmethod
5279
5382
  def WINDOWS(cls) -> "Os":
5280
5383
  '''(experimental) Windows.
5281
5384
 
@@ -8001,7 +8104,7 @@ class AmiBuilder(
8001
8104
  if __debug__:
8002
8105
  type_hints = cached_type_hints(_typecheckingstub__8088868062a70621aab7b900883cf52d9c930de8a458039564d69a7d0cc80f52)
8003
8106
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
8004
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
8107
+ jsii.set(self, "components", value)
8005
8108
 
8006
8109
 
8007
8110
  @jsii.implements(IRunnerImageBuilder)
@@ -8417,6 +8520,7 @@ class CodeBuildRunnerProvider(
8417
8520
 
8418
8521
  @jsii.python.classproperty
8419
8522
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
8523
+ @builtins.classmethod
8420
8524
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
8421
8525
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner.
8422
8526
 
@@ -8439,6 +8543,7 @@ class CodeBuildRunnerProvider(
8439
8543
 
8440
8544
  @jsii.python.classproperty
8441
8545
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
8546
+ @builtins.classmethod
8442
8547
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
8443
8548
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner.
8444
8549
 
@@ -9179,7 +9284,7 @@ class ContainerImageBuilder(
9179
9284
  if __debug__:
9180
9285
  type_hints = cached_type_hints(_typecheckingstub__f4c47d52e3f51709153fc49a53f833f06b1fd2ba44d3c86696b418a3bf88a972)
9181
9286
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
9182
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
9287
+ jsii.set(self, "components", value)
9183
9288
 
9184
9289
 
9185
9290
  @jsii.implements(IRunnerProvider, _constructs_77d1e7e8.IConstruct)
@@ -10856,6 +10961,7 @@ class FargateRunnerProvider(
10856
10961
 
10857
10962
  @jsii.python.classproperty
10858
10963
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
10964
+ @builtins.classmethod
10859
10965
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
10860
10966
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner.
10861
10967
 
@@ -10874,6 +10980,7 @@ class FargateRunnerProvider(
10874
10980
 
10875
10981
  @jsii.python.classproperty
10876
10982
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
10983
+ @builtins.classmethod
10877
10984
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
10878
10985
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirement for Fargate runner.
10879
10986
 
@@ -12165,7 +12272,7 @@ class RunnerImageBuilder(
12165
12272
  if __debug__:
12166
12273
  type_hints = cached_type_hints(_typecheckingstub__705c18a1eedaa490aebad511aac32a801519a57162e30be4673a8ab87ca434dc)
12167
12274
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
12168
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
12275
+ jsii.set(self, "components", value)
12169
12276
 
12170
12277
 
12171
12278
  class _RunnerImageBuilderProxy(RunnerImageBuilder):
@@ -19,9 +19,9 @@ import constructs._jsii
19
19
 
20
20
  __jsii_assembly__ = jsii.JSIIAssembly.load(
21
21
  "@cloudsnorkel/cdk-github-runners",
22
- "0.17.1",
22
+ "0.18.0",
23
23
  __name__[0:-6],
24
- "cdk-github-runners@0.17.1.jsii.tgz",
24
+ "cdk-github-runners@0.18.0.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.17.1
3
+ Version: 0.18.0
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>
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
24
  Requires-Dist: aws-cdk-lib<3.0.0,>=2.239.0
25
25
  Requires-Dist: constructs<11.0.0,>=10.5.1
26
- Requires-Dist: jsii<2.0.0,>=1.139.0
26
+ Requires-Dist: jsii<2.0.0,>=1.142.0
27
27
  Requires-Dist: publication>=0.0.3
28
28
 
29
29
  # GitHub Self-Hosted Runners CDK Constructs
@@ -36,6 +36,7 @@ Requires-Dist: publication>=0.0.3
36
36
  [![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)
37
37
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
38
38
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
39
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
39
40
 
40
41
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
41
42
 
@@ -50,7 +51,7 @@ Self-hosted runners in AWS are useful when:
50
51
  * You need easy access to internal resources in your actions
51
52
  * You want to pre-install some software for your actions
52
53
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
53
- * You are using GitHub Enterprise Server
54
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
54
55
 
55
56
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
56
57
 
@@ -67,6 +68,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
67
68
  * [Examples](#examples)
68
69
  * [Architecture](#architecture)
69
70
  * [Troubleshooting](#troubleshooting)
71
+
72
+ * [Rebuilding runner images](#rebuilding-runner-images)
70
73
  * [Monitoring](#monitoring)
71
74
  * [Getting Help](#getting-help)
72
75
  * [Contributing](#contributing)
@@ -636,6 +639,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
636
639
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
637
640
  2. If you see too many errors, make sure you're only sending `workflow_job` events
638
641
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
642
+ 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
639
643
 
640
644
  All logs are saved in CloudWatch.
641
645
 
@@ -648,6 +652,29 @@ To get `status.json`, check out the CloudFormation stack output for a command th
648
652
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
649
653
  ```
650
654
 
655
+ ### Rebuilding runner images
656
+
657
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
658
+
659
+ ```sh
660
+ STACK=my-runners-stack
661
+ resources() {
662
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
663
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
664
+ }
665
+ for project in $(resources AWS::CodeBuild::Project); do
666
+ # skip runner projects of CodeBuild providers, we only want image builders
667
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
668
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
669
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
670
+ done
671
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
672
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
673
+ done
674
+ ```
675
+
676
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
677
+
651
678
  ## Monitoring
652
679
 
653
680
  There are three important ways to monitor your runners:
@@ -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.17.1.jsii.tgz
14
+ src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz
@@ -1,4 +1,4 @@
1
1
  aws-cdk-lib<3.0.0,>=2.239.0
2
2
  constructs<11.0.0,>=10.5.1
3
- jsii<2.0.0,>=1.139.0
3
+ jsii<2.0.0,>=1.142.0
4
4
  publication>=0.0.3