Announcing Ruby build support for AWS SAM CLI

At AWS re:Invent 2018, we announced Ruby support in AWS Lambda. The Ruby runtime in Lambda has built-in logic to make packaging your dependencies simple.

AWS SAM CLI is a CLI tool currently in beta for local development and testing of serverless applications. It encapsulates several build, test, and deployment patterns for Lambda functions. Today, we’ve launched support for Ruby builds in the SAM CLI tool.

How to build AWS Lambda functions with dependencies in Ruby

In most cases, vendoring your dependencies for deployment to Lambda is simple. Using Ruby 2.5, you can run bundle install to create a Gemfile.lock file if you don’t have one, then vendor and zip your dependencies.

bundle install --deployment
zip -r source.zip *

Because the Ruby runtime looks in /var/task/vendor/bundle/ruby/2.5.0 for dependencies, you don’t need to do any additional configuration for Lambda to automatically recognize your dependencies. However, there are a couple of caveats to building Ruby functions to keep in mind:

• You must use Ruby 2.5 to build your dependencies. Dependencies that are vendored for deployment are sensitive to the Ruby minor version used when you run the bundle command.
• Dependency installations that include native extensions are platform sensitive. You must build in an environment compatible with Amazon Linux for these dependencies to work on Lambda.

Using AWS SAM CLI to simplify Ruby function builds

With the AWS SAM CLI Ruby build support, you can address both of these build questions. Let’s create a SAM CLI project to see how it works.

sam init --runtime ruby2.5 --name hello-ruby-sam
cd hello-ruby-sam

This provides an example method using Ruby on Lambda. With the Ruby build support in SAM CLI, we can now reduce the build process to a single command.

sam build

If we include dependencies with native extensions, such as nokogiri, we want to make sure we’re building on an Amazon Linux-compatible image. With SAM CLI, you can do that in a single command as well.

sam build --use-container

We’re now ready to deploy our function to Lambda.

Exploring SAM CLI

First, let’s test our function locally. The following command stands up our function on a local endpoint, simulating Amazon API Gateway.

sam local start-api

You can also run sam local invoke to test out singular calls with event JSON files. After testing, we can use SAM CLI to help package and deploy our function to Lambda.

sam package \
    --template-file template.yaml \
    --output-template-file packaged.yaml \
    --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME

sam deploy \
    --template-file packaged.yaml \
    --stack-name sam-app \
    --capabilities CAPABILITY_IAM

aws cloudformation describe-stacks \
    --stack-name sam-app --query 'Stacks[].Outputs'

The final command gives you an API Gateway endpoint that you can navigate to so that you can see your function in action!

Conclusion

One of the goals of the AWS SAM CLI project is to standardize on several best practices around building, testing, and deploying AWS Lambda functions. We hope this launch makes it even easier to develop Ruby functions for Lambda.

One thing to note, SAM CLI is an open-source project. Customers have added functionality for .NET Core and Node.js into the SAM CLI. We welcome your feedback and contributions on GitHub to AWS SAM CLI and AWS Lambda Builders!