[plugin] Display a warning when compiling on Amazon Linux 2 and optin documentation and examples for Amazon Linux 2023

[sebsto]

This PR has been reworked. Instead of silently switching the default base image based on Swift version, we now:

1. Keep Amazon Linux 2 as the default base Docker image for the packager plugin
2. Add a prominent deprecation warning when AL2 is used (either via Docker or natively), informing developers that AL2 reaches End of Life on June 30, 2026
3. Migrate all examples (READMEs, SAM templates, scripts) to build and deploy on Amazon Linux 2023 (provided.al2023 runtime + --base-docker-image swift:amazonlinux2023)
4. Update documentation (readme, quick-setup) with migration notes

The warning includes the --base-docker-image swift:6.3-amazonlinux2023 flag and reminds developers to use the provided.al2023 runtime when deploying.

After June 30, 2026, the default will switch to AL2023.

---

Original PR description (superseded)

Now that Docker Hub has official Swift images based on Amazon Linux 2023 (starting with 6.3), the packager plugin picks the right base image automatically depending on the Swift version:
- Swift 6.3 and later: swift:<version>-amazonlinux2023
- Earlier versions: swift:<version>-amazonlinux2 (unchanged behavior)
- No version specified (latest): defaults to amazonlinux2023

When only a major version is provided (e.g. --swift-version 6 without a minor), we conservatively treat it as 6.0 and use Amazon Linux 2, since we can't be sure it's 6.3+.
Also added a verbose log line showing the resolved Swift version, Amazon Linux version, and final base image to help with debugging.
The --base-docker-image flag still overrides everything as before.

[sebsto]

The swift-nightly-main failure is unrelated to this PR. It is caused by stricter region-isolation diagnostics in the nightly compiler hitting the current pinned version of swift-async-algorithms (MultiProducerSingleConsumerAsyncChannel+Internal.swift). See apple/swift-async-algorithms#418.

[sebsto]

Hey @MahdiBM Can you have a look and comment on this change ?

[Copilot]

Pull request overview

This PR updates the Lambda packager to select Amazon Linux 2023 Swift Docker images by default for Swift 6.3+ while preserving Amazon Linux 2 for older Swift versions.

Changes:

• Adds Swift-version-based Amazon Linux image selection and verbose logging in the packager plugin.
• Bumps several package dependency minimum versions.
• Adds documentation for the ResourcesPackaging example and links it from the examples index.

Reviewed changes

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

File	Description
Plugins/AWSLambdaPackager/Plugin.swift	Updates default Docker image selection and help text for Amazon Linux 2023/2.
Package.swift	Raises minimum versions for NIO, swift-log, swift-collections, and service-lifecycle.
Examples/ResourcesPackaging/README.md	Adds usage, deployment, invocation, and cleanup instructions for the resources packaging example.
Examples/README.md	Adds the ResourcesPackaging example to the examples list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MahdiBM]

Technically speaking, any app that runs on Swift 6.2 and below should also be able to run on Swift 6.3. So checking the Swift version is probably not very helpful. A swift version upgrade is supposed to always work out, although sometimes it can go wrong when the newer compiler comes with some issues or bugs.

I'm only worried maybe some people are relying on the plugin using amazonlinux2 images. If that is a concern (e.g. if something breaks when you upload a amazonlinux2023 executable to a amazonlinux2 aws lambda) then the safest option would be to print a big scary warning by default and mention that they should pass some kind of flag to ensure they'll use amazon linux 2023 since amazon linux 2 is very outdated 🤔.

So yeah. I'm not sure how gracefully AWS handles that. If things will be just fine, then we can take a bit of a risk and just get rid of amazon Linux 2. Otherwise the safer option is a big warning to ask users to manually choose amazonlinux2023 (--base-docker-image swift:amazonlinux2023 ?), IMO.

[sebsto]

Good points. Let me address them:

On the Swift version check: You're right that a package targeting swift-tools-version 6.1 will compile fine with the Swift 6.3 compiler (source compatibility is forward). The --swift-version flag in the plugin is really just about choosing which Docker image to pull from Docker Hub, not about language compatibility. Since we dropped support for Swift 6.0 in this release and the minimum is now 6.1, we could simplify this further and always default to swift:amazonlinux2023 (latest). The version-based logic is only there as a safety net for people who explicitly pass --swift-version 6.1 (which pulls swift:6.1-amazonlinux2... because there's no swift:6.1-amazonlinux2023 image on Docker Hub).

On the real risk (build/deploy mismatch): The actual concern is not Swift version compatibility but OS-level library compatibility. --static-swift-stdlib only statically links the Swift runtime, not system C libraries. If someone uses aws-sdk-swift (which dynamically links libcrypto via aws-crt-swift), a binary built on AL2023 (OpenSSL 3.x / libcrypto.so.3) will crash on a provided.al2 Lambda runtime (which only has libcrypto.so.1.1). The reverse is also true. glibc differences (2.26 on AL2 vs 2.34 on AL2023) add another layer.

So the build environment and the Lambda runtime must match. This was already the case before this PR (build on AL2 → deploy to provided.al2). The change here just updates the default to match the current state of the world: AL2 is EOL (June 2025), provided.al2023 is the recommended Lambda runtime, and Swift 6.3 images are available for it.

On the approach: I think we can simplify: always default to amazonlinux2023 regardless of --swift-version, and print a note like:

note: building on amazonlinux2023. Deploy with --runtime provided.al2023.
      Use --base-docker-image swift:amazonlinux2 if you still target provided.al2.

This makes the migration explicit without being scary. Users who still need AL2 have a clear escape hatch.

What do you think?

[MahdiBM]

So ... I think we should take the safer approach unless we can confirm just updating to al2023 will not cause issues for like more than ~1% of the users.

The actual issue is that users will need to manually update to provided.al2023.
We shouldn't deploy al2023-built images to al2 because there are no ABI gurantees on Linux and shared libraries like glibc. If we have a binary linked against a previous glibc version (or any other system libraries), it might not work properly with a newer glibc version. In theory at least.

So unless someone with deep knowledge/experience can come through and say the risk is very low, we should take the safer route IMO.
Which is something like a very big and eye catching warning about the need to ensure provided.al2023 is used in the lambda definition, and that a flag is passed to the plugin to make it build for al2023. Perhaps + a link to aws docs. Essentially a big warning that is also helpful.

In the future we can still change the default to 2023 if we ever think it's a safe default.

[MahdiBM]

Which then means we'll also have to update the docs and mention that they default al2 is only kept for legacy reasons and users should theoretically always pass that argument to make the plugin use al2023, if the machine they're building on is not already al2023.

Also ... a question. Penny CI builds stuff in an amazonlinux2023 container. Shouldn't the plugin simply just use the environment instead of using the al2 default?
Basically I think there should be a detection mechanism that if the plugin is triggered already in al2023, then just proceed with al2023 and don't default to al2.

[sebsto]

Hello @MahdiBM

The ABI compatibility is not in the discussion because the binaries are statically linked with all Swift libraries. The risk is about system libraries, such as libgc and the crypto ones.

If I summarize your message, you're suggesting to have an Amazon Linux 2023 compilation as an opt-in flag to avoid breaking builds or deployments.

I kind of agree with that suggestion.

Let's bring in the wider community for discussion before taking a decision.

[sebsto]

@MahdiBM I apologize for the pause working on this. I pushed a set of changes to address your feedback. Instead of silently switching the default base image, the plugin now keeps AL2 as the default and displays a prominent deprecation warning when AL2 is used. All examples have been migrated to build and deploy on AL2023. Please take a look when you get a chance.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[sebsto]

Here is the output when compiling on Amazon Linux 2

➜  HelloJSON git:(plugin/amazonlinux2023) LAMBDA_USE_LOCAL_DEPS=../..  swift package archive --allow-network-connections docker
====================================================================
WARNING: Amazon Linux 2 reaches End of Life on June 30, 2026.

You must migrate to Amazon Linux 2023.
Amazon Linux 2023 will become the default after June 30, 2026.

To switch now, re-run with:
  --base-docker-image swift:amazonlinux2023

When using Amazon Linux 2023, you must also update your Lambda
deployment to use the provided.al2023 runtime.

For more information: https://aws.amazon.com/amazon-linux-2
====================================================================

-------------------------------------------------------------------------
building "hellojson" in docker
-------------------------------------------------------------------------
updating "swift:amazonlinux2" image
  amazonlinux2: Pulling from library/swift
  Digest: sha256:49ad698b70e08c773f378b3616b272dc070cdd5e04935208714064ceab060dc2
Status: Image is up to date for swift:amazonlinux2
  docker.io/library/swift:amazonlinux2
building "HelloJSON"
  [0/1] Planning build
  Building for production...
  [0/3] Write sources
  [1/3] Write swift-version-24593BA9C3E375BF.txt
  [3/4] Compiling AWSLambdaRuntime Context+Foundation.swift
  [4/6] Compiling HelloJSON main.swift
  [4/6] Write Objects.LinkFileList
  /usr/lib/swift_static/linux/libFoundationEssentials.a(Data+Writing.swift.o):_ThreadLocal.swift.o:function $s20FoundationEssentials19createTemporaryFile33_FC9EC52B075D2ACCFF86F1C9F84293BELL2at6inPath6prefix7options7variants5Int32V_SStSS_AA0Q5OrURLOSSAA4DataV14WritingOptionsVSSSgtKFAJ_SStSgSpys4Int8VGSgKXEfU_: warning: the use of `mktemp' is dangerous, better use `mkstemp' or `mkdtemp'
[5/6] Linking HelloJSON
  Build of product 'HelloJSON' complete! (20.66s)
-------------------------------------------------------------------------
archiving "HelloJSON"
-------------------------------------------------------------------------
1 archive created
  * HelloJSON at /Users/stormacq/Documents/code-amzn/swift/lambda/swift-aws-lambda-runtime/Examples/HelloJSON/.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/HelloJSON/HelloJSON.zip

[sebsto]

and here is the output when compiling on Amazon Linux 2023

➜  HelloJSON git:(plugin/amazonlinux2023) ✗ LAMBDA_USE_LOCAL_DEPS=../..  swift package archive --allow-network-connections docker --base-docker-image swift:amazonlinux2023
-------------------------------------------------------------------------
building "hellojson" in docker
-------------------------------------------------------------------------
updating "swift:amazonlinux2023" image
  amazonlinux2023: Pulling from library/swift
  Digest: sha256:dab6dd1e149263977ca6e833a748c12d8e777c9da6772180413a6db0c694143c
Status: Image is up to date for swift:amazonlinux2023
docker.io/library/swift:amazonlinux2023
building "HelloJSON"
  [0/1] Planning build
  Building for production...
  [0/2] Write swift-version-24593BA9C3E375BF.txt
...
  [29/31] Compiling HelloJSON main.swift
  [29/31] Write Objects.LinkFileList
  /usr/bin/ld: /usr/lib/swift_static/linux/libFoundationEssentials.a(Data+Writing.swift.o): in function `$s20FoundationEssentials19createTemporaryFile33_FC9EC52B075D2ACCFF86F1C9F84293BELL2at6inPath6prefix7options7variants5Int32V_SStSS_AA0Q5OrURLOSSAA4DataV14WritingOptionsVSSSgtKFAJ_SStSgSpys4Int8VGSgKXEfU_':
_ThreadLocal.swift.o:(.text+0x804): warning: the use of `mktemp' is dangerous, better use `mkstemp' or `mkdtemp'
[30/31] Linking HelloJSON
  Build of product 'HelloJSON' complete! (75.38s)
-------------------------------------------------------------------------
archiving "HelloJSON"
-------------------------------------------------------------------------
1 archive created
  * HelloJSON at /Users/stormacq/Documents/code-amzn/swift/lambda/swift-aws-lambda-runtime/Examples/HelloJSON/.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/HelloJSON/HelloJSON.zip

[MahdiBM]

One minor issue + 3 subjective comments. Feel free to reject / accept / discuss.

Also thank you, no worries, I wasn't blocked 🙂. I noticed I should use the --base-docker-image flag and just did that.