feat(runner-providers): add MicroVM webhook routing

Author: edersonbrilhante

lambdas/libs/runner-providers/aws/ec2/src/webhook/dynamic-labels.ts

@@ -1,6 +1,7 @@
 import { createChildLogger } from '@aws-github-runner/aws-powertools-util';
 
 import type { DynamicLabelDispatchTarget, DynamicLabelProvider, RunnerMatcherConfig } from '../../../../contracts';
+import { dynamicLabelsForOtherProvider } from '../../../../dynamic-labels';
 import { violationsAgainstPolicy } from './dynamic-labels-policy';
 
 const logger = createChildLogger('handler');
@@ -34,6 +35,14 @@ export function selectEc2DynamicLabelQueue(
       continue;
     }
 
+    const labelsForOtherProvider = dynamicLabelsForOtherProvider(sanitizedGhrLabels, 'ec2');
+    if (labelsForOtherProvider.length > 0) {
+      logger.warn(`Queue ${queue.id}: dynamic labels target another runner provider; trying next match`, {
+        dynamicLabels: labelsForOtherProvider,
+      });
+      continue;
+    }
+
     const violations = violationsAgainstPolicy(sanitizedGhrLabels, resolveEc2DynamicLabelsPolicy(queue));
     if (violations.length === 0) {
       return {

lambdas/libs/runner-providers/aws/microvm/provider.test.ts

@@ -0,0 +1,30 @@
+import { expect, it, vi } from 'vitest';
+
+import { provider as controlPlaneProvider } from './control-plane';
+import { provider as webhookProvider } from './webhook';
+
+it('exposes every MicroVM provider capability from its lane entry point', () => {
+  const controlPlanePlugin = controlPlaneProvider.createPlugin(vi.fn(async () => []));
+  const webhookPlugin = webhookProvider.createPlugin();
+
+  expect(controlPlanePlugin.type).toBe('microvm');
+  expect(controlPlanePlugin.capabilities.pool()).toEqual({
+    listRunners: expect.any(Function),
+    countAvailableRunners: expect.any(Function),
+    createRunners: expect.any(Function),
+  });
+  expect(controlPlanePlugin.capabilities.scaleUp()).toEqual({
+    resolveLabelsForRunners: expect.any(Function),
+    getCurrentRunners: expect.any(Function),
+    createRunners: expect.any(Function),
+  });
+  expect(controlPlanePlugin.capabilities.scaleDown()).toEqual({
+    list: expect.any(Function),
+    bootTimeExceeded: expect.any(Function),
+    markOrphan: expect.any(Function),
+    unmarkOrphan: expect.any(Function),
+    terminate: expect.any(Function),
+  });
+  expect(webhookPlugin.type).toBe('microvm');
+  expect(webhookPlugin.capabilities.dynamicLabels.selectQueue).toEqual(expect.any(Function));
+});

lambdas/libs/runner-providers/aws/microvm/src/webhook/dynamic-labels.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+
+import type { RunnerMatcherConfig } from '../../../../contracts';
+import { microvmDynamicLabelProvider } from './dynamic-labels';
+
+const imageArn = 'arn:aws:lambda:eu-west-1:123456789012:microvm-image:runner-large';
+const egressConnectorArn = 'arn:aws:lambda:eu-west-1:123456789012:network-connector:github-runner-private-egress';
+
+describe('microvmDynamicLabelProvider', () => {
+  it('accepts supported MicroVM overrides', () => {
+    const queue = microvmQueue();
+    const dynamicLabels = [
+      `ghr-microvm-egress-network-connectors:${egressConnectorArn}`,
+      `ghr-microvm-image-arn:${imageArn}`,
+      'ghr-microvm-image-version:3.0',
+      'ghr-microvm-maximum-duration-in-seconds:7200',
+    ];
+
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: dynamicLabels,
+      }),
+    ).toEqual({ queue, labels: ['self-hosted', 'microvm', ...dynamicLabels] });
+  });
+
+  it('rejects unsupported MicroVM resource overrides', () => {
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue: microvmQueue(),
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: ['ghr-microvm-memory:8192'],
+      }),
+    ).toBeUndefined();
+  });
+
+  it('rejects labels owned by another runner provider', () => {
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue: microvmQueue(),
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: ['ghr-ec2-instance-type:m7i.large'],
+      }),
+    ).toBeUndefined();
+  });
+
+  it('requires dynamic labels to be enabled for the queue', () => {
+    const queue = microvmQueue();
+    queue.matcherConfig.enableDynamicLabels = false;
+
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: ['ghr-microvm-image-version:3.0'],
+      }),
+    ).toBeUndefined();
+  });
+
+  it('enforces the AWS dynamic-label policy', () => {
+    const queue = microvmQueue();
+    queue.matcherConfig.awsDynamicLabelsPolicy = {
+      restricted_keys: { 'maximum-duration-in-seconds': { max: 3600 } },
+    };
+
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: ['ghr-microvm-maximum-duration-in-seconds:7200'],
+      }),
+    ).toBeUndefined();
+  });
+
+  it('applies allowed patterns to the complete image ARN', () => {
+    const queue = microvmQueue();
+    queue.matcherConfig.awsDynamicLabelsPolicy = {
+      restricted_keys: {
+        'image-arn': {
+          allowed: ['arn:aws:lambda:eu-west-1:123456789012:microvm-image:approved-*'],
+        },
+      },
+    };
+
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: [
+          'ghr-microvm-image-arn:arn:aws:lambda:eu-west-1:123456789012:microvm-image:approved-large',
+        ],
+      }),
+    ).toBeDefined();
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: ['ghr-microvm-image-arn:arn:aws:lambda:eu-west-1:123456789012:microvm-image:unapproved'],
+      }),
+    ).toBeUndefined();
+  });
+
+  it('applies the policy to each egress connector label', () => {
+    const queue = microvmQueue();
+    queue.matcherConfig.awsDynamicLabelsPolicy = {
+      restricted_keys: {
+        'egress-network-connectors': {
+          allowed: ['arn:aws:lambda:eu-west-1:123456789012:network-connector:approved-*'],
+        },
+      },
+    };
+
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: [
+          'ghr-microvm-egress-network-connectors:arn:aws:lambda:eu-west-1:123456789012:network-connector:approved-private',
+        ],
+      }),
+    ).toBeDefined();
+    expect(
+      microvmDynamicLabelProvider.selectQueue({
+        queue,
+        nonGhrLabels: ['self-hosted', 'microvm'],
+        sanitizedGhrLabels: [
+          'ghr-microvm-egress-network-connectors:arn:aws:lambda:eu-west-1:123456789012:network-connector:unapproved',
+        ],
+      }),
+    ).toBeUndefined();
+  });
+});
+
+function microvmQueue(): RunnerMatcherConfig {
+  return {
+    id: 'microvm',
+    arn: 'arn:aws:sqs:eu-west-1:123456789012:microvm',
+    runnerProvider: 'microvm',
+    matcherConfig: {
+      labelMatchers: [['self-hosted', 'linux', 'arm64', 'microvm']],
+      exactMatch: false,
+      enableDynamicLabels: true,
+    },
+  };
+}

lambdas/libs/runner-providers/aws/microvm/src/webhook/dynamic-labels.ts

@@ -0,0 +1,54 @@
+import { createChildLogger } from '@aws-github-runner/aws-powertools-util';
+
+import { violationsAgainstAwsDynamicLabelsPolicy } from '../../../dynamic-labels-policy';
+import type { DynamicLabelDispatchTarget, DynamicLabelProvider, RunnerMatcherConfig } from '../../../../contracts';
+import { dynamicLabelsForOtherProvider } from '../../../../dynamic-labels';
+import { MICROVM_DYNAMIC_LABEL_PREFIX, parseMicrovmDynamicLabels } from '../dynamic-labels';
+
+const logger = createChildLogger('handler');
+
+export function selectMicrovmDynamicLabelQueue(
+  matches: RunnerMatcherConfig[],
+  nonGhrLabels: string[],
+  sanitizedGhrLabels: string[],
+): DynamicLabelDispatchTarget | undefined {
+  for (const queue of matches) {
+    if (!queue.matcherConfig.enableDynamicLabels) {
+      logger.warn(`Queue ${queue.id} matches non-dynamic labels but does not allow dynamic labels; trying next match`);
+      continue;
+    }
+
+    const labelsForOtherProvider = dynamicLabelsForOtherProvider(sanitizedGhrLabels, 'microvm');
+    if (labelsForOtherProvider.length > 0) {
+      logger.warn(`Queue ${queue.id}: dynamic labels target another runner provider; trying next match`, {
+        dynamicLabels: labelsForOtherProvider,
+      });
+      continue;
+    }
+
+    const parsedLabels = parseMicrovmDynamicLabels(sanitizedGhrLabels);
+    const policyViolations = violationsAgainstAwsDynamicLabelsPolicy(
+      sanitizedGhrLabels,
+      queue.matcherConfig.awsDynamicLabelsPolicy,
+      MICROVM_DYNAMIC_LABEL_PREFIX,
+    );
+    const violations = [...parsedLabels.violations, ...policyViolations];
+
+    if (violations.length === 0) {
+      return { queue, labels: [...nonGhrLabels, ...sanitizedGhrLabels] };
+    }
+
+    for (const violation of violations) {
+      logger.warn(
+        `Queue ${queue.id}: dynamic label '${violation.label}' is not accepted (${violation.reason}); trying next match`,
+      );
+    }
+  }
+
+  return undefined;
+}
+
+export const microvmDynamicLabelProvider: DynamicLabelProvider = {
+  selectQueue: ({ queue, nonGhrLabels, sanitizedGhrLabels }) =>
+    selectMicrovmDynamicLabelQueue([queue], nonGhrLabels, sanitizedGhrLabels),
+};

lambdas/libs/runner-providers/aws/microvm/webhook.ts

@@ -0,0 +1,16 @@
+import type { RunnerProviderPlugin } from '../../core';
+
+import type { WebhookProviderCapabilities, WebhookProviderModule } from '../../contracts';
+import { microvmDynamicLabelProvider } from './src/webhook/dynamic-labels';
+
+export function createMicrovmWebhookPlugin(): RunnerProviderPlugin<WebhookProviderCapabilities, 'microvm'> {
+  return {
+    type: 'microvm',
+    capabilities: { dynamicLabels: microvmDynamicLabelProvider },
+  };
+}
+
+export const provider = {
+  type: 'microvm',
+  createPlugin: createMicrovmWebhookPlugin,
+} satisfies WebhookProviderModule<'microvm'>;

lambdas/libs/runner-providers/dynamic-labels.ts

@@ -0,0 +1,8 @@
+import { runnerProviderTypes } from './provider-types';
+import type { RunnerProviderType } from './provider-types';
+
+export function dynamicLabelsForOtherProvider(labels: string[], provider: RunnerProviderType): string[] {
+  return labels.filter((label) =>
+    runnerProviderTypes.some((candidate) => candidate !== provider && label.startsWith(`ghr-${candidate}-`)),
+  );
+}

lambdas/libs/runner-providers/package.json

@@ -12,6 +12,7 @@
     "./aws/ec2/control-plane": "./aws/ec2/control-plane.ts",
     "./aws/ec2/control-plane/runners": "./aws/ec2/src/control-plane/runners.ts",
     "./aws/ec2/control-plane/runner-config": "./aws/ec2/src/control-plane/runner-config.ts",
+    "./aws/microvm/webhook": "./aws/microvm/webhook.ts",
     "./aws/microvm/control-plane": "./aws/microvm/control-plane.ts"
   },
   "type": "module",

lambdas/libs/runner-providers/providers.config.webhook.ts

@@ -1,5 +1,6 @@
 import { provider as ec2 } from './aws/ec2/webhook';
+import { provider as microvm } from './aws/microvm/webhook';
 import type { WebhookProviderModule } from './contracts';
 
 /** Provider plugins included in the webhook bundle. */
-export const enabledWebhookProviders = [ec2] as const satisfies readonly WebhookProviderModule[];
+export const enabledWebhookProviders = [ec2, microvm] as const satisfies readonly WebhookProviderModule[];

lambdas/libs/runner-providers/webhook.test.ts

@@ -32,6 +32,28 @@ describe('selectDynamicLabelQueue', () => {
       selectDynamicLabelQueue([queue], ['self-hosted', 'linux'], ['ghr-ec2-instance-type:t3.large']),
     ).toThrow(`Unsupported runner provider type '${String(runnerProvider)}'`);
   });
+
+  it('skips EC2 and selects the MicroVM queue for MicroVM override labels', () => {
+    const ec2Queue = runnerQueue('ec2', 'ec2');
+    const microvmQueue = runnerQueue('microvm', 'microvm');
+    const imageVersionLabel = 'ghr-microvm-image-version:3.0';
+
+    expect(selectDynamicLabelQueue([ec2Queue, microvmQueue], ['self-hosted', 'linux'], [imageVersionLabel])).toEqual({
+      queue: microvmQueue,
+      labels: ['self-hosted', 'linux', imageVersionLabel],
+    });
+  });
+
+  it('skips MicroVM and selects the EC2 queue for EC2 override labels', () => {
+    const microvmQueue = runnerQueue('microvm', 'microvm');
+    const ec2Queue = runnerQueue('ec2', 'ec2');
+    const instanceTypeLabel = 'ghr-ec2-instance-type:m7i.large';
+
+    expect(selectDynamicLabelQueue([microvmQueue, ec2Queue], ['self-hosted', 'linux'], [instanceTypeLabel])).toEqual({
+      queue: ec2Queue,
+      labels: ['self-hosted', 'linux', instanceTypeLabel],
+    });
+  });
 });
 
 function runnerQueue(id: string, runnerProvider?: RunnerProviderType): RunnerMatcherConfig {