fix: support pass-through of container runtime opts

Author: eoinsha

README.md

@@ -109,6 +109,8 @@ PythonFunction(
 - Use `bundling` to pass Docker environment variables, asset excludes, build args, command hooks, or a custom builder image.
 - Set `bundling.buildArgs.BUNDLING_IMAGE` to swap the Python base image used by the default builder.
 - Set `bundling.image` to provide a fully custom builder image.
+- `bundling.volumes`, `bundling.volumesFrom`, `bundling.network`, and `bundling.securityOpt` are applied to the reusable builder container.
+- `bundling.entrypoint`, `bundling.command`, `bundling.workingDirectory`, and `bundling.platform` are deprecated in this construct and will emit warnings if used.
 - See [API.md](API.md) for the full API reference.
 
 ## Customizing The Builder Image
@@ -135,6 +137,12 @@ Alpine-based images.
 
 If you need full control over the builder container, pass `bundling.image` instead. Custom images must include Python, `uv`, and the `/opt/uv-python-lambda` scripts expected by this library.
 
+For the default builder container, this construct also supports a safe subset
+of Docker run options: `volumes`, `volumesFrom`, `network`, and
+`securityOpt`. Other generic Docker run options such as `entrypoint`,
+`command`, `workingDirectory`, and `platform` do not fit the reusable
+builder-container model and are deprecated here.
+
 ```ts
 import { DockerImage } from 'aws-cdk-lib';
 

src/bundling.ts

@@ -113,6 +113,7 @@ export class Bundling {
   }
 
   public readonly entrypoint?: string[];
+  public readonly command?: string[];
   public readonly volumes?: DockerVolume[];
   public readonly volumesFrom?: string[];
   public readonly environment?: { [key: string]: string };
@@ -132,8 +133,10 @@ export class Bundling {
   private readonly props: BundlingProps;
 
   constructor(props: BundlingProps) {
+    warnForUnsupportedOptions(props);
     this.props = props;
     this.entrypoint = props.entrypoint;
+    this.command = props.command;
     this.volumes = props.volumes;
     this.volumesFrom = props.volumesFrom;
     this.environment = props.environment;
@@ -196,6 +199,24 @@ export class Bundling {
       dockerArgs.push('--user', builderUser);
     }
 
+    if (this.network) {
+      dockerArgs.push('--network', this.network);
+    }
+
+    if (this.securityOpt) {
+      dockerArgs.push('--security-opt', this.securityOpt);
+    }
+
+    for (const volume of this.volumes ?? []) {
+      const mount = `${volume.hostPath}:${volume.containerPath}`;
+      const consistency = volume.consistency ? `:${volume.consistency}` : '';
+      dockerArgs.push('-v', `${mount}${consistency}`);
+    }
+
+    for (const volumeSource of this.volumesFrom ?? []) {
+      dockerArgs.push('--volumes-from', volumeSource);
+    }
+
     for (const [name, value] of this.getBuilderEnvironmentEntries()) {
       dockerArgs.push('--env', `${name}=${value}`);
     }
@@ -358,3 +379,40 @@ function getDockerUserArg() {
 
   return `${process.getuid()}:${process.getgid()}`;
 }
+
+function warnForUnsupportedOptions(props: BundlingProps) {
+  if (props.entrypoint) {
+    emitDeprecatedBundlingOptionWarning(
+      'entrypoint',
+      'This construct manages the reusable builder container entrypoint internally. Use bundling.image for a fully custom builder image.',
+    );
+  }
+
+  if (props.command) {
+    emitDeprecatedBundlingOptionWarning(
+      'command',
+      'This construct manages the reusable builder container command internally. Use bundling.image for a fully custom builder image.',
+    );
+  }
+
+  if (props.workingDirectory) {
+    emitDeprecatedBundlingOptionWarning(
+      'workingDirectory',
+      'The reusable builder container manages its own working directory. Use command hooks or bundling.image if you need different behavior.',
+    );
+  }
+
+  if (props.platform) {
+    emitDeprecatedBundlingOptionWarning(
+      'platform',
+      'The builder image platform is derived from the Lambda architecture option. Set architecture instead.',
+    );
+  }
+}
+
+function emitDeprecatedBundlingOptionWarning(option: string, details: string) {
+  process.emitWarning(
+    `bundling.${option} is deprecated and ignored. ${details}`,
+    'DeprecationWarning',
+  );
+}

src/types.ts

@@ -7,6 +7,13 @@ import type {
 
 /**
  * Options for bundling
+ *
+ * This construct applies `environment`, `user`, `volumes`, `volumesFrom`,
+ * `network`, and `securityOpt` to its reusable builder container.
+ *
+ * The inherited `entrypoint`, `command`, `workingDirectory`, and `platform`
+ * options do not fit this builder-container model and are ignored with a
+ * deprecation warning at runtime.
  */
 export interface BundlingOptions extends DockerRunOptions {
   /**

test/bundling.test.ts

@@ -44,6 +44,42 @@ describe('Bundling', () => {
     jest.restoreAllMocks();
   });
 
+  test('warns when deprecated unsupported bundling options are used', () => {
+    const emitWarningSpy = jest
+      .spyOn(process, 'emitWarning')
+      .mockImplementation(() => undefined);
+
+    new Bundling({
+      rootDir: '/tmp/project-deprecated-options',
+      runtime: Runtime.PYTHON_3_12,
+      architecture: Architecture.X86_64,
+      entrypoint: ['/bin/sh', '-c'],
+      command: ['echo', 'hello'],
+      workingDirectory: '/tmp',
+      platform: 'linux/amd64',
+    });
+
+    expect(emitWarningSpy).toHaveBeenCalledTimes(4);
+    expect(emitWarningSpy).toHaveBeenCalledWith(
+      expect.stringContaining('bundling.entrypoint is deprecated and ignored'),
+      'DeprecationWarning',
+    );
+    expect(emitWarningSpy).toHaveBeenCalledWith(
+      expect.stringContaining('bundling.command is deprecated and ignored'),
+      'DeprecationWarning',
+    );
+    expect(emitWarningSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'bundling.workingDirectory is deprecated and ignored',
+      ),
+      'DeprecationWarning',
+    );
+    expect(emitWarningSpy).toHaveBeenCalledWith(
+      expect.stringContaining('bundling.platform is deprecated and ignored'),
+      'DeprecationWarning',
+    );
+  });
+
   test('returns a no-op command when bundling is skipped', () => {
     const bundling = new Bundling({
       rootDir: '/tmp/project',
@@ -346,4 +382,48 @@ describe('Bundling', () => {
       }),
     );
   });
+
+  test('passes supported docker run options to the builder container', () => {
+    const ensureBuilderContainerMock = jest.fn();
+    const bundlingModule = loadBundlingModule(ensureBuilderContainerMock);
+    jest
+      .spyOn(DockerImage, 'fromBuild')
+      .mockReturnValue({ image: 'mock-image' } as DockerImage);
+
+    const bundling = new bundlingModule.Bundling({
+      rootDir: '/tmp/project-run-options',
+      runtime: Runtime.PYTHON_3_12,
+      architecture: Architecture.X86_64,
+      network: 'test-network',
+      securityOpt: 'label=disable',
+      volumes: [
+        {
+          hostPath: '/tmp/cache',
+          containerPath: '/cache',
+        },
+      ],
+      volumesFrom: ['shared-container'],
+    });
+
+    Reflect.get(bundling, 'ensureBuilderReady').call(
+      bundling,
+      '/tmp/cdk-run-options',
+    );
+
+    expect(ensureBuilderContainerMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        args: expect.arrayContaining([
+          '--network',
+          'test-network',
+          '--security-opt',
+          'label=disable',
+          '-v',
+          '/tmp/cache:/cache',
+          '--volumes-from',
+          'shared-container',
+          'mock-image',
+        ]),
+      }),
+    );
+  });
 });