Working with .zip file archives for Ruby Lambda functions - Amazon Lambda
Dependencies in RubyCreating a .zip deployment package with no dependenciesCreating a .zip deployment packaged with dependenciesCreating a Ruby layer for your dependenciesCreating .zip deployment packages with native librariesCreating and updating Ruby Lambda functions using .zip files
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with .zip file archives for Ruby Lambda functions

Your Amazon Lambda function’s code comprises a .rb file containing your function’s handler code, together with any additional dependencies (gems) your code depends on. To deploy this function code to Lambda, you use a deployment package. This package may either be a .zip file archive or a container image. For more information about using container images with Ruby, see Deploy Ruby Lambda functions with container images.

To create your deployment package as .zip file archive, you can use your command-line tool’s built-in .zip file archive utility, or any other .zip file utility such as 7zip. The examples shown in the following sections assume you’re using a command-line zip tool in a Linux or MacOS environment. To use the same commands in Windows, you can install the Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Note that Lambda uses POSIX file permissions, so you may need to set permissions for the deployment package folder before you create the .zip file archive.

The example commands in the following sections use the Bundler utility to add dependencies to your deployment package. To install bundler, run the following command.

gem install bundler

Dependencies in Ruby

For Lambda functions that use the Ruby runtime, a dependency can be any Ruby gem. When you deploy your function using a .zip archive, you can either add these dependencies to your .zip file with your function code or use a Lambda layer. A layer is a separate .zip file that can contain additional code and other content. To learn more about using Lambda layers, see Working with Lambda layers.

The Ruby runtime includes the Amazon SDK for Ruby. If your function uses the SDK, you don't need to bundle it with your code. However, to maintain full control of your dependencies, or to use a specific version of the SDK, you can add it to your function's deployment package. You can either include the SDK in your .zip file, or add it using a Lambda layer. Dependencies in your .zip file or in Lambda layers take precedence over versions included in the runtime. To find out which version of the SDK for Ruby is included in your runtime version, see Runtime-included SDK versions.

Under the Amazon shared responsibility model, you are responsible for the management of any dependencies in your functions' deployment packages. This includes applying updates and security patches. To update dependencies in your function's deployment package, first create a new .zip file and then upload it to Lambda. See Creating a .zip deployment packaged with dependencies and Creating and updating Ruby Lambda functions using .zip files for more information.

Creating a .zip deployment package with no dependencies

If your function code has no dependencies, your .zip file contains only the .rb file with your function’s handler code. Use your preferred zip utility to create a .zip file with your .rb file at the root. If the .rb file is not at the root of your .zip file, Lambda won’t be able to run your code.

To learn how to deploy your .zip file to create a new Lambda function or update an existing one, see Creating and updating Ruby Lambda functions using .zip files.

Creating a .zip deployment packaged with dependencies

If your function code depends on additional Ruby gems, you can either add these dependencies to your .zip file with your function code or use a Lambda layer. The instructions in this section show you how to include dependencies in your .zip deployment package. For instructions on how to include your dependencies in a layer, see Creating a Ruby layer for your dependencies.

Suppose your function code is saved in a file named lambda_function.rb in your project directory. The following example CLI commands create a .zip file named my_deployment_package.zip containing your function code and its dependencies.

To create the deployment package

  1. In your project directory, create a Gemfile to specify your dependencies in.

    bundle init

  2. Using your preferred text editor, edit the Gemfile to specify your function's dependencies. For example, to use the TZInfo gem, edit your Gemfile to look like the following. 

    source "https://rubygems.org"
gem "tzinfo"

  3. Run the following command to install the gems specified in your Gemfile in your project directory. This command sets vendor/bundle as the default path for gem installations.

    bundle config set --local path 'vendor/bundle' && bundle install

    You should see output similar to the following.

    Fetching gem metadata from https://rubygems.org/...........
Resolving dependencies...
Using bundler 2.4.13
Fetching tzinfo 2.0.6
Installing tzinfo 2.0.6
...
    Note

    To install gems globally again later, run the following command.

    bundle config set --local system 'true'

  4. Create a .zip file archive containing the lambda_function.rb file with your function's handler code and the dependencies you installed in the previous step.

    zip -r my_deployment_package.zip lambda_function.rb vendor

    You should see output similar to the following.

    adding: lambda_function.rb (deflated 37%)
  adding: vendor/ (stored 0%)
  adding: vendor/bundle/ (stored 0%)
  adding: vendor/bundle/ruby/ (stored 0%)
  adding: vendor/bundle/ruby/3.2.0/ (stored 0%)
  adding: vendor/bundle/ruby/3.2.0/build_info/ (stored 0%)
  adding: vendor/bundle/ruby/3.2.0/cache/ (stored 0%)
  adding: vendor/bundle/ruby/3.2.0/cache/aws-eventstream-1.0.1.gem (deflated 36%)
...

Creating a Ruby layer for your dependencies

The instructions in this section show you how to include your dependencies in a layer. For instructions on how to include your dependencies in your deployment package, see Creating a .zip deployment packaged with dependencies.

When you add a layer to a function, Lambda loads the layer content into the /opt directory of that execution environment. For each Lambda runtime, the PATH variable already includes specific folder paths within the /opt directory. To ensure that the PATH variable picks up your layer content, your layer .zip file should have its dependencies in the following folder paths:

  • ruby/gems/2.7.0 (GEM_PATH)

  • ruby/lib (RUBYLIB)

For example, your layer .zip file structure might look like the following:

json.zip
└ ruby/gems/2.7.0/
               | build_info
               | cache
               | doc
               | extensions
               | gems
               | └ json-2.1.0
               └ specifications
                 └ json-2.1.0.gemspec

In addition, Lambda automatically detects any libraries in the /opt/lib directory, and any binaries in the /opt/bin directory. To ensure that Lambda properly finds your layer content, you can also create a layer with the following structure:

custom-layer.zip
└ lib
    | lib_1
    | lib_2
└ bin
    | bin_1
    | bin_2

After you package your layer, see Creating and deleting layers in Lambda and Adding layers to functions to complete your layer setup.

Creating .zip deployment packages with native libraries

Many common Ruby gems such as nokogiri, nio4r, and mysql contain native extensions written in C. When you add libraries containing C code to your deployment package, you must build your package correctly to ensure that it’s compatible with the Lambda execution environment.

For production applications, we recommend building and deploying your code using the Amazon Serverless Application Model (Amazon SAM). In Amazon SAM use the sam build --use-container option to build your function inside a Lambda-like Docker container. To learn more about using Amazon SAM to deploy your function code, see Building applications in the Amazon SAM Developer Guide.

To create a .zip deployment package containing gems with native extensions without using Amazon SAM, you can alternatively use a container to bundle your dependencies in an environment that is the same as the Lambda Ruby runtime environment. To complete these steps, you must have Docker installed on your build machine. To learn more about installing Docker, see Install Docker Engine.

To create a .zip deployment package in a Docker container

  1. Create a folder on your local build machine to save your container in. Inside that folder, create a file named dockerfile and paste the following code into it.

    FROM public.ecr.aws/sam/build-ruby3.2:latest-x86_64
RUN gem update bundler 
CMD "/bin/bash"

  2. Inside the folder you created your dockerfile in, run the following command to create the Docker container.

    docker build -t awsruby32 .

  3. Navigate to the project directory containing the .rb file with your function's handler code and the Gemfile specifying your function's dependencies. From inside that directory, run the following command to start the Lambda Ruby container.

    Linux/MacOS
    docker run --rm -it -v $PWD:/var/task -w /var/task awsruby32
    Note

    In MacOS, you might see a warning informing you that the requested image's platform does not match the detected host platform. Ignore this warning.

    Windows PowerShell
    docker run --rm -it -v ${pwd}:var/task -w /var/task awsruby32

    When your container starts, you should see a bash prompt.

    bash-4.2#

  4. Configure the bundle utility to install the gems specified in your Gemfile in a local vendor/bundle directory and install your dependencies.

    bash-4.2# bundle config set --local path 'vendor/bundle' && bundle install

  5. Create the .zip deployment package with your function code and its dependencies. In this example, the file containing your function's handler code is named lambda_function.rb.

    bash-4.2# zip -r my_deployment_package.zip lambda_function.rb vendor

  6. Exit the container and return to your local project directory.

    bash-4.2# exit

    You can now use the .zip file deployment package to create or update your Lambda function. See Creating and updating Ruby Lambda functions using .zip files

Creating and updating Ruby Lambda functions using .zip files

Once you have created your .zip deployment package, you can use it to create a new Lambda function or update an existing one. You can deploy your .zip package using the Lambda console, the Amazon Command Line Interface, and the Lambda API. You can also create and update Lambda functions using Amazon Serverless Application Model (Amazon SAM) and Amazon CloudFormation.

The maximum size for a .zip deployment package for Lambda is 250 MB (unzipped). Note that this limit applies to the combined size of all the files you upload, including any Lambda layers.

The Lambda runtime needs permission to read the files in your deployment package. In Linux permissions octal notation, Lambda needs 644 permissions for non-executable files (rw-r--r--) and 755 permissions (rwxr-xr-x) for directories and executable files.

In Linux and MacOS, use the chmod command to change file permissions on files and directories in your deployment package. For example, to give an executable file the correct permissions, run the following command.

chmod 755 <filepath>

To change file permissions in Windows, see Set, View, Change, or Remove Permissions on an Object in the Microsoft Windows documentation.

Creating and updating functions with .zip files using the console

To create a new function, you must first create the function in the console, then upload your .zip archive. To update an existing function, open the page for your function, then follow the same procedure to add your updated .zip file.

If your .zip file is less than 50MB, you can create or update a function by uploading the file directly from your local machine. For .zip files greater than 50MB, you must upload your package to an Amazon S3 bucket first. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon Web Services Management Console, see Getting started with Amazon S3. To upload files using the Amazon CLI, see Move objects in the Amazon CLI User Guide.

Note

You cannot change the deployment package type (.zip or container image) for an existing function. For example, you cannot convert a container image function to use a .zip file archive. You must create a new function.

To create a new function (console)

  1. Open the Functions page of the Lambda console and choose Create Function.

  2. Choose Author from scratch.

  3. Under Basic information, do the following:

    1. For Function name, enter the name for your function.

    2. For Runtime, select the runtime you want to use.

    3. (Optional) For Architecture, choose the instruction set architecture for your function. The default architecture is x86_64. Ensure that the .zip deployment package for your function is compatible with the instruction set architecture you select.

  4. (Optional) Under Permissions, expand Change default execution role. You can create a new Execution role or use an existing one.

  5. Choose Create function. Lambda creates a basic 'Hello world' function using your chosen runtime.

To upload a .zip archive from your local machine (console)

  1. In the Functions page of the Lambda console, choose the function you want to upload the .zip file for.

  2. Select the Code tab.

  3. In the Code source pane, choose Upload from.

  4. Choose .zip file.

  5. To upload the .zip file, do the following:

    1. Select Upload, then select your .zip file in the file chooser.

    2. Choose Open.

    3. Choose Save.

To upload a .zip archive from an Amazon S3 bucket (console)

  1. In the Functions page of the Lambda console, choose the function you want to upload a new .zip file for.

  2. Select the Code tab.

  3. In the Code source pane, choose Upload from.

  4. Choose Amazon S3 location.

  5. Paste the Amazon S3 link URL of your .zip file and choose Save.

Updating .zip file functions using the console code editor

For some functions with .zip deployment packages, you can use the Lambda console’s built-in code editor to update your function code directly. To use this feature, your function must meet the following criteria:

  • Your function must use one of the interpreted language runtimes (Python, Node.js, or Ruby)

  • Your function’s deployment package must be smaller than 3MB.

Function code for functions with container image deployment packages cannot be edited directly in the console.

To update function code using the console code editor

  1. Open the Functions page of the Lambda console and select your function.

  2. Select the Code tab.

  3. In the Code source pane, select your source code file and edit it in the integrated code editor.

  4. When you have finished editing your code, choose Deploy to save your changes and update your function.

Creating and updating functions with .zip files using the Amazon CLI

You can can use the Amazon CLI to create a new function or to update an existing one using a .zip file. Use the create-function and update-function-code commands to deploy your .zip package. If your .zip file is smaller than 50MB, you can upload the .zip package from a file location on your local build machine. For larger files, you must upload your .zip package from an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see Move objects in the Amazon CLI User Guide.

Note

If you upload your .zip file from an Amazon S3 bucket using the Amazon CLI, the bucket must be located in the same Amazon Web Services Region as your function.

To create a new function using a .zip file with the Amazon CLI, you must specify the following:

  • The name of your function (--function-name)

  • Your function’s runtime (--runtime)

  • The Amazon Resource Name (ARN) of your function’s execution role (--role)

  • The name of the handler method in your function code (--handler)

You must also specify the location of your .zip file. If your .zip file is located in a folder on your local build machine, use the --zip-file option to specify the file path, as shown in the following example command. 

aws lambda create-function --function-name myFunction \
--runtime ruby3.2 --handler lambda_function.lambda_handler \
--role arn:aws-cn:iam::111122223333:role/service-role/my-lambda-role \
--zip-file fileb://myFunction.zip

To specify the location of .zip file in an Amazon S3 bucket, use the --code option as shown in the following example command. You only need to use the S3ObjectVersion parameter for versioned objects. 

aws lambda create-function --function-name myFunction \
--runtime ruby3.2 --handler lambda_function.lambda_handler \
--role arn:aws-cn:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=myBucketName,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion

To update an existing function using the CLI, you specify the the name of your function using the --function-name parameter. You must also specify the location of the .zip file you want to use to update your function code. If your .zip file is located in a folder on your local build machine, use the --zip-file option to specify the file path, as shown in the following example command. 

aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip

To specify the location of .zip file in an Amazon S3 bucket, use the --s3-bucket and --s3-key options as shown in the following example command. You only need to use the --s3-object-version parameter for versioned objects. 

aws lambda update-function-code --function-name myFunction \
--s3-bucket myBucketName --s3-key myFileName.zip --s3-object-version myObject Version

Creating and updating functions with .zip files using the Lambda API

To create and update functions using a .zip file archive, use the following API operations:

Creating and updating functions with .zip files using Amazon SAM

The Amazon Serverless Application Model (Amazon SAM) is a toolkit that helps streamline the process of building and running serverless applications on Amazon. You define the resources for your application in a YAML or JSON template and use the Amazon SAM command line interface (Amazon SAM CLI) to build, package, and deploy your applications. When you build a Lambda function from an Amazon SAM template, Amazon SAM automatically creates a .zip deployment package or container image with your function code and any dependencies you specify. To learn more about using Amazon SAM to build and deploy Lambda functions, see Getting started with Amazon SAM in the Amazon Serverless Application Model Developer Guide.

You can also use Amazon SAM to create a Lambda function using an existing .zip file archive. To create a Lambda function using Amazon SAM, you can save your .zip file in an Amazon S3 bucket or in a local folder on your build machine. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see Move objects in the Amazon CLI User Guide.

In your Amazon SAM template, the AWS::Serverless::Function resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:

  • PackageType - set to Zip

  • CodeUri - set to the function code's Amazon S3 URI, path to local folder, or FunctionCode object

  • Runtime - Set to your chosen runtime

With Amazon SAM, if your .zip file is larger than 50MB, you don’t need to upload it to an Amazon S3 bucket first. Amazon SAM can upload .zip packages up to the maximum allowed size of 250MB (unzipped) from a location on your local build machine.

To learn more about deploying functions using .zip file in Amazon SAM, see AWS::Serverless::Function in the Amazon SAM Developer Guide.

Creating and updating functions with .zip files using Amazon CloudFormation

You can use Amazon CloudFormation to create a Lambda function using a .zip file archive. To create a Lambda function from a .zip file, you must first upload your file to an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see Move objects in the Amazon CLI User Guide.

In your Amazon CloudFormation template, the AWS::Lambda::Function resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:

  • PackageType - Set to Zip

  • Code - Enter the Amazon S3 bucket name and the .zip file name in the S3Bucket and S3Key fields

  • Runtime - Set to your chosen runtime

The .zip file that Amazon CloudFormation generates cannot exceed 4MB. To learn more about deploying functions using .zip file in Amazon CloudFormation, see AWS::Lambda::Function in the Amazon CloudFormation User Guide.