feat(microvm): expose runner config ARN

Author: edersonbrilhante

modules/compute-providers/aws/microvm/README.md

@@ -6,7 +6,7 @@ Select it with the `compute_provider.aws.microvm` leaf. The Terraform dispatch k
 
 MicroVM runners use the provider's fixed 28,800-second (8-hour) lifetime; this is not a Terraform input.
 
-The resolved provider-neutral `runner.iam.role` is passed to Lambda as the MicroVM execution role. The provider creates `/github-self-hosted-runners/<prefix>/microvm` with the common observability lifecycle and derives a control-plane-only metadata prefix at `<ssm.paths.root>/<ssm.paths.config>/microvm-metadata`. Scale-up, scale-down, and pool use that non-secret prefix for MicroVM ownership and lifecycle state; the runner role retains value-read and deletion access only on the lane-scoped one-time JIT path, plus runtime logging. When the runner role is supplied externally, its Lambda trust, JIT parameter access, and stream-write permissions remain caller-owned.
+The resolved provider-neutral `runner.iam.role` is passed to Lambda as the MicroVM execution role. The provider creates `/github-self-hosted-runners/<prefix>/microvm` with the common observability lifecycle and derives a metadata prefix at `<ssm.paths.root>/<ssm.paths.config>/microvm-metadata`. Scale-up, scale-down, and pool use that non-secret prefix for MicroVM ownership and lifecycle state; the runner role receives read access to the lane metadata child prefix, value-read and deletion access on the lane-scoped one-time JIT path, and runtime logging. MicroVMs sharing the execution role can read the metadata records for that lane. When the runner role is supplied externally, its Lambda trust and these permissions remain caller-owned.
 
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
@@ -51,7 +51,7 @@ No modules.
 | <a name="input_github"></a> [github](#input\_github) | GitHub Enterprise Server settings available to compute-provider bootstrap data.<br/><br/>- `enterprise_server.url`: Optional GitHub Enterprise Server base URL. Null selects GitHub.com.<br/>- `enterprise_server.ssl_verify`: Enables TLS certificate verification for GitHub Enterprise Server. | <pre>object({<br/>    enterprise_server = optional(object({<br/>      url        = optional(string, null)<br/>      ssl_verify = optional(bool, true)<br/>    }), {})<br/>  })</pre> | `{}` | no |
 | <a name="input_observability"></a> [observability](#input\_observability) | Provider-neutral observability settings applied to the provider-managed MicroVM runtime log group.<br/><br/>- `logs.retention_in_days`: CloudWatch Logs retention period.<br/>- `logs.kms_key_id`: Optional KMS key ID or ARN used to encrypt the log group.<br/>- `logs.class`: CloudWatch log-group class.<br/>- `logs.tags`: Tags merged after module-level tags on the log group. | <pre>object({<br/>    logs = optional(object({<br/>      retention_in_days = optional(number, 180)<br/>      kms_key_id        = optional(string, null)<br/>      class             = optional(string, "STANDARD")<br/>      tags              = optional(map(string), {})<br/>    }), {})<br/>  })</pre> | `{}` | no |
 | <a name="input_prefix"></a> [prefix](#input\_prefix) | Prefix used to identify resources created for the runner configuration. | `string` | `"github-actions"` | no |
-| <a name="input_runner"></a> [runner](#input\_runner) | Resolved runner settings consumed by the Lambda MicroVM compute provider.<br/><br/>- `os`: Runner operating system. Lambda MicroVM requires `linux`.<br/>- `architecture`: Runner distribution architecture. Lambda MicroVM requires `arm64`.<br/>- `name_prefix`: Prefix added to registered runner names.<br/>- `run_as_root`: Runs the runner service as root.<br/>- `run_as`: Operating-system user used when `run_as_root` is false.<br/>- `hooks.job_started`: Script installed as the runner job-started hook.<br/>- `hooks.job_completed`: Script installed as the runner job-completed hook.<br/>- `iam.role.arn`: Resolved runner-role ARN used as the MicroVM execution role and referenced by provider policies.<br/>- `iam.role.name`: Resolved runner-role name used by provider resources.<br/>- `iam.role.managed`: Whether runner-config manages the resolved runner role. Callers own an external role and must grant it `ssm:GetParameter` and `ssm:DeleteParameter` on the lane token path plus `logs:CreateLogStream` and `logs:PutLogEvents` on the provider-managed runtime log group.<br/>- `iam.managed_policy_arns`: Common managed-policy ARNs returned with the provider-specific runner policies for attachment by runner-config.<br/>- `iam.path`: IAM path available to provider-managed IAM resources. Null derives the path from `prefix`. | <pre>object({<br/>    os           = optional(string, "linux")<br/>    architecture = optional(string, "arm64")<br/>    name_prefix  = optional(string, "")<br/>    run_as_root  = optional(bool, false)<br/>    run_as       = optional(string, "ec2-user")<br/>    hooks = optional(object({<br/>      job_started   = optional(string, "")<br/>      job_completed = optional(string, "")<br/>    }), {})<br/>    iam = object({<br/>      role = object({<br/>        arn     = string<br/>        name    = string<br/>        managed = optional(bool, true)<br/>      })<br/>      managed_policy_arns = optional(map(string), {})<br/>      path                = optional(string, null)<br/>    })<br/>  })</pre> | n/a | yes |
+| <a name="input_runner"></a> [runner](#input\_runner) | Resolved runner settings consumed by the Lambda MicroVM compute provider.<br/><br/>- `os`: Runner operating system. Lambda MicroVM requires `linux`.<br/>- `architecture`: Runner distribution architecture. Lambda MicroVM requires `arm64`.<br/>- `name_prefix`: Prefix added to registered runner names.<br/>- `run_as_root`: Runs the runner service as root.<br/>- `run_as`: Operating-system user used when `run_as_root` is false.<br/>- `hooks.job_started`: Script installed as the runner job-started hook.<br/>- `hooks.job_completed`: Script installed as the runner job-completed hook.<br/>- `iam.role.arn`: Resolved runner-role ARN used as the MicroVM execution role and referenced by provider policies.<br/>- `iam.role.name`: Resolved runner-role name used by provider resources.<br/>- `iam.role.managed`: Whether runner-config manages the resolved runner role. Callers own an external role and must grant it `ssm:GetParameter` on the lane metadata child prefix, `ssm:GetParameter` and `ssm:DeleteParameter` on the lane token path, plus `logs:CreateLogStream` and `logs:PutLogEvents` on the provider-managed runtime log group.<br/>- `iam.managed_policy_arns`: Common managed-policy ARNs returned with the provider-specific runner policies for attachment by runner-config.<br/>- `iam.path`: IAM path available to provider-managed IAM resources. Null derives the path from `prefix`. | <pre>object({<br/>    os           = optional(string, "linux")<br/>    architecture = optional(string, "arm64")<br/>    name_prefix  = optional(string, "")<br/>    run_as_root  = optional(bool, false)<br/>    run_as       = optional(string, "ec2-user")<br/>    hooks = optional(object({<br/>      job_started   = optional(string, "")<br/>      job_completed = optional(string, "")<br/>    }), {})<br/>    iam = object({<br/>      role = object({<br/>        arn     = string<br/>        name    = string<br/>        managed = optional(bool, true)<br/>      })<br/>      managed_policy_arns = optional(map(string), {})<br/>      path                = optional(string, null)<br/>    })<br/>  })</pre> | n/a | yes |
 | <a name="input_ssm"></a> [ssm](#input\_ssm) | Parameter Store paths and tag scopes available to compute-provider bootstrap resources.<br/><br/>- `paths.root`: Root Parameter Store path for the runner configuration.<br/>- `paths.tokens`: Path segment used for registration tokens and just-in-time configuration.<br/>- `paths.config`: Path segment used for persistent runner and provider configuration. MicroVM control-plane metadata is stored under its `microvm-metadata` child prefix.<br/>- `tags`: Shared SSM tags that override module-level `tags`.<br/>- `parameters.tags`: Parameter-specific tags that override module-level and shared SSM tags. | <pre>object({<br/>    paths = object({<br/>      root   = string<br/>      tokens = string<br/>      config = string<br/>    })<br/>    tags = optional(map(string), {})<br/>    parameters = optional(object({<br/>      tags = optional(map(string), {})<br/>    }), {})<br/>  })</pre> | n/a | yes |
 | <a name="input_tags"></a> [tags](#input\_tags) | Base tags available to taggable compute-provider resources. Provider-specific tags override this map within their documented scopes. | `map(string)` | `{}` | no |
 

modules/compute-providers/aws/microvm/control-plane.tf

@@ -70,7 +70,7 @@ data "aws_iam_policy_document" "scale_down" {
 }
 
 locals {
-  microvm_metadata_ssm_path      = "${trimsuffix(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.config, "/")}/microvm-metadata"
+  microvm_metadata_ssm_path      = "/${trim(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.config, "/")}/microvm-metadata"
   microvm_metadata_path_arn      = "${local.ssm_parameter_arn_prefix}${local.microvm_metadata_ssm_path}"
   microvm_metadata_parameter_arn = "${local.microvm_metadata_path_arn}/*"
   microvm_metadata_tags = {
@@ -80,14 +80,14 @@ locals {
       local.provider_tags["Name"],
     )
     "ghr:environment"        = var.prefix
-    "ghr:ssm_config_path"    = "${trimsuffix(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.config, "/")}"
+    "ghr:ssm_config_path"    = "/${trim(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.config, "/")}"
     "ghr:runner_name_prefix" = var.runner.name_prefix
   }
   microvm_image_resource_arns = coalesce(
     var.config.iam.resource_arns.images,
     [var.config.image_arn],
   )
-  runner_jit_ssm_path = "${trimsuffix(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.tokens, "/")}"
+  runner_jit_ssm_path = "/${trim(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.tokens, "/")}"
 
   microvm_environment_variables = merge(var.config.environment_variables, {
     MICROVM_EGRESS_NETWORK_CONNECTORS  = length(var.config.egress_network_connectors) == 0 ? "" : jsonencode(var.config.egress_network_connectors)
@@ -97,6 +97,7 @@ locals {
     MICROVM_INGRESS_NETWORK_CONNECTORS = length(var.config.ingress_network_connectors) == 0 ? "" : jsonencode(var.config.ingress_network_connectors)
     MICROVM_LOG_GROUP                  = aws_cloudwatch_log_group.runtime.name
     MICROVM_METADATA_SSM_PATH          = local.microvm_metadata_ssm_path
+    MICROVM_RUNNER_CONFIG_SSM_ARN      = local.ssm_config_arn
     MICROVM_METADATA_TAGS = jsonencode([
       for key, value in local.microvm_metadata_tags : {
         Key   = key

modules/compute-providers/aws/microvm/policies-runner.tf

@@ -2,9 +2,8 @@ data "aws_caller_identity" "current" {}
 
 locals {
   ssm_parameter_arn_prefix = "arn:${var.aws_partition}:ssm:${var.aws_region}:${data.aws_caller_identity.current.account_id}:parameter"
-  runner_token_path_arn    = "${local.ssm_parameter_arn_prefix}${var.ssm.paths.root}/${var.ssm.paths.tokens}/*"
-  ssm_config_arn           = "${local.ssm_parameter_arn_prefix}${var.ssm.paths.root}/${var.ssm.paths.config}"
-
+  runner_token_path_arn    = "${local.ssm_parameter_arn_prefix}/${trim(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.tokens, "/")}/*"
+  ssm_config_arn           = "${local.ssm_parameter_arn_prefix}/${trim(var.ssm.paths.root, "/")}/${trim(var.ssm.paths.config, "/")}"
 
   runner_inline_policies = {
     ssm_jit = {
@@ -35,16 +34,9 @@ data "aws_iam_policy_document" "runner_ssm_jit" {
 
 data "aws_iam_policy_document" "runner_metadata" {
   statement {
-    effect = "Allow"
-    actions = [
-      "ssm:GetParameter",
-      "ssm:GetParameters",
-      "ssm:GetParametersByPath",
-    ]
-    resources = [
-      local.ssm_config_arn,
-      "${local.ssm_config_arn}/*",
-    ]
+    effect    = "Allow"
+    actions   = ["ssm:GetParameter"]
+    resources = [local.microvm_metadata_parameter_arn]
   }
 }
 

modules/compute-providers/aws/microvm/tests/provider.tftest.hcl

@@ -37,10 +37,11 @@ variables {
       "arn:aws:lambda:eu-west-1:123456789012:network-connector:egress",
     ]
     environment_variables = {
-      MICROVM_CLUSTER           = "runner-cluster"
-      MICROVM_IMAGE_ARN         = "caller-cannot-override-provider-contract"
-      MICROVM_METADATA_SSM_PATH = "/caller/cannot/override/provider-contract"
-      MICROVM_METADATA_TAGS     = "caller-cannot-override-provider-contract"
+      MICROVM_CLUSTER               = "runner-cluster"
+      MICROVM_IMAGE_ARN             = "caller-cannot-override-provider-contract"
+      MICROVM_METADATA_SSM_PATH     = "/caller/cannot/override/provider-contract"
+      MICROVM_METADATA_TAGS         = "caller-cannot-override-provider-contract"
+      MICROVM_RUNNER_CONFIG_SSM_ARN = "caller-cannot-override-provider-contract"
     }
   }
 
@@ -111,6 +112,7 @@ run "exposes_microvm_control_plane_contract" {
       && jsondecode(output.provider.environment_variables.scale_up["MICROVM_EGRESS_NETWORK_CONNECTORS"])[0] == "arn:aws:lambda:eu-west-1:123456789012:network-connector:egress"
       && output.provider.environment_variables.scale_up["MICROVM_LOG_GROUP"] == "/github-self-hosted-runners/microvm-test/microvm"
       && output.provider.environment_variables.scale_up["MICROVM_METADATA_SSM_PATH"] == "/github-action-runners/config/microvm-metadata"
+      && output.provider.environment_variables.scale_up["MICROVM_RUNNER_CONFIG_SSM_ARN"] == "arn:aws:ssm:eu-west-1:123456789012:parameter/github-action-runners/config"
       && tomap({
         for tag in jsondecode(output.provider.environment_variables.scale_up["MICROVM_METADATA_TAGS"]) :
         tag.Key => tag.Value
@@ -136,6 +138,7 @@ run "exposes_microvm_control_plane_contract" {
         "MICROVM_LOG_GROUP",
         "MICROVM_METADATA_SSM_PATH",
         "MICROVM_METADATA_TAGS",
+        "MICROVM_RUNNER_CONFIG_SSM_ARN",
       ])
       && output.provider.environment_variables.scale_up == output.provider.environment_variables.scale_down
       && output.provider.environment_variables.scale_up == output.provider.environment_variables.pool
@@ -208,7 +211,8 @@ run "exposes_microvm_control_plane_contract" {
   assert {
     condition = (
       toset(keys(output.provider.policies)) == toset(["runner", "scale_up", "scale_down", "pool"])
-      && toset(keys(output.provider.policies.runner.inline_policies)) == toset(["runtime_logs", "ssm_jit"])
+      && toset(keys(output.provider.policies.runner.inline_policies)) == toset(["runner_metadata", "runtime_logs", "ssm_jit"])
+      && output.provider.policies.runner.inline_policies.runner_metadata.name == "runner-microvm-metadata"
       && output.provider.policies.runner.inline_policies.ssm_jit.name == "runner-microvm-ssm-jit"
       && output.provider.policies.runner.inline_policies.runtime_logs.name == "runner-microvm-runtime-logs"
       && output.provider.policies.runner.managed_policy_arns["readonly"] == "arn:aws:iam::aws:policy/ReadOnlyAccess"
@@ -222,11 +226,13 @@ run "exposes_microvm_control_plane_contract" {
     condition = (
       data.aws_iam_policy_document.runner_ssm_jit.statement[0].actions == toset(["ssm:DeleteParameter", "ssm:GetParameter"])
       && data.aws_iam_policy_document.runner_ssm_jit.statement[0].resources == toset(["arn:aws:ssm:eu-west-1:123456789012:parameter/github-action-runners/tokens/*"])
+      && data.aws_iam_policy_document.runner_metadata.statement[0].actions == toset(["ssm:GetParameter"])
+      && data.aws_iam_policy_document.runner_metadata.statement[0].resources == toset(["${output.provider.environment_variables.scale_up["MICROVM_RUNNER_CONFIG_SSM_ARN"]}/microvm-metadata/*"])
       && length(data.aws_iam_policy_document.runner_runtime_logs.statement) == 1
       && data.aws_iam_policy_document.runner_runtime_logs.statement[0].actions == toset(["logs:CreateLogStream", "logs:PutLogEvents"])
       && data.aws_iam_policy_document.runner_runtime_logs.statement[0].resources == toset(["arn:aws:logs:eu-west-1:123456789012:log-group:/github-self-hosted-runners/microvm-test/microvm:*"])
     )
-    error_message = "Managed MicroVM runners must receive lane-token value, tag, and deletion access plus stream-write permissions on the provider-managed runtime log group."
+    error_message = "Managed MicroVM runners must receive lane-scoped metadata read access, lane-token value and deletion access, plus stream-write permissions on the provider-managed runtime log group."
   }
 
   assert {
@@ -257,6 +263,30 @@ run "exposes_microvm_control_plane_contract" {
   }
 }
 
+run "normalizes_ssm_paths_and_arns" {
+  command = plan
+
+  variables {
+    ssm = {
+      paths = {
+        root   = "/github-action-runners/"
+        tokens = "/tokens/"
+        config = "/config/"
+      }
+    }
+  }
+
+  assert {
+    condition = (
+      output.provider.environment_variables.scale_up["MICROVM_METADATA_SSM_PATH"] == "/github-action-runners/config/microvm-metadata"
+      && output.provider.environment_variables.scale_up["MICROVM_RUNNER_CONFIG_SSM_ARN"] == "arn:aws:ssm:eu-west-1:123456789012:parameter/github-action-runners/config"
+      && data.aws_iam_policy_document.runner_ssm_jit.statement[0].resources == toset(["arn:aws:ssm:eu-west-1:123456789012:parameter/github-action-runners/tokens/*"])
+      && data.aws_iam_policy_document.runner_metadata.statement[0].resources == toset(["arn:aws:ssm:eu-west-1:123456789012:parameter/github-action-runners/config/microvm-metadata/*"])
+    )
+    error_message = "The MicroVM provider must normalize SSM path segments before exposing hook values or IAM resources."
+  }
+}
+
 run "accepts_external_runner_role_and_policy_overrides" {
   command = plan
 
@@ -330,7 +360,8 @@ run "accepts_external_runner_role_and_policy_overrides" {
 
   assert {
     condition = (
-      toset(keys(output.provider.policies.runner.inline_policies)) == toset(["runtime_logs", "ssm_jit"])
+      toset(keys(output.provider.policies.runner.inline_policies)) == toset(["runner_metadata", "runtime_logs", "ssm_jit"])
+      && data.aws_iam_policy_document.runner_metadata.statement[0].resources == toset(["${output.provider.environment_variables.scale_up["MICROVM_RUNNER_CONFIG_SSM_ARN"]}/microvm-metadata/*"])
       && length(data.aws_iam_policy_document.runner_runtime_logs.statement) == 1
       && data.aws_iam_policy_document.runner_runtime_logs.statement[0].resources == toset(["arn:aws:logs:eu-west-1:123456789012:log-group:/github-self-hosted-runners/microvm-test/microvm:*"])
     )

modules/compute-providers/aws/microvm/variables.tf

@@ -82,7 +82,7 @@ variable "runner" {
     - `hooks.job_completed`: Script installed as the runner job-completed hook.
     - `iam.role.arn`: Resolved runner-role ARN used as the MicroVM execution role and referenced by provider policies.
     - `iam.role.name`: Resolved runner-role name used by provider resources.
-    - `iam.role.managed`: Whether runner-config manages the resolved runner role. Callers own an external role and must grant it `ssm:GetParameter` and `ssm:DeleteParameter` on the lane token path plus `logs:CreateLogStream` and `logs:PutLogEvents` on the provider-managed runtime log group.
+    - `iam.role.managed`: Whether runner-config manages the resolved runner role. Callers own an external role and must grant it `ssm:GetParameter` on the lane metadata child prefix, `ssm:GetParameter` and `ssm:DeleteParameter` on the lane token path, plus `logs:CreateLogStream` and `logs:PutLogEvents` on the provider-managed runtime log group.
     - `iam.managed_policy_arns`: Common managed-policy ARNs returned with the provider-specific runner policies for attachment by runner-config.
     - `iam.path`: IAM path available to provider-managed IAM resources. Null derives the path from `prefix`.
   EOT