Documentation says to exclude @aws-sdk/* when bundling using the CDK. Should it?

[willjones9]

Hello!

Looking at the documentation here, it says to exclude @aws-sdk/* when bundling, "since the packages are already present the layer"

I took a look at the contents of the layer published, and whilst some of the @aws-sdk packages are present, not all are. This then causes the function to fallback to whatever version of the SDK is present in the runtime.

The question I have is "is there something obvious I've missed here, or does the documentation need updating?"

[dreamorosi]

Taken at face value the docs are technically incorrect - they do say the packages "are already present in the layer" when only 5 specific ones actually are. Fair point!

However, the recommendation to exclude @aws-sdk/* is still correct for practical reasons. The AWS SDK has a deeply interconnected dependency tree - even if we only excluded the 5-6 top-level modules we bundle, you'd still get duplicates in shared modules like credential resolvers, signature helpers, etc. This creates version conflicts and bloats your bundle.

The Powertools utilities use their own AWS SDK modules from the layer, and mixing those with bundled versions can cause runtime issues. For any AWS SDK clients not in the layer or your bundle, Lambda falls back to the runtime's built-in SDK.

So while the wording could be clearer (and we should fix that), the guidance is there to prevent dependency conflicts rather than just avoiding redundant packages.

[willjones9]

Ah ok, I understand.
So it there not a concern of dependency conflicts between the version present in the layer and the version present in the runtime?
From some brief tests I've done, there is a version mismatch here as well

[dreamorosi]

There is, but colocation priority applies: bundle > layer > runtime, with the runtime being the one with least update velocity.

Since we don't know what your function code will do or what it will bundle, we decided to bring our own AWS SDK modules in the Lambda layer - you on the other hand control your function code so you can either bundle what you need or rely on the runtime modules since you have the chance to test.

With that said, if you need/want strict control over which versions get used and what is bundled and used at runtime in your functions - perhaps it might be a good idea to do away with our public Lambda layers entirely and either bundle everything you need (highest degree of control, optimized perf) or create your own layer (good degree of control, easy to audit, baseline perf) instead.