Skip to content

docs(lambda): document bundling image version pinning - #38650

Merged
mergify[bot] merged 20 commits into
aws:mainfrom
fukunaga-kengo:fix/issue-38404-document-bundling-image-tags
Nov 18, 2026
Merged

mergify[bot] merged 20 commits into
aws:mainfrom
fukunaga-kengo:fix/issue-38404-document-bundling-image-tags

Conversation

@fukunaga-kengo

@fukunaga-kengo fukunaga-kengo commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

Issue # (if applicable)

Closes #38404.

Reason for this change

Predefined Lambda runtimes expose untagged AWS SAM build images. Those images follow the latest published image, so their bundled tool versions can change independently of the AWS CDK version. Users whose builds require a specific tool version need clear guidance on selecting an explicit image tag.

Description of changes

  • Document the untagged/latest behavior on Runtime.bundlingImage.
  • Expand the Lambda README with an explicit Java 21 SAM build image tag example.
  • Recommend choosing a compatible tag and updating pinned images regularly for tool and security updates.
  • Link to the official AWS SAM build image repository documentation.

This is a documentation-only change. It does not pin CDK's predefined runtime images or change any runtime behavior.

Describe any new or updated permissions being added

None.

Description of how you validated changes

  • Ran yarn build --fix in packages/aws-cdk-lib.
  • Ran npx jest aws-lambda/test/runtime.test.ts --runInBand --coverage=false (7 tests passed).
  • Ran strict Rosetta validation for the new README snippet.
  • Ran git diff --check.
  • Integration tests were not run because no executable or CloudFormation behavior changed.

Checklist


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@github-actions github-actions Bot added the beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK label Aug 24, 2026
@github-actions github-actions Bot added bug This issue is a bug. effort/small Small work item – less than a day of effort p2 labels Aug 24, 2026
@aws-cdk-automation
aws-cdk-automation requested a review from a team August 24, 2026 18:58
@aws-cdk-automation aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Aug 24, 2026
@aws-cdk-automation aws-cdk-automation added pr/community-review-timeout pr/needs-maintainer-review This PR needs a review from a Core Team Member and removed pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. labels Sep 24, 2026
@maintainer-for-aws

maintainer-for-aws Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Automated review

A maintainer will still review this — treat the notes below as a starting point.

📌 Commit 9e45110

This PR documents how to pin the Lambda bundling image version (in response to #38404). It expands the JSDoc on Runtime.bundlingImage in aws-lambda/lib/runtime.ts and rewrites the "Bundling Asset Code" section of the Lambda README. The README now explains that the default SAM build image is untagged, gives a pinned Java 21 example, recommends digest pinning, and covers the custom-runtime approach for constructs such as NodejsFunction.

The change is documentation only, with no API, behavior or synthesis impact, and the new text matches the code and the AWS SAM documentation. The only finding is optional: the asset-hash sentence should say it applies to the default hash type. Maintainers may also want to confirm that documentation alone is enough to close #38404. The predefined runtimes still point at a floating image, so "Relates to" may fit better than "Closes".

🔴 0 blocking · 🟡 0 recommended · ⚪ 1 optional

Files with findings (1)
File Findings
packages/aws-cdk-lib/aws-lambda/README.md ⚪ 1

Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.

@maintainer-for-aws maintainer-for-aws Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review summary comment for the overview; the notes below are inline.

Co-authored-by: maintainer-for-aws[bot] <223376586+maintainer-for-aws[bot]@users.noreply.github.com>

@matboros matboros left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for applying the earlier suggestions, including the NodejsFunction fix. The section reads much better now. One small correction is still needed on the new custom-runtime example; the other inline suggestions are optional polish.

Resolved

  • NodejsFunction pinning advice in the JSDoc (thread · resolved in 507d7dd) — now pins the base image through a custom Runtime with bundlingDockerImage. (The bundling.dockerImage example I suggested earlier was wrong, sorry for the extra round.)
  • Pinned image wired into the bundling options (thread · resolved in 3565a55) — the example now passes the pinned image to bundling.image with Runtime.JAVA_21.
  • :latest and local cache wording (thread · resolved in b3d6c06) — no longer implies a fresh pull.
  • Tag meaning and digest pinning (thread · resolved in d160e6b) — explains SAM CLI release tags and shows @sha256: pinning.
  • JSDoc scope and @see link (thread · resolved in 10286ed) — covers custom runtimes and links the SAM image docs.
  • DockerImage naming (thread · resolved in 8f1a304) — prose matches the snippets.

New findings: 7 — see the inline comments below.

@mergify
mergify Bot dismissed matboros’s stale review November 17, 2026 10:35

Pull request has been modified.

matboros
matboros previously approved these changes Nov 17, 2026
@mergify

mergify Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

@mergify

mergify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

🚫 Left the queue · pull request branch update failed

1 min in the queue, with no time running CI.

So far

  • ✅ Entered the queue Tue 17 Nov, 20:53 · rule default-squash · triggered by rule automatic merge
  • 🚫 Left the queue 20:54 · 6888492

Reason

The pull request can't be updated

GitHub response: refusing to allow a GitHub App to create or update workflow .github/workflows/codebuild-pr-build.yml without workflows permission
GitHub only lets Mergify write to .github/workflows/ with the workflows permission. An organization owner can accept Mergify's pending permissions at https://dashboard.mergify.com/orgs/aws/repositories.

To get back in the queue

  • Update or rebase the branch yourself: the pull request is queued again once its queue conditions match.
  • If the failure is a flake, tick the box below to queue it again as it is.

Requeue requested — the merge queue status continues in this comment ↓.

Times in UTC · dashboard · how the merge queue works

@mergify
mergify Bot dismissed matboros’s stale review November 18, 2026 00:36

Pull request has been modified.

@maintainer-for-aws maintainer-for-aws Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review summary comment for the overview; the notes below are inline.

Comment on lines +2007 to +2009
reproducible build, pin the image by digest instead (`public.ecr.aws/sam/build-java21@sha256:<digest>`). The bundling
image is part of the asset hash, so changing the pinned tag or digest updates the function code on the next deployment,
even if your source code is unchanged.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Optional — The sentence saying the bundling image is part of the asset hash, so changing the pinned tag or digest always updates the function code, reads as unconditional. It only holds under the default AssetHashType.SOURCE (and CUSTOM). With AssetHashType.OUTPUT or BUNDLE, the hash comes from the bundled output, so changing the image triggers an update only if that output changes. Documented behavior should match what the code does (default-behavior).

Suggested change
reproducible build, pin the image by digest instead (`public.ecr.aws/sam/build-java21@sha256:<digest>`). The bundling
image is part of the asset hash, so changing the pinned tag or digest updates the function code on the next deployment,
even if your source code is unchanged.
reproducible build, pin the image by digest instead (`public.ecr.aws/sam/build-java21@sha256:<digest>`). With the default
asset hash type (`AssetHashType.SOURCE`), the bundling image is part of the asset hash, so changing the pinned tag or
digest updates the function code on the next deployment, even if your source code is unchanged.

@fukunaga-kengo

Copy link
Copy Markdown
Contributor Author

@matboros Thank you for the review and approval!

The merge queue couldn't update this branch from main. Mergify doesn't have the workflows permission, and main now includes changes under .github/workflows/ (#39796), so I merged main into the branch myself. The PR diff is the same as before; the only new commit is the merge from main.

That push dismissed the earlier approval. Could you re-approve when you have a moment? Thank you!

@mergify

mergify Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

@mergify
mergify Bot merged commit 387d29b into aws:main Nov 18, 2026
24 of 25 checks passed
@mergify

mergify Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

✅ Merged into main as 387d29b at 07:22 UTC

Less than a minute in the queue, with no time running CI.

So far

  • ✅ Entered the queue Wed 18 Nov, 07:22 · rule default-squash · triggered by rule automatic merge
  • ✅ Checks skipped · PR is already up-to-date
  • ✅ Merged 07:22 · 387d29b · squash
3 merge conditions met
  • github-review-approved · required by GitHub branch protection
  • any of · required by GitHub branch protection:
    • check-success = validate-pr
    • check-neutral = validate-pr
    • check-skipped = validate-pr
  • any of · required by GitHub branch protection:
    • check-success = build
    • check-neutral = build
    • check-skipped = build

Times in UTC · dashboard · how the merge queue works

@github-actions

Copy link
Copy Markdown
Contributor

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Nov 18, 2026
@fukunaga-kengo
fukunaga-kengo deleted the fix/issue-38404-document-bundling-image-tags branch November 18, 2026 07:29

This branch was previously deployed

1 inactive deployment
automation — 9e451101 Deployed Nov 18, 2026 by fukunaga-kengo via validate-pr #380250
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK bug This issue is a bug. effort/small Small work item – less than a day of effort p2 pr/community-review-timeout pr/needs-maintainer-review This PR needs a review from a Core Team Member pr/request-review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

(lambda): lambda.Runtime.JAVA_21.bundlingImage changed from providing Gradle 8.4 to Gradle 9, breaking builds

3 participants