feat(examples): demonstrate scale-set orchestration

.github/workflows/terraform.yml

@@ -156,7 +156,8 @@ jobs:
             "termination-watcher",
             "multi-runner",
             "multi-runner-v2",
-            "external-managed-ssm-secrets"
+            "external-managed-ssm-secrets",
+            "multi-runner-scale-set"
           ]
     defaults:
       run:

examples/multi-runner-scale-set/README.md

@@ -0,0 +1,83 @@
+# Multi-runner scale-set 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 four lanes from one deployment:
+
+- Linux ARM64 Amazon Linux runners.
+- Ephemeral Linux x64 Amazon Linux runners with job retry enabled.
+- Linux x64 runners managed by a GitHub Actions scale set.
+- 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.
+
+The scale-set lane uses `orchestration_provider.scale_set`. Its controller
+network is configured under the global scale-set block and its GitHub
+installation ID is read from the SSM parameter described by `var.scale_set`.
+
+Configure the GitHub App variables before applying:
+
+```bash
+terraform init
+terraform apply \
+  -var='github_app={id="123456",key_base64="..."}' \
+  -var='scale_set={config_url="https://github.com/example" installation_id_ssm={name="/github/scale-set/installation-id",arn="arn:aws:ssm:eu-west-1:123456789012:parameter/github/scale-set/installation-id"} name="linux-scale-set" id=123}'
+```
+
+The `github_app` value is sensitive and should be supplied through a secure
+variable source in real deployments rather than committed to configuration.
+The scale-set installation ID must already exist in the referenced SSM
+parameter and the GitHub App must be installed for the configured URL.
+
+<!-- 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 |
+| <a name="input_scale_set"></a> [scale\_set](#input\_scale\_set) | GitHub Actions scale-set configuration. | <pre>object({<br/>    config_url = string<br/>    installation_id_ssm = object({<br/>      arn  = string<br/>      name = string<br/>    })<br/>    name            = string<br/>    id              = number<br/>    runner_group_id = optional(number)<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-scale-set/main.tf

@@ -0,0 +1,210 @@
+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"]
+      }
+    }
+    scale_set = {
+      grouping = {
+        strategy = "runner_config"
+      }
+      network = {
+        vpc_id     = module.base.vpc.vpc_id
+        subnet_ids = module.base.vpc.private_subnets
+      }
+    }
+  }
+
+  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"]
+          }
+        }
+      }
+    }
+
+    linux-scale-set = {
+      runner = {
+        name_prefix  = "scale-set-"
+        extra_labels = ["scale-set"]
+      }
+      orchestration_provider = {
+        scale_set = {
+          github = {
+            config_url          = var.scale_set.config_url
+            installation_id_ssm = var.scale_set.installation_id_ssm
+          }
+          name            = var.scale_set.name
+          id              = var.scale_set.id
+          runner_group_id = var.scale_set.runner_group_id
+          min_runners     = 0
+          max_runners     = 10
+          work_folder     = "_work/scale-set"
+        }
+      }
+      compute_provider = {
+        aws = {
+          ec2 = {
+            instance_types = ["m5.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
+}