feat(microvm): add image build example

.github/workflows/packer-build.yml

@@ -28,7 +28,7 @@ jobs:
       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"]
+        image: ["linux-al2023", "windows-core-2019", "windows-core-2022", "ubuntu-focal", "ubuntu-jammy", "ubuntu-jammy-arm64", "microvm-ubuntu"]
     defaults:
       run:
         working-directory: images/${{ matrix.image }}

.github/workflows/terraform.yml

@@ -160,7 +160,8 @@ jobs:
             "multi-runner",
             "multi-runner-v2",
             "external-managed-ssm-secrets",
-            "microvm-foundation"
+            "microvm-foundation",
+            "microvm"
           ]
     defaults:
       run:

docs/examples/microvm.md

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

examples/microvm-foundation/README.md

@@ -14,7 +14,7 @@ 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:
+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`

examples/microvm/README.md

@@ -0,0 +1,102 @@
+# Lambda MicroVM runner example
+
+This example creates the VPC and GitHub Actions runner control plane for one
+Linux ARM64 Lambda MicroVM lane. The lane uses ephemeral runners and
+just-in-time configuration, which are required by the MicroVM provider.
+
+The regional MicroVM foundation is provisioned separately by the
+[`microvm-foundation`](../microvm-foundation) example. Apply that example
+first and provide its artifact bucket, build role, and egress Network Connector
+outputs to the image build script. The image ARN produced by that build is then
+supplied to this example.
+
+The GitHub App credentials must already exist in SSM Parameter Store. The
+example outputs the webhook endpoint; configure that endpoint on the GitHub
+App with the same secret stored in the referenced SSM parameter.
+
+## Usage
+
+Build or download the Lambda archives into an S3 bucket, then create a
+`terraform.tfvars` file. The parameter references below are examples only:
+
+```hcl
+aws_region             = "eu-west-1"
+lambda_artifact_bucket = "my-runner-lambda-artifacts"
+microvm_image_arn      = "arn:aws:lambda:eu-west-1:123456789012:microvm-image:github-runner-arm64"
+egress_network_connector_arn = "arn:aws:lambda:eu-west-1:123456789012:network-connector:example"
+
+github_app = {
+  key_base64_ssm = {
+    arn  = "arn:aws:ssm:eu-west-1:123456789012:parameter/github-runner/app-key"
+    name = "/github-runner/app-key"
+  }
+  id_ssm = {
+    arn  = "arn:aws:ssm:eu-west-1:123456789012:parameter/github-runner/app-id"
+    name = "/github-runner/app-id"
+  }
+  webhook_secret_ssm = {
+    arn  = "arn:aws:ssm:eu-west-1:123456789012:parameter/github-runner/webhook-secret"
+    name = "/github-runner/webhook-secret"
+  }
+}
+```
+
+Run Terraform from this directory:
+
+```bash
+terraform init
+terraform apply
+terraform output -raw webhook_endpoint
+```
+
+The MicroVM image must be built for Linux ARM64 and should use a versioned image
+ARN in production. Network connector egress remains bounded by the VPC route
+tables and network ACLs configured by the helper module.
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 6.33 |
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_base"></a> [base](#module\_base) | ../base | n/a |
+| <a name="module_runners"></a> [runners](#module\_runners) | ../../modules/multi-runner | n/a |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS Region where the runner control plane and MicroVM resources are deployed. | `string` | `"eu-west-1"` | no |
+| <a name="input_egress_network_connector_arn"></a> [egress\_network\_connector\_arn](#input\_egress\_network\_connector\_arn) | Regional Lambda Network Connector ARN used by MicroVMs and the image build. | `string` | n/a | yes |
+| <a name="input_environment"></a> [environment](#input\_environment) | Name prefix for the example resources. | `string` | `null` | no |
+| <a name="input_github_app"></a> [github\_app](#input\_github\_app) | Pre-created SSM parameter references for the GitHub App credentials. | <pre>object({<br/>    key_base64 = optional(string)<br/>    key_base64_ssm = optional(object({<br/>      arn  = string<br/>      name = string<br/>    }))<br/>    id = optional(string)<br/>    id_ssm = optional(object({<br/>      arn  = string<br/>      name = string<br/>    }))<br/>    webhook_secret = optional(string)<br/>    webhook_secret_ssm = optional(object({<br/>      arn  = string<br/>      name = string<br/>    }))<br/>  })</pre> | n/a | yes |
+| <a name="input_ingress_network_connector_arns"></a> [ingress\_network\_connector\_arns](#input\_ingress\_network\_connector\_arns) | Optional regional Lambda Network Connector ARNs exposed to MicroVMs. | `list(string)` | `[]` | no |
+| <a name="input_lambda_artifact_bucket"></a> [lambda\_artifact\_bucket](#input\_lambda\_artifact\_bucket) | S3 bucket containing the runner-control Lambda artifacts. | `string` | n/a | yes |
+| <a name="input_microvm_image_arn"></a> [microvm\_image\_arn](#input\_microvm\_image\_arn) | Lambda MicroVM image ARN produced by the MicroVM image build. | `string` | n/a | yes |
+| <a name="input_microvm_image_version"></a> [microvm\_image\_version](#input\_microvm\_image\_version) | Optional immutable version of the Lambda MicroVM image. | `string` | `null` | no |
+| <a name="input_organization_runners"></a> [organization\_runners](#input\_organization\_runners) | Register the MicroVM runners at organization scope when true. | `bool` | `false` | no |
+| <a name="input_runners_lambda_s3_key"></a> [runners\_lambda\_s3\_key](#input\_runners\_lambda\_s3\_key) | S3 key for the runners Lambda archive. | `string` | `"runners.zip"` | no |
+| <a name="input_runners_maximum_count"></a> [runners\_maximum\_count](#input\_runners\_maximum\_count) | Maximum number of concurrent MicroVM runners. | `number` | `10` | no |
+| <a name="input_webhook_lambda_s3_key"></a> [webhook\_lambda\_s3\_key](#input\_webhook\_lambda\_s3\_key) | S3 key for the webhook Lambda archive. | `string` | `"webhook.zip"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_microvm_image_arn"></a> [microvm\_image\_arn](#output\_microvm\_image\_arn) | The MicroVM image ARN consumed by this runner configuration. |
+| <a name="output_webhook_endpoint"></a> [webhook\_endpoint](#output\_webhook\_endpoint) | Webhook endpoint to configure on the GitHub App. |
+<!-- END_TF_DOCS -->

examples/microvm/main.tf

@@ -0,0 +1,110 @@
+locals {
+  environment = coalesce(var.environment, "microvm")
+  aws_region  = var.aws_region
+}
+
+module "base" {
+  source = "../base"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+}
+
+module "runners" {
+  source = "../../modules/multi-runner"
+
+  aws_region = local.aws_region
+  vpc_id     = module.base.vpc.vpc_id
+  subnet_ids = module.base.vpc.private_subnets
+  prefix     = local.environment
+
+  # Required for backwards-compatible module input validation; the non-empty
+  # experimental map selects the MicroVM configuration below.
+  multi_runner_config = {}
+
+  # Keep GitHub App credentials in pre-created SSM parameters. This example
+  # therefore does not place the private key or webhook secret in Terraform
+  # configuration or state.
+  github_app = var.github_app
+
+  experimental_global_config_github = {
+    app = var.github_app
+  }
+
+  experimental_global_config_lambda = {
+    artifact = {
+      s3 = {
+        bucket = var.lambda_artifact_bucket
+      }
+    }
+  }
+
+  experimental_global_config_orchestration_provider = {
+    webhook = {
+      runner = {
+        ephemeral            = true
+        jit_config_enabled   = true
+        maximum_count        = var.runners_maximum_count
+        boot_time_in_minutes = 5
+      }
+      github = {
+        organization_runners = var.organization_runners
+      }
+      lambda = {
+        artifact = {
+          s3 = {
+            key = var.runners_lambda_s3_key
+          }
+        }
+        webhook = {
+          artifact = {
+            s3 = {
+              key = var.webhook_lambda_s3_key
+            }
+          }
+        }
+      }
+    }
+  }
+
+  experimental_global_config_ssm = {
+    paths = {
+      root = "/github-action-runners/${local.environment}"
+    }
+  }
+
+  experimental_global_config_compute_provider = {
+    aws = {
+      microvm = {
+        image_arn                  = var.microvm_image_arn
+        image_version              = var.microvm_image_version
+        ingress_network_connectors = var.ingress_network_connector_arns
+        egress_network_connectors  = [var.egress_network_connector_arn]
+      }
+    }
+  }
+
+  experimental_multi_runner_config = {
+    microvm = {
+      runner = {
+        os           = "linux"
+        architecture = "arm64"
+        name_prefix  = "microvm-"
+        extra_labels = ["microvm"]
+      }
+      orchestration_provider = {
+        webhook = {
+          matcherConfig = {
+            labelMatchers           = [["self-hosted", "linux", "arm64", "microvm"]]
+            bidirectionalLabelMatch = true
+          }
+        }
+      }
+      compute_provider = {
+        aws = {
+          microvm = {}
+        }
+      }
+    }
+  }
+}

examples/microvm/outputs.tf

@@ -0,0 +1,9 @@
+output "webhook_endpoint" {
+  description = "Webhook endpoint to configure on the GitHub App."
+  value       = module.runners.webhook.endpoint
+}
+
+output "microvm_image_arn" {
+  description = "The MicroVM image ARN consumed by this runner configuration."
+  value       = var.microvm_image_arn
+}

examples/microvm/providers.tf

@@ -0,0 +1,9 @@
+provider "aws" {
+  region = local.aws_region
+
+  default_tags {
+    tags = {
+      Example = local.environment
+    }
+  }
+}