Occasionally, you may need to change how you interact with your tools. Sometimes it’s because you want to, or it could happen because of external factors. Regardless, if you are accustomed to a certain workflow, the general idea is to reduce the friction of that change as much as possible.

This article aims to provide some advice if you find yourself in a situation where you need to transition from AWS SAM + Docker + Windows to AWS SAM + Podman + Windows.

One cool feature that AWS SAM offers is the ability to test our AWS Lambdas locally with a simple command.

sam local start-api

I understand that depending on your use case, it could be more complicated than that, but bear with me. As I mentioned earlier, you replace Docker with Podman, and when you execute the command, everything starts to fall apart.

What Works for Me

I wondered why my Podman installation wasn't compatible with AWS SAM. The answer, in my environment, was a combination of factors that led me to write this article.

My machine had the following tools installed:

AWS SAM CLI 1.110.0
WSL 2

When I installed Podman instead of Docker, many issues appeared. After some trial and error and research on GitHub, I recommend to follow these steps:

Remove or rename the file ~/.docker/config.json (only if you previously had installed Docker Desktop)
Install Podman

Create a machine (you can do it graphically or using commands)

  > podmand machine init
  Looking up Podman Machine image at quay.io/podman/machine-os-wsl:5.4 to create VM
  Getting image source signatures
  Copying blob ba1b89c218e0 done   |
  Copying config 44136fa355 done   |
  Writing manifest to image destination
  ba1b89c218e00915feb327db05a10d9de7f158736c26be3d58e8b141ce5a7238
  Extracting compressed file: podman-machine-default-amd64: done
  Importing operating system into WSL (this may take a few minutes on a new WSL install)...
  Import in progress, this may take a few minutes.
  The operation completed successfully.
  Configuring system...
  Machine init complete
  To start your machine run:

          podman machine start

  > podman machine start
  Starting machine "podman-machine-default"

  This machine is currently configured in rootless mode. If your containers
  require root permissions (e.g. ports < 1024), or if you run into compatibility
  issues with non-podman clients, you can switch using the following command:

          podman machine set --rootful

  API forwarding listening on: npipe:////./pipe/docker_engine

  Docker API clients default to this address. You do not need to set DOCKER_HOST.
  Machine "podman-machine-default" started successfully

Upgrade or install AWS SAM CLI (at the time of writing this article, I suggest using version 1.133.0, which should include a version of the Docker library greater than 7.0.0)
```
  > pip list
  Package            Version
  ------------------ -----------
  aws-sam-cli        1.133.0
  ...
  docker             7.1.0
```

Create a symbolic link inside the Podman machine.

  > wsl -d podman-machine-default -e bash -li

  You will be automatically entered into a nested process namespace where
  systemd is running. If you need to access the parent namespace, hit ctrl-d
  or type exit. This also means to log out you need to exit twice.

  [user@PC ~]$ cd /
  [user@PC /]$ sudo ln -s /mnt/c c

Now you can execute your “sam local“ command as you used to. In some cases, you could use the parameter —skip-pull-image.

Few Notes

Following the steps above should provide a smoother experience, but you might deal with one of the issues in this section. Hopefully, these issues will be resolved in future updates.

First Internal Server Error

At least for me, the first invocation I made for the lambda starts with an “Internal Server Error”, but subsequent invocations return the expected result for your lambda.

Lambda does not contain my change

In some cases, the lambda doesn’t sync with new changes. The reason for that, especially if you stop and start the application is that the container is not destroyed by SAM CLI. So a workaround is to delete it manually. Here's the command for Windows to manually delete the container based on the image, just in case.

-- replace {image} with the language for you lambda
podman rm -f ((podman ps |findstr "{image}") -split '\s+' | Select-Object -First 1)
-- .NET
podman rm -f ((podman ps |findstr "public.ecr.aws/lambda/dotnet:8-rapid-x86_64") -split '\s+' | Select-Object -First 1)
-- Go
podman rm -f ((podman ps |findstr "public.ecr.aws/lambda/provided:al2023-rapid-x86_64") -split '\s+' | Select-Object -First 1)

Cannot connect to external resources

This occurs because Podman cannot resolve the DNS. To resolve this issue, I executed the following command.

> podman machine stop
Machine "podman-machine-default" stopped successfully

> podman machine set --user-mode-networking
Installing user-mode networking distribution...
The operation completed successfully.

> podman machine start
Starting machine "podman-machine-default"
Starting user-mode networking...
API forwarding listening on: npipe:////./pipe/docker_engine

Docker API clients default to this address. You do not need to set DOCKER_HOST.
Machine "podman-machine-default" started successfully

That’s a wrap! I hope this article helps you in your endeavors.

Until the next scribble, bytes for now!

References

https://github.com/aws/aws-sam-cli/issues/7043#issuecomment-2119648906

https://github.com/aws/aws-sam-cli/issues/5421#issuecomment-1786479608

https://github.com/containers/podman/issues/24839#issuecomment-2544290005

Navigating the Transition: AWS SAM with Podman on Windows

Table of contents