|
| 1 | +## AWS Lambda Java Runtime Interface Client |
| 2 | + |
| 3 | +We have open-sourced a set of software packages, Runtime Interface Clients (RIC), that implement the Lambda |
| 4 | + [Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html), allowing you to seamlessly extend your preferred |
| 5 | + base images to be Lambda compatible. |
| 6 | +The Lambda Runtime Interface Client is a lightweight interface that allows your runtime to receive requests from and send requests to the Lambda service. |
| 7 | + |
| 8 | +You can include this package in your preferred base image to make that base image Lambda compatible. |
| 9 | + |
| 10 | +## Usage |
| 11 | + |
| 12 | +### Creating a Docker Image for Lambda with the Runtime Interface Client |
| 13 | + |
| 14 | +Choose a preferred base image. The Runtime Interface Client is tested on Amazon Linux, Alpine, Ubuntu, Debian, and CentOS. The requirements are that the image is: |
| 15 | + |
| 16 | +* built for x86_64 |
| 17 | +* contains Java >= 8 |
| 18 | +* contains glibc >= 2.12 or musl |
| 19 | + |
| 20 | +### Example |
| 21 | + |
| 22 | +The Runtime Interface Client library can be installed into the image separate from the function code, but the simplest approach to keeping the Dockerfile simple is to include the library as a part of the function's dependencies! |
| 23 | + |
| 24 | +Dockerfile |
| 25 | +```dockerfile |
| 26 | +# we'll use Amazon Linux 2 + Corretto 11 as our base |
| 27 | +FROM amazoncorretto:11 as base |
| 28 | + |
| 29 | +# configure the build environment |
| 30 | +FROM base as build |
| 31 | +RUN yum install -y maven |
| 32 | +WORKDIR /src |
| 33 | + |
| 34 | +# cache and copy dependencies |
| 35 | +ADD pom.xml . |
| 36 | +RUN mvn dependency:go-offline dependency:copy-dependencies |
| 37 | + |
| 38 | +# compile the function |
| 39 | +ADD . . |
| 40 | +RUN mvn package |
| 41 | + |
| 42 | +# copy the function artifact and dependencies onto a clean base |
| 43 | +FROM base |
| 44 | +WORKDIR /function |
| 45 | + |
| 46 | +COPY --from=build /src/target/dependency/*.jar ./ |
| 47 | +COPY --from=build /src/target/*.jar ./ |
| 48 | + |
| 49 | +# configure the runtime startup as main |
| 50 | +ENTRYPOINT [ "java", "-cp", "./*", "com.amazonaws.services.lambda.runtime.api.client.AWSLambda" ] |
| 51 | +# pass the name of the function handler as an argument to the runtime |
| 52 | +CMD [ "example.App::sayHello" ] |
| 53 | +``` |
| 54 | +pom.xml |
| 55 | +```xml |
| 56 | +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 57 | + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> |
| 58 | + <modelVersion>4.0.0</modelVersion> |
| 59 | + <groupId>example</groupId> |
| 60 | + <artifactId>hello-lambda</artifactId> |
| 61 | + <packaging>jar</packaging> |
| 62 | + <version>1.0-SNAPSHOT</version> |
| 63 | + <name>hello-lambda</name> |
| 64 | + <url>http://maven.apache.org</url> |
| 65 | + <properties> |
| 66 | + <maven.compiler.source>1.8</maven.compiler.source> |
| 67 | + <maven.compiler.target>1.8</maven.compiler.target> |
| 68 | + </properties> |
| 69 | + <dependencies> |
| 70 | + <dependency> |
| 71 | + <groupId>com.amazonaws</groupId> |
| 72 | + <artifactId>aws-lambda-java-runtime-interface-client</artifactId> |
| 73 | + <version>1.0.0</version> |
| 74 | + </dependency> |
| 75 | + </dependencies> |
| 76 | +</project> |
| 77 | +``` |
| 78 | +src/main/java/example/App.java |
| 79 | +```java |
| 80 | +package example; |
| 81 | + |
| 82 | +public class App { |
| 83 | + public static String sayHello() { |
| 84 | + return "Hello λ!"; |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +### Local Testing |
| 90 | + |
| 91 | +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](https://github.com/aws/aws-lambda-runtime-interface-emulator) on your local machine to test your function. Then when you run the image function, you set the entrypoint to be the emulator. |
| 92 | + |
| 93 | +*To install the emulator and test your Lambda function* |
| 94 | + |
| 95 | +1) From your project directory, run the following command to download the RIE from GitHub and install it on your local machine. |
| 96 | + |
| 97 | +```shell script |
| 98 | +mkdir -p ~/.aws-lambda-rie && \ |
| 99 | + curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie && \ |
| 100 | + chmod +x ~/.aws-lambda-rie/aws-lambda-rie |
| 101 | +``` |
| 102 | +2) Run your Lambda image function using the docker run command. |
| 103 | + |
| 104 | +```shell script |
| 105 | +docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \ |
| 106 | + --entrypoint /aws-lambda/aws-lambda-rie \ |
| 107 | + myfunction:latest \ |
| 108 | + java -cp ./* com.amazonaws.services.lambda.runtime.api.client.AWSLambda example.App::sayHello |
| 109 | +``` |
| 110 | + |
| 111 | +This runs the image as a container and starts up an endpoint locally at `http://localhost:9000/2015-03-31/functions/function/invocations`. |
| 112 | + |
| 113 | +3) Post an event to the following endpoint using a curl command: |
| 114 | + |
| 115 | +```shell script |
| 116 | +curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'. |
| 117 | +``` |
| 118 | + |
| 119 | +This command invokes the function running in the container image and returns a response. |
| 120 | + |
| 121 | +*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](https://docs.aws.amazon.com/lambda/latest/dg/images-test.html#images-test-alternative).* |
| 122 | + |
| 123 | + |
| 124 | +## Security |
| 125 | + |
| 126 | +If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. |
| 127 | + |
| 128 | +## License |
| 129 | + |
| 130 | +This project is licensed under the Apache-2.0 License. |
| 131 | + |
0 commit comments