Deploy docker images directly to AWS Lambda

How to use AWS Lambda images to run your own Docker containers on AWS Lambda
Yossi Ittach

May 11 2022 · 9 min read


Deploy docker images directly to AWS Lambda

If you're using cloud compute, you're probably already using AWS Lambda. It's easily scalable, easy, cost-effective (usually), and takes away the hustle of provisioning servers, managing them, defining auto scaling groups, patching OS's, and following utilization statistics.

However, using AWS Lambda with a code zip file does have its caveats - not all languages and versions are supported (Node 16, anyone?), your zipped code file size is capped at 50 MB, and building code for AWS Lambda usually requires a dedicated CI/CD pipeline.

To make AWS Lambda more versatile, and to align with modern CI/CD targets which usually result in Docker image objects, AWS announced in December 2020 that Lambda will support Docker images.

As part of our efforts to help our users deploy their solutions on the best platform - be it Lambda, ECS tasks, or ECS clusters - we've added the option to use Docker images based Lambdas as a native Altostra resource.

Image requirements

To use your own Docker image for your lambda, your image needs to fulfill some basic AWS requirements, the main ones being:

  • Lambda only supports Linux-based images
  • Your image extends an AWS base image, or
  • Your image must implement the Lambda Runtime API.
  • The default Lambda user must be able to read all the files required to run your function code.

You can read more about the image requirements on AWS Lambda images page

Creating a new Image Based Lambda

Image-based lambda works exactly like a regular, code-based Lambda - the only difference is that instead of providing the code, you need to provide the image ARN, like this:

creating a new image-based lambda

Or use an environment parameter:

creating a new image-based lambda with env param

Triggering and accessing resources with image-based Lambdas

Image-based Lambdas can be triggered exactly like code-based Lambdas, and can access all the resources a code-based Lambda can:

connecting lambda resources and targets

Updating a project when your image changes

Like other Docker repositories, AWS ECR uses tags to manage your images, and the ARN you provide usually includes that image tag, like this sample tag:

However, when your lambda is deployed, your image ARN is translated to its digest - in this case


This means that if you pushed a new image to your ECR repository, with the same tag as the one you used in your project deployment, AWS will still be running the old image. This is done to prevent unintentional version changes.

If you want to update your project deployment to use the new image, you'll need to update the environment param containing the image ARN, and re-deploy the project. If it's the same tag, just re-deploy the project, and the newly tagged image will be deployed.

If you're pushing your images via a CI/CD process, you can use Altostra CLI to update the relevant environment variables and re-deploy the project.

alto env update-params <ENV NAME> --key <PARAM_NAME> --value <PARAM_VALUE>

alto env update-params Demo --key MY_IMAGE_ARN --value
Using cli to update env param

Regional Concerns

It's important to remember that AWS Lambda requires the Lambda image to be stored in the same region as the Lambda.

This means that you need the ECR image used for the Lambda to be stored in the same region as the Lambda itself. So, if you're deployed in multiple regions, make sure to either:

  • Deploy your image to the relevant repositories in each region and update the relevant environment parameters
  • Use AWS ECR cross-region repository replication. You can read more about it here


Using Lambda images frees you to run your services in a serverless, highly scalable way, and pay only for what you use. It's a great way to integrate Lambda's into your Docker-based CI/CD, and test your loads before switching to cluster-based deployments.

Next steps

Want to give it a try? We provide a free-forever plan for developers. Create your free account today at

We want to hear from you! Share your Altostra experience with us on Twitter @AltostraHQ and LinkedIn and any suggestions that can make your work with Altostra even better.

Happy coding!

By submitting this form, you are accepting our Terms of Service and our Privacy Policy

Thanks for subscribing!

Ready to Get Started?

Get Started for Free

Copyright © 2022 Altostra. All rights reserved.