Deploy Ruby Lambda functions with container images - AWS Lambda

Deploy Ruby Lambda functions with container images

You can deploy your Lambda function code as a container image. AWS provides the following resources to help you build a container image for your Ruby function:

  • AWS base images for Lambda

    These base images are preloaded with a language runtime and other components that are required to run the image on Lambda. AWS provides a Dockerfile for each of the base images to help with building your container image.

  • Open-source runtime interface clients (RIC)

    If you use a community or private enterprise base image, you must add a Runtime interface client to the base image to make it compatible with Lambda.

  • Open-source runtime interface emulator (RIE)

    Lambda provides a runtime interface emulator for you to test your function locally. The base images for Lambda and base images for custom runtimes include the RIE. For other base images, you can download the RIE for testing your image locally.

The workflow for a function defined as a container image includes these steps:

  1. Build your container image using the resources listed in this topic.

  2. Upload the image to your Amazon ECR container registry.

  3. Create the Lambda function or update the function code to deploy the image to an existing function.

AWS base images for Ruby

AWS provides the following base images for Ruby:

Tags Runtime Operating system Dockerfile

2, 2.7

Ruby 2.7 Amazon Linux 2 Dockerfile for Ruby 2.7 on GitHub


Ruby 2.5 Amazon Linux 2018.03 Dockerfile for Ruby 2.5 on GitHub

Amazon ECR repository:

Using a Ruby base image

For instructions on how to use a Ruby base image, choose the usage tab on AWS Lambda base images for Ruby in the Amazon ECR repository.

Ruby runtime interface clients

Install the runtime interface client for Ruby using the package manager:

gem install aws_lambda_ric

For package details, see Lambda RIC on

You can also download the Ruby runtime interface client from GitHub.

Create a Ruby image from an AWS base image

When you build a container image for Ruby using an AWS base image, you only need to copy the ruby app to the container and install any dependencies.

To build and deploy a Ruby function with the ruby:2.7 base image.

  1. On your local machine, create a project directory for your new function.

  2. In your project directory, add a file named app.rb containing your function code. The following example shows a simple Ruby handler.

    module LambdaFunction class Handler def self.process(event:,context:) "Hello from Ruby 2.7 container image!" end end end
  3. Use a text editor to create a Dockerfile in your project directory. The following example shows the Dockerfile for the handler that you created in the previous step. Install any dependencies under the ${LAMBDA_TASK_ROOT} directory alongside the function handler to ensure that the Lambda runtime can locate them when the function is invoked.

    FROM # Copy function code COPY app.rb ${LAMBDA_TASK_ROOT} # Copy dependency management file COPY Gemfile ${LAMBDA_TASK_ROOT} # Install dependencies under LAMBDA_TASK_ROOT ENV GEM_HOME=${LAMBDA_TASK_ROOT} RUN bundle install # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "app.LambdaFunction::Handler.process" ]
  4. To create the container image, follow steps 4 through 7 in Create an image from an AWS base image for Lambda.

Deploy the container image

For a new function, you deploy the Ruby image when you create the function. For an existing function, if you rebuild the container image, you need to redeploy the image by updating the function code.