feat(microvm): add microvm example

.github/workflows/ministack.yml

@@ -51,14 +51,15 @@ jobs:
           - prebuilt
           - default
           - ephemeral
+          - microvm-foundation
           - multi-runner
-          - multi-runner-v2
           - multi-runner-scale-set
           - migration-test
+          - multi-runner
           - termination-watcher
     services:
       ministack:
-        image: ghcr.io/ministackorg/ministack:1.5.13@sha256:ce3c906f2866ff953ce4c56f06b1fa3e453bc32e41c00de17b5f5a8672c5a42c
+        image: ghcr.io/ministackorg/ministack:1.5.16@sha256:9813da34285a0760477c761c1c03717e0290d259213c0ca97f551fefd87b292d
         ports:
           - 4566:4566
         env:

.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

@@ -51,8 +51,8 @@ env:
     prebuilt
     ephemeral
     termination-watcher
+    microvm-foundation
     multi-runner
-    multi-runner-v2
     multi-runner-scale-set
     external-managed-ssm-secrets
   TEST_MODULES: |

docs/examples/index.md

@@ -5,10 +5,11 @@ Examples are located in the [examples](https://github.com/github-aws-runners/ter
 - _[Default](default.md)_: The default example of the module
 - _[Ephemeral](ephemeral.md)_: Example usages of ephemeral runners based on the default example.
 - _[Multi Runner](multi-runner.md)_ : Example usage of creating a multi runner which creates multiple runners/ configurations with a single deployment. The examples including: "arm64", "windows", and "ubuntu" runners.
-- _[Multi Runner v2](multi-runner-v2.md)_ : Example usage of the experimental v2 multi-runner configuration interface with shared defaults and per-lane overrides.
+- _[Multi Runner Webhook](multi-runner-webhook.md)_: Example usage of one webhook deployment serving EC2 and Lambda MicroVM runner lanes.
 - _[Multi Runner scale-set](multi-runner-scale-set.md)_ : Example usage of a v2 deployment combining webhook lanes with an experimental GitHub Actions scale-set lane.
 - _[Permissions boundary](permissions-boundary.md)_: Example usages of permissions boundaries.
 - _[Prebuilt Images](prebuilt.md)_: Example usages of deploying runners with a custom prebuilt image.
 - _[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.

docs/examples/microvm-foundation.md

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

docs/examples/multi-runner-webhook.md

@@ -0,0 +1 @@
+--8<-- "examples/multi-runner-webhook/README.md"

docs/microvm-runners.md

@@ -0,0 +1,129 @@
+# Lambda MicroVM Runners (Experimental)
+
+!!! warning
+    Lambda MicroVM runner support is experimental. The image build, lifecycle-hook server, control-plane integration, and AWS MicroVM APIs must be configured together. Validate the complete flow in a non-production environment before relying on it for workloads.
+
+## Overview
+
+Lambda MicroVM runners provide ephemeral GitHub Actions runners backed by
+Lambda MicroVMs. The runner control plane receives demand, obtains the
+one-time runner configuration, starts a MicroVM from a published image, and
+passes the runtime execution role to the MicroVM.
+
+The repository includes a combined [multi-runner webhook example](examples/multi-runner-webhook.md)
+that places EC2 and Lambda MicroVM lanes behind one webhook endpoint. The
+provider-specific lifecycle checks are shared where possible, so the same
+deployment can validate both providers.
+
+## Prerequisites
+
+Before deploying the MicroVM runner lane, prepare all of the following in the
+target AWS Region:
+
+1. **MicroVM foundation.** Apply the
+   [MicroVM foundation example](examples/microvm-foundation.md). It creates the
+   regional artifact bucket, Lambda Network Connectors, the image-build role,
+   and the reusable MicroVM usage policy.
+2. **Lifecycle-hook artifact.** Build and release
+   `lambdas/services/microvm-lifecycle-hooks` through the same workspace
+   artifact process used for the repository's Lambda services. The resulting
+   ZIP is embedded in the MicroVM image.
+3. **Published MicroVM image.** Use the
+   [MicroVM Ubuntu image instructions](https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/images/microvm-ubuntu/README.md)
+   to build and publish an image with Packer. The image must contain the
+   compatible lifecycle-hook server and runner entrypoint.
+4. **Runner execution role.** Configure the runner role through the runner
+   configuration. This is different from the foundation's build role. The
+   control-plane TypeScript passes the execution role to `RunMicrovm`, so the
+   Lambda that starts the MicroVM must have permission to pass it.
+5. **Runner control plane and artifacts.** Deploy the runner control plane with
+   the published image ARN/version, Network Connector ARNs, GitHub App
+   configuration, and the runner-control and webhook Lambda ZIPs.
+
+The foundation does not create the image or the runner execution role. The
+image build does not choose the runtime role. These are separate dependencies
+owned by the image build and runner-control-plane stages respectively.
+
+## IAM roles
+
+MicroVM deployments use two roles for two different operations:
+
+| Role | Used by | Responsibility |
+| --- | --- | --- |
+| Build role (`build_role_arn`) | Packer/image publisher | Creates and publishes the MicroVM image and accesses the foundation build artifacts. |
+| Execution role | Runner control plane and the MicroVM | Is passed to `RunMicrovm` and provides the permissions used by the ephemeral runner at runtime. |
+
+Do not use the build role as the runner execution role. The control-plane
+Lambda needs `iam:PassRole` for the configured execution role, and the
+execution role must contain the runtime permissions required by the selected
+runner lane.
+
+## Deployment order
+
+The complete dependency chain is:
+
+```text
+MicroVM foundation
+        |
+        v
+Build/release lifecycle-hook server
+        |
+        v
+Packer builds and publishes image
+        |
+        v
+Runner control plane resolves execution role
+        |
+        v
+RunMicrovm starts an ephemeral runner
+```
+
+The lifecycle-hook server is part of the image artifact. Updating the hook
+server therefore requires building/releasing the artifact and publishing a
+new compatible image before deploying that image version to the runner lane.
+
+## Combined EC2 and MicroVM deployment
+
+The [multi-runner webhook example](examples/multi-runner-webhook.md) accepts
+explicit `runners_lambda_zip` and `webhook_lambda_zip` inputs and configures
+both compute providers behind one webhook. Its MicroVM settings require a
+published image:
+
+```hcl
+compute_provider = {
+  aws = {
+    microvm = {
+      image_arn                 = "arn:aws:lambda:eu-west-1:123456789012:microvm-image:gha-ubuntu-arm64"
+      image_version             = null
+      ingress_network_connectors = []
+      egress_network_connectors  = ["arn:aws:lambda:eu-west-1:123456789012:network-connector:example"]
+    }
+  }
+}
+```
+
+Use the example's complete Terraform configuration as the source of truth for
+the current input shape. The example deploys the control plane; it does not
+build the foundation, lifecycle-hook artifact, or MicroVM image for you.
+
+## Known limitations
+
+- This integration is experimental and depends on AWS Lambda MicroVM APIs and
+  the lifecycle-hook protocol.
+- A compatible lifecycle-hook server must be present in every image used by
+  the MicroVM provider.
+- Image publication and activation are separate from Terraform deployment;
+  wait for the image version to become active before starting jobs.
+- The build role and execution role are intentionally separate. Changes to
+  either role can affect a different stage of the lifecycle.
+- The combined webhook example is useful for integration testing, but a real
+  deployment still needs a real MicroVM image and the network/runtime IAM
+  configuration described above.
+
+## Repository examples
+
+- [MicroVM foundation](examples/microvm-foundation.md)
+- [MicroVM image build README](https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/images/microvm-ubuntu/README.md)
+- [Lifecycle-hook service README](https://github.com/github-aws-runners/terraform-aws-github-runner/blob/main/lambdas/services/microvm-lifecycle-hooks/README.md)
+- [Multi-runner webhook](examples/multi-runner-webhook.md)
+- [MicroVM foundation module](modules/public/microvm-foundation.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",
+  ]
+}