cloudsnorkel.cdk-github-runners 0.14.15__tar.gz → 0.14.19__tar.gz

{cloudsnorkel_cdk_github_runners-0.14.15/src/cloudsnorkel.cdk_github_runners.egg-info → cloudsnorkel_cdk_github_runners-0.14.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloudsnorkel.cdk-github-runners
-Version: 0.14.15
+Version: 0.14.19
 Summary: CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.
 Home-page: https://github.com/CloudSnorkel/cdk-github-runners.git
 Author: Amir Szekely<amir@cloudsnorkel.com>
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aws-cdk-lib<3.0.0,>=2.155.0
 Requires-Dist: constructs<11.0.0,>=10.0.5
-Requires-Dist: jsii<2.0.0,>=1.120.0
+Requires-Dist: jsii<2.0.0,>=1.124.0
 Requires-Dist: publication>=0.0.3
 Requires-Dist: typeguard==2.13.3
 
@@ -350,11 +350,196 @@ new GitHubRunners(this, 'runners', {
 });
 ```
 
+### Composite Providers
+
+Composite providers allow you to combine multiple runner providers with different strategies. There are two types:
+
+**Fallback Strategy**: Try providers in order until one succeeds. Useful for trying spot instances first, then falling back to on-demand if spot capacity is unavailable.
+
+```python
+// Try spot instances first, fall back to on-demand if spot is unavailable
+const ecsFallback = CompositeProvider.fallback(this, 'ECS Fallback', [
+  new EcsRunnerProvider(this, 'ECS Spot', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: true,
+    // ... other config
+  }),
+  new EcsRunnerProvider(this, 'ECS On-Demand', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: false,
+    // ... other config
+  }),
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [ecsFallback],
+});
+```
+
+**Weighted Distribution Strategy**: Randomly select a provider based on weights. Useful for distributing load across multiple availability zones or instance types.
+
+```python
+// Distribute 60% of traffic to AZ-1, 40% to AZ-2
+const distributedProvider = CompositeProvider.distribute(this, 'Fargate Distribution', [
+  {
+    weight: 3, // 3/(3+2) = 60%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-1', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[0]],
+      }),
+      // ... other config
+    }),
+  },
+  {
+    weight: 2, // 2/(3+2) = 40%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-2', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[1]],
+      }),
+      // ... other config
+    }),
+  },
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [distributedProvider],
+});
+```
+
+**Important**: All providers in a composite must have the exact same labels. This ensures any provisioned runner can match the labels requested by the GitHub workflow job.
+
+### Custom Provider Selection
+
+By default, providers are selected based on label matching: the first provider that has all the labels requested by the job is selected. You can customize this behavior using a provider selector Lambda function to:
+
+* Filter out certain jobs (prevent runner provisioning)
+* Dynamically select a provider based on job characteristics (repository, branch, time of day, etc.)
+* Customize labels for the runner (add, remove, or modify labels dynamically)
+
+The selector function receives the full GitHub webhook payload, a map of all available providers and their labels, and the default provider/labels that would have been selected. It returns the provider to use (or `undefined` to skip runner creation) and the labels to assign to the runner.
+
+**Example: Route jobs to different providers based on repository**
+
+```python
+import { ComputeType } from 'aws-cdk-lib/aws-codebuild';
+import { Function, Code, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { GitHubRunners, CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners';
+
+const defaultProvider = new CodeBuildRunnerProvider(this, 'default', {
+  labels: ['custom-runner', 'default'],
+});
+const productionProvider = new CodeBuildRunnerProvider(this, 'production', {
+  labels: ['custom-runner', 'production'],
+  computeType: ComputeType.LARGE,
+});
+
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, providers, defaultProvider, defaultLabels } = event;
+
+      // Route production repos to dedicated provider
+      if (payload.repository.name.includes('prod')) {
+        return {
+          provider: '${productionProvider.node.path}',
+          labels: ['custom-runner', 'production', 'modified-via-selector'],
+        };
+      }
+
+      // Filter out draft PRs
+      if (payload.workflow_job.head_branch?.startsWith('draft/')) {
+        return { provider: undefined }; // Skip runner provisioning
+      }
+
+      // Use default for everything else
+      return {
+        provider: defaultProvider,
+        labels: defaultLabels,
+      };
+    };
+  `),
+});
+
+new GitHubRunners(this, 'runners', {
+   providers: [defaultProvider, productionProvider],
+   providerSelector: providerSelector,
+});
+```
+
+**Example: Add dynamic labels based on job metadata**
+
+```python
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, defaultProvider, defaultLabels } = event;
+
+      // Add branch name as a label
+      const branch = payload.workflow_job.head_branch || 'unknown';
+      const labels = [...(defaultLabels || []), 'branch:' + branch];
+
+      return {
+        provider: defaultProvider,
+        labels: labels,
+      };
+    };
+  `),
+});
+```
+
+**Important considerations:**
+
+* ⚠️ **Label matching responsibility**: You are responsible for ensuring the selected provider's labels match what the job requires. If labels don't match, the runner will be provisioned but GitHub Actions won't assign the job to it.
+* ⚠️ **No guarantee of assignment**: Provider selection only determines which provider will provision a runner. GitHub Actions may still route the job to any available runner with matching labels. For reliable provider assignment, consider repo-level runner registration (the default).
+* ⚡ **Performance**: The selector runs synchronously during webhook processing. Keep it fast and efficient—the webhook has a 30-second timeout total.
+
 ## Examples
 
-Beyond the code snippets above, the fullest example available is the [integration test](test/default.integ.ts).
+We provide comprehensive examples in the [`examples/`](examples/) folder to help you get started quickly:
+
+### Getting Started
+
+* **[Simple CodeBuild](examples/typescript/simple-codebuild/)** - Basic setup with just a CodeBuild provider (also available in [Python](examples/python/simple-codebuild/))
+
+### Provider Configuration
+
+* **[Composite Provider](examples/typescript/composite-provider/)** - Fallback and weighted distribution strategies (also available in [Python](examples/python/composite-provider/))
+* **[Provider Selector](examples/typescript/provider-selector/)** - Custom provider selection with Lambda function (also available in [Python](examples/python/provider-selector/))
+* **[EC2 Windows Provider](examples/typescript/ec2-windows-provider/)** - EC2 configuration for Windows runners (also available in [Python](examples/python/ec2-windows-provider/))
+
+### Compute & Performance
+
+* **[Compute Options](examples/typescript/compute-options/)** - Configure CPU, memory, and instance types for different providers (also available in [Python](examples/python/compute-options/))
+* **[Spot Instances](examples/typescript/spot-instances/)** - Use spot instances for cost savings across EC2, Fargate, and ECS (also available in [Python](examples/python/spot-instances/))
+* **[Storage Options](examples/typescript/storage-options/)** - Custom EBS storage options for EC2 runners (also available in [Python](examples/python/storage-options/))
+* **[ECS Scaling](examples/typescript/ecs-scaling/)** - Custom autoscaling group scaling policies for ECS providers (also available in [Python](examples/python/ecs-scaling/))
+
+### Security & Access
+
+* **[IAM Permissions](examples/typescript/iam-permissions/)** - Grant AWS IAM permissions to runners (also available in [Python](examples/python/iam-permissions/))
+* **[Network Access](examples/typescript/network-access/)** - Configure network access with VPCs and security groups (also available in [Python](examples/python/network-access/))
+* **[Access Control](examples/typescript/access-control/)** - Configure access control for webhook and setup functions (also available in [Python](examples/python/access-control/))
+
+### Customization
+
+* **[Add Software](examples/typescript/add-software/)** - Add custom software to runner images (also available in [Python](examples/python/add-software/))
+
+### Enterprise & Monitoring
+
+* **[GHES](examples/typescript/ghes/)** - Configure runners for GitHub Enterprise Server (also available in [Python](examples/python/ghes/))
+* **[Monitoring](examples/typescript/monitoring/)** - Set up CloudWatch alarms and SNS notifications (also available in [Python](examples/python/monitoring/))
+
+Each example is self-contained with its own dependencies and README. Start with the simple examples and work your way up to more advanced configurations.
+
+Another good and very full example is the [integration test](test/default.integ.ts).
 
-If you have more to share, please open a PR adding them to the `examples` folder.
+If you have more to share, please open a PR adding examples to the `examples` folder.
 
 ## Architecture
 

{cloudsnorkel_cdk_github_runners-0.14.15 → cloudsnorkel_cdk_github_runners-0.14.19}/README.md

@@ -323,11 +323,196 @@ new GitHubRunners(this, 'runners', {
 });
 ```
 
+### Composite Providers
+
+Composite providers allow you to combine multiple runner providers with different strategies. There are two types:
+
+**Fallback Strategy**: Try providers in order until one succeeds. Useful for trying spot instances first, then falling back to on-demand if spot capacity is unavailable.
+
+```python
+// Try spot instances first, fall back to on-demand if spot is unavailable
+const ecsFallback = CompositeProvider.fallback(this, 'ECS Fallback', [
+  new EcsRunnerProvider(this, 'ECS Spot', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: true,
+    // ... other config
+  }),
+  new EcsRunnerProvider(this, 'ECS On-Demand', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: false,
+    // ... other config
+  }),
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [ecsFallback],
+});
+```
+
+**Weighted Distribution Strategy**: Randomly select a provider based on weights. Useful for distributing load across multiple availability zones or instance types.
+
+```python
+// Distribute 60% of traffic to AZ-1, 40% to AZ-2
+const distributedProvider = CompositeProvider.distribute(this, 'Fargate Distribution', [
+  {
+    weight: 3, // 3/(3+2) = 60%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-1', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[0]],
+      }),
+      // ... other config
+    }),
+  },
+  {
+    weight: 2, // 2/(3+2) = 40%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-2', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[1]],
+      }),
+      // ... other config
+    }),
+  },
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [distributedProvider],
+});
+```
+
+**Important**: All providers in a composite must have the exact same labels. This ensures any provisioned runner can match the labels requested by the GitHub workflow job.
+
+### Custom Provider Selection
+
+By default, providers are selected based on label matching: the first provider that has all the labels requested by the job is selected. You can customize this behavior using a provider selector Lambda function to:
+
+* Filter out certain jobs (prevent runner provisioning)
+* Dynamically select a provider based on job characteristics (repository, branch, time of day, etc.)
+* Customize labels for the runner (add, remove, or modify labels dynamically)
+
+The selector function receives the full GitHub webhook payload, a map of all available providers and their labels, and the default provider/labels that would have been selected. It returns the provider to use (or `undefined` to skip runner creation) and the labels to assign to the runner.
+
+**Example: Route jobs to different providers based on repository**
+
+```python
+import { ComputeType } from 'aws-cdk-lib/aws-codebuild';
+import { Function, Code, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { GitHubRunners, CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners';
+
+const defaultProvider = new CodeBuildRunnerProvider(this, 'default', {
+  labels: ['custom-runner', 'default'],
+});
+const productionProvider = new CodeBuildRunnerProvider(this, 'production', {
+  labels: ['custom-runner', 'production'],
+  computeType: ComputeType.LARGE,
+});
+
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, providers, defaultProvider, defaultLabels } = event;
+
+      // Route production repos to dedicated provider
+      if (payload.repository.name.includes('prod')) {
+        return {
+          provider: '${productionProvider.node.path}',
+          labels: ['custom-runner', 'production', 'modified-via-selector'],
+        };
+      }
+
+      // Filter out draft PRs
+      if (payload.workflow_job.head_branch?.startsWith('draft/')) {
+        return { provider: undefined }; // Skip runner provisioning
+      }
+
+      // Use default for everything else
+      return {
+        provider: defaultProvider,
+        labels: defaultLabels,
+      };
+    };
+  `),
+});
+
+new GitHubRunners(this, 'runners', {
+   providers: [defaultProvider, productionProvider],
+   providerSelector: providerSelector,
+});
+```
+
+**Example: Add dynamic labels based on job metadata**
+
+```python
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, defaultProvider, defaultLabels } = event;
+
+      // Add branch name as a label
+      const branch = payload.workflow_job.head_branch || 'unknown';
+      const labels = [...(defaultLabels || []), 'branch:' + branch];
+
+      return {
+        provider: defaultProvider,
+        labels: labels,
+      };
+    };
+  `),
+});
+```
+
+**Important considerations:**
+
+* ⚠️ **Label matching responsibility**: You are responsible for ensuring the selected provider's labels match what the job requires. If labels don't match, the runner will be provisioned but GitHub Actions won't assign the job to it.
+* ⚠️ **No guarantee of assignment**: Provider selection only determines which provider will provision a runner. GitHub Actions may still route the job to any available runner with matching labels. For reliable provider assignment, consider repo-level runner registration (the default).
+* ⚡ **Performance**: The selector runs synchronously during webhook processing. Keep it fast and efficient—the webhook has a 30-second timeout total.
+
 ## Examples
 
-Beyond the code snippets above, the fullest example available is the [integration test](test/default.integ.ts).
+We provide comprehensive examples in the [`examples/`](examples/) folder to help you get started quickly:
+
+### Getting Started
+
+* **[Simple CodeBuild](examples/typescript/simple-codebuild/)** - Basic setup with just a CodeBuild provider (also available in [Python](examples/python/simple-codebuild/))
+
+### Provider Configuration
+
+* **[Composite Provider](examples/typescript/composite-provider/)** - Fallback and weighted distribution strategies (also available in [Python](examples/python/composite-provider/))
+* **[Provider Selector](examples/typescript/provider-selector/)** - Custom provider selection with Lambda function (also available in [Python](examples/python/provider-selector/))
+* **[EC2 Windows Provider](examples/typescript/ec2-windows-provider/)** - EC2 configuration for Windows runners (also available in [Python](examples/python/ec2-windows-provider/))
+
+### Compute & Performance
+
+* **[Compute Options](examples/typescript/compute-options/)** - Configure CPU, memory, and instance types for different providers (also available in [Python](examples/python/compute-options/))
+* **[Spot Instances](examples/typescript/spot-instances/)** - Use spot instances for cost savings across EC2, Fargate, and ECS (also available in [Python](examples/python/spot-instances/))
+* **[Storage Options](examples/typescript/storage-options/)** - Custom EBS storage options for EC2 runners (also available in [Python](examples/python/storage-options/))
+* **[ECS Scaling](examples/typescript/ecs-scaling/)** - Custom autoscaling group scaling policies for ECS providers (also available in [Python](examples/python/ecs-scaling/))
+
+### Security & Access
+
+* **[IAM Permissions](examples/typescript/iam-permissions/)** - Grant AWS IAM permissions to runners (also available in [Python](examples/python/iam-permissions/))
+* **[Network Access](examples/typescript/network-access/)** - Configure network access with VPCs and security groups (also available in [Python](examples/python/network-access/))
+* **[Access Control](examples/typescript/access-control/)** - Configure access control for webhook and setup functions (also available in [Python](examples/python/access-control/))
+
+### Customization
+
+* **[Add Software](examples/typescript/add-software/)** - Add custom software to runner images (also available in [Python](examples/python/add-software/))
+
+### Enterprise & Monitoring
+
+* **[GHES](examples/typescript/ghes/)** - Configure runners for GitHub Enterprise Server (also available in [Python](examples/python/ghes/))
+* **[Monitoring](examples/typescript/monitoring/)** - Set up CloudWatch alarms and SNS notifications (also available in [Python](examples/python/monitoring/))
+
+Each example is self-contained with its own dependencies and README. Start with the simple examples and work your way up to more advanced configurations.
+
+Another good and very full example is the [integration test](test/default.integ.ts).
 
-If you have more to share, please open a PR adding them to the `examples` folder.
+If you have more to share, please open a PR adding examples to the `examples` folder.
 
 ## Architecture
 

{cloudsnorkel_cdk_github_runners-0.14.15 → cloudsnorkel_cdk_github_runners-0.14.19}/setup.py

@@ -5,7 +5,7 @@ kwargs = json.loads(
     """
 {
     "name": "cloudsnorkel.cdk-github-runners",
-    "version": "0.14.15",
+    "version": "0.14.19",
     "description": "CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.",
     "license": "Apache-2.0",
     "url": "https://github.com/CloudSnorkel/cdk-github-runners.git",
@@ -26,7 +26,7 @@ kwargs = json.loads(
     ],
     "package_data": {
         "cloudsnorkel.cdk_github_runners._jsii": [
-            "cdk-github-runners@0.14.15.jsii.tgz"
+            "cdk-github-runners@0.14.19.jsii.tgz"
         ],
         "cloudsnorkel.cdk_github_runners": [
             "py.typed"
@@ -36,7 +36,7 @@ kwargs = json.loads(
     "install_requires": [
         "aws-cdk-lib>=2.155.0, <3.0.0",
         "constructs>=10.0.5, <11.0.0",
-        "jsii>=1.120.0, <2.0.0",
+        "jsii>=1.124.0, <2.0.0",
         "publication>=0.0.3",
         "typeguard==2.13.3"
     ],