GitHub - aws/aws-lambda-ruby-runtime-interface-client (original) (raw)

AWS Lambda Ruby Runtime Interface Client

We have open-sourced a set of software packages, Runtime Interface Clients (RIC), that implements the LambdaRuntime API, allowing you to seamlessly extend your preferred base images to be Lambda compatible. The Lambda Runtime Interface Client is a lightweight interface that allows your runtime to receive requests from and send requests to the Lambda service.

The Lambda Ruby Runtime Interface Client is vended through rubygems. You can include this package in your preferred base image to make that base image Lambda compatible.

Requirements

The Ruby Runtime Interface Client package currently supports ruby 3.0 and above.

Usage

Creating a Docker Image for Lambda with the Runtime Interface Client

First step is to choose the base image to be used. The supported Linux OS distributions are:

In order to install the Runtime Interface Client, either add this line to your application's Gemfile:

And then execute:

Or install it manually as:

$ gem install aws_lambda_ric

The next step would be to copy your Lambda function code into the image's working directory. You will need to set the ENTRYPOINT property of the Docker image to invoke the Runtime Interface Client and then set the CMD argument to specify the desired handler.

Example Dockerfile:

FROM amazonlinux:latest

Define custom function directory

ARG FUNCTION_DIR="/function"

Install ruby

RUN dnf install -y ruby3.2 make

Install bundler

RUN gem install bundler

Install the Runtime Interface Client

RUN gem install aws_lambda_ric

If you want to install Runtime Interface Client From Source, you can uncomment the following ADD and RUN layers.

Do not forget to comment/remove the above RUN gem install aws_lambda_ric command.

ADD https://github.com/aws/aws-lambda-ruby-runtime-interface-client.git /aws_lambda_ric

RUN cd /aws_lambda_ric && \

make init && \

make build && \

gem install --local /aws_lambda_ric/pkg/aws_lambda_ric-3.0.0.gem && \

rm -rf /aws_lambda_ric

Copy function code

RUN mkdir -p ${FUNCTION_DIR} COPY app.rb ${FUNCTION_DIR}

WORKDIR ${FUNCTION_DIR}

ENTRYPOINT ["/usr/local/bin/aws_lambda_ric"] CMD ["app.App::Handler.process"]

Note that the ENTRYPOINT may differ based on the base image used. You can find the correct path by running an interactive shell in the container and checking the installed location of the gem.

docker run -it --rm amazonlinux:latest bash yum install -y which ruby gem install aws_lambda_ric which aws_lambda_ric

Finally, create a Ruby handler. This is an example app.rb:

module App class Handler def self.process(event:, context:) "Hello World!" end end end

Local Testing

To make it easy to locally test Lambda functions packaged as container images we open-sourced a lightweight web-server, Lambda Runtime Interface Emulator (RIE), which allows your function packaged as a container image to accept HTTP requests. You can install the AWS Lambda Runtime Interface Emulator on your local machine to test your function. Thenm when you run the image function, you set the entrypoint to be the emulator.

To install the emulator and test your Lambda function

  1. From your project directory, run the following command to download the RIE from GitHub and install it on your local machine.

mkdir -p ~/.aws-lambda-rie &&
curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie &&
chmod +x ~/.aws-lambda-rie/aws-lambda-rie

  1. Run your Lambda image function using the docker run command.

docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080
--entrypoint /aws-lambda/aws-lambda-rie
myfunction:latest
/usr/local/bin/aws_lambda_ric app.App::Handler.process

This runs the image as a container and starts up an endpoint locally at http://localhost:9000/2015-03-31/functions/function/invocations.

  1. Post an event to the following endpoint using a curl command:

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

This command invokes the function running in the container image and returns a response.

Alternately, you can also include RIE as a part of your base image. See the AWS documentation on how to Build RIE into your base image.

Development

Building the package

Clone this repository and run:

Running tests

Make sure the project is built:

Then,

Troubleshooting

While running integration tests, you might encounter the Docker Hub rate limit error with the following body:

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

To fix the above issue, consider authenticating to a Docker Hub account by setting the Docker Hub credentials as below CodeBuild environment variables.

DOCKERHUB_USERNAME= DOCKERHUB_PASSWORD=

Recommended way is to set the Docker Hub credentials in CodeBuild job by retrieving them from AWS Secrets Manager.

Security

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

License

This project is licensed under the Apache-2.0 License.