Introduce object to configure eventbridge

Author: npalm

docs/configuration.md

@@ -6,7 +6,7 @@ To be able to support a number of use-cases, the module has quite a lot of confi
 
 - Org vs Repo level. You can configure the module to connect the runners in GitHub on an org level and share the runners in your org, or set the runners on repo level and the module will install the runner to the repo. There can be multiple repos but runners are not shared between repos.
 - Multi-Runner module. This modules allows you to create multiple runner configurations with a single webhook and single GitHub App to simplify deployment of different types of runners. Check the detailed module [documentation](modules/public/multi-runner.md) for more information or checkout the [multi-runner example](examples/multi-runner.md).
-- Webhook mode, the module can be deployed in the mode `direct` and `eventbridge`. The `direct` mode is the default and will directly distribute to SQS for the scale-up lambda. The `eventbridge` mode will publish the event to an event bus with a target rule the events are sent to a dispatch lambda. The dispatch lambda will send the event to the SQS queue. The `eventbridge` mode is useful when you want to have more control over the events and potentially filter them. The `eventbridge` mode is disabled by default. We expect thhe `eventbridge` mode will be the future direction to build a data lake, build metrics, acto on `workflow_job` job started events, etc.
+- Webhook mode, the module can be deployed in the mode `direct` and `eventbridge` (Experimental). The `direct` mode is the default and will directly distribute to SQS for the scale-up lambda. The `eventbridge` mode will publish the event to an event bus with a target rule the events are sent to a dispatch lambda. The dispatch lambda will send the event to the SQS queue. The `eventbridge` mode is useful when you want to have more control over the events and potentially filter them. The `eventbridge` mode is disabled by default. We expect thhe `eventbridge` mode will be the future direction to build a data lake, build metrics, acto on `workflow_job` job started events, etc.
 - Linux vs Windows. You can configure the OS types linux and win. Linux will be used by default.
 - Re-use vs Ephemeral. By default runners are re-used, until detected idle. Once idle they will be removed from the pool. To improve security we are introducing ephemeral runners. Those runners are only used for one job. Ephemeral runners only work in combination with the workflow job event. For ephemeral runners the lambda requests a JIT (just in time) configuration via the GitHub API to register the runner. [JIT configuration](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners) is limited to ephemeral runners (and currently not supported by GHES). For non-ephemeral runners, a registration token is always requested. In both cases the configuration is made available to the instance via the same SSM parameter. To disable JIT configuration for ephemeral runners set `enable_jit_config` to `false`. We also suggest using a pre-build AMI to improve the start time of jobs for ephemeral runners.
 - Job retry (**Beta**). By default the scale-up lambda will discard the message when it is handled. Meaning in the ephemeral use-case an instance is created. The created runner will ask GitHub for a job, no guarantee it will run the job for which it was scaling. Result could be that with small system hick-up the job is keeping waiting for a runner. Enable a pool (org runners) is one option to avoid this problem. Another option is to enable the job retry function. Which will retry the job after a delay for a configured number of times.
@@ -259,8 +259,83 @@ Below an example of the the log messages created.
 }
 ```
 
+### EventBridge
+
+The module can be deployed in the mode `eventbridge` (Experimental). The `eventbridge` mode will publish the event to an event bus with a target rule the events are sent to a dispatch lambda. The dispatch lambda will send the event to the SQS queue. The `eventbridge` mode is disabled by default. We expect thhe `eventbridge` mode will be the future direction to build a data lake, build metrics, acto on `workflow_job` job started events, etc.
+
+Example to use the EventBridge:
+
+```hcl
+
+module "runners" {
+  source = "philips-labs/github-runners/aws"
+
+  ...
+  eventbridge = {
+    enable = true
+  }
+  ...
+}
+
+locals {
+  event_bus_name = module.runners.webhook.eventbridge.event_bus.name
+}
+
+resource "aws_cloudwatch_event_rule" "example" {
+  name           = "${local.prefix}-github-events-all"
+  description    = "Caputure all GitHub events"
+  event_bus_name = local.event_bus_name
+  event_pattern  = <<EOF
+{
+  "source": [{
+    "prefix": "github"
+  }]
+}
+EOF
+}
+
+resource "aws_cloudwatch_event_target" "main" {
+  rule           = aws_cloudwatch_event_rule.example.name
+  arn            = <arn of target>
+  event_bus_name = local.event_bus_name
+  role_arn       = aws_iam_role.event_rule_firehose_role.arn
+}
+
+data "aws_iam_policy_document" "event_rule_firehose_role" {
+  statement {
+    actions = ["sts:AssumeRole"]
+
+    principals {
+      type        = "Service"
+      identifiers = ["events.amazonaws.com"]
+    }
+  }
+}
+
+resource "aws_iam_role" "event_rule_role" {
+  name               = "${local.prefix}-eventbridge-github-rule"
+  assume_role_policy = data.aws_iam_policy_document.event_rule_firehose_role.json
+}
+
+data aws_iam_policy_document firehose_stream {
+  statement {
+    INSER_YOUR_POIICY_HERE_TO_ACCESS_THE_TARGET
+  }
+}
+
+resource "aws_iam_role_policy" "event_rule_firehose_role" {
+  name = "target-event-rule-firehose"
+  role = aws_iam_role.event_rule_firehose_role.name
+  policy = data.aws_iam_policy_document.firehose_stream.json
+}
+```
+
 ### Queue to publish workflow job events
 
+!!! warning "Deprecated
+
+    This fearure will be removed since we introducing the EventBridge. Same functinallity can be implemented by adding a rule to the EventBridge to forward `workflow_job` events to the SQS queue.
+
 This queue is an experimental feature to allow you to receive a copy of the wokflow_jobs events sent by the GitHub App. This can be used to calculate a matrix or monitor the system.
 
 To enable the feature set `enable_workflow_job_events_queue = true`. Be aware though, this feature is experimental!

examples/default/main.tf

@@ -97,8 +97,12 @@ module "runners" {
   # prefix GitHub runners with the environment name
   runner_name_prefix = "${local.environment}_"
 
-  # webhook supports to modes, either direct or via the eventbridge
-  # webhook_mode = "direct" # or "eventbridge"
+  # webhook supports to modes, either direct or via the eventbridge, uncommet to enable eventbridge
+  # eventbridge = {
+  #   enable = true
+  #   # adjust the allow events to only allow specific events, like workflow_job
+  #   # allowed_events = ['workflow_job']
+  # }
 
   # Enable debug logging for the lambda functions
   # log_level = "debug"

examples/multi-runner/main.tf

@@ -78,10 +78,12 @@ module "runners" {
     webhook_secret = random_id.random.hex
   }
 
-  # Deploy webhook in EventBridge mode
-  webhook_mode = "eventbridge"
-  # adjust the allow events to only allow specific events, like workflow_job
-  # eventbridge_allowed_events = ['workflow_job']
+  # 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 = {

lambdas/functions/webhook/src/ConfigLoader.test.ts

@@ -176,7 +176,7 @@ describe('ConfigLoader Tests', () => {
 
   describe('ConfigWebhookEventBridge', () => {
     it('should load config successfully', async () => {
-      process.env.ALLOWED_EVENTS = '["push", "pull_request"]';
+      process.env.ACCEPT_EVENTS = '["push", "pull_request"]';
       process.env.EVENT_BUS_NAME = 'event-bus';
       process.env.PARAMETER_GITHUB_APP_WEBHOOK_SECRET = '/path/to/webhook/secret';
 
@@ -244,6 +244,33 @@ describe('ConfigLoader Tests', () => {
       );
     });
 
+    it('should rely on default when optionals are not set.', async () => {
+      process.env.ACCEPT_EVENTS = 'null';
+      process.env.PARAMETER_RUNNER_MATCHER_CONFIG_PATH = '/path/to/matcher/config';
+      const matcherConfig: RunnerMatcherConfig[] = [
+        {
+          arn: 'arn:aws:sqs:eu-central-1:123456:npalm-default-queued-builds',
+          fifo: true,
+          id: 'https://sqs.eu-central-1.amazonaws.com/123456/npalm-default-queued-builds',
+          matcherConfig: {
+            exactMatch: true,
+            labelMatchers: [['default', 'example', 'linux', 'self-hosted', 'x64']],
+          },
+        },
+      ];
+      mocked(getParameter).mockImplementation(async (paramPath: string) => {
+        if (paramPath === '/path/to/matcher/config') {
+          return JSON.stringify(matcherConfig);
+        }
+        return '';
+      });
+
+      const config: ConfigDispatcher = await ConfigDispatcher.load();
+
+      expect(config.repositoryAllowList).toEqual([]);
+      expect(config.matcherConfig).toEqual(matcherConfig);
+    });
+
     it('should throw an error if runner matcher config is empty.', async () => {
       process.env.REPOSITORY_ALLOW_LIST = '["repo1", "repo2"]';
       process.env.PARAMETER_RUNNER_MATCHER_CONFIG_PATH = '/path/to/matcher/config';

lambdas/functions/webhook/src/ConfigLoader.ts

@@ -44,7 +44,7 @@ abstract class BaseConfig {
 
   protected loadEnvVar<T>(envVar: string, propertyName: keyof this, defaultValue?: T): void {
     logger.debug(`Loading env var for ${String(propertyName)}`, { envVar });
-    if (envVar !== undefined) {
+    if (!(envVar == undefined || envVar === 'null')) {
       this.loadProperty(propertyName, envVar);
     } else if (defaultValue !== undefined) {
       this[propertyName] = defaultValue as unknown as this[keyof this];
@@ -113,7 +113,7 @@ export class ConfigWebhookEventBridge extends BaseConfig {
   webhookSecret: string = '';
 
   async loadConfig(): Promise<void> {
-    this.loadEnvVar(process.env.ALLOWED_EVENTS, 'allowedEvents', []);
+    this.loadEnvVar(process.env.ACCEPT_EVENTS, 'allowedEvents', []);
     this.loadEnvVar(process.env.EVENT_BUS_NAME, 'eventBusName');
     await this.loadParameter(process.env.PARAMETER_GITHUB_APP_WEBHOOK_SECRET, 'webhookSecret');
 

lambdas/functions/webhook/src/modules.d.ts

@@ -6,7 +6,7 @@ declare namespace NodeJS {
     PARAMETER_RUNNER_MATCHER_CONFIG_PATH: string;
     REPOSITORY_ALLOW_LIST: string;
     RUNNER_LABELS: string;
-    ALLOWED_EVENTS: string;
+    ACCEPT_EVENTS: string;
     SQS_WORKFLOW_JOB_QUEUE: string;
   }
 }

lambdas/functions/webhook/src/webhook/index.test.ts

@@ -196,7 +196,7 @@ describe('handle GitHub webhook events', () => {
       });
 
       ConfigWebhookEventBridge.reset();
-      process.env.ALLOWED_EVENTS = JSON.stringify(input.events);
+      process.env.ACCEPT_EVENTS = JSON.stringify(input.events);
       config = await ConfigWebhookEventBridge.load();
 
       await expect(
@@ -239,7 +239,7 @@ describe('handle GitHub webhook events', () => {
         });
 
         ConfigWebhookEventBridge.reset();
-        process.env.ALLOWED_EVENTS = JSON.stringify(input.events);
+        process.env.ACCEPT_EVENTS = JSON.stringify(input.events);
         config = await ConfigWebhookEventBridge.load();
 
         await expect(

main.tf

@@ -124,16 +124,14 @@ module "ssm" {
 module "webhook" {
   source = "./modules/webhook"
 
-  mode                       = var.webhook_mode
-  eventbridge_allowed_events = var.eventbridge_allowed_events
-
   ssm_paths = {
     root    = local.ssm_root_path
     webhook = var.ssm_paths.webhook
   }
   prefix      = var.prefix
   tags        = local.tags
   kms_key_arn = var.kms_key_arn
+  eventbridge = var.eventbridge
 
   runner_matcher_config = {
     (aws_sqs_queue.queued_builds.id) = {

modules/multi-runner/outputs.tf

@@ -39,8 +39,8 @@ output "webhook" {
     lambda_role      = module.webhook.role
     endpoint         = "${module.webhook.gateway.api_endpoint}/${module.webhook.endpoint_relative_path}"
     webhook          = module.webhook.webhook
-    dispatcher       = var.webhook_mode == "eventbridge" ? module.webhook.dispatcher : null
-    eventbridge      = var.webhook_mode == "eventbridge" ? module.webhook.eventbridge : null
+    dispatcher       = var.eventbridge.enable ? module.webhook.dispatcher : null
+    eventbridge      = var.eventbridge.enable ? module.webhook.eventbridge : null
   }
 }
 

modules/multi-runner/variables.tf

@@ -271,24 +271,6 @@ variable "lambda_s3_bucket" {
   default     = null
 }
 
-
-variable "webhook_mode" {
-  description = "The webhook and dispatching to runner queues supports two modes. Direct messages, are delivered directly to the runner queues. EventBridge messages are delivered to an EventBridge bus and then dispatched to the runner queues. Valid values are `direct` and `eventbridge`."
-  type        = string
-  default     = "direct"
-
-  validation {
-    condition     = contains(["direct", "eventbridge"], var.webhook_mode)
-    error_message = "`mode` value is not valid, valid values are: `direct`, and `eventbridge`."
-  }
-}
-
-variable "eventbridge_allowed_events" {
-  description = "List of events that are allowed (accepted) to be sent to the eventbridge by the webhook. Variable only have effect if `webhook_mode` is set to `eventbridge`."
-  type        = list(string)
-  default     = []
-}
-
 variable "webhook_lambda_s3_key" {
   description = "S3 key for webhook lambda function. Required if using S3 bucket to specify lambdas."
   type        = string
@@ -701,3 +683,13 @@ variable "metrics" {
   })
   default = {}
 }
+
+variable "eventbridge" {
+  description = "Enable the use of EventBridge by the module. By enable this feature events will be putted on the EventBridge bhy the webhook instead of directly dispatchting to queues for sacling."
+  type = object({
+    enable        = optional(bool, false)
+    accept_events = optional(list(string), [])
+  })
+
+  default = {}
+}

modules/multi-runner/webhook.tf

@@ -1,13 +1,12 @@
 module "webhook" {
-  source                     = "../webhook"
-  prefix                     = var.prefix
-  tags                       = local.tags
-  mode                       = var.webhook_mode
-  eventbridge_allowed_events = var.eventbridge_allowed_events
-  kms_key_arn                = var.kms_key_arn
-
+  source                              = "../webhook"
+  prefix                              = var.prefix
+  tags                                = local.tags
+  kms_key_arn                         = var.kms_key_arn
+  eventbridge                         = var.eventbridge
   runner_matcher_config               = local.runner_config
   matcher_config_parameter_store_tier = var.matcher_config_parameter_store_tier
+
   ssm_paths = {
     root    = local.ssm_root_path
     webhook = var.ssm_paths.webhook

modules/webhook/eventbridge/variables.tf

@@ -50,6 +50,6 @@ variable "config" {
       arn     = string
       version = string
     })
-    allowed_events = optional(list(string), [])
+    accept_events = optional(list(string), null)
   })
 }

modules/webhook/eventbridge/webhook.tf

@@ -22,7 +22,7 @@ resource "aws_lambda_function" "webhook" {
         POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS = var.config.tracing_config.capture_http_requests
         POWERTOOLS_TRACER_CAPTURE_ERROR          = var.config.tracing_config.capture_error
         # Parameters required for lambda configuration
-        ALLOWED_EVENTS                       = jsonencode(var.config.allowed_events)
+        ACCEPT_EVENTS                        = jsonencode(var.config.accept_events)
         EVENT_BUS_NAME                       = aws_cloudwatch_event_bus.main.name
         PARAMETER_GITHUB_APP_WEBHOOK_SECRET  = var.config.github_app_parameters.webhook_secret.name
         PARAMETER_RUNNER_MATCHER_CONFIG_PATH = var.config.ssm_parameter_runner_matcher_config.name

modules/webhook/main.tf

@@ -62,5 +62,5 @@ resource "aws_apigatewayv2_integration" "webhook" {
   connection_type    = "INTERNET"
   description        = "GitHub App webhook for receiving build events."
   integration_method = "POST"
-  integration_uri    = var.mode == "direct" ? module.direct[0].webhook.lambda.invoke_arn : module.eventbridge[0].webhook.lambda.invoke_arn
+  integration_uri    = !var.eventbridge.enable ? module.direct[0].webhook.lambda.invoke_arn : module.eventbridge[0].webhook.lambda.invoke_arn
 }

modules/webhook/outputs.tf

@@ -7,27 +7,27 @@ output "endpoint_relative_path" {
 }
 
 output "webhook" {
-  value = var.mode == "direct" ? module.direct[0].webhook : module.eventbridge[0].webhook
+  value = !var.eventbridge.enable ? module.direct[0].webhook : module.eventbridge[0].webhook
 }
 
 output "dispatcher" {
-  value = var.mode == "eventbridge" ? module.eventbridge[0].dispatcher : null
+  value = var.eventbridge.enable ? module.eventbridge[0].dispatcher : null
 }
 
 output "eventbridge" {
-  value = var.mode == "eventbridge" ? module.eventbridge[0].eventbridge : null
+  value = var.eventbridge.enable ? module.eventbridge[0].eventbridge : null
 }
 
 ### For backwards compatibility
 
 output "lambda" {
-  value = var.mode == "direct" ? module.direct[0].webhook.lambda : module.eventbridge[0].webhook.lambda
+  value = !var.eventbridge.enable ? module.direct[0].webhook.lambda : module.eventbridge[0].webhook.lambda
 }
 
 output "lambda_log_group" {
-  value = var.mode == "direct" ? module.direct[0].webhook.log_group : module.eventbridge[0].webhook.log_group
+  value = !var.eventbridge.enable ? module.direct[0].webhook.log_group : module.eventbridge[0].webhook.log_group
 }
 
 output "role" {
-  value = var.mode == "direct" ? module.direct[0].webhook.role : module.eventbridge[0].webhook.role
+  value = !var.eventbridge.enable ? module.direct[0].webhook.role : module.eventbridge[0].webhook.role
 }

modules/webhook/variables.tf

@@ -211,18 +211,16 @@ variable "matcher_config_parameter_store_tier" {
   }
 }
 
-variable "mode" {
-  description = "The webhook and dispatching to runner queues supports two modes. Direct messages, are delivered directly to the runner queues. EventBridge messages are delivered to an EventBridge bus and then dispatched to the runner queues. Valid values are `direct` and `eventbridge`."
-  type        = string
-
-  validation {
-    condition     = contains(["direct", "eventbridge"], var.mode)
-    error_message = "`mode` value is not valid, valid values are: `direct`, and `eventbridge`."
-  }
-}
-
-variable "eventbridge_allowed_events" {
-  description = "List of events that are allowed (accepted) to be sent to the eventbridge by the webhook."
-  type        = list(string)
-  default     = []
+variable "eventbridge" {
+  description = <<EOF
+    Enable the use of EventBridge by the module. By enable this feature events will be putted on the EventBridge bhy the
+    webhook instead of directly dispatchting to queues for sacling.
+
+    `enable`: Enable the EventBridge feature.
+    `accept_events`: List can be used to only allow specific events to be putted on the EventBridge. By default all events, empty list will be be interpreted as all events.
+EOF
+  type = object({
+    enable        = optional(bool, false)
+    accept_events = optional(list(string), null)
+  })
 }