fix: reduce docker build image size by over 13x

[garysassano]

Motivation

The current SAM image is unnecessarily large, leaving room for improvement. Below is a comparison of the resulting Docker images before and after the Dockerfile optimization:

Premise

• uv requires Python 3.8 or later
• AWS Lambda's Python 3.8 runtime is deprecated, and function creation will no longer be possible after Feb 28, 2025.

Given this, Python 3.9 is the minimum viable version. However, setting Python 3.13 as the default makes more sense, allowing users to override the build argument if needed.

Approach

We'll leverage the official uv Docker images, which bundle both uv and Python. This eliminates the need to install them manually, enabling seamless selection of any uv and Python version. By default, we'll use the latest uv binary and Python 3.13.

To simplify customization, we could introduce a uvVersion property in the PythonFunction construct. This would allow users to override the uv version without touching buildArgs in the bundling property.

Simplifications

1. Removed all PIP-related environment variables, as uv ignores them.
2. Removed UV_CACHE_DIR, defaulting to $HOME/.cache/uv instead of setting a custom cache directory.

Results

These changes reduce the Docker image size from over 2GB to just 156MB, while retaining flexibility to select any Python and uv version directly from the base image.

[eoinsha]

Thanks @garysassano! Although this is a build image, it makes sense to have a smaller one indeed as it can reduce CI/CD build times.

Note however that, as the original Dockerfile comment states, this is derived from the aws-lambda-python-alpha template and maintaining similarity is useful so we can incorporate any changes made there. Perhaps a similar size reduction is warranted in the AWS CDK official package too?

I'd also like to consider the reasons for using the AWS SAM base image in the first place. I believe that this allows close binary compatibility between the build environment and the runtime environment in AWS Lambda, considering things like libc version and available shared libraries.

Perhaps it would be a good compromise to base any new Dockerfile on the AWS Lambda runtime images rather then the build images.

If we look at how the AWS SAM build images are assembled, (FROM public.ecr.aws/lambda/python:3.12-$IMAGE_ARCH), that might be a better starting point, ensuring binary compatibility but avoiding the bloat of AWS CLI AND SAM, etc.

[garysassano]

I would have opted for an even more minimal image, such as Alpine, if not for the need to support bash commands during bundling. I genuinely don't see any advantage in including the Lambda RIC. While it might be useful for SAM to enable local function testing, in this case, we're simply bundling the code, so it seems unnecessary to me. The goal is to keep the image as lightweight as possible—just enough to install dependencies, build the ZIP package, and deploy the Python Lambda function. This approach already works well, as I'm currently using it.

[garysassano]

I wouldn’t overanalyze why AWS initially chose to use the AWS SAM image. In my opinion, it was likely a rushed decision that wasn't given much thought. Users of this construct have reported many issues, including a caching problem that has remained unresolved since 2023, as reported here.

The purpose of PythonFunction should align with NodejsFunction, meaning local testing shouldn't be a factor. Including the Lambda RIC would make sense if we were building a containerized Lambda, but here we're dealing with a zipped Lambda, so it's unnecessary.