feat: add input use_dedicated_host

Author: edersonbrilhante

lambdas/functions/control-plane/src/aws/runners.d.ts

@@ -46,4 +46,5 @@ export interface RunnerInputParameters {
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
   scaleErrors: string[];
+  useDedicatedHost?: boolean;
 }

lambdas/functions/control-plane/src/aws/runners.test.ts

@@ -10,6 +10,7 @@ import {
   DescribeInstancesCommand,
   type DescribeInstancesResult,
   EC2Client,
+  RunInstancesCommand,
   SpotAllocationStrategy,
   TerminateInstancesCommand,
 } from '@aws-sdk/client-ec2';
@@ -704,6 +705,7 @@ interface RunnerConfig {
   tracingEnabled?: boolean;
   onDemandFailoverOnError?: string[];
   scaleErrors: string[];
+  useDedicatedHost?: boolean;
 }
 
 function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
@@ -724,6 +726,7 @@ function createRunnerConfig(runnerConfig: RunnerConfig): RunnerInputParameters {
     tracingEnabled: runnerConfig.tracingEnabled,
     onDemandFailoverOnError: runnerConfig.onDemandFailoverOnError,
     scaleErrors: runnerConfig.scaleErrors,
+    useDedicatedHost: runnerConfig.useDedicatedHost,
   };
 }
 
@@ -811,3 +814,211 @@ function expectedCreateFleetRequest(expectedValues: ExpectedFleetRequestValues):
 
   return request;
 }
+
+describe('create runner with useDedicatedHost', () => {
+  const dedicatedHostRunnerConfig: RunnerConfig = {
+    allocationStrategy: SpotAllocationStrategy.CAPACITY_OPTIMIZED,
+    capacityType: 'on-demand',
+    type: 'Org',
+    scaleErrors: [],
+    useDedicatedHost: true,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockEC2Client.reset();
+    mockSSMClient.reset();
+
+    mockEC2Client.on(RunInstancesCommand).resolves({
+      Instances: [{ InstanceId: 'i-dedicated-1' }],
+    });
+    mockSSMClient.on(GetParameterCommand).resolves({});
+  });
+
+  it('uses RunInstances instead of CreateFleet when useDedicatedHost is true', async () => {
+    const result = await createRunner(createRunnerConfig(dedicatedHostRunnerConfig));
+
+    expect(result).toEqual(['i-dedicated-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(RunInstancesCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(CreateFleetCommand);
+  });
+
+  it('uses CreateFleet when useDedicatedHost is false', async () => {
+    mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
+
+    const result = await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      useDedicatedHost: false,
+    }));
+
+    expect(result).toEqual(['i-fleet-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('uses CreateFleet when useDedicatedHost is undefined', async () => {
+    mockEC2Client.on(CreateFleetCommand).resolves({ Instances: [{ InstanceIds: ['i-fleet-1'] }] });
+
+    const result = await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      useDedicatedHost: undefined,
+    }));
+
+    expect(result).toEqual(['i-fleet-1']);
+    expect(mockEC2Client).toHaveReceivedCommand(CreateFleetCommand);
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('passes correct parameters to RunInstances', async () => {
+    await createRunner(createRunnerConfig(dedicatedHostRunnerConfig));
+
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 1,
+      MaxCount: 1,
+      SubnetId: 'subnet-123',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('creates multiple instances via RunInstances', async () => {
+    mockEC2Client.on(RunInstancesCommand).resolves({
+      Instances: [{ InstanceId: 'i-dedicated-1' }, { InstanceId: 'i-dedicated-2' }],
+    });
+
+    const result = await createRunner({
+      ...createRunnerConfig(dedicatedHostRunnerConfig),
+      numberOfRunners: 2,
+    });
+
+    expect(result).toEqual(['i-dedicated-1', 'i-dedicated-2']);
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 2,
+      MaxCount: 2,
+      SubnetId: 'subnet-123',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'pool-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'pool-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('throws error when spot is used with dedicated host', async () => {
+    await expect(
+      createRunner(createRunnerConfig({
+        ...dedicatedHostRunnerConfig,
+        capacityType: 'spot',
+      })),
+    ).rejects.toThrow('Spot instances are not supported with RunInstances');
+    expect(mockEC2Client).not.toHaveReceivedCommand(RunInstancesCommand);
+  });
+
+  it('throws error when RunInstances returns no instances', async () => {
+    mockEC2Client.on(RunInstancesCommand).resolves({ Instances: [] });
+
+    await expect(
+      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
+    ).rejects.toThrow('RunInstances returned no instances for dedicated host.');
+  });
+
+  it('throws error when RunInstances fails', async () => {
+    mockEC2Client.on(RunInstancesCommand).rejects(new Error('EC2 error'));
+
+    await expect(
+      createRunner(createRunnerConfig(dedicatedHostRunnerConfig)),
+    ).rejects.toThrow('EC2 error');
+  });
+
+  it('uses ami id override from ssm parameter', async () => {
+    const paramValue: GetParameterResult = {
+      Parameter: {
+        Value: 'ami-dedicated',
+      },
+    };
+    mockSSMClient.on(GetParameterCommand).resolves(paramValue);
+
+    await createRunner(createRunnerConfig({
+      ...dedicatedHostRunnerConfig,
+      amiIdSsmParameterName: 'my-ami-id-param',
+    }));
+
+    expect(mockEC2Client).toHaveReceivedCommandWith(RunInstancesCommand, {
+      LaunchTemplate: {
+        LaunchTemplateName: LAUNCH_TEMPLATE,
+        Version: '$Default',
+      },
+      InstanceType: 'm5.large',
+      MinCount: 1,
+      MaxCount: 1,
+      SubnetId: 'subnet-123',
+      ImageId: 'ami-dedicated',
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+        {
+          ResourceType: 'volume',
+          Tags: [
+            { Key: 'ghr:Application', Value: 'github-action-runner' },
+            { Key: 'ghr:created_by', Value: 'scale-up-lambda' },
+            { Key: 'ghr:Type', Value: 'Org' },
+            { Key: 'ghr:Owner', Value: REPO_NAME },
+          ],
+        },
+      ],
+    });
+    expect(mockSSMClient).toHaveReceivedCommandWith(GetParameterCommand, {
+      Name: 'my-ami-id-param',
+    });
+  });
+});

lambdas/functions/control-plane/src/aws/runners.ts

@@ -5,6 +5,7 @@ import {
   DeleteTagsCommand,
   DescribeInstancesCommand,
   DescribeInstancesResult,
+  RunInstancesCommand,
   EC2Client,
   FleetLaunchTemplateOverridesRequest,
   Tag,
@@ -152,6 +153,15 @@ export async function createRunner(runnerParameters: Runners.RunnerInputParamete
   const ec2Client = getTracedAWSV3Client(new EC2Client({ region: process.env.AWS_REGION }));
   const amiIdOverride = await getAmiIdOverride(runnerParameters);
 
+  // EC2 Fleet (CreateFleet) does not support launching instances onto dedicated hosts
+  // for instance types like mac*.metal. Use RunInstances directly instead.
+  if (runnerParameters.useDedicatedHost) {
+    logger.info('Using RunInstances for dedicated host placement (CreateFleet does not support dedicated hosts).');
+    const instances = await createInstancesWithRunInstances(runnerParameters, amiIdOverride, ec2Client);
+    logger.info(`Created instance(s) via RunInstances: ${instances.join(',')}`);
+    return instances;
+  }
+
   const fleet: CreateFleetResult = await createInstances(runnerParameters, amiIdOverride, ec2Client);
 
   const instances: string[] = await processFleetResult(fleet, runnerParameters);
@@ -288,6 +298,7 @@ async function createInstances(
       ],
       Type: 'instant',
     });
+    logger.debug('CreateFleet request payload.', { payload: createFleetCommand.input });
     fleet = await ec2Client.send(createFleetCommand);
   } catch (e) {
     logger.warn('Create fleet request failed.', { error: e as Error });
@@ -296,6 +307,67 @@ async function createInstances(
   return fleet;
 }
 
+async function createInstancesWithRunInstances(
+  runnerParameters: Runners.RunnerInputParameters,
+  amiIdOverride: string | undefined,
+  ec2Client: EC2Client,
+): Promise<string[]> {
+  const tags = [
+    { Key: 'ghr:Application', Value: 'github-action-runner' },
+    { Key: 'ghr:created_by', Value: runnerParameters.numberOfRunners === 1 ? 'scale-up-lambda' : 'pool-lambda' },
+    { Key: 'ghr:Type', Value: runnerParameters.runnerType },
+    { Key: 'ghr:Owner', Value: runnerParameters.runnerOwner },
+  ];
+
+  if (runnerParameters.tracingEnabled) {
+    const traceId = tracer.getRootXrayTraceId();
+    tags.push({ Key: 'ghr:trace_id', Value: traceId! });
+  }
+
+  try {
+    if (runnerParameters.ec2instanceCriteria.targetCapacityType === 'spot') {
+      throw new Error('Spot instances are not supported with RunInstances. Please set targetCapacityType to on-demand for dedicated hosts.');
+    }
+
+    const instanceType = runnerParameters.ec2instanceCriteria.instanceTypes[0] as _InstanceType;
+    const runInstancesCommand = new RunInstancesCommand({
+      LaunchTemplate: {
+        LaunchTemplateName: runnerParameters.launchTemplateName,
+        Version: '$Default',
+      },
+      InstanceType: instanceType,
+      MinCount: runnerParameters.numberOfRunners,
+      MaxCount: runnerParameters.numberOfRunners,
+      SubnetId: runnerParameters.subnets[0],
+      ...(amiIdOverride ? { ImageId: amiIdOverride } : {}),
+      TagSpecifications: [
+        {
+          ResourceType: 'instance',
+          Tags: tags,
+        },
+        {
+          ResourceType: 'volume',
+          Tags: tags,
+        },
+      ],
+    });
+
+    logger.debug('RunInstances request payload.', { payload: runInstancesCommand.input });
+    const result = await ec2Client.send(runInstancesCommand);
+    const instanceIds = result.Instances?.map((i) => i.InstanceId!).filter(Boolean) || [];
+
+    if (instanceIds.length === 0) {
+      throw new Error('RunInstances returned no instances for dedicated host.');
+    }
+
+    return instanceIds;
+  } catch (e) {
+    logger.warn('RunInstances request failed for dedicated host.', { error: e as Error });
+    throw e;
+  }
+}
+
+
 // If launchTime is undefined, this will return false
 export function bootTimeExceeded(ec2Runner: { launchTime?: Date }): boolean {
   const runnerBootTimeInMinutes = process.env.RUNNER_BOOT_TIME_IN_MINUTES;

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

@@ -113,6 +113,7 @@ const EXPECTED_RUNNER_PARAMS: RunnerInputParameters = {
   tracingEnabled: false,
   onDemandFailoverOnError: [],
   scaleErrors: ['UnfulfillableCapacity', 'MaxSpotInstanceCountExceeded', 'TargetCapacityLimitExceededException'],
+  useDedicatedHost: false,
 };
 let expectedRunnerParams: RunnerInputParameters;
 
@@ -2018,6 +2019,42 @@ describe('Retry mechanism tests', () => {
   });
 });
 
+describe('useDedicatedHost', () => {
+  beforeEach(() => {
+    process.env.ENABLE_ORGANIZATION_RUNNERS = 'true';
+    process.env.ENABLE_EPHEMERAL_RUNNERS = 'true';
+    process.env.RUNNER_NAME_PREFIX = 'unit-test-';
+    process.env.RUNNER_GROUP_NAME = 'Default';
+    process.env.SSM_CONFIG_PATH = '/github-action-runners/default/runners/config';
+    process.env.SSM_TOKEN_PATH = '/github-action-runners/default/runners/config';
+    process.env.RUNNER_LABELS = 'label1,label2';
+  });
+
+  it('defaults to false when USE_DEDICATED_HOST env var is not set', async () => {
+    delete process.env.USE_DEDICATED_HOST;
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: false }),
+    );
+  });
+
+  it('is true when USE_DEDICATED_HOST is "true"', async () => {
+    process.env.USE_DEDICATED_HOST = 'true';
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: true }),
+    );
+  });
+
+  it('is false when USE_DEDICATED_HOST is "false"', async () => {
+    process.env.USE_DEDICATED_HOST = 'false';
+    await scaleUpModule.scaleUp(TEST_DATA);
+    expect(createRunner).toHaveBeenCalledWith(
+      expect.objectContaining({ useDedicatedHost: false }),
+    );
+  });
+});
+
 function defaultOctokitMockImpl() {
   mockOctokit.actions.getJobForWorkflowRun.mockImplementation(() => ({
     data: {