feat(microvm): add microvm example

.github/workflows/ministack.yml

@@ -70,9 +70,11 @@ jobs:
           - prebuilt
           - default
           - ephemeral
+          - microvm
+          - microvm-foundation
+          - migration-test
           - multi-runner
           - multi-runner-v2
-          - migration-test
           - termination-watcher
     services:
       ministack:

.github/workflows/packer-build.yml

@@ -26,12 +26,6 @@ jobs:
     runs-on: ubuntu-latest
     container:
       image: index.docker.io/hashicorp/packer@sha256:12c441b8a3994e7df9f0e2692d9298f14c387e70bcc06139420977dbf80a137b # 1.11.2
-    strategy:
-      matrix:
-        image: ["linux-al2023", "windows-core-2019", "windows-core-2022", "ubuntu-focal", "ubuntu-jammy", "ubuntu-jammy-arm64"]
-    defaults:
-      run:
-        working-directory: images/${{ matrix.image }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
@@ -42,9 +36,29 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - name: packer init
-        run: packer init .
-      - name: check packer formatting
-        run: packer fmt -recursive -check=true .
-      - name: packer validate
-        run: packer validate -evaluate-datasources .
+
+      - name: Verify images
+        run: |
+          set -- "${GITHUB_WORKSPACE}"/images/*
+          found_image=false
+
+          while [ "$#" -gt 0 ]; do
+            image_dir="$1"
+            shift
+            [ -d "${image_dir}" ] || continue
+
+            found_image=true
+            image="${image_dir##*/}"
+
+            echo "::group::Verifying ${image}"
+            cd "${image_dir}"
+            packer init .
+            packer fmt -recursive -check=true .
+            packer validate -evaluate-datasources .
+            echo "::endgroup::"
+          done
+
+          [ "${found_image}" = true ] || {
+            echo "No image directories found under ${GITHUB_WORKSPACE}/images"
+            exit 1
+          }

.github/workflows/terraform.yml

@@ -50,6 +50,8 @@ env:
     prebuilt
     ephemeral
     termination-watcher
+    microvm
+    microvm-foundation
     multi-runner
     multi-runner-v2
     external-managed-ssm-secrets

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/examples/microvm.md

@@ -0,0 +1,3 @@
+# Lambda MicroVM
+
+--8<-- "examples/microvm/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/.terraform.lock.hcl.tofu

@@ -0,0 +1,76 @@
+# This file is maintained automatically by "tofu init".
+# Manual edits may be lost in future updates.
+
+provider "registry.opentofu.org/hashicorp/aws" {
+  version     = "6.63.0"
+  constraints = ">= 6.61.0"
+  hashes = [
+    "h1:1jhQJPHOPu2mzDG/ke3tK8PNcEqQHA4vhF05WWlM/yg=",
+    "h1:3+pvT0KN/bkJ6TBuExj+gxptEozhnpo80Ztblwq85eo=",
+    "h1:5aTequ87wZS7Mh4dEIayDGKcFdaFgHtw74NtqY5Idi0=",
+    "h1:AMRlrrM3z1SmrslOtotqKq02zapxLKtXaSN9Jbs0Oho=",
+    "h1:OTjECFWTDxsjcUfOKCNBp75Z5lGrW/KplRDsjTZYT2g=",
+    "h1:b8LORLOKMOOl+nK1M2UhCjELSjjziClJuAv6hYuySHs=",
+    "h1:bUfTX1giRLOyfDbBvsDbwR3tJmsTFRWcOTQdj2npDWA=",
+    "h1:dzs4kwx+itVGAH7yEOyeoWcE3LNRMnWtlt4ROgyAa0M=",
+    "h1:lnjou+SiwpYJ+j9PXWozXPHSPlhxIZb0RqpsSEBzfGw=",
+    "h1:pqzUeHAQj9NctgkwaynaF2aB+3QiZXcoslzMGjT743w=",
+    "h1:qTXEWOWxA6sfUpC29UXrsbHnNzWH7+j1RTUVG4YCm+U=",
+    "h1:qdHKOKt/ISn9RLjUe22OZBpN3F7H2DFeHJL/CSc2x8E=",
+    "h1:tpNzIZBzzUW7/kLU3BhYf3jhdO5uNwYfNmgC9B8kvMM=",
+    "h1:uVVlFgjg6GyxJLbCsTO1+R5fTNbZ73mLpVpSd0mMrFk=",
+    "h1:xGJsV5IFf7c11cXzJrsY40hiJCghp4odT0eJyTyAUYY=",
+    "zh:039a03e920e55f14a691feb67216a2d142bfee603128e15f9c5138f9ecd85016",
+    "zh:14e060b7f46ca7b0fa009b91aef419c58cbdff854de96e9a1d853166f8d902fd",
+    "zh:18803e8fe2c291c8db5526c71b3287ff7c81453f10ca6d8e69cdf9c535b00783",
+    "zh:1b83fce6e31a6095e932d80a7c3f47ac04252653a2de2b98ec6204563310fcba",
+    "zh:2add7bc976ceebb1a94d84598762c9b9cf281ca52ec83deeb4e95e90aa200a12",
+    "zh:2f22cd5372408f11937fa5513a7b960d3cebc334c5ec65fc5322c3bac1c1f664",
+    "zh:41c5e857dacfd83b7ca12a435204957ff6ca8830b9efefd0d381ad4d63b19779",
+    "zh:4eace6246e46999782d219bc4f50f83d19ef9156bacf5ca1528da12da4918015",
+    "zh:5e1c1281c3f929399e2ed3dbdce03426fd57a9ec55cd36e04acf1712aa5954ba",
+    "zh:608272b1f5d75ead123c9d933aa1fed7dc832cedd1506019046b4c8fdcc91dce",
+    "zh:6b3680f8a2f7be2c171953aba89d639fb2624b9cf52ec304e16434874566601d",
+    "zh:99aa1006f2141f3341a02020e1c91abfb02280e57c77e0415c98b8d900353d88",
+    "zh:9ad235bef34a89a8dd9943f9fa9f05cc729bb52a4e0dc926a31bb13cb0ae2418",
+    "zh:e0e3ac361e04748a4ca0c1cdbb6abab2aa817f4ad67e1692817d16e370161d59",
+    "zh:f60962c982a41fde956e796425e7194b4311741c179c060c1c8b5e16a557d635",
+  ]
+}
+
+provider "registry.opentofu.org/hashicorp/time" {
+  version     = "0.14.1"
+  constraints = ">= 0.13.0"
+  hashes = [
+    "h1:+anTsiSl8j75hcu7gKWF2ZlKS/qZDk4Ll0Oq2mVoArU=",
+    "h1:BZtorvSdYDM6pFE8nz7yUVVR2Pe1i0MxZFyBnaKlguY=",
+    "h1:Do/MjWRafefFS6RumnUVbIDH9MyMLuwQXs0kEc4Evrs=",
+    "h1:RoJeKHJjlqMikWdptWEWOBfBv4YxXf8KtZcg6oS8OWE=",
+    "h1:Ssb164oIHIO9VWGljof/xqbxbnPmrT5jyJ+WegAj2+k=",
+    "h1:WGgegEyoMb7nzXr09OvAxaSJls6honSdJiXfNaPTSkw=",
+    "h1:jfH6FAhiYd3hKB29s8cxk9PUKGdEN0fPB3zQ0IE5pdQ=",
+    "h1:lVTdvsa16YmLYJOmGq6ryESpdeWhLyo7Y4MAPPh/gIc=",
+    "h1:nD1nfDyZxI1PgTNT5Zs9G+R9PIiS25xQw9y7tuOD2G0=",
+    "h1:nPu3DGOZfwDier2k8DjNq2ZK3GQDzHYLghIUjb4/KJc=",
+    "h1:o7oRgk39V8okQzrI9DX4AKMTZrIqo6oBj1zQ3tMZJiI=",
+    "h1:oJSgnSkg9lXMISdrA+pXkV8FhgLPk+mAzbFE209jar0=",
+    "h1:oT/ffb2Uy19qRCLu9QSbuAguWwJI9rwW1j6RPjluqRY=",
+    "h1:vWWQpPBXFR9AVZM1o22/pHjNQjRa/IWSVL1mZgMqgLk=",
+    "h1:yTRqKp4efJyAq7bPZjFGcnR1KUDUl2/dBMzILxn5Z+c=",
+    "zh:032ea0f53759a5ade64286ad8a403956bb390860429de3647c6652701c2fff8b",
+    "zh:204581f170c50a579357b1a067f407b890adfc0404952cb922fefe2aba7655a8",
+    "zh:331119864191614a81ce9e8d1ec3ea6fe13da0bea6130f9e1dfd94e3b16ddaaa",
+    "zh:373a8b1b227a92b5e5fee611fef03df7aea82f51c3b1a62b33ac29a1b0ee927f",
+    "zh:46796e7616d511fa264a367ee447f6d0de64e8145f315a12271f4ec5c183f044",
+    "zh:5e3199e6dcc9bb99868764339c35aa169903baa4e150490da2980b2620cdfdbc",
+    "zh:5f95ee94a83a13e6b1e26d3d9f0297ed1036387d7a8adbab90b4ef990b6a1331",
+    "zh:68e1f75602423236d947d9464d62c4cc0a6312ff2206b9306067faf03bed7011",
+    "zh:72ee59f4f859abe6288b59eaacf9a838b8490a132c1c17f393dd8355401704df",
+    "zh:993775eeb0f0b4c898e305dead3cd6cd732b48c1c0fab20c2e4431ef6b678626",
+    "zh:a7b38fea85a1edea7f9afa33e9585970219a788d0300ca095e80b19eec39b291",
+    "zh:b7a8ef0dbee5b76295b1a11d88452ad2798e8d2598925af193884ce405093497",
+    "zh:d3ff8770f4b7cc4dccd4b1b7b40c933b468b7e07a05c704b7ea4c1673c74bf9c",
+    "zh:e59043c6f98aa986956a79c47f1d6bc150d409bbd9c88c9c42d41713bc539f04",
+    "zh:e6c2ae3bdccf6a2e3f106b61895cf7f125684204c1406b29f74fa408671f81cc",
+  ]
+}

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 `aws_region` and `artifact_bucket_name` in `terraform.tfvars` (copy
+`terraform.tfvars.example`). The example creates its VPC and private subnets
+through the reusable `base` example and wires them into the Network Connector.
+
+```bash
+terraform init
+terraform apply
+terraform output
+```
+
+Apply this foundation before building an image with the direct Packer commands
+documented in `../../images/microvm-ubuntu/README.md`. Use the outputs as the build inputs:
+
+- `artifact_bucket_name` -> `MICROVM_ARTIFACT_BUCKET`
+- `build_role_arn` -> `MICROVM_BUILD_ROLE_ARN`
+- `connector_arns.ministack` -> `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.5.6 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.61 |
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_base"></a> [base](#module\_base) | ../base | n/a |
+| <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) | Name for the regional MicroVM build-artifact bucket. | `string` | n/a | yes |
+| <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` | `"gha-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` | `"gha-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` | `"gha-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` | `"gha-microvm-network-operator-"` | no |
+| <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` | `"gha-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,35 @@
+locals {
+  environment = "microvm-foundation"
+  aws_region  = var.aws_region
+
+  network_connectors = {
+    ministack = {
+      name       = "ministack"
+      vpc_id     = module.base.vpc.vpc_id
+      subnet_ids = module.base.vpc.private_subnets
+    }
+  }
+}
+
+module "base" {
+  source = "../base"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+}
+
+module "microvm_foundation" {
+  source = "../../modules/microvm-foundation"
+
+  aws_region                                  = local.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                          = local.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,8 @@
+aws_region = "eu-west-1"
+artifact_bucket_name = "microvm-foundation-artifacts-eu-west-1"
+
+# 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",
+# ]