feat(microvm): add foundation module example

.github/workflows/terraform.yml

@@ -87,6 +87,7 @@ jobs:
             "multi-runner",
             "compute-providers/aws/microvm",
             "compute-providers/aws/microvm/trust-policy",
+            "microvm-foundation",
             "runner-binaries-syncer",
             "runners",
             "setup-iam-permissions",
@@ -158,7 +159,8 @@ jobs:
             "termination-watcher",
             "multi-runner",
             "multi-runner-v2",
-            "external-managed-ssm-secrets"
+            "external-managed-ssm-secrets",
+            "microvm-foundation"
           ]
     defaults:
       run:

docs/examples/index.md

@@ -11,3 +11,5 @@ Examples are located in the [examples](https://github.com/github-aws-runners/ter
 - _[Termination watcher](termination-watcher.md)_: Example usages of termination watcher.
 - _[Dedicated Mac Hosts](dedicated-mac-hosts.md)_: Example usage of setting up dedicated hosts for macOS runners.
 - _[Externally managed SSM secrets](external-managed-ssm-secrets.md)_: Example usage of externally managed SSM secrets for the GitHub App credentials.
+- _[MicroVM foundation](microvm-foundation.md)_: Example usage of the regional Lambda MicroVM image-build and Network Connector prerequisites.
+- _[Lambda MicroVM](microvm.md)_: Example usage of Linux ARM64 ephemeral runners backed by Lambda MicroVM images.

docs/examples/microvm-foundation.md

@@ -0,0 +1,3 @@
+# Lambda MicroVM foundation
+
+--8<-- "examples/microvm-foundation/README.md"

docs/modules/public/microvm-foundation.md

@@ -0,0 +1,3 @@
+# Lambda MicroVM regional foundation
+
+--8<-- "modules/microvm-foundation/README.md"

examples/microvm-foundation/README.md

@@ -0,0 +1,77 @@
+# MicroVM foundation example
+
+This example creates the regional dependencies required by the Lambda MicroVM
+image build and runner runtime using the reusable module in this repository.
+
+Set real VPC and subnet IDs in `terraform.tfvars` (copy
+`terraform.tfvars.example`). The module validates that every selected subnet
+belongs to its configured VPC.
+
+```bash
+terraform init
+terraform apply
+terraform output
+```
+
+Apply this foundation before building an image with the direct Packer commands
+documented in `../../images/microvm/README.md`. Use the outputs as the build inputs:
+
+- `artifact_bucket_name` -> `MICROVM_ARTIFACT_BUCKET`
+- `build_role_arn` -> `MICROVM_BUILD_ROLE_ARN`
+- `connector_arns.cicd` -> `MICROVM_EGRESS_NETWORK_CONNECTOR_ARN`
+- `usage_policy_arn` -> attach to the control-plane role used by the runner example
+
+The foundation module owns regional storage, build IAM, Network Connectors,
+and the reusable runtime policy. It does not publish an image or create the
+runner control plane; those steps remain explicit and can be performed after
+the foundation is available.
+
+<!-- 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.61 |
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_microvm_foundation"></a> [microvm\_foundation](#module\_microvm\_foundation) | ../../modules/microvm-foundation | n/a |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_artifact_bucket_name"></a> [artifact\_bucket\_name](#input\_artifact\_bucket\_name) | Optional globally unique S3 bucket name. When null, AWS generates the bucket name. | `string` | `null` | no |
+| <a name="input_artifact_retention_days"></a> [artifact\_retention\_days](#input\_artifact\_retention\_days) | Number of days to retain current and noncurrent build artifacts. | `number` | `30` | no |
+| <a name="input_aws_profile"></a> [aws\_profile](#input\_aws\_profile) | Optional local AWS CLI profile. Leave null when credentials are provided by the environment or role. | `string` | `null` | no |
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region in which to create the MicroVM foundation. | `string` | `"eu-west-1"` | no |
+| <a name="input_build_policy_name_prefix"></a> [build\_policy\_name\_prefix](#input\_build\_policy\_name\_prefix) | Name prefix for the Lambda MicroVM build policy. | `string` | `"github-actions-runner-microvm-build-policy-"` | no |
+| <a name="input_build_role_name_prefix"></a> [build\_role\_name\_prefix](#input\_build\_role\_name\_prefix) | Name prefix for the Lambda MicroVM build role. | `string` | `"github-actions-runner-microvm-build-"` | no |
+| <a name="input_ecr_repository_arns"></a> [ecr\_repository\_arns](#input\_ecr\_repository\_arns) | Optional private ECR repository ARNs used by the image build. | `set(string)` | `[]` | no |
+| <a name="input_image_name_prefix"></a> [image\_name\_prefix](#input\_image\_name\_prefix) | Reserved Lambda MicroVM image-name namespace used by the runtime policy. | `string` | `"github-actions-runner-ubuntu-arm64"` | no |
+| <a name="input_network_connector_operator_role_name_prefix"></a> [network\_connector\_operator\_role\_name\_prefix](#input\_network\_connector\_operator\_role\_name\_prefix) | Name prefix for the Lambda Network Connector operator role. | `string` | `"github-actions-runner-microvm-network-operator-"` | no |
+| <a name="input_network_connectors"></a> [network\_connectors](#input\_network\_connectors) | VPC and subnet configuration for regional Lambda MicroVM egress connectors. | <pre>map(object({<br/>    name             = string<br/>    vpc_id           = string<br/>    subnet_ids       = set(string)<br/>    network_protocol = optional(string, "IPv4")<br/>  }))</pre> | n/a | yes |
+| <a name="input_tags"></a> [tags](#input\_tags) | Additional tags applied by the foundation module. | `map(string)` | <pre>{<br/>  "Component": "microvm-foundation"<br/>}</pre> | no |
+| <a name="input_usage_policy_name_prefix"></a> [usage\_policy\_name\_prefix](#input\_usage\_policy\_name\_prefix) | Name prefix for the Lambda MicroVM runtime usage policy. | `string` | `"github-actions-runner-microvm-runtime-usage-policy-"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_artifact_bucket_name"></a> [artifact\_bucket\_name](#output\_artifact\_bucket\_name) | S3 bucket to pass to the MicroVM image build. |
+| <a name="output_artifact_prefix"></a> [artifact\_prefix](#output\_artifact\_prefix) | S3 prefix used for MicroVM build artifacts. |
+| <a name="output_build_role_arn"></a> [build\_role\_arn](#output\_build\_role\_arn) | Lambda build role ARN to pass to the image build. |
+| <a name="output_connector_arns"></a> [connector\_arns](#output\_connector\_arns) | Regional Network Connector ARNs keyed by configuration name. |
+| <a name="output_usage_policy_arn"></a> [usage\_policy\_arn](#output\_usage\_policy\_arn) | Unattached runtime usage policy for the runner control-plane role. |
+<!-- END_TF_DOCS -->

examples/microvm-foundation/main.tf

@@ -0,0 +1,15 @@
+module "microvm_foundation" {
+  source = "../../modules/microvm-foundation"
+
+  aws_region                                  = var.aws_region
+  tags                                        = var.tags
+  build_policy_name_prefix                    = var.build_policy_name_prefix
+  build_role_name_prefix                      = var.build_role_name_prefix
+  network_connector_operator_role_name_prefix = var.network_connector_operator_role_name_prefix
+  usage_policy_name_prefix                    = var.usage_policy_name_prefix
+  artifact_bucket_name                        = var.artifact_bucket_name
+  artifact_retention_days                     = var.artifact_retention_days
+  image_name_prefix                           = var.image_name_prefix
+  ecr_repository_arns                         = var.ecr_repository_arns
+  network_connectors                          = var.network_connectors
+}

examples/microvm-foundation/outputs.tf

@@ -0,0 +1,24 @@
+output "artifact_bucket_name" {
+  description = "S3 bucket to pass to the MicroVM image build."
+  value       = module.microvm_foundation.artifact_bucket_name
+}
+
+output "artifact_prefix" {
+  description = "S3 prefix used for MicroVM build artifacts."
+  value       = module.microvm_foundation.artifact_prefix
+}
+
+output "build_role_arn" {
+  description = "Lambda build role ARN to pass to the image build."
+  value       = module.microvm_foundation.build_role_arn
+}
+
+output "connector_arns" {
+  description = "Regional Network Connector ARNs keyed by configuration name."
+  value       = module.microvm_foundation.connector_arns
+}
+
+output "usage_policy_arn" {
+  description = "Unattached runtime usage policy for the runner control-plane role."
+  value       = module.microvm_foundation.usage_policy_arn
+}

examples/microvm-foundation/providers.tf

@@ -0,0 +1,4 @@
+provider "aws" {
+  region  = var.aws_region
+  profile = var.aws_profile
+}

examples/microvm-foundation/terraform.tfvars.example

@@ -0,0 +1,15 @@
+aws_region = "eu-west-1"
+
+network_connectors = {
+  cicd = {
+    name       = "github-actions-runner-egress"
+    vpc_id     = "vpc-0123456789abcdef0"
+    subnet_ids = ["subnet-0123456789abcdef0", "subnet-0fedcba9876543210"]
+  }
+}
+
+# Add the private ECR repository that contains the regional Ubuntu base image
+# when the image build pulls from ECR.
+# ecr_repository_arns = [
+#   "arn:aws:ecr:eu-west-1:123456789012:repository/actions-runner-base-image",
+# ]

examples/microvm-foundation/variables.tf

@@ -0,0 +1,79 @@
+variable "aws_profile" {
+  type        = string
+  description = "Optional local AWS CLI profile. Leave null when credentials are provided by the environment or role."
+  default     = null
+  nullable    = true
+}
+
+variable "aws_region" {
+  type        = string
+  description = "AWS region in which to create the MicroVM foundation."
+  default     = "eu-west-1"
+}
+
+variable "tags" {
+  type        = map(string)
+  description = "Additional tags applied by the foundation module."
+  default = {
+    Component = "microvm-foundation"
+  }
+}
+
+variable "build_policy_name_prefix" {
+  type        = string
+  description = "Name prefix for the Lambda MicroVM build policy."
+  default     = "github-actions-runner-microvm-build-policy-"
+}
+
+variable "usage_policy_name_prefix" {
+  type        = string
+  description = "Name prefix for the Lambda MicroVM runtime usage policy."
+  default     = "github-actions-runner-microvm-runtime-usage-policy-"
+}
+
+variable "build_role_name_prefix" {
+  type        = string
+  description = "Name prefix for the Lambda MicroVM build role."
+  default     = "github-actions-runner-microvm-build-"
+}
+
+variable "network_connector_operator_role_name_prefix" {
+  type        = string
+  description = "Name prefix for the Lambda Network Connector operator role."
+  default     = "github-actions-runner-microvm-network-operator-"
+}
+
+variable "artifact_bucket_name" {
+  type        = string
+  description = "Optional globally unique S3 bucket name. When null, AWS generates the bucket name."
+  default     = null
+  nullable    = true
+}
+
+variable "artifact_retention_days" {
+  type        = number
+  description = "Number of days to retain current and noncurrent build artifacts."
+  default     = 30
+}
+
+variable "image_name_prefix" {
+  type        = string
+  description = "Reserved Lambda MicroVM image-name namespace used by the runtime policy."
+  default     = "github-actions-runner-ubuntu-arm64"
+}
+
+variable "ecr_repository_arns" {
+  type        = set(string)
+  description = "Optional private ECR repository ARNs used by the image build."
+  default     = []
+}
+
+variable "network_connectors" {
+  type = map(object({
+    name             = string
+    vpc_id           = string
+    subnet_ids       = set(string)
+    network_protocol = optional(string, "IPv4")
+  }))
+  description = "VPC and subnet configuration for regional Lambda MicroVM egress connectors."
+}

examples/microvm-foundation/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.4.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 6.61"
+    }
+  }
+}

mkdocs.yaml

@@ -65,6 +65,7 @@ nav:
       - AMI Housekeeper: modules/public/ami-housekeeper.md
       - Lambda Downloader: modules/public/download-lambda.md
       - Setup IAM permissions: modules/public/setup-iam-permissions.md
+      - MicroVM foundation: modules/public/microvm-foundation.md
     - Submodules (internal):
       - Runners: modules/internal/runners.md
       - Syncer: modules/internal/runner-binaries-syncer.md