fix(compute-providers): replace unsupported MicroVM tags

Author: edersonbrilhante

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

@@ -1,6 +1,8 @@
 import {
+  DeleteParameterCommand,
   GetParameterCommand,
   GetParameterCommandOutput,
+  GetParametersByPathCommand,
   GetParametersCommand,
   PutParameterCommand,
   PutParameterCommandOutput,
@@ -10,7 +12,16 @@ import 'aws-sdk-client-mock-jest/vitest';
 import { mockClient } from 'aws-sdk-client-mock';
 import nock from 'nock';
 
-import { getParameter, getParameters, putParameter, resetSSMClient, ssmClient, SSM_ADVANCED_TIER_THRESHOLD } from '.';
+import {
+  deleteParameter,
+  getParameter,
+  getParameters,
+  getParametersByPath,
+  putParameter,
+  resetSSMClient,
+  ssmClient,
+  SSM_ADVANCED_TIER_THRESHOLD,
+} from '.';
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 
 const mockSSMClient = mockClient(SSMClient);
@@ -104,6 +115,30 @@ describe('Test getParameter and putParameter', () => {
     });
   });
 
+  it('overwrites a parameter only when explicitly requested', async () => {
+    mockSSMClient.on(PutParameterCommand).resolves({});
+
+    await putParameter('testParam', 'updated', false, { overwrite: true });
+
+    expect(mockSSMClient).toHaveReceivedCommandWith(PutParameterCommand, {
+      Name: 'testParam',
+      Value: 'updated',
+      Type: 'String',
+      Overwrite: true,
+    });
+  });
+
+  it('rejects tags when overwriting an existing parameter', async () => {
+    mockSSMClient.resetHistory();
+    await expect(
+      putParameter('testParam', 'updated', false, {
+        overwrite: true,
+        tags: [{ Key: 'owner', Value: 'runner' }],
+      } as never),
+    ).rejects.toThrow('tags cannot be supplied when overwriting');
+    expect(mockSSMClient).not.toHaveReceivedCommand(PutParameterCommand);
+  });
+
   it('Puts parameters as SecureString', async () => {
     // Arrange
     const parameterValue = 'test';
@@ -256,6 +291,46 @@ describe('Test getParameters (batch)', () => {
   });
 });
 
+describe('Test direct parameter path operations', () => {
+  beforeEach(() => {
+    mockSSMClient.reset();
+  });
+
+  it('paginates direct, non-secret children of a parameter path', async () => {
+    mockSSMClient
+      .on(GetParametersByPathCommand, {
+        Path: '/metadata',
+        Recursive: false,
+        WithDecryption: false,
+        NextToken: undefined,
+      })
+      .resolves({ Parameters: [{ Name: '/metadata/one', Value: '1' }], NextToken: 'page-2' })
+      .on(GetParametersByPathCommand, {
+        Path: '/metadata',
+        Recursive: false,
+        WithDecryption: false,
+        NextToken: 'page-2',
+      })
+      .resolves({ Parameters: [{ Name: '/metadata/two', Value: '2' }] });
+
+    await expect(getParametersByPath('/metadata')).resolves.toEqual(
+      new Map([
+        ['/metadata/one', '1'],
+        ['/metadata/two', '2'],
+      ]),
+    );
+    expect(mockSSMClient).toHaveReceivedCommandTimes(GetParametersByPathCommand, 2);
+  });
+
+  it('deletes an exact parameter name', async () => {
+    mockSSMClient.on(DeleteParameterCommand).resolves({});
+
+    await deleteParameter('/metadata/one');
+
+    expect(mockSSMClient).toHaveReceivedCommandWith(DeleteParameterCommand, { Name: '/metadata/one' });
+  });
+});
+
 describe('SSM client configuration', () => {
   it('configures adaptive retry with a raised attempt cap', async () => {
     const config = ssmClient().config;

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

@@ -1,4 +1,11 @@
-import { GetParametersCommand, PutParameterCommand, SSMClient, Tag } from '@aws-sdk/client-ssm';
+import {
+  DeleteParameterCommand,
+  GetParametersByPathCommand,
+  GetParametersCommand,
+  PutParameterCommand,
+  SSMClient,
+  Tag,
+} from '@aws-sdk/client-ssm';
 import { getTracedAWSV3Client } from '@aws-github-runner/aws-powertools-util';
 import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
 
@@ -103,14 +110,56 @@ export async function getParameters(parameter_names: string[]): Promise<Map<stri
   return result;
 }
 
+/**
+ * Retrieves every direct child of an SSM Parameter Store path.
+ *
+ * Values are returned without decryption because this helper is intended for
+ * non-secret provider metadata. API failures are propagated so callers do not
+ * mistake an authorization or throttling failure for an empty path.
+ */
+export async function getParametersByPath(parameter_path: string): Promise<Map<string, string>> {
+  const result = new Map<string, string>();
+  let nextToken: string | undefined;
+
+  do {
+    const response = await ssmClient().send(
+      new GetParametersByPathCommand({
+        Path: parameter_path,
+        Recursive: false,
+        WithDecryption: false,
+        NextToken: nextToken,
+      }),
+    );
+
+    for (const parameter of response.Parameters ?? []) {
+      if (parameter.Name && parameter.Value) {
+        result.set(parameter.Name, parameter.Value);
+      }
+    }
+    nextToken = response.NextToken;
+  } while (nextToken);
+
+  return result;
+}
+
+export async function deleteParameter(parameter_name: string): Promise<void> {
+  await ssmClient().send(new DeleteParameterCommand({ Name: parameter_name }));
+}
+
 export const SSM_ADVANCED_TIER_THRESHOLD = 4000;
 
+type PutParameterOptions = { overwrite: true; tags?: never } | { overwrite?: false | undefined; tags?: Tag[] };
+
 export async function putParameter(
   parameter_name: string,
   parameter_value: string,
   secure: boolean,
-  options: { tags?: Tag[] } = {},
+  options: PutParameterOptions = {},
 ): Promise<void> {
+  if (options.overwrite && options.tags !== undefined) {
+    throw new Error('SSM parameter tags cannot be supplied when overwriting an existing parameter');
+  }
+
   const client = ssmClient();
 
   // Determine tier based on parameter_value size
@@ -121,6 +170,7 @@ export async function putParameter(
       Name: parameter_name,
       Value: parameter_value,
       Type: secure ? 'SecureString' : 'String',
+      Overwrite: options.overwrite,
       Tags: options.tags,
       Tier: valueSizeBytes >= SSM_ADVANCED_TIER_THRESHOLD ? 'Advanced' : 'Standard',
     }),

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

@@ -13,6 +13,15 @@ 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.
 
+Runner ownership and lifecycle state are stored separately as non-secret `String`
+parameters under `<MICROVM_METADATA_SSM_PATH>/<microvmId>`. The immutable base
+record and independent state parameters prevent concurrent GitHub ID, orphan,
+and cleanup updates from overwriting one another. Deleting the JIT SecureString
+does not delete this metadata. Use a dedicated metadata prefix that does not
+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 control-plane Lambda requires these provider environment variables:
 
 - `MICROVM_IMAGE_ARN`
@@ -21,8 +30,31 @@ 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_MAXIMUM_DURATION_IN_SECONDS` (optional, defaults to 3600)
+- `MICROVM_METADATA_SSM_PATH` (dedicated SSM path for control-plane metadata)
 - `MICROVM_LOG_GROUP` (optional)
 
+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.
+
+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.
+
+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.
+
 ## Dynamic labels
 
 When a runner matcher enables dynamic labels, workflow jobs can override the
@@ -45,9 +77,10 @@ image and version with the required resources instead. Labels such as
 `ghr-microvm-memory` are rejected.
 
 Execution roles, ingress network connectors, logging, idle policy, run hook
-payloads, and client tokens remain deployment-controlled. Egress connector
-overrides change the runner's network boundary and should be restricted to
-approved connector ARNs with `awsDynamicLabelsPolicy`.
+payloads, and client tokens remain deployment-controlled. Image ARN, image
+version, and egress connector overrides change executable code or the network
+boundary, so they are rejected unless `awsDynamicLabelsPolicy` supplies an
+explicit `allowed` list for the corresponding key.
 
 Use the matcher's `awsDynamicLabelsPolicy` to restrict values accepted from
 workflow jobs. The MicroVM policy keys are `egress-network-connectors`,
@@ -62,6 +95,9 @@ workflow jobs. The MicroVM policy keys are `egress-network-connectors`,
     "image-arn": {
       "allowed": ["arn:aws:lambda:eu-west-1:123456789012:microvm-image:github-runner-*"]
     },
+    "image-version": {
+      "allowed": ["3.*"]
+    },
     "maximum-duration-in-seconds": {
       "max": 3600
     }

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

@@ -8,6 +8,7 @@ beforeEach(() => {
   process.env = { ...cleanEnv };
   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_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,
       maximumDurationInSeconds: 3600,
+      metadataSsmPath: '/github-action-runners/unit-test/microvm-metadata',
       logging: undefined,
     });
   });
@@ -47,6 +49,7 @@ describe('loadMicrovmProviderConfig', () => {
   it.each([
     ['MICROVM_IMAGE_ARN', 'MICROVM_IMAGE_ARN'],
     ['MICROVM_EXECUTION_ROLE_ARN', 'MICROVM_EXECUTION_ROLE_ARN'],
+    ['MICROVM_METADATA_SSM_PATH', 'MICROVM_METADATA_SSM_PATH'],
   ])('requires %s', (environmentVariable, expectedName) => {
     delete process.env[environmentVariable];
 
@@ -68,4 +71,15 @@ describe('loadMicrovmProviderConfig', () => {
 
     expect(() => loadMicrovmProviderConfig()).toThrow(/MICROVM_EGRESS_NETWORK_CONNECTORS must/);
   });
+
+  it.each(['metadata', '/', '/metadata//nested', '/metadata/has space'])(
+    'rejects malformed metadata SSM path %s',
+    (metadataPath) => {
+      process.env.MICROVM_METADATA_SSM_PATH = metadataPath;
+
+      expect(() => loadMicrovmProviderConfig()).toThrow(
+        'MICROVM_METADATA_SSM_PATH must be a valid absolute SSM parameter path',
+      );
+    },
+  );
 });

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

@@ -11,6 +11,7 @@ export interface MicrovmProviderConfig {
   ingressNetworkConnectors?: string[];
   logging?: Logging;
   maximumDurationInSeconds: number;
+  metadataSsmPath: string;
 }
 
 function requiredEnvironmentValue(name: string, value: string | undefined): string {
@@ -26,6 +27,14 @@ function optionalEnvironmentValue(value: string | undefined): string | undefined
   return trimmed ? trimmed : undefined;
 }
 
+function parseMetadataSsmPath(value: string | undefined): string {
+  const path = requiredEnvironmentValue('MICROVM_METADATA_SSM_PATH', value).replace(/\/+$/, '');
+  if (path === '' || !/^\/[A-Za-z0-9_.\-/]+$/.test(path) || path.includes('//')) {
+    throw new Error('MICROVM_METADATA_SSM_PATH must be a valid absolute SSM parameter path');
+  }
+  return path;
+}
+
 function parseNetworkConnectors(name: string, value: string | undefined): string[] | undefined {
   const configuredValue = optionalEnvironmentValue(value);
   if (!configuredValue) return undefined;
@@ -83,6 +92,7 @@ export function loadMicrovmProviderConfig(): MicrovmProviderConfig {
       process.env.MICROVM_EGRESS_NETWORK_CONNECTORS,
     ),
     maximumDurationInSeconds: parseMaximumDuration(process.env.MICROVM_MAXIMUM_DURATION_IN_SECONDS),
+    metadataSsmPath: parseMetadataSsmPath(process.env.MICROVM_METADATA_SSM_PATH),
     logging: logGroup ? ({ cloudWatch: { logGroup } } satisfies RunMicrovmCommandInput['logging']) : undefined,
   };
 }