feat: allow overriding builder image or base

Author: eoinsha

API.md

@@ -106,5 +106,44 @@ PythonFunction(
 ## Notes
 
 - `index` can be passed as `handler.py` or `handler`.
-- Use `bundling` to pass Docker environment variables, asset excludes, build args, or command hooks.
+- 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.
 - See [API.md](API.md) for the full API reference.
+
+## Customizing The Builder Image
+
+If you want to keep the default `uv-python-lambda` builder logic but use a different Python base image, override `BUNDLING_IMAGE`:
+
+```ts
+new PythonFunction(this, 'Fn', {
+  rootDir: path.join(__dirname, '..', '..', 'services', 'fetcher'),
+  bundling: {
+    buildArgs: {
+      BUNDLING_IMAGE: 'python:3.12-slim',
+    },
+  },
+});
+```
+
+When you override `BUNDLING_IMAGE`, the library still uses its own default
+builder scripts. Those scripts need `bash`, `rsync`, and a few standard Unix
+utilities, so the default builder image now installs them on top of the chosen
+base image. The conditional `RUN if command -v ...` block in
+`resources/Dockerfile` exists to do that across common Debian, RPM, and
+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.
+
+```ts
+import { DockerImage } from 'aws-cdk-lib';
+
+new PythonFunction(this, 'Fn', {
+  rootDir: path.join(__dirname, '..', '..', 'services', 'fetcher'),
+  bundling: {
+    image: DockerImage.fromBuild(path.join(__dirname, '..', '..'), {
+      file: 'docker/uv-python-lambda-builder.Dockerfile',
+    }),
+  },
+});
+```

README.md

@@ -1,14 +1,40 @@
 # Use for the container image that uv-python-lambda will use to bundle one or more Lambda functions
 # from a uv project (including those with one or more workspaces).
 
-ARG IMAGE_ARCH=arm64   # or x86_64 (not amd64 as per Docker platform)
 ARG UV_VERSION=0.5.27
-ARG PYTHON_VERSION=3.12
-ARG BUNDLING_IMAGE=public.ecr.aws/sam/build-python${PYTHON_VERSION}:latest-${IMAGE_ARCH}
+ARG BUNDLING_IMAGE=public.ecr.aws/sam/build-python3.12:latest-arm64
 
 FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
 FROM ${BUNDLING_IMAGE}
 
+# The default builder scripts depend on a few basic Unix tools that are present
+# in the SAM build images but may be missing from slimmer custom base images
+# such as `python:3.12-slim`.
+# - `bash` is required because `entrypoint.sh` and `export.sh` are bash scripts.
+# - `coreutils` / `util-linux` provide commands used by the scripts such as
+#   `realpath`, `mktemp`, and `flock`-adjacent utilities across distros.
+# - `rsync` is used to stage workspace and source files efficiently.
+#
+# We detect the distro package manager here so `BUNDLING_IMAGE` can point at a
+# broader range of Debian, RPM, or Alpine-based Python images without requiring
+# users to maintain a separate custom builder image just to install these tools.
+RUN if command -v apt-get >/dev/null 2>&1; then \
+      apt-get update && \
+      apt-get install -y --no-install-recommends bash coreutils rsync util-linux && \
+      rm -rf /var/lib/apt/lists/*; \
+    elif command -v dnf >/dev/null 2>&1; then \
+      dnf install -y bash coreutils rsync util-linux && \
+      dnf clean all; \
+    elif command -v yum >/dev/null 2>&1; then \
+      yum install -y bash coreutils rsync util-linux && \
+      yum clean all; \
+    elif command -v apk >/dev/null 2>&1; then \
+      apk add --no-cache bash coreutils rsync util-linux; \
+    else \
+      echo "Unsupported base image: install bash, coreutils, rsync, and util-linux in the custom BUNDLING_IMAGE" >&2; \
+      exit 1; \
+    fi
+
 COPY --from=uv /uv /uvx /bin/
 COPY *.sh /opt/uv-python-lambda/
 RUN chmod +x /opt/uv-python-lambda/*.sh

resources/Dockerfile

@@ -157,10 +157,13 @@ export class Bundling {
     const hashableProperties = {
       runtime: props.runtime.name,
       architecture: props.architecture ?? Architecture.ARM_64,
-      buildArgs: props.buildArgs,
       environment: getBuilderEnvironment(props.environment),
       rootDir: path.resolve(props.rootDir),
-      uvVersion: props.uvVersion ?? DEFAULT_UV_VERSION,
+      builderImage: props.image
+        ? { image: props.image.image }
+        : {
+            buildArgs: this.getDefaultBuilderBuildArgs(),
+          },
     };
 
     this.containerBuilderKey = `uv-bundling-${hash(hashableProperties)}`;
@@ -272,24 +275,13 @@ export class Bundling {
       return existing;
     }
 
-    const buildImage = DockerImage.fromBuild(
-      path.resolve(__dirname, '..', 'resources'),
-      {
-        buildArgs: {
-          ...this.props.buildArgs,
-          UV_VERSION: this.props.uvVersion ?? DEFAULT_UV_VERSION,
-          IMAGE: this.props.runtime.bundlingImage.image,
-          IMAGE_ARCH:
-            this.props.architecture === Architecture.X86_64
-              ? 'x86_64'
-              : 'arm64',
-          PYTHON_VERSION: this.props.runtime.name.slice(6),
-          BUNDLING_IMAGE: this.props.runtime.bundlingImage.image,
-        },
+    const buildImage =
+      this.props.image ??
+      DockerImage.fromBuild(path.resolve(__dirname, '..', 'resources'), {
+        buildArgs: this.getDefaultBuilderBuildArgs(),
         platform: (this.props.architecture ?? Architecture.ARM_64)
           .dockerPlatform,
-      },
-    );
+      });
 
     Bundling.buildImages[imageKey] = buildImage;
     return buildImage;
@@ -315,6 +307,16 @@ export class Bundling {
       ([a], [b]) => a.localeCompare(b),
     );
   }
+
+  private getDefaultBuilderBuildArgs(): Record<string, string> {
+    return {
+      ...this.props.buildArgs,
+      UV_VERSION: this.props.uvVersion ?? DEFAULT_UV_VERSION,
+      BUNDLING_IMAGE:
+        this.props.buildArgs?.BUNDLING_IMAGE ??
+        this.props.runtime.bundlingImage.image,
+    };
+  }
 }
 
 function encodeCommands(commands: string[]) {

src/bundling.ts

@@ -1,6 +1,7 @@
 import type {
   AssetHashType,
   BundlingFileAccess,
+  DockerImage,
   DockerRunOptions,
 } from 'aws-cdk-lib/core';
 
@@ -33,8 +34,23 @@ export interface BundlingOptions extends DockerRunOptions {
   readonly outputPathSuffix?: string;
 
   /**
-   * Optional build arguments to pass to the default container. This can be used to customize
-   * the index URLs used for installing dependencies.
+   * Custom builder image to use for bundling.
+   *
+   * Use this for full control over the bundling environment. The image must
+   * include Python, `uv`, and the `/opt/uv-python-lambda` scripts expected by
+   * this library.
+   *
+   * To customize only the base image used by the default builder, prefer
+   * `buildArgs.BUNDLING_IMAGE`.
+   *
+   * @default - Build the library default builder image from `resources/`
+   */
+  readonly image?: DockerImage;
+
+  /**
+   * Optional build arguments to pass to the default builder image. This can be
+   * used to customize the index URLs used for installing dependencies, or to
+   * override `BUNDLING_IMAGE` with a different Python base image.
    * This is not used if a custom image is provided.
    *
    * @default - No build arguments.