feat(examples): add multi-runner-v2 example

.github/workflows/terraform.yml

@@ -155,6 +155,7 @@ jobs:
             "ephemeral",
             "termination-watcher",
             "multi-runner",
+            "multi-runner-v2",
             "external-managed-ssm-secrets"
           ]
     defaults:

docs/examples/index.md

@@ -5,6 +5,7 @@ Examples are located in the [examples](https://github.com/github-aws-runners/ter
 - _[Default](default.md)_: The default example of the module
 - _[Ephemeral](ephemeral.md)_: Example usages of ephemeral runners based on the default example.
 - _[Multi Runner](multi-runner.md)_ : Example usage of creating a multi runner which creates multiple runners/ configurations with a single deployment. The examples including: "arm64", "windows", and "ubuntu" runners.
+- _[Multi Runner v2](multi-runner-v2.md)_ : Example usage of the experimental v2 multi-runner configuration interface with shared defaults and per-lane overrides.
 - _[Permissions boundary](permissions-boundary.md)_: Example usages of permissions boundaries.
 - _[Prebuilt Images](prebuilt.md)_: Example usages of deploying runners with a custom prebuilt image.
 - _[Termination watcher](termination-watcher.md)_: Example usages of termination watcher.

docs/examples/multi-runner-v2.md

@@ -0,0 +1 @@
+--8<-- "examples/multi-runner-v2/README.md"

examples/multi-runner-v2/README.md

@@ -0,0 +1,74 @@
+# Multi-runner v2 example
+
+This example demonstrates the experimental multi-runner v2 interface. Shared
+defaults are configured with `experimental_global_config*` variables, while
+each runner lane uses `experimental_multi_runner_config` for its matcher,
+runner lifecycle, and compute-provider settings.
+
+The example creates three lanes from one deployment:
+
+- Linux ARM64 Amazon Linux runners.
+- Ephemeral Linux x64 Amazon Linux runners with job retry enabled.
+- Windows x64 Server Core 2022 runners.
+
+The v2 interface keeps provider-owned settings inside the selected provider
+configuration. For example, VPC and subnet settings are under
+`experimental_global_config_compute_provider.aws.ec2`, while the per-lane
+instance types and AMI filter are under each lane's compute provider block.
+
+Configure the GitHub App variables before applying:
+
+```bash
+terraform init
+terraform apply \
+  -var='github_app={id="123456",key_base64="..."}'
+```
+
+The `github_app` value is sensitive and should be supplied through a secure
+variable source in real deployments rather than committed to configuration.
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
+| <a name="requirement_local"></a> [local](#requirement\_local) | ~> 2.0 |
+| <a name="requirement_random"></a> [random](#requirement\_random) | ~> 3.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_random"></a> [random](#provider\_random) | 3.9.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_base"></a> [base](#module\_base) | ../base | n/a |
+| <a name="module_runners"></a> [runners](#module\_runners) | ../../modules/multi-runner | n/a |
+| <a name="module_webhook_github_app"></a> [webhook\_github\_app](#module\_webhook\_github\_app) | ../../modules/webhook-github-app | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [random_id.random](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/id) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region to deploy to. | `string` | `"eu-west-1"` | no |
+| <a name="input_environment"></a> [environment](#input\_environment) | Environment name, used as prefix. | `string` | `null` | no |
+| <a name="input_github_app"></a> [github\_app](#input\_github\_app) | GitHub App ID and base64-encoded private key. | <pre>object({<br/>    id         = string<br/>    key_base64 = string<br/>  })</pre> | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_webhook_endpoint"></a> [webhook\_endpoint](#output\_webhook\_endpoint) | n/a |
+| <a name="output_webhook_secret"></a> [webhook\_secret](#output\_webhook\_secret) | n/a |
+<!-- END_TF_DOCS -->

examples/multi-runner-v2/main.tf

@@ -0,0 +1,173 @@
+locals {
+  environment = var.environment != null ? var.environment : "multi-runner-v2"
+  aws_region  = var.aws_region
+}
+
+resource "random_id" "random" {
+  byte_length = 20
+}
+
+module "base" {
+  source = "../base"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+}
+
+module "runners" {
+  source = "../../modules/multi-runner"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+
+  experimental_global_config = {
+    tags = {
+      Example = local.environment
+      Project = "ProjectX"
+    }
+    runner = {
+      os           = "linux"
+      architecture = "x64"
+      extra_labels = ["v2"]
+    }
+  }
+
+  experimental_global_config_github = {
+    app = {
+      key_base64     = var.github_app.key_base64
+      id             = var.github_app.id
+      webhook_secret = random_id.random.hex
+    }
+  }
+
+  experimental_global_config_lambda = {
+    architecture = "arm64"
+  }
+
+  experimental_global_config_orchestration_provider = {
+    webhook = {
+      eventbridge = {
+        enabled       = true
+        accept_events = ["workflow_job"]
+      }
+    }
+  }
+
+  experimental_global_config_compute_provider = {
+    aws = {
+      ec2 = {
+        vpc_id      = module.base.vpc.vpc_id
+        subnet_ids  = module.base.vpc.private_subnets
+        ssm_enabled = true
+        runner_binaries = {
+          enabled = true
+        }
+      }
+    }
+  }
+
+  experimental_multi_runner_config = {
+    linux-arm64 = {
+      runner = {
+        architecture = "arm64"
+        name_prefix  = "amazon-arm64-"
+        extra_labels = ["amazon"]
+      }
+      orchestration_provider = {
+        webhook = {
+          runner = {
+            maximum_count = 1
+          }
+          matcherConfig = {
+            exactMatch    = true
+            labelMatchers = [["self-hosted", "linux", "arm64", "amazon"]]
+          }
+        }
+      }
+      compute_provider = {
+        aws = {
+          ec2 = {
+            instance_types = ["t4g.large", "c6g.large"]
+          }
+        }
+      }
+    }
+
+    linux-x64 = {
+      runner = {
+        name_prefix  = "amazon-x64-"
+        extra_labels = ["amazon"]
+      }
+      orchestration_provider = {
+        webhook = {
+          runner = {
+            ephemeral     = true
+            maximum_count = 1
+          }
+          matcherConfig = {
+            labelMatchers = [["self-hosted", "linux", "x64", "amazon"]]
+            exactMatch    = false
+            priority      = 1
+          }
+          queue = {
+            delay_webhook_event = 0
+          }
+          job_retry = {
+            enabled = true
+          }
+        }
+      }
+      compute_provider = {
+        aws = {
+          ec2 = {
+            instance_types = ["m5a.large", "m5ad.large"]
+          }
+        }
+      }
+    }
+
+    windows-x64 = {
+      runner = {
+        os          = "windows"
+        name_prefix = "windows-x64-"
+      }
+      orchestration_provider = {
+        webhook = {
+          runner = {
+            boot_time_in_minutes = 20
+            maximum_count        = 1
+          }
+          matcherConfig = {
+            exactMatch    = true
+            labelMatchers = [["self-hosted", "windows", "x64", "servercore-2022"]]
+          }
+        }
+      }
+      compute_provider = {
+        aws = {
+          ec2 = {
+            instance_types = ["m5.large", "c5.large"]
+            ami = {
+              filter = {
+                name  = ["Windows_Server-2022-English-Full-ECS_Optimized-*"]
+                state = ["available"]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+module "webhook_github_app" {
+  source     = "../../modules/webhook-github-app"
+  depends_on = [module.runners]
+
+  github_app = {
+    key_base64     = var.github_app.key_base64
+    id             = var.github_app.id
+    webhook_secret = random_id.random.hex
+  }
+  webhook_endpoint = module.runners.webhook.endpoint
+}

examples/multi-runner-v2/outputs.tf

@@ -0,0 +1,8 @@
+output "webhook_endpoint" {
+  value = module.runners.webhook.endpoint
+}
+
+output "webhook_secret" {
+  sensitive = true
+  value     = random_id.random.hex
+}

examples/multi-runner-v2/providers.tf

@@ -0,0 +1,9 @@
+provider "aws" {
+  region = local.aws_region
+
+  default_tags {
+    tags = {
+      Example = local.environment
+    }
+  }
+}

examples/multi-runner-v2/variables.tf

@@ -0,0 +1,23 @@
+variable "github_app" {
+  description = "GitHub App ID and base64-encoded private key."
+
+  type = object({
+    id         = string
+    key_base64 = string
+  })
+  sensitive = true
+}
+
+variable "environment" {
+  description = "Environment name, used as prefix."
+
+  type    = string
+  default = null
+}
+
+variable "aws_region" {
+  description = "AWS region to deploy to."
+
+  type    = string
+  default = "eu-west-1"
+}