Docker
AWS Lambda supports running a Docker image, instead of running your application in the default Linux environment. We recommend Docker as a last resort, as it is less practical and usually comes with slightly worse cold starts. Yes, Docker is great and probably sounds familiar, but is often not worth it on Lambda.
You should consider deploying using Docker when:
- Your Lambda Function is larger than 250MB when unzipped
- You reached the limit of 5 Lambda layers (e.g. for extra PHP extensions)
- You need resources installed locally (e.g. mysqldump)
Note: this documentation page assumes that you have read about web apps on Lambda first.
Docker Image
Bref helps you deploy to AWS Lambda using Docker by offering out-of-the-box base images that are package for the Lambda environment. Here is an example of a Docker image
FROM bref/php-80-fpm:2
COPY . /var/task
# Configure the handler file (the entrypoint that receives all HTTP requests)
CMD ["public/index.php"]
This Dockerfile outlines the 3 key aspects of Docker on Lambda:
- Base image compatible with Lambda Runtime
- Source code placed under
/var/task
- CMD pointing to the entrypoint that will handle requests
You may also enable PHP extensions by pulling them from Bref Extensions
FROM bref/php-80-fpm:2
COPY --from=bref/extra-redis-php-80:1 /opt /opt
COPY --from=bref/extra-gmp-php-80:1 /opt /opt
COPY . /var/task
CMD ["public/index.php"]
Deployment
The Serverless Framework supports deploying Docker images to Lambda:
service: bref-with-docker
provider:
name: aws
ecr:
images:
hello-world:
path: ./
functions:
hello:
image:
name: hello-world
events:
- httpApi: '*'
Instead of having a handler
and a runtime
, we'll declare an
image
. In the provider
block, we'll declare Docker images
that we want to build and deploy.
When running serverless deploy
, the framework will:
- Build the Docker images according to their specified
path
- Create an ECR Repository called
serverless-{service}-{env}
- Authenticate against your ECR Account
- Push the newly built Docker Image
- Deploy the Lambda Function pointing to the Docker Image
When the deployment finishes, your lambda is ready to be invoked from your API Gateway address.
Filesystem
The filesystem for Docker on AWS Lambda is also readonly with
a limited disk space under /tmp
for read/write. This folder
will always be empty when a new cold start happens. Avoid
writing content to /tmp
in your Dockerfile because that
content will not be available for your Lambda function.
Read more about file storage in Lambda.
Docker Registry
AWS Lambda only support AWS ECR as the source location for Docker images. The Lambda service will use the image digest as the unique identifier. This means that even if you overwrite the exact same tag on ECR, your lambda will still run the previous image code until you actually redeploy using the new image.