Major upgrade, ongoing

Author: sdarwin

examples/multi-runner-cppal/README.md

@@ -2,10 +2,11 @@
 
 This module shows how to create GitHub action runners with multiple runner configuration together in one deployment. This example has the configurations for the following runner types with the relevant labels supported by them as matchers:
 
-- Linux ARM64 `["self-hosted", "linux", "arm64", "amazon"]`
-- Linux Ubuntu `["self-hosted", "linux", "x64", "ubuntu-latest"]` or `["self-hosted", "linux", "x64", "ubuntu-2204"]``
-- Linux X64 `["self-hosted", "linux", "x64", "amazon"]`
-- Windows X64 `["self-hosted", "windows", "x64", "servercore-2022"]`
+- Linux ARM64 `["self-hosted", "linux", "arm64", "amazon"]`: Amazon Linux ARM64 non ephemeral runner based on module defaults
+- Linux Ubuntu 24.04 `["self-hosted", "linux", "x64", "ubuntu-latest"]` or `["self-hosted", "linux", "x64", "ubuntu-2404"]`: Ubuntu runners non ephemeral based on a custom start script.
+- Linux Ubuntu 22.04 `["self-hosted", "linux", "x64", "ubuntu-2204"]`: Ubuntu runners non ephemeral based on a custom start script.
+- Linux X64 `["self-hosted", "linux", "x64", "amazon"]`: Amazon X64 Linux runners ephemeral with retry enabled.
+- Windows X64 `["self-hosted", "windows", "x64", "servercore-2022"]`: Windows X64 Servercore 2022 runners non ephemeral based on a custom start script.
 
 The module will decide the runner for the workflow job based on the match in the labels defined in the workflow job and runner configuration. Also the runner configuration allows the match to be exact or non-exact match. We recommend to use only exact matches.
 
@@ -21,9 +22,9 @@ Per combination of OS and architecture a lambda distribution syncer will be crea
 
 ## Usages
 
-Steps for the full setup, such as creating a GitHub app can be found in the root module's [README](../../README.md). First download the Lambda releases from GitHub. Alternatively you can build the lambdas locally with Node or Docker, there is a simple build script in `<root>/.ci/build.sh`. In the `main.tf` you can simply remove the location of the lambda zip files, the default location will work in this case.
+Steps for the full setup, such as creating a GitHub app can be found the [docs](https://github-aws-runners.github.io/terraform-aws-github-runner/). First download the Lambda releases from GitHub. Alternatively you can build the lambdas locally with Node or Docker, there is a simple build script in `<root>/.ci/build.sh`. In the `main.tf` you can simply remove the location of the lambda zip files, the default location will work in this case.
 
-> Ensure you have set the version in `lambdas-download/main.tf` for running the example. The version needs to be set to a GitHub release version, see https://github.com/philips-labs/terraform-aws-github-runner/releases
+> The default example assumes local built lambda's available. Ensure you have built the lambda's. Alternatively you can download the lambda's. The version needs to be set to a GitHub release version, see https://github.com/github-aws-runners/terraform-aws-github-runner/releases
 
 ```bash
 cd ../lambdas-download
@@ -32,61 +33,68 @@ terraform apply -var=module_version=<VERSION>
 cd -
 ```
 
-Before running Terraform, ensure the GitHub app is configured. See the [configuration details](../../README.md#usages) for more details.
+
+Before running Terraform, ensure the GitHub app is configured. See the [configuration details](https://github-aws-runners.github.io/terraform-aws-github-runner/configuration/) for more details.
 
 ```bash
 terraform init
 terraform apply
 ```
 
-You can receive the webhook details by running:
+The example will try to update the webhook of your GitHub. In case the update fails the apply will not fail. You can receive the webhook details by running:
 
 ```bash
 terraform output -raw webhook_secret
 ```
 
-Be-aware some shells will print some end of line character `%`.
-
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.27 |
 | <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.4.3 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 5.82.1 |
+| <a name="provider_random"></a> [random](#provider\_random) | 3.6.3 |
 
 ## Modules
 
 | Name | Source | Version |
 |------|--------|---------|
-| <a name="module_multi-runner"></a> [multi-runner](#module\_multi-runner) | ../../modules/multi-runner | n/a |
-| <a name="module_vpc"></a> [vpc](#module\_vpc) | terraform-aws-modules/vpc/aws | 3.11.2 |
+| <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 |
 |------|------|
+| [aws_ssm_parameter.al2023_arm64](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter) | resource |
 | [random_id.random](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/id) | resource |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [aws_ssm_parameter.al2023_arm64](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | data source |
+| [aws_ssm_parameter.al2023_x64](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | data source |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_environment"></a> [environment](#input\_environment) | n/a | `string` | `null` | no |
-| <a name="input_github_app"></a> [github\_app](#input\_github\_app) | GitHub for API usages. | <pre>object({<br>    id         = string<br>    key_base64 = string<br>  })</pre> | n/a | yes |
+| <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 for API usages. | <pre>object({<br/>    id         = string<br/>    key_base64 = string<br/>  })</pre> | n/a | yes |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
+| <a name="output_deprecated_variables_warning"></a> [deprecated\_variables\_warning](#output\_deprecated\_variables\_warning) | n/a |
 | <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 -->
+<!-- END_TF_DOCS -->

examples/multi-runner-cppal/main.tf

@@ -1,9 +1,69 @@
+# The module provides several ways to chose the AMI ID for the runners. The recommended way is to use the SSM parameter ARN.
+# The default is (still) a build in filter that creates internally an SSM parameter for the AMI ID.
+#
+# Here we show two other options
+# 1. Use the SSM parameter ARN directly via a public available SSM parameter
+# 2. Use the SSM parameter ARN via a private SSM parameter injected to the module
+# 3. Other runners like ubuntu, windows, etc. are using the build in one parameter.
+
+data "aws_ssm_parameter" "al2023_x64" {
+  name = "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64"
+}
+
+data "aws_ssm_parameter" "al2023_arm64" {
+  name = "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64"
+}
+
+resource "aws_ssm_parameter" "al2023_arm64" {
+  name      = local.al2023_arm64_name
+  type      = "String"
+  data_type = "aws:ec2:image"
+  value     = data.aws_ssm_parameter.al2023_arm64.value
+}
+
+data "aws_caller_identity" "current" {}
+
 locals {
   environment = var.environment != null ? var.environment : "gha"
   aws_region  = var.aws_region
 
+  # create map only with amazon linux 2023 x64 and arm64 to overwrite the default
+  al2023_arm64_name = "/examples/multi-runner/aws-github-runners/ami/amazon-linux-2023-arm64"
+  ssm_ami_arns = {
+    "linux-x64" = data.aws_ssm_parameter.al2023_x64.arn
+    # construct the arn to avoid terraform count errors
+    "linux-arm64" = "arn:aws:ssm:${var.aws_region}:${data.aws_caller_identity.current.account_id}:parameter${local.al2023_arm64_name}"
+  }
+
   # Load runner configurations from Yaml files
-  multi_runner_config = { for c in fileset("${path.module}/templates/runner-configs", "*.yaml") : trimsuffix(c, ".yaml") => yamldecode(file("${path.module}/templates/runner-configs/${c}")) }
+  multi_runner_config_files = {
+    for c in fileset("${path.module}/templates/runner-configs", "*.yaml") :
+
+    trimsuffix(c, ".yaml") => yamldecode(file("${path.module}/templates/runner-configs/${c}"))
+  }
+
+  multi_runner_config = {
+    for k, v in local.multi_runner_config_files :
+
+    k => merge(
+      v,
+      {
+        runner_config = merge(
+          v.runner_config,
+          {
+            subnet_ids = lookup(v.runner_config, "subnet_ids", null) != null ? [module.base.vpc.private_subnets[0]] : null
+            vpc_id     = lookup(v.runner_config, "vpc_id", null) != null ? module.base.vpc.vpc_id : null
+            ami = contains(keys(v.runner_config), "ami") ? merge(
+              v.runner_config.ami,
+              {
+                id_ssm_parameter_arn = lookup(local.ssm_ami_arns, k, null) != null ? local.ssm_ami_arns[k] : null
+              }
+            ) : null
+          }
+        )
+      }
+    )
+  }
 }
 
 resource "random_id" "random" {
@@ -17,7 +77,7 @@ module "base" {
   aws_region = local.aws_region
 }
 
-module "multi-runner" {
+module "runners" {
   source              = "../../modules/multi-runner"
   multi_runner_config = local.multi_runner_config
   #  Alternative to loading runner configuration from Yaml files is using static configuration:
@@ -27,7 +87,6 @@ module "multi-runner" {
   #        labelMatchers = [["self-hosted", "linux", "x64", "amazon"]]
   #        exactMatch    = false
   #      }
-  #      fifo                = true
   #      delay_webhook_event = 0
   #      runner_config = {
   #        runner_os                       = "linux"
@@ -36,7 +95,7 @@ module "multi-runner" {
   #        create_service_linked_role_spot = true
   #        enable_ssm_on_runners           = true
   #        instance_types                  = ["m5ad.large", "m5a.large"]
-  #        runner_extra_labels             = "amazon"
+  #        runner_extra_labels             = ["amazon"]
   #        runners_maximum_count           = 1
   #        enable_ephemeral_runners        = true
   #        scale_down_schedule_expression  = "cron(* * * * ? *)"
@@ -59,15 +118,52 @@ module "multi-runner" {
     webhook_secret = random_id.random.hex
   }
 
+  # Deploy webhook using the EventBridge
+  eventbridge = {
+    enable = true
+    # adjust the allow events to only allow specific events, like workflow_job
+    accept_events = ["workflow_job"]
+  }
+
+  # enable this section for tracing
+  # tracing_config = {
+  #   mode                  = "Active"
+  #   capture_error         = true
+  #   capture_http_requests = true
+  # }
   # Assuming local build lambda's to use pre build ones, uncomment the lines below and download the
   # lambda zip files lambda_download
   webhook_lambda_zip                = "../lambdas-download-cppal/webhook.zip"
   runner_binaries_syncer_lambda_zip = "../lambdas-download-cppal/runner-binaries-syncer.zip"
   runners_lambda_zip                = "../lambdas-download-cppal/runners.zip"
 
-  # enable_workflow_job_events_queue = true
-  # override delay of events in seconds
-
   # Enable debug logging for the lambda functions
   # log_level = "debug"
+
+  # Enable to track the spot instance termination warning
+  # instance_termination_watcher = {
+  #   enable         = true
+  # }
+
+  # Enable metrics
+  # metrics = {
+  #   enable = true
+  #   metric = {
+  #     enable_github_app_rate_limit    = true
+  #     enable_job_retry                = false
+  #     enable_spot_termination_warning = true
+  #   }
+  # }
+}
+
+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-cppal/outputs.tf

@@ -1,8 +1,14 @@
 output "webhook_endpoint" {
-  value = module.multi-runner.webhook.endpoint
+  value = module.runners.webhook.endpoint
 }
 
 output "webhook_secret" {
   sensitive = true
   value     = random_id.random.hex
 }
+
+output "deprecated_variables_warning" {
+  value = join("", [
+    module.runners.deprecated_variables_warning,
+  ])
+}

examples/multi-runner-cppal/providers.tf

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

examples/multi-runner-cppal/templates/runner-configs/ubuntu-bionic-arm64.yaml

@@ -15,7 +15,7 @@ runner_config:
   enable_userdata: false
   runner_os: linux
   runner_architecture: arm64
-  runner_extra_labels: "ubuntu-18.04-aws"
+  runner_extra_labels: ["ubuntu-18.04-aws"]
   runner_run_as: ubuntu
   runner_name_prefix: ubuntu-1804-arm64_
   enable_ssm_on_runners: true
@@ -27,8 +27,9 @@ runner_config:
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
   # userdata_template: ./templates/user-data.sh
-  ami_owners: [ "047402373783" ]
-  ami_filter: { 'name': ['github-runner-ubuntu-bionic-arm64-202410151633'] }
+  ami:
+    owners: [ "047402373783" ]
+    filter: { 'name': ['github-runner-ubuntu-bionic-arm64-202410151633'] }
   block_device_mappings:
     - device_name: /dev/sda1
       delete_on_termination: true

examples/multi-runner-cppal/templates/runner-configs/ubuntu-bionic.yaml

@@ -15,7 +15,7 @@ runner_config:
   enable_userdata: false
   runner_os: linux
   runner_architecture: x64
-  runner_extra_labels: "ubuntu-18.04-aws"
+  runner_extra_labels: ["ubuntu-18.04-aws"]
   runner_run_as: ubuntu
   runner_name_prefix: ubuntu-1804-x64_
   enable_ssm_on_runners: true
@@ -27,8 +27,9 @@ runner_config:
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
   # userdata_template: ./templates/user-data.sh
-  ami_owners: [ "047402373783" ]
-  ami_filter: { 'name': ['github-runner-ubuntu-bionic-amd64-202411261305'] }
+  ami:
+    owners: [ "047402373783" ]
+    filter: { 'name': ['github-runner-ubuntu-bionic-amd64-202411261305'] }
   block_device_mappings:
     - device_name: /dev/sda1
       delete_on_termination: true

examples/multi-runner-cppal/templates/runner-configs/ubuntu-focal-arm64.yaml

@@ -15,7 +15,7 @@ runner_config:
   enable_userdata: false
   runner_os: linux
   runner_architecture: arm64
-  runner_extra_labels: "ubuntu-20.04-aws"
+  runner_extra_labels: ["ubuntu-20.04-aws"]
   runner_run_as: ubuntu
   runner_name_prefix: ubuntu-2004-arm64_
   enable_ssm_on_runners: true
@@ -27,8 +27,9 @@ runner_config:
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
   # userdata_template: ./templates/user-data.sh
-  ami_owners: [ "047402373783" ]
-  ami_filter: { 'name': ['github-runner-ubuntu-focal-arm64-202410151633'] }
+  ami:
+    owners: [ "047402373783" ]
+    filter: { 'name': ['github-runner-ubuntu-focal-arm64-202410151633'] }
   block_device_mappings:
     - device_name: /dev/sda1
       delete_on_termination: true

examples/multi-runner-cppal/templates/runner-configs/ubuntu-focal.yaml

@@ -15,7 +15,7 @@ runner_config:
   enable_userdata: false
   runner_os: linux
   runner_architecture: x64
-  runner_extra_labels: "ubuntu-20.04-aws"
+  runner_extra_labels: ["ubuntu-20.04-aws"]
   runner_run_as: ubuntu
   runner_name_prefix: ubuntu-2004-x64_
   enable_ssm_on_runners: true
@@ -27,8 +27,9 @@ runner_config:
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
   # userdata_template: ./templates/user-data.sh
-  ami_owners: [ "047402373783" ]
-  ami_filter: { 'name': ['github-runner-ubuntu-focal-amd64-202411261305'] }
+  ami:
+    owners: [ "047402373783" ]
+    filter: { 'name': ['github-runner-ubuntu-focal-amd64-202411261305'] }
   block_device_mappings:
     - device_name: /dev/sda1
       delete_on_termination: true

examples/multi-runner-cppal/templates/runner-configs/ubuntu-jammy-arm64.yaml

@@ -16,7 +16,7 @@ runner_config:
   enable_userdata: false
   runner_os: linux
   runner_architecture: arm64
-  runner_extra_labels: "ubuntu-latest-aws,ubuntu-22.04-aws"
+  runner_extra_labels: ["ubuntu-latest-aws,ubuntu-22.04-aws"]
   runner_run_as: ubuntu
   runner_name_prefix: ubuntu-2204-arm64_
   enable_ssm_on_runners: true
@@ -28,8 +28,9 @@ runner_config:
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
   # userdata_template: ./templates/user-data.sh
-  ami_owners: [ "047402373783" ]
-  ami_filter: { 'name': ['github-runner-ubuntu-jammy-arm64-202410151633'] }
+  ami:
+    owners: [ "047402373783" ]
+    filter: { 'name': ['github-runner-ubuntu-jammy-arm64-202410151633'] }
   block_device_mappings:
     - device_name: /dev/sda1
       delete_on_termination: true