refactor(runner-stack): isolate provider trust policies

Author: edersonbrilhante

.github/workflows/terraform.yml

@@ -86,7 +86,9 @@ jobs:
             "lambda",
             "multi-runner",
             "compute-providers/ec2",
+            "compute-providers/ec2/trust-policy",
             "compute-providers/microvm",
+            "compute-providers/microvm/trust-policy",
             "runner-binaries-syncer",
             "runner-stack",
             "runner-stack/job-retry",
@@ -227,7 +229,9 @@ jobs:
           - modules/runner-stack/scale-runners
           - modules/runner-stack/ssm-housekeeper
           - modules/compute-providers/ec2
+          - modules/compute-providers/ec2/trust-policy
           - modules/compute-providers/microvm
+          - modules/compute-providers/microvm/trust-policy
     defaults:
       run:
         working-directory: ${{ matrix.module }}

docs/modules/internal/compute-provider-refactor.md

@@ -22,26 +22,27 @@ The implementation is split into orchestration, provider-neutral control-plane c
 | `runner-stack/pool` | Optional scheduled runner-pool resources and their Lambda and IAM wiring. |
 | `runner-stack/job-retry` | Optional queued-job retry resources and their Lambda and IAM wiring. |
 | `runner-stack/ssm-housekeeper` | Parameter Store cleanup Lambda, schedule, logging, and IAM resources. |
-| `compute-providers/<provider>` | Provider-specific resources, runner-role trust and permission requirements, and the IAM and environment-variable fragments consumed by the common control plane. |
+| `compute-providers/<provider>/trust-policy` | Provider-specific default runner-role trust, merged with the optional caller-provided trust document before the common role is created. |
+| `compute-providers/<provider>` | Provider-specific resources, permission requirements, and the IAM and environment-variable fragments consumed by the common control plane after the runner role is resolved. |
 
 The EC2 provider owns the instance profile, launch template, security group, AMI and bootstrap parameters, runner log groups, EC2 policy statements, and EC2 Lambda environment variables. The MicroVM provider owns the Lambda MicroVM runtime configuration, execution-role policy, and MicroVM Lambda environment variables. Terraform does not manage MicroVM lifecycle resources directly; the runtime control plane creates and terminates MicroVM runners.
 
 The modules below `runner-stack` are internal implementation boundaries, not standalone public modules. Callers opt into the experimental interface through `experimental.multi_runner_config_v2`; `multi-runner` calls `runner-stack`, which composes the internal modules. Their direct input and output contracts may change while v2 remains experimental.
 
 `runner-stack` selects a compute provider from the single populated typed block under `compute_provider`. For example, `compute_provider = { ec2 = { ... } }` selects EC2 and `compute_provider = { microvm = { ... } }` selects MicroVM; there is no separate `type` input that can disagree with the populated block. Exactly one provider block must be populated, and its presence must be known during planning because it determines the module graph. Native input validation enforces this common selection rule, while each compute-provider module owns its provider-specific semantic validation. The stack passes `compute_provider.<provider>` to the selected provider module as one nested `config` object. It also passes the provider-neutral `runner`, `github`, `ssm`, and `observability` objects without expanding them back into prefixed scalar inputs. This keeps ownership visible at the module boundary and gives future compute providers an equivalent contract to implement.
 
-The common stack creates or selects the runner IAM role, but the selected provider owns the role's trust-policy document. Each provider exposes that document through a dedicated `assume_role_policy` output and separately returns its nested `provider` contract containing `policies.runner`, `policies.scale_up`, `policies.scale_down`, and `policies.pool`, component environment variables, and provider resources. The common stack uses the trust document when it creates the runner role and attaches the returned permission documents to the roles owned by the corresponding common components. A provider never creates or attaches a common IAM role.
+The common stack creates or selects the runner IAM role, but the selected provider owns the role's default trust-policy document. Each provider implements a small `trust-policy` submodule that accepts `additional_trust_policy_json` and returns the final `assume_role_policy`. The full provider separately returns its nested `provider` contract containing `policies.runner`, `policies.scale_up`, `policies.scale_down`, and `policies.pool`, component environment variables, and provider resources. The common stack uses the isolated trust-policy output when it creates the runner role and attaches the full provider's permission documents to the roles owned by the corresponding common components. A provider never creates or attaches a common IAM role.
 
-The trust relationship is deliberately rendered by a dedicated file and output inside each compute-provider module:
+The trust relationship is deliberately rendered by an isolated provider submodule:
 
 1. `runner-stack` selects the provider from the populated typed block.
-2. `compute-providers/<provider>/assume-role.tf` renders the provider-specific policy without referencing the runner-role input.
-3. `runner-stack` creates or selects the common runner role from that policy.
+2. `compute-providers/<provider>/trust-policy` combines the provider default with `runner.iam.additional_trust_policy_json` without referencing the runner-role input.
+3. `runner-stack` creates or selects the common runner role from the returned `assume_role_policy`.
 4. The full compute provider receives the resolved role so it can create resources such as the EC2 instance profile and render `iam:PassRole` statements.
 5. The provider returns its nested policy, environment-variable, and resource contract.
 6. The common components attach the returned policies to the runner, scale-up, scale-down, and pool roles they own.
 
-The dedicated `assume_role_policy` output depends only on the provider's trust document, not on resources that consume the runner role. `runner-stack` accesses the selected counted module through a direct `[0]` reference so Terraform preserves that output-level dependency; a full splat would add the module-close dependency and recreate the role cycle. This preserves provider ownership of the trust relationship while keeping the dependency graph one-way.
+The trust-policy output depends only on its input documents, not on the full provider resources that consume the runner role. This preserves provider ownership of the trust relationship while keeping the dependency graph one-way.
 
 ## Phase 1 dispatch and compatibility
 
@@ -61,7 +62,7 @@ flowchart TD
   Stack --> Pool["runner-stack/pool"]
   Stack --> Retry["runner-stack/job-retry"]
   Stack --> Housekeeper["runner-stack/ssm-housekeeper"]
-  Stack --> Trust["compute-providers/provider/assume-role.tf"]
+  Stack --> Trust["compute-providers/provider/trust-policy"]
   Trust --> Role["common runner role"]
   Role --> Provider
   Stack --> Provider["compute-providers/<provider>"]

modules/compute-providers/ec2/README.md

@@ -43,7 +43,6 @@ No modules.
 | [aws_ami.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ami) | data source |
 | [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
 | [aws_iam_policy_document.ami_id_ssm_parameter_read](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
-| [aws_iam_policy_document.assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
 | [aws_iam_policy_document.cloudwatch](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
 | [aws_iam_policy_document.create_tags](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
 | [aws_iam_policy_document.describe_tags](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
@@ -78,5 +77,4 @@ No modules.
 | <a name="output_policies"></a> [policies](#output\_policies) | Provider-specific IAM policy fragments consumed by runner-stack. |
 | <a name="output_provider"></a> [provider](#output\_provider) | Nested EC2 compute-provider contract consumed by runner-stack. |
 | <a name="output_resources"></a> [resources](#output\_resources) | Provider-specific EC2 resources exposed by runner-stack. |
-| <a name="output_runner_role"></a> [runner\_role](#output\_runner\_role) | Role-independent EC2 runner-role contract consumed before runner-stack creates the role. |
 <!-- END_TF_DOCS -->

modules/compute-providers/ec2/outputs.tf

@@ -13,11 +13,6 @@ output "resources" {
   value       = local.provider_resources
 }
 
-output "runner_role" {
-  description = "Role-independent EC2 runner-role contract consumed before runner-stack creates the role."
-  value       = local.provider_runner_role
-}
-
 output "provider" {
   description = "Nested EC2 compute-provider contract consumed by runner-stack."
   value = {

modules/compute-providers/ec2/tests/provider.tftest.hcl

@@ -446,29 +446,3 @@ run "requires_distribution_object_when_sync_is_enabled" {
 
   expect_failures = [terraform_data.validate_config]
 }
-
-run "returns_ec2_assume_role_policy" {
-  command = plan
-
-  assert {
-    condition     = toset(data.aws_iam_policy_document.assume_role.statement[0].actions) == toset(["sts:AssumeRole"])
-    error_message = "The EC2 runner role must allow sts:AssumeRole."
-  }
-
-  assert {
-    condition = anytrue([
-      for principal in data.aws_iam_policy_document.assume_role.statement[0].principals :
-      principal.type == "Service" && toset(principal.identifiers) == toset(["ec2.amazonaws.com"])
-    ])
-    error_message = "The EC2 runner role must trust the EC2 service principal."
-  }
-
-  assert {
-    condition = (
-      toset(keys(output.runner_role)) == toset(["trust_policy_json"])
-      && output.runner_role.trust_policy_json == data.aws_iam_policy_document.assume_role.json
-      && !contains(keys(output.policies.runner), "assume_role_policy")
-    )
-    error_message = "The EC2 provider must return trust through only the role-independent runner_role contract."
-  }
-}

modules/compute-providers/ec2/trust-policy/README.md

@@ -0,0 +1,41 @@
+# EC2 runner trust policy
+
+This internal submodule builds the EC2 runner-role trust policy independently from EC2 resources that consume the runner role. It preserves the default EC2 service trust and optionally merges an additional IAM trust policy document supplied by the common runner stack.
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 6.33 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_iam_policy_document.assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_iam_policy_document.default](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_additional_trust_policy_json"></a> [additional\_trust\_policy\_json](#input\_additional\_trust\_policy\_json) | Optional IAM policy document merged with the default EC2 runner-role trust policy. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_assume_role_policy"></a> [assume\_role\_policy](#output\_assume\_role\_policy) | EC2 runner-role trust policy with the optional additional trust policy merged into it. |
+<!-- END_TF_DOCS -->

…les/compute-providers/ec2/assume-role.tf …roviders/ec2/trust-policy/assume-role.tfmodules/compute-providers/ec2/assume-role.tf renamed to modules/compute-providers/ec2/trust-policy/assume-role.tf modules/compute-providers/ec2/assume-role.tf renamed to modules/compute-providers/ec2/trust-policy/assume-role.tf

@@ -1,4 +1,4 @@
-data "aws_iam_policy_document" "assume_role" {
+data "aws_iam_policy_document" "default" {
   statement {
     effect  = "Allow"
     actions = ["sts:AssumeRole"]
@@ -10,9 +10,9 @@ data "aws_iam_policy_document" "assume_role" {
   }
 }
 
-locals {
-  assume_role_policy = data.aws_iam_policy_document.assume_role.json
-  provider_runner_role = {
-    trust_policy_json = local.assume_role_policy
-  }
+data "aws_iam_policy_document" "assume_role" {
+  source_policy_documents = compact([
+    data.aws_iam_policy_document.default.json,
+    var.additional_trust_policy_json,
+  ])
 }

modules/compute-providers/ec2/trust-policy/outputs.tf

@@ -0,0 +1,4 @@
+output "assume_role_policy" {
+  description = "EC2 runner-role trust policy with the optional additional trust policy merged into it."
+  value       = data.aws_iam_policy_document.assume_role.json
+}

modules/compute-providers/ec2/trust-policy/tests/trust-policy.tftest.hcl

@@ -0,0 +1,67 @@
+mock_provider "aws" {
+  mock_data "aws_iam_policy_document" {
+    defaults = {
+      json = "{}"
+    }
+  }
+}
+
+run "returns_default_ec2_trust_policy" {
+  command = plan
+
+  assert {
+    condition     = toset(data.aws_iam_policy_document.default.statement[0].actions) == toset(["sts:AssumeRole"])
+    error_message = "The default EC2 runner role trust policy must allow sts:AssumeRole."
+  }
+
+  assert {
+    condition = anytrue([
+      for principal in data.aws_iam_policy_document.default.statement[0].principals :
+      principal.type == "Service" && toset(principal.identifiers) == toset(["ec2.amazonaws.com"])
+    ])
+    error_message = "The default EC2 runner role trust policy must trust the EC2 service principal."
+  }
+
+  assert {
+    condition = (
+      length(data.aws_iam_policy_document.assume_role.source_policy_documents) == 1
+      && output.assume_role_policy == data.aws_iam_policy_document.assume_role.json
+    )
+    error_message = "The submodule must return the final EC2 assume-role policy."
+  }
+}
+
+run "merges_additional_trust_policy" {
+  command = plan
+
+  variables {
+    additional_trust_policy_json = jsonencode({
+      Version = "2012-10-17"
+      Statement = [{
+        Sid       = "TrustedAccount"
+        Effect    = "Allow"
+        Action    = "sts:AssumeRole"
+        Principal = { AWS = "arn:aws:iam::123456789012:root" }
+      }]
+    })
+  }
+
+  assert {
+    condition = (
+      length(data.aws_iam_policy_document.assume_role.source_policy_documents) == 2
+      && data.aws_iam_policy_document.assume_role.source_policy_documents[1] == var.additional_trust_policy_json
+      && output.assume_role_policy == data.aws_iam_policy_document.assume_role.json
+    )
+    error_message = "The submodule must merge the additional trust policy into the final assume-role policy."
+  }
+}
+
+run "rejects_invalid_additional_trust_policy" {
+  command = plan
+
+  variables {
+    additional_trust_policy_json = "not-json"
+  }
+
+  expect_failures = [var.additional_trust_policy_json]
+}

modules/compute-providers/ec2/trust-policy/variables.tf

@@ -0,0 +1,10 @@
+variable "additional_trust_policy_json" {
+  description = "Optional IAM policy document merged with the default EC2 runner-role trust policy."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = var.additional_trust_policy_json == null ? true : can(jsondecode(var.additional_trust_policy_json))
+    error_message = "additional_trust_policy_json must be valid JSON when set."
+  }
+}