cloudsnorkel.cdk-github-runners 0.18.0__tar.gz → 0.18.1__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.1}/PKG-INFO +21 -1
  2. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/README.md +20 -0
  3. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/setup.py +2 -2
  4. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/src/cloudsnorkel/cdk_github_runners/__init__.py +49 -13
  5. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
  6. cloudsnorkel_cdk_github_runners-0.18.1/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.1.jsii.tgz +0 -0
  7. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1/src/cloudsnorkel.cdk_github_runners.egg-info}/PKG-INFO +21 -1
  8. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/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.1}/LICENSE +0 -0
  11. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/MANIFEST.in +0 -0
  12. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/pyproject.toml +0 -0
  13. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/setup.cfg +0 -0
  14. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
  15. {cloudsnorkel_cdk_github_runners-0.18.0 → cloudsnorkel_cdk_github_runners-0.18.1}/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.1}/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.1}/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.1
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
@@ -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
@@ -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.1",
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.1.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
@@ -4700,6 +4720,9 @@ class LambdaRunnerProvider(
4700
4720
 
4701
4721
  Creates a Docker-based function that gets executed for each job.
4702
4722
 
4723
+ Execution environments can be reused between jobs. All jobs that can run on the same function should be equally trusted. See
4724
+ https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
4725
+
4703
4726
  This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.
4704
4727
 
4705
4728
  :stability: experimental
@@ -5199,8 +5222,8 @@ class LogOptions:
5199
5222
  ) -> None:
5200
5223
  '''(experimental) Defines what execution history events are logged and where they are logged.
5201
5224
 
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
5225
+ :param include_execution_data: (experimental) Determines whether execution data is included in your log. Default: true
5226
+ :param level: (experimental) Defines which category of execution history events are logged. Default: ALL
5204
5227
  :param log_group_name: (experimental) The log group where the execution history events will be logged.
5205
5228
  :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
5229
 
@@ -5226,7 +5249,7 @@ class LogOptions:
5226
5249
  def include_execution_data(self) -> typing.Optional[builtins.bool]:
5227
5250
  '''(experimental) Determines whether execution data is included in your log.
5228
5251
 
5229
- :default: false
5252
+ :default: true
5230
5253
 
5231
5254
  :stability: experimental
5232
5255
  '''
@@ -5237,7 +5260,7 @@ class LogOptions:
5237
5260
  def level(self) -> typing.Optional["_aws_cdk_aws_stepfunctions_ceddda9d.LogLevel"]:
5238
5261
  '''(experimental) Defines which category of execution history events are logged.
5239
5262
 
5240
- :default: ERROR
5263
+ :default: ALL
5241
5264
 
5242
5265
  :stability: experimental
5243
5266
  '''
@@ -9927,6 +9950,9 @@ class EcsRunnerProvider(
9927
9950
  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
9951
  infrastructure to spin up.
9929
9952
 
9953
+ 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
9954
+ cluster should be equally trusted. See https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
9955
+
9930
9956
  This construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.
9931
9957
 
9932
9958
  :stability: experimental
@@ -9969,10 +9995,10 @@ class EcsRunnerProvider(
9969
9995
  :param scope: -
9970
9996
  :param id: -
9971
9997
  :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
9998
+ :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
9999
+ :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
10000
  :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
10001
+ :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
10002
  :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
10003
  :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
10004
  :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 +10293,10 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10267
10293
  :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
10294
  :param retry_options:
10269
10295
  :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
10296
+ :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
10297
+ :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
10298
  :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
10299
+ :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
10300
  :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
10301
  :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
10302
  :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 +10475,10 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10449
10475
 
10450
10476
  Make sure the AMI used by the capacity provider is compatible with ECS.
10451
10477
 
10478
+ Runner containers use bridge networking and share the instance with other jobs. Its launch template must require IMDSv2 and set the
10479
+ metadata hop limit to 1 (``requireImdsv2: true`` and ``httpPutResponseHopLimit: 1``), or jobs can take the instance role. A warning is
10480
+ added when we can't confirm both.
10481
+
10452
10482
  :default: new capacity provider
10453
10483
 
10454
10484
  :stability: experimental
@@ -10460,8 +10490,11 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10460
10490
  def cluster(self) -> typing.Optional["_aws_cdk_aws_ecs_ceddda9d.Cluster"]:
10461
10491
  '''(experimental) Existing ECS cluster to use.
10462
10492
 
10493
+ Jobs from all providers using the same cluster can share instances. Only share a cluster between providers whose jobs are equally trusted.
10494
+
10463
10495
  :default: a new cluster
10464
10496
 
10497
+ :see: https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
10465
10498
  :stability: experimental
10466
10499
  '''
10467
10500
  result = self._values.get("cluster")
@@ -10482,13 +10515,16 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10482
10515
 
10483
10516
  @builtins.property
10484
10517
  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.
10518
+ '''(experimental) Support building and running Docker images by enabling Docker-in-Docker (dind) and the required privileged mode for the runner container.
10486
10519
 
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.
10520
+ 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
10521
+ later. All jobs that can run on the same cluster should be equally trusted. Disable this if your jobs don't need Docker.
10522
+
10523
+ Disabling Docker-in-Docker can also speed up runner provisioning as the runner doesn't have to wait for Docker to boot.
10489
10524
 
10490
10525
  :default: true
10491
10526
 
10527
+ :see: https://github.com/CloudSnorkel/cdk-github-runners#job-isolation
10492
10528
  :stability: experimental
10493
10529
  '''
10494
10530
  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.1",
23
23
  __name__[0:-6],
24
- "cdk-github-runners@0.18.0.jsii.tgz",
24
+ "cdk-github-runners@0.18.1.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.1
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
@@ -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.1.jsii.tgz