feat: Natively support runner job started/completed hooks (github-aws-runners#4260)

Pre and post job hooks were added to github actions to help
administrators run custom scripts at the beginning and end of every job.
As of today the module doesn't support these options out of the box.

Add variables to accept these optional scripts and register the hook in
user-data.

Also enrich linux-arm64 example in multi-runner with pre/post hooks

Related to: https://github.com/philips-labs/terraform-aws-github-runner/issues/3854

Author: winwinashwin

examples/multi-runner/templates/runner-configs/linux-arm64.yaml

@@ -18,3 +18,12 @@ runner_config:
   runners_maximum_count: 1
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
+  runner_hook_job_started: |
+    echo "Running pre job hook as \$(whoami)"
+
+    # Clean github workspace from previous runs
+    if [[ -n "\$GITHUB_WORKSPACE" ]]; do
+      rm -rf "\$GITHUB_WORKSPACE"
+    done
+  runner_hook_job_completed: |
+    echo "Running post job hook as \$(whoami)"

examples/multi-runner/templates/user-data.sh

@@ -81,4 +81,18 @@ ${post_install}
 
 cd /opt/actions-runner
 
+%{ if hook_job_started != "" }
+cat > /opt/actions-runner/hook_job_started.sh << EOF
+${hook_job_started}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/actions-runner/hook_job_started.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+%{ if hook_job_completed != "" }
+cat > /opt/actions-runner/hook_job_completed.sh << EOF
+${hook_job_completed}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/actions-runner/hook_job_completed.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
 ${start_runner}

main.tf

@@ -249,6 +249,8 @@ module "runners" {
   userdata_content               = var.userdata_content
   userdata_pre_install           = var.userdata_pre_install
   userdata_post_install          = var.userdata_post_install
+  runner_hook_job_started        = var.runner_hook_job_started
+  runner_hook_job_completed      = var.runner_hook_job_completed
   key_name                       = var.key_name
   runner_ec2_tags                = var.runner_ec2_tags
 

modules/multi-runner/runners.tf

@@ -86,13 +86,15 @@ module "runners" {
   role_path                 = var.role_path
   role_permissions_boundary = var.role_permissions_boundary
 
-  enable_userdata       = each.value.runner_config.enable_userdata
-  userdata_template     = each.value.runner_config.userdata_template
-  userdata_content      = each.value.runner_config.userdata_content
-  userdata_pre_install  = each.value.runner_config.userdata_pre_install
-  userdata_post_install = each.value.runner_config.userdata_post_install
-  key_name              = var.key_name
-  runner_ec2_tags       = each.value.runner_config.runner_ec2_tags
+  enable_userdata           = each.value.runner_config.enable_userdata
+  userdata_template         = each.value.runner_config.userdata_template
+  userdata_content          = each.value.runner_config.userdata_content
+  userdata_pre_install      = each.value.runner_config.userdata_pre_install
+  userdata_post_install     = each.value.runner_config.userdata_post_install
+  runner_hook_job_started   = each.value.runner_config.runner_hook_job_started
+  runner_hook_job_completed = each.value.runner_config.runner_hook_job_completed
+  key_name                  = var.key_name
+  runner_ec2_tags           = each.value.runner_config.runner_ec2_tags
 
   create_service_linked_role_spot = each.value.runner_config.create_service_linked_role_spot
 

modules/multi-runner/variables.tf

@@ -78,6 +78,8 @@ variable "multi_runner_config" {
       cloudwatch_config                       = optional(string, null)
       userdata_pre_install                    = optional(string, "")
       userdata_post_install                   = optional(string, "")
+      runner_hook_job_started                 = optional(string, "")
+      runner_hook_job_completed               = optional(string, "")
       runner_ec2_tags                         = optional(map(string), {})
       runner_iam_role_managed_policy_arns     = optional(list(string), [])
       vpc_id                                  = optional(string, null)
@@ -180,6 +182,8 @@ variable "multi_runner_config" {
         cloudwatch_config: "(optional) Replaces the module default cloudwatch log config. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html for details."
         userdata_pre_install: "Script to be ran before the GitHub Actions runner is installed on the EC2 instances"
         userdata_post_install: "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"
+        runner_hook_job_started: "Script to be ran in the runner environment at the beginning of every job"
+        runner_hook_job_completed: "Script to be ran in the runner environment at the end of every job"
         runner_ec2_tags: "Map of tags that will be added to the launch template instance tag specifications."
         runner_iam_role_managed_policy_arns: "Attach AWS or customer-managed IAM policies (by ARN) to the runner IAM role"
         vpc_id: "The VPC for security groups of the action runners. If not set uses the value of `var.vpc_id`."

modules/runners/main.tf

@@ -54,7 +54,9 @@ locals {
       S3_LOCATION_RUNNER_DISTRIBUTION = local.s3_location_runner_distribution
       RUNNER_ARCHITECTURE             = var.runner_architecture
     })
-    post_install = var.userdata_post_install
+    post_install       = var.userdata_post_install
+    hook_job_started   = var.runner_hook_job_started
+    hook_job_completed = var.runner_hook_job_completed
     start_runner = templatefile(local.userdata_start_runner[var.runner_os], {
       metadata_tags = var.metadata_options != null ? var.metadata_options.instance_metadata_tags : "enabled"
     })

modules/runners/templates/user-data.sh

@@ -62,4 +62,20 @@ ${install_runner}
 
 ${post_install}
 
+# Register runner job hooks
+# Ref: https://github.com/actions/runner/blob/main/docs/adrs/1751-runner-job-hooks.md
+%{ if hook_job_started != "" }
+cat > /opt/actions-runner/hook_job_started.sh << EOF
+${hook_job_started}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/actions-runner/hook_job_started.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+%{ if hook_job_completed != "" }
+cat > /opt/actions-runner/hook_job_completed.sh << EOF
+${hook_job_completed}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/actions-runner/hook_job_completed.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
 ${start_runner}

modules/runners/variables.tf

@@ -172,6 +172,18 @@ variable "userdata_post_install" {
   default     = ""
 }
 
+variable "runner_hook_job_started" {
+  description = "Script to be ran in the runner environment at the beginning of every job"
+  type        = string
+  default     = ""
+}
+
+variable "runner_hook_job_completed" {
+  description = "Script to be ran in the runner environment at the end of every job"
+  type        = string
+  default     = ""
+}
+
 variable "sqs_build_queue" {
   description = "SQS queue to consume accepted build events."
   type = object({

variables.tf

@@ -280,6 +280,18 @@ variable "userdata_post_install" {
   description = "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"
 }
 
+variable "runner_hook_job_started" {
+  type        = string
+  default     = ""
+  description = "Script to be ran in the runner environment at the beginning of every job"
+}
+
+variable "runner_hook_job_completed" {
+  type        = string
+  default     = ""
+  description = "Script to be ran in the runner environment at the end of every job"
+}
+
 variable "idle_config" {
   description = "List of time periods, defined as a cron expression, to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."
   type = list(object({