If a Lambda function can be cheaper by changing one field, why does the change sometimes fail at deploy time or on the first invoke? For container-image functions, the field is not the hard part. The architecture is now a property of two separate things, the function configuration and the image, and the pipeline has to keep them in agreement. Whether arm64 is worth it for a given function, including the price difference and the compatibility checklist, is covered in AWS Lambda ARM64 Container Images: Should You Build for Graviton or x86_64?. This guide covers the part after that decision: making sure what you build is what you deploy.
A container function has two architecture declarations
| Where | What it declares | Default when unspecified |
|---|---|---|
| Function configuration | The Architectures setting: exactly one value | x86_64 |
| The image | The platform it was built for, decided by the build host, base image and build flags | Whatever machine ran the build |
The Lambda documentation says the code in a function's package must be compatible with the function's architecture, which for a container means the whole image. Nothing reconciles the two declarations for you, and a smarter tag cannot make a mismatch safe. If a deploy script never mentions the architecture, the function gets the default.
What Lambda documents about container images
- One architecture per image. Lambda provides multi-architecture base images, but the image you build for your function must target only one architecture. Lambda does not support functions that use multi-architecture container images. A multi-arch base image does not make the image you ship multi-arch.
- Accepted formats. Lambda supports images that conform to the Docker image manifest V2 schema 2 or the OCI specification (v1.0.0 and up).
- Keep the manifest small. For best performance, keep the image manifest under 25,400 bytes by minimizing layers and annotations.
- Images must stay available. Lambda periodically fetches the image from Amazon ECR. If the image no longer exists or permissions are revoked, the function enters the
Failedstate and invocations fail.
Three ways the mismatch shows up
A build host that picks the wrong platform. A plain docker build targets the machine it runs on. An Apple Silicon laptop builds arm64 by default, while an x86 CI runner builds amd64, so the same Dockerfile produces different artifacts depending on where it runs. Some infrastructure tools can derive the platform from the function's architecture setting, which is preferable to stating it in two places. Check your tool's documentation for how it chooses the build platform.
A build that produces an index instead of a single image. Recent BuildKit-based builds can attach provenance or SBOM attestations, which turns the pushed artifact into a manifest index rather than a single image manifest. Lambda's own container guides tell you to build with the --provenance=false option for this reason, and the usual symptom is an error about an unsupported media type when creating or updating the function. Defaults vary by Docker version and image store configuration, so check what your build actually pushes rather than assuming.
A native dependency without an arm64 build. The Lambda migration guidance requires each third-party library or package to provide an arm64 version, including binaries in dependencies, layers and extensions. This is where "just flip the setting" really fails, because the failure comes from something you did not write.
Make the architecture one value, and check after the build
A single source of truth for architecture, with a gate between build and deploy, closes most of these gaps. This sketch shows the shape, with placeholders for account and repository details. It is not a tested pipeline.
ARCH=arm64 # one value: build platform and function config both derive from it
IMAGE=ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/REPO:GIT_SHA
docker buildx build \
--platform linux/${ARCH} \
--provenance=false \
-t ${IMAGE} \
--push .
# Gate 1: the pushed artifact must be a single image manifest, not an index
docker buildx imagetools inspect --raw ${IMAGE} | jq -r '.mediaType'
aws lambda update-function-code \
--function-name FUNCTION_NAME \
--image-uri ${IMAGE} \
--architectures ${ARCH}
# Gate 2: read the configured architecture back instead of assuming it
aws lambda get-function-configuration \
--function-name FUNCTION_NAME \
--query Architectures
# Gate 3: a smoke invocation proves the image actually runs on that architecture
aws lambda invoke --function-name FUNCTION_NAME /dev/stdout
What each part buys you:
--platform linux/${ARCH}removes the dependency on the build host.--provenance=falseavoids the extra attestation manifest. The trade-off is that you give up BuildKit's provenance attestation, so if supply-chain evidence matters, record provenance somewhere else instead of dropping it quietly.- Gate 1 should fail the pipeline if the media type indicates an index. The exact flags and output of the inspect command depend on your Docker version, so verify it on yours.
- Passing
--architecturesin the same call as the code update keeps the function setting aligned with the image. - Gate 3 is the check that cannot be fooled by metadata. A wrong-architecture image typically fails on invoke rather than at deploy, so run it before real traffic arrives.
Tag by commit SHA instead of latest, so the image you inspected is the image that runs. Also make sure any ECR lifecycle rule cannot delete an image that a function still references, since a missing image puts the function into the Failed state.
A checklist for changing a container function's architecture
- List native dependencies, including OS packages installed in the Dockerfile, and confirm each has a build for the target architecture.
- Decide where the image is built, and make the platform explicit even on a single-architecture CI runner.
- Confirm the pushed artifact is a single image manifest, not an index.
- Deploy the image and the architecture together, then read the configured architecture back.
- Run a smoke invocation before sending traffic, and compare duration and memory before and after in CloudWatch.
- Keep a rollback path that restores both image and architecture, since rolling back only one recreates the mismatch.
When to hold off
Stay on the current architecture if a dependency cannot be built for the new one without work you cannot justify, or if the team builds images on a mix of laptops and runners and cannot yet make the platform explicit. Both are pipeline problems, not Lambda problems, and they are cheaper to fix before the switch than after it.
Some write-ups claim that pointing a function at a multi-arch tag makes Lambda pull the matching variant. That conflicts with the official statement that multi-architecture container images are not supported, so treat the documentation as authoritative and test before relying on any other behavior.
Whether the saving is kept depends less on the Lambda setting than on whether the pipeline can state the architecture once, build for it explicitly, and fail when the image says otherwise.
Comments
Post a Comment