feat(microvm): tag runner metadata

Author: edersonbrilhante

lambdas/functions/control-plane/src/scale-runners/github-runner.ts

@@ -264,6 +264,15 @@ function addDelay(runnerIds: string[]) {
   return { isDelay, delay };
 }
 
+function mergeSsmParameterTags(
+  configuredTags: CreateGitHubRunnerConfig['ssmParameterStoreTags'],
+  providerTags: CreateGitHubRunnerConfig['ssmParameterStoreTags'],
+): CreateGitHubRunnerConfig['ssmParameterStoreTags'] {
+  const tagsByKey = new Map(configuredTags.map(({ Key, Value }) => [Key, Value]));
+  for (const { Key, Value } of providerTags) tagsByKey.set(Key, Value);
+  return [...tagsByKey].map(([Key, Value]) => ({ Key, Value }));
+}
+
 /**
  * Creates registration token configuration for non-ephemeral runners.
  *
@@ -285,7 +294,10 @@ async function createRegistrationTokenConfig(
 
   for (const runnerId of runnerIds) {
     await putParameter(`${githubRunnerConfig.ssmTokenPath}/${runnerId}`, runnerServiceConfig.join(' '), true, {
-      tags: [...(options.getSsmParameterTags?.(runnerId) ?? []), ...githubRunnerConfig.ssmParameterStoreTags],
+      tags: mergeSsmParameterTags(
+        githubRunnerConfig.ssmParameterStoreTags,
+        options.getSsmParameterTags?.(runnerId) ?? [],
+      ),
     });
     if (isDelay) {
       // Delay to prevent AWS ssm rate limits by being within the max throughput limit
@@ -352,7 +364,10 @@ async function createJitConfig(
         instance: runnerId,
       });
       await putParameter(`${githubRunnerConfig.ssmTokenPath}/${runnerId}`, runnerConfig.data.encoded_jit_config, true, {
-        tags: [...(options.getSsmParameterTags?.(runnerId) ?? []), ...githubRunnerConfig.ssmParameterStoreTags],
+        tags: mergeSsmParameterTags(
+          githubRunnerConfig.ssmParameterStoreTags,
+          options.getSsmParameterTags?.(runnerId) ?? [],
+        ),
       });
       if (isDelay) {
         // Delay to prevent AWS ssm rate limits by being within the max throughput limit

lambdas/functions/control-plane/src/scale-runners/scale-up.test.ts

@@ -409,6 +409,25 @@ describe('scaleUp with GHES', () => {
       });
     });
 
+    it.each([true, false])(
+      'keeps the provider runner identity tag authoritative for ephemeral=%s',
+      async (ephemeral) => {
+        process.env.ENABLE_EPHEMERAL_RUNNERS = String(ephemeral);
+        process.env.RUNNERS_MAXIMUM_COUNT = '2';
+        process.env.SSM_PARAMETER_STORE_TAGS = JSON.stringify([
+          { Key: 'RunnerId', Value: 'configured-value-cannot-win' },
+          { Key: 'CostCenter', Value: '1234' },
+        ]);
+
+        await scaleUpModule.scaleUp(TEST_DATA);
+
+        expect(mockSSMClient.commandCalls(PutParameterCommand)[0].args[0].input.Tags).toEqual([
+          { Key: 'RunnerId', Value: 'i-12345' },
+          { Key: 'CostCenter', Value: '1234' },
+        ]);
+      },
+    );
+
     it('quotes runner labels with semicolon separators in non-ephemeral runner config', async () => {
       process.env.ENABLE_EPHEMERAL_RUNNERS = 'false';
       process.env.RUNNERS_MAXIMUM_COUNT = '2';

lambdas/libs/aws-ssm-util/src/index.test.ts

@@ -1,4 +1,5 @@
 import {
+  AddTagsToResourceCommand,
   DeleteParameterCommand,
   GetParameterCommand,
   GetParameterCommandOutput,
@@ -13,6 +14,7 @@ import { mockClient } from 'aws-sdk-client-mock';
 import nock from 'nock';
 
 import {
+  addParameterTags,
   deleteParameter,
   getParameter,
   getParameters,
@@ -329,6 +331,30 @@ describe('Test direct parameter path operations', () => {
 
     expect(mockSSMClient).toHaveReceivedCommandWith(DeleteParameterCommand, { Name: '/metadata/one' });
   });
+
+  it('adds tags to an exact parameter name', async () => {
+    mockSSMClient.on(AddTagsToResourceCommand).resolves({});
+
+    await addParameterTags('/metadata/one', [{ Key: 'ghr:environment', Value: 'unit-test' }]);
+
+    expect(mockSSMClient).toHaveReceivedCommandWith(AddTagsToResourceCommand, {
+      ResourceType: 'Parameter',
+      ResourceId: '/metadata/one',
+      Tags: [{ Key: 'ghr:environment', Value: 'unit-test' }],
+    });
+  });
+
+  it('does not call SSM when there are no parameter tags to add', async () => {
+    await addParameterTags('/metadata/one', []);
+
+    expect(mockSSMClient).not.toHaveReceivedCommand(AddTagsToResourceCommand);
+  });
+
+  it('propagates failures when adding parameter tags', async () => {
+    mockSSMClient.on(AddTagsToResourceCommand).rejects(new Error('AccessDenied'));
+
+    await expect(addParameterTags('/metadata/one', [{ Key: 'Name', Value: 'runner' }])).rejects.toThrow('AccessDenied');
+  });
 });
 
 describe('SSM client configuration', () => {

lambdas/libs/aws-ssm-util/src/index.ts

@@ -1,4 +1,5 @@
 import {
+  AddTagsToResourceCommand,
   DeleteParameterCommand,
   GetParametersByPathCommand,
   GetParametersCommand,
@@ -146,6 +147,18 @@ export async function deleteParameter(parameter_name: string): Promise<void> {
   await ssmClient().send(new DeleteParameterCommand({ Name: parameter_name }));
 }
 
+export async function addParameterTags(parameter_name: string, tags: Tag[]): Promise<void> {
+  if (tags.length === 0) return;
+
+  await ssmClient().send(
+    new AddTagsToResourceCommand({
+      ResourceType: 'Parameter',
+      ResourceId: parameter_name,
+      Tags: tags,
+    }),
+  );
+}
+
 export const SSM_ADVANCED_TIER_THRESHOLD = 4000;
 
 type PutParameterOptions = { overwrite: true; tags?: never } | { overwrite?: false | undefined; tags?: Tag[] };

lambdas/libs/compute-providers/aws/microvm/README.md

@@ -11,7 +11,7 @@ The MicroVM image `/run` hook receives this `runHookPayload`:
 }
 ```
 
-Lambda adds `microvmId` beside that payload. The image must poll the SecureString parameter at `<runnerConfigSsmPath>/<microvmId>`, start the GitHub runner with its encoded JIT configuration, delete the parameter after reading it, and terminate the MicroVM after the job completes.
+Lambda adds `microvmId` beside that payload. The image must poll the SecureString parameter at `<runnerConfigSsmPath>/<microvmId>`, start the GitHub runner with its encoded JIT configuration, delete the parameter after reading it, and exit its lifecycle entrypoint after the job completes. Trusted control-plane cleanup and the fixed lifetime remain termination backstops.
 
 Runner ownership and lifecycle state are stored separately as non-secret `String`
 parameters under `<MICROVM_METADATA_SSM_PATH>/<microvmId>`. The immutable base
@@ -22,6 +22,19 @@ overlap the JIT path, and do not grant the MicroVM execution role access to it.
 The control plane retries pending cleanup, removes metadata after termination,
 and reconciles expired records during inventory.
 
+The immutable base metadata parameter is also the canonical tag surface for a
+runner. It merges `SSM_PARAMETER_STORE_TAGS` with the Terraform-generated
+`MICROVM_METADATA_TAGS`. Terraform supplies `Name`, `ghr:environment`,
+`ghr:ssm_config_path`, and `ghr:runner_name_prefix`; the Lambda then adds
+authoritative runtime tags:
+`ghr:Application`, `ghr:created_by`, `ghr:environment`, `ghr:Owner`,
+`ghr:Type`, `ghr:microvm_id`, `ghr:microvm_image_arn`, and, when available,
+`ghr:microvm_image_version`. After JIT registration, the control plane adds
+`ghr:github_runner_id` and base64url-encoded runner-label groups under
+`ghr:runner_labels` through `ghr:runner_labels:5`. Runtime-owned values override
+configured collisions. The `aws:` tag prefix is reserved and cannot be used for
+these SSM parameters.
+
 The control-plane Lambda requires these provider environment variables:
 
 - `MICROVM_IMAGE_ARN`
@@ -30,31 +43,33 @@ The control-plane Lambda requires these provider environment variables:
 - `MICROVM_INGRESS_NETWORK_CONNECTORS` (optional JSON array or comma-separated list)
 - `MICROVM_EGRESS_NETWORK_CONNECTORS` (optional JSON array or comma-separated list)
 - `MICROVM_METADATA_SSM_PATH` (dedicated SSM path for control-plane metadata)
+- `MICROVM_METADATA_TAGS` (optional JSON array of base tags for the canonical metadata parameter)
 - `MICROVM_LOG_GROUP` (optional)
 
 Each runner is launched with a fixed lifetime of 28,800 seconds (8 hours).
 
 The control-plane role requires `ssm:GetParametersByPath`, `ssm:PutParameter`,
-and `ssm:DeleteParameter` on the dedicated metadata prefix, plus
-`lambda:ListMicrovms`, `lambda:RunMicrovm`, and `lambda:TerminateMicrovm` for
-inventory and lifecycle reconciliation. Restrict `lambda:RunMicrovm` and
-`lambda:TerminateMicrovm` to approved image resources; `lambda:ListMicrovms`
-does not support resource-level permissions.
+`ssm:AddTagsToResource`, and `ssm:DeleteParameter` on the dedicated metadata
+prefix, plus `lambda:ListMicrovms`, `lambda:RunMicrovm`, and
+`lambda:TerminateMicrovm` for inventory and lifecycle reconciliation. Restrict
+`lambda:RunMicrovm` and `lambda:TerminateMicrovm` to approved image resources;
+`lambda:ListMicrovms` does not support resource-level permissions.
 
 The MicroVM execution role must trust `lambda.amazonaws.com` for both
 `sts:AssumeRole` and `sts:TagSession`. Restrict `iam:PassRole` to that exact role
-with `iam:PassedToService=lambda.amazonaws.com`. Egress connectors also require
-`lambda:PassNetworkConnector`; because that action does not currently support
-resource-level permissions, enforce the connector boundary with the explicit
-dynamic-label allowlist described below.
+ARN. Network connectors also require `lambda:PassNetworkConnector`; because
+that action does not currently support resource-level permissions, enforce the
+connector boundary with the explicit dynamic-label allowlist described below.
 
 All MicroVMs using one execution role and JIT prefix share a trust boundary.
-Grant that role only `ssm:GetParameter` and `ssm:DeleteParameter` on the JIT
-prefix; do not grant parameter-listing APIs or access to the metadata prefix.
-The `MicrovmId` tag on each JIT parameter supports operations but is not a
-documented binding to the calling MicroVM's session identity. Only allow trusted
-images and workloads within a shared role, or isolate trust domains with
-separate roles, prefixes, and provider deployments.
+Grant that role only `ssm:GetParameter` and `ssm:DeleteParameter` on the
+lane-scoped JIT prefix. The image must use the
+exact `<runnerConfigSsmPath>/<microvmId>` parameter name and must not receive
+access to the metadata prefix or path-listing APIs. The `MicrovmId` tag on each
+JIT parameter supports operations but is not a documented binding to the
+calling MicroVM's session identity. Only allow trusted images and workloads
+within a shared role, or isolate trust domains with separate roles, prefixes,
+and provider deployments.
 
 ## Dynamic labels
 

lambdas/libs/compute-providers/aws/microvm/src/control-plane/config.test.ts

@@ -9,6 +9,7 @@ beforeEach(() => {
   process.env.MICROVM_IMAGE_ARN = 'arn:aws:lambda:eu-west-1:123456789012:microvm-image:runner';
   process.env.MICROVM_EXECUTION_ROLE_ARN = 'arn:aws:iam::123456789012:role/microvm-runner';
   process.env.MICROVM_METADATA_SSM_PATH = '/github-action-runners/unit-test/microvm-metadata/';
+  delete process.env.MICROVM_METADATA_TAGS;
   delete process.env.MICROVM_IMAGE_VERSION;
   delete process.env.MICROVM_INGRESS_NETWORK_CONNECTORS;
   delete process.env.MICROVM_EGRESS_NETWORK_CONNECTORS;
@@ -24,6 +25,7 @@ describe('loadMicrovmProviderConfig', () => {
       ingressNetworkConnectors: undefined,
       egressNetworkConnectors: undefined,
       metadataSsmPath: '/github-action-runners/unit-test/microvm-metadata',
+      metadataTags: [],
       logging: undefined,
     });
   });
@@ -33,11 +35,19 @@ describe('loadMicrovmProviderConfig', () => {
     process.env.MICROVM_INGRESS_NETWORK_CONNECTORS = '["arn:ingress:one","arn:ingress:two"]';
     process.env.MICROVM_EGRESS_NETWORK_CONNECTORS = 'arn:egress:one, arn:egress:two';
     process.env.MICROVM_LOG_GROUP = ' /aws/lambda-microvms/runner ';
+    process.env.MICROVM_METADATA_TAGS = JSON.stringify([
+      { Key: 'Name', Value: 'unit-test-runner' },
+      { Key: 'ghr:environment', Value: 'unit-test' },
+    ]);
 
     expect(loadMicrovmProviderConfig()).toMatchObject({
       imageVersion: '3.0',
       ingressNetworkConnectors: ['arn:ingress:one', 'arn:ingress:two'],
       egressNetworkConnectors: ['arn:egress:one', 'arn:egress:two'],
+      metadataTags: [
+        { Key: 'Name', Value: 'unit-test-runner' },
+        { Key: 'ghr:environment', Value: 'unit-test' },
+      ],
       logging: { cloudWatch: { logGroup: '/aws/lambda-microvms/runner' } },
     });
   });
@@ -70,4 +80,17 @@ describe('loadMicrovmProviderConfig', () => {
       );
     },
   );
+
+  it.each([
+    '[not-json',
+    '{}',
+    '[{"Key":"Name"}]',
+    '[{"Key":"","Value":"runner"}]',
+    '[{"Key":"Name","Value":1}]',
+    '[{"Key":"Name","Value":"one"},{"Key":"Name","Value":"two"}]',
+  ])('rejects malformed metadata tags %s', (tags) => {
+    process.env.MICROVM_METADATA_TAGS = tags;
+
+    expect(() => loadMicrovmProviderConfig()).toThrow(/MICROVM_METADATA_TAGS must/);
+  });
 });

lambdas/libs/compute-providers/aws/microvm/src/control-plane/config.ts

@@ -1,5 +1,10 @@
 import type { Logging, RunMicrovmCommandInput } from '@aws-sdk/client-lambda-microvms';
 
+export interface MicrovmMetadataTag {
+  Key: string;
+  Value: string;
+}
+
 export interface MicrovmProviderConfig {
   egressNetworkConnectors?: string[];
   executionRoleArn: string;
@@ -8,6 +13,7 @@ export interface MicrovmProviderConfig {
   ingressNetworkConnectors?: string[];
   logging?: Logging;
   metadataSsmPath: string;
+  metadataTags: MicrovmMetadataTag[];
 }
 
 function requiredEnvironmentValue(name: string, value: string | undefined): string {
@@ -55,6 +61,41 @@ function parseNetworkConnectors(name: string, value: string | undefined): string
   return connectors.map((connector) => connector.trim());
 }
 
+function parseMetadataTags(value: string | undefined): MicrovmMetadataTag[] {
+  const configuredValue = optionalEnvironmentValue(value);
+  if (!configuredValue) return [];
+
+  let tags: unknown;
+  try {
+    tags = JSON.parse(configuredValue);
+  } catch (error) {
+    throw new Error('MICROVM_METADATA_TAGS must be a JSON array of SSM tag objects', { cause: error });
+  }
+
+  if (
+    !Array.isArray(tags) ||
+    tags.some(
+      (tag) =>
+        typeof tag !== 'object' ||
+        tag === null ||
+        !('Key' in tag) ||
+        typeof tag.Key !== 'string' ||
+        tag.Key.length === 0 ||
+        !('Value' in tag) ||
+        typeof tag.Value !== 'string',
+    )
+  ) {
+    throw new Error('MICROVM_METADATA_TAGS must be a JSON array of SSM tag objects');
+  }
+
+  const typedTags = tags as MicrovmMetadataTag[];
+  if (new Set(typedTags.map((tag) => tag.Key)).size !== typedTags.length) {
+    throw new Error('MICROVM_METADATA_TAGS must not contain duplicate tag keys');
+  }
+
+  return typedTags;
+}
+
 export function loadMicrovmProviderConfig(): MicrovmProviderConfig {
   const logGroup = optionalEnvironmentValue(process.env.MICROVM_LOG_GROUP);
 
@@ -71,6 +112,7 @@ export function loadMicrovmProviderConfig(): MicrovmProviderConfig {
       process.env.MICROVM_EGRESS_NETWORK_CONNECTORS,
     ),
     metadataSsmPath: parseMetadataSsmPath(process.env.MICROVM_METADATA_SSM_PATH),
+    metadataTags: parseMetadataTags(process.env.MICROVM_METADATA_TAGS),
     logging: logGroup ? ({ cloudWatch: { logGroup } } satisfies RunMicrovmCommandInput['logging']) : undefined,
   };
 }