feat(runner-role): Enable using separate IAM role for runners (github-aws-runners#4875)

### What
Allow customization of runner IAM role

### Description
This PR introduces the ability to explicitly specify an IAM role and
instance profile for the runner instances. This is motivated by a need
to accommodate legacy IAM roles that remain from previous infrastructure
migrations.
Proposed change is backward-compatible.

---------

Co-authored-by: Niek Palm <npalm@users.noreply.github.com>
Co-authored-by: Brend Smits <brend.smits@philips.com>

Author: 3 people

main.tf

@@ -159,6 +159,7 @@ module "runners" {
   subnet_ids    = var.subnet_ids
   prefix        = var.prefix
   tags          = local.tags
+  iam_overrides = var.iam_overrides
 
   ssm_paths = {
     root   = local.ssm_root_path

modules/multi-runner/runners.tf

@@ -106,6 +106,7 @@ module "runners" {
   create_service_linked_role_spot = each.value.runner_config.create_service_linked_role_spot
 
   runner_iam_role_managed_policy_arns = each.value.runner_config.runner_iam_role_managed_policy_arns
+  iam_overrides                       = each.value.runner_config.iam_overrides
 
   ghes_url        = var.ghes_url
   ghes_ssl_verify = var.ghes_ssl_verify

modules/multi-runner/variables.tf

@@ -186,6 +186,17 @@ variable "multi_runner_config" {
         lambda_timeout     = optional(number, 30)
         max_attempts       = optional(number, 1)
       }), {})
+      iam_overrides = optional(object({
+        override_instance_profile = optional(bool, null)
+        instance_profile_name     = optional(string, null)
+        override_runner_role      = optional(bool, null)
+        runner_role_arn           = optional(string, null)
+        }), {
+        override_instance_profile = false
+        instance_profile_name     = null
+        override_runner_role      = false
+        runner_role_arn           = null
+      })
     })
     matcherConfig = object({
       labelMatchers = list(list(string))
@@ -259,6 +270,7 @@ variable "multi_runner_config" {
         block_device_mappings: "The EC2 instance block device configuration. Takes the following keys: `device_name`, `delete_on_termination`, `volume_type`, `volume_size`, `encrypted`, `iops`, `throughput`, `kms_key_id`, `snapshot_id`."
         job_retry: "Experimental! Can be removed / changed without trigger a major release. Configure job retries. The configuration enables job retries (for ephemeral runners). After creating the instances a message will be published to a job retry queue. The job retry check lambda is checking after a delay if the job is queued. If not the message will be published again on the scale-up (build queue). Using this feature can impact the rate limit of the GitHub app."
         pool_config: "The configuration for updating the pool. The `pool_size` to adjust to by the events triggered by the `schedule_expression`. For example you can configure a cron expression for week days to adjust the pool to 10 and another expression for the weekend to adjust the pool to 1. Use `schedule_expression_timezone` to override the schedule time zone (defaults to UTC)."
+        iam_overrides: "Allows to (optionally) override the instance profile and runner role created by the module. Set `override_instance_profile` to true and provide the `instance_profile_name` to use an existing instance profile. Set `override_runner_role` to true and provide the `runner_role_arn` to use an existing role for the runner instances."
       }
       matcherConfig: {
         labelMatchers: "The list of list of labels supported by the runner configuration. `[[self-hosted, linux, x64, example]]`"
@@ -762,6 +774,33 @@ variable "user_agent" {
   default     = "github-aws-runners"
 }
 
+variable "iam_overrides" {
+  description = "This map provides the possibility to override some IAM defaults. The following attributes are supported: `instance_profile_name` overrides the instance profile name used in the launch template. `runner_role_arn` overrides the IAM role ARN used for the runner instances."
+  type = object({
+    override_instance_profile = optional(bool, null)
+    instance_profile_name     = optional(string, null)
+    override_runner_role      = optional(bool, null)
+    runner_role_arn           = optional(string, null)
+  })
+
+  default = {
+    override_instance_profile = false
+    instance_profile_name     = null
+    override_runner_role      = false
+    runner_role_arn           = null
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_instance_profile || var.iam_overrides.instance_profile_name != null
+    error_message = "instance_profile_name must be provided when override_instance_profile is true."
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_runner_role || var.iam_overrides.runner_role_arn != null
+    error_message = "runner_role_arn must be provided when override_runner_role is true."
+  }
+}
+
 variable "lambda_event_source_mapping_batch_size" {
   description = "Maximum number of records to pass to the lambda function in a single batch for the event source mapping. When not set, the AWS default of 10 events will be used."
   type        = number

modules/runners/logging.tf

@@ -74,9 +74,9 @@ resource "aws_cloudwatch_log_group" "gh_runners" {
 }
 
 resource "aws_iam_role_policy" "cloudwatch" {
-  count = var.enable_cloudwatch_agent ? 1 : 0
+  count = var.iam_overrides["override_runner_role"] ? 0 : (var.enable_cloudwatch_agent ? 1 : 0)
   name  = "CloudWatchLogginAndMetrics"
-  role  = aws_iam_role.runner.name
+  role  = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-cloudwatch-policy.json",
     {
       ssm_parameter_arn = aws_ssm_parameter.cloudwatch_agent_config_runner[0].arn

modules/runners/main.tf

@@ -211,7 +211,7 @@ resource "aws_launch_template" "runner" {
   }
 
   iam_instance_profile {
-    name = aws_iam_instance_profile.runner.name
+    name = var.iam_overrides["override_instance_profile"] ? var.iam_overrides["instance_profile_name"] : aws_iam_instance_profile.runner[0].name
   }
 
   instance_initiated_shutdown_behavior = "terminate"

modules/runners/policies-runner.tf

@@ -1,6 +1,7 @@
 data "aws_caller_identity" "current" {}
 
 resource "aws_iam_role" "runner" {
+  count                = var.iam_overrides["override_runner_role"] ? 0 : 1
   name                 = "${substr("${var.prefix}-runner", 0, 54)}-${substr(md5("${var.prefix}-runner"), 0, 8)}"
   assume_role_policy   = templatefile("${path.module}/policies/instance-role-trust-policy.json", {})
   path                 = local.role_path
@@ -9,22 +10,24 @@ resource "aws_iam_role" "runner" {
 }
 
 resource "aws_iam_instance_profile" "runner" {
-  name = "${var.prefix}-runner-profile"
-  role = aws_iam_role.runner.name
-  path = local.instance_profile_path
-  tags = local.tags
+  count = (var.iam_overrides["override_instance_profile"] || var.iam_overrides["override_runner_role"]) ? 0 : 1
+  name  = "${var.prefix}-runner-profile"
+  role  = aws_iam_role.runner[0].name
+  path  = local.instance_profile_path
+  tags  = local.tags
 }
 
 resource "aws_iam_role_policy" "runner_session_manager_aws_managed" {
+  count  = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : (var.enable_ssm_on_runners ? 1 : 0)
   name   = "runner-ssm-session"
-  count  = var.enable_ssm_on_runners ? 1 : 0
-  role   = aws_iam_role.runner.name
+  role   = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-ssm-policy.json", {})
 }
 
 resource "aws_iam_role_policy" "ssm_parameters" {
-  name = "runner-ssm-parameters"
-  role = aws_iam_role.runner.name
+  count = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : 1
+  name  = "runner-ssm-parameters"
+  role  = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-ssm-parameters-policy.json",
     {
       arn_ssm_parameters_path_tokens = "arn:${var.aws_partition}:ssm:${var.aws_region}:${data.aws_caller_identity.current.account_id}:parameter${var.ssm_paths.root}/${var.ssm_paths.tokens}"
@@ -34,10 +37,10 @@ resource "aws_iam_role_policy" "ssm_parameters" {
 }
 
 resource "aws_iam_role_policy" "dist_bucket" {
-  count = var.enable_runner_binaries_syncer ? 1 : 0
+  count = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : (var.enable_runner_binaries_syncer ? 1 : 0)
 
   name = "distribution-bucket"
-  role = aws_iam_role.runner.name
+  role = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-s3-policy.json",
     {
       s3_arn = "${var.s3_runner_binaries.arn}/${var.s3_runner_binaries.key}"
@@ -46,33 +49,35 @@ resource "aws_iam_role_policy" "dist_bucket" {
 }
 
 resource "aws_iam_role_policy_attachment" "xray_tracing" {
-  count      = var.tracing_config.mode != null ? 1 : 0
-  role       = aws_iam_role.runner.name
+  count      = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : (var.tracing_config.mode != null ? 1 : 0)
+  role       = aws_iam_role.runner[0].name
   policy_arn = "arn:${var.aws_partition}:iam::aws:policy/AWSXRayDaemonWriteAccess"
 }
 
 resource "aws_iam_role_policy" "describe_tags" {
+  count  = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : 1
   name   = "runner-describe-tags"
-  role   = aws_iam_role.runner.name
+  role   = aws_iam_role.runner[0].name
   policy = file("${path.module}/policies/instance-describe-tags-policy.json")
 }
 
 resource "aws_iam_role_policy" "create_tag" {
+  count  = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : 1
   name   = "runner-create-tags"
-  role   = aws_iam_role.runner.name
+  role   = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-create-tags-policy.json", {})
 }
 
 resource "aws_iam_role_policy_attachment" "managed_policies" {
-  count      = length(var.runner_iam_role_managed_policy_arns)
-  role       = aws_iam_role.runner.name
+  count      = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : length(var.runner_iam_role_managed_policy_arns)
+  role       = aws_iam_role.runner[0].name
   policy_arn = element(var.runner_iam_role_managed_policy_arns, count.index)
 }
 
-
 resource "aws_iam_role_policy" "ec2" {
+  count  = (var.iam_overrides["override_runner_role"] || var.iam_overrides["override_instance_profile"]) ? 0 : 1
   name   = "ec2"
-  role   = aws_iam_role.runner.name
+  role   = aws_iam_role.runner[0].name
   policy = templatefile("${path.module}/policies/instance-ec2.json", {})
 }
 

modules/runners/pool.tf

@@ -51,7 +51,7 @@ module "pool" {
       group_name                           = var.runner_group_name
       name_prefix                          = var.runner_name_prefix
       pool_owner                           = var.pool_runner_owner
-      role                                 = aws_iam_role.runner
+      role                                 = var.iam_overrides["override_runner_role"] ? { arn = var.iam_overrides["runner_role_arn"] } : aws_iam_role.runner[0]
       use_dedicated_host                   = var.use_dedicated_host
     }
     subnet_ids                           = var.subnet_ids

modules/runners/scale-up.tf

@@ -120,7 +120,7 @@ resource "aws_iam_role_policy" "scale_up" {
   name = "scale-up-policy"
   role = aws_iam_role.scale_up.name
   policy = templatefile("${path.module}/policies/lambda-scale-up.json", {
-    arn_runner_instance_role  = aws_iam_role.runner.arn
+    arn_runner_instance_role  = var.iam_overrides["override_runner_role"] ? var.iam_overrides["runner_role_arn"] : aws_iam_role.runner[0].arn
     sqs_arn                   = var.sqs_build_queue.arn
     github_app_id_arn         = var.github_app_parameters.id.arn
     github_app_key_base64_arn = var.github_app_parameters.key_base64.arn

modules/runners/variables.tf

@@ -45,6 +45,33 @@ variable "overrides" {
   }
 }
 
+variable "iam_overrides" {
+  description = "This map provides the possibility to override some IAM defaults. The following attributes are supported: `instance_profile_name` overrides the instance profile name used in the launch template. `runner_role_arn` overrides the IAM role ARN used for the runner instances."
+  type = object({
+    override_instance_profile = optional(bool, null)
+    instance_profile_name     = optional(string, null)
+    override_runner_role      = optional(bool, null)
+    runner_role_arn           = optional(string, null)
+  })
+
+  default = {
+    override_instance_profile = false
+    instance_profile_name     = null
+    override_runner_role      = false
+    runner_role_arn           = null
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_instance_profile || var.iam_overrides.instance_profile_name != null
+    error_message = "instance_profile_name must be provided when override_instance_profile is true."
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_runner_role || var.iam_overrides.runner_role_arn != null
+    error_message = "runner_role_arn must be provided when override_runner_role is true."
+  }
+}
+
 variable "tags" {
   description = "Map of tags that will be added to created resources. By default resources will be tagged with name."
   type        = map(string)

variables.tf

@@ -108,6 +108,33 @@ variable "runner_group_name" {
   default     = "Default"
 }
 
+variable "iam_overrides" {
+  description = "This map provides the possibility to override some IAM defaults. Note that when using this variable, you are responsible for ensuring the role has necessary permissions to access required resources. `override_instance_profile`: When set to true, uses the instance profile name specified in `instance_profile_name` instead of creating a new instance profile. `override_runner_role`: When set to true, uses the role ARN specified in `runner_role_arn` instead of creating a new IAM role."
+  type = object({
+    override_instance_profile = optional(bool, null)
+    instance_profile_name     = optional(string, null)
+    override_runner_role      = optional(bool, null)
+    runner_role_arn           = optional(string, null)
+  })
+
+  default = {
+    override_instance_profile = false
+    instance_profile_name     = null
+    override_runner_role      = false
+    runner_role_arn           = null
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_instance_profile || var.iam_overrides.instance_profile_name != null
+    error_message = "instance_profile_name must be provided when override_instance_profile is true."
+  }
+
+  validation {
+    condition     = !var.iam_overrides.override_runner_role || var.iam_overrides.runner_role_arn != null
+    error_message = "runner_role_arn must be provided when override_runner_role is true."
+  }
+}
+
 variable "scale_up_reserved_concurrent_executions" {
   description = "Amount of reserved concurrent executions for the scale-up lambda function. A value of 0 disables lambda from being triggered and -1 removes any concurrency limitations."
   type        = number