Skip to content

Initial Java RIC Implementation #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 1, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
4 changes: 4 additions & 0 deletions .github/workflows/maven-build-all.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,7 @@ jobs:
run: mvn -B package --file aws-lambda-java-events-sdk-transformer/pom.xml
- name: Build log4j2 with Maven
run: mvn -B package --file aws-lambda-java-log4j2/pom.xml
- name: Build serialization with Maven
run: mvn -B package --file aws-lambda-java-serialization/pom.xml
- name: Build runtime-interface-client with Maven
run: mvn -B package --file aws-lambda-java-runtime-interface-client/pom.xml
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,12 @@ hs_err_pid*

# Maven build
target/
dependency-reduced-pom.xml

# IDEA internal
*.iml
.idea
.gradle
.settings
.classpath
.project
35 changes: 27 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Check out the per-module release notes:
- [aws-lambda-java-events](aws-lambda-java-events/RELEASE.CHANGELOG.md)
- [aws-lambda-java-events-sdk-transformer](aws-lambda-java-events-sdk-transformer/RELEASE.CHANGELOG.md)
- [aws-lambda-java-log4j2](aws-lambda-java-log4j2/RELEASE.CHANGELOG.md)
- [aws-lambda-java-runtime-interface-client](aws-lambda-java-runtime-interface-client/RELEASE.CHANGELOG.md)
- [aws-lambda-java-serialization](aws-lambda-java-serialization/RELEASE.CHANGELOG.md)

# Where to get packages
___
Expand All @@ -34,45 +36,53 @@ ___
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-lambda-java-events</artifactId>
<version>3.4.0</version>
<version>3.6.0</version>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-lambda-java-events-sdk-transformer</artifactId>
<version>2.0.6</version>
<version>2.0.8</version>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-lambda-java-log4j2</artifactId>
<version>1.2.0</version>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-lambda-java-runtime-interface-client</artifactId>
<version>1.0.0</version>
</dependency>
```

[Gradle](https://gradle.org)

```groovy
'com.amazonaws:aws-lambda-java-core:1.2.1'
'com.amazonaws:aws-lambda-java-events:3.4.0'
'com.amazonaws:aws-lambda-java-events-sdk-transformer:2.0.6'
'com.amazonaws:aws-lambda-java-events:3.6.0'
'com.amazonaws:aws-lambda-java-events-sdk-transformer:2.0.8'
'com.amazonaws:aws-lambda-java-log4j2:1.2.0'
'com.amazonaws:aws-lambda-java-runtime-interface-client:1.0.0'
```

[Leiningen](http://leiningen.org) and [Boot](http://boot-clj.com)

```clojure
[com.amazonaws/aws-lambda-java-core "1.2.1"]
[com.amazonaws/aws-lambda-java-events "3.4.0"]
[com.amazonaws/aws-lambda-java-events-sdk-transformer "2.0.6"]
[com.amazonaws/aws-lambda-java-events "3.6.0"]
[com.amazonaws/aws-lambda-java-events-sdk-transformer "2.0.8"]
[com.amazonaws/aws-lambda-java-log4j2 "1.2.0"]
[com.amazonaws/aws-lambda-java-runtime-interface-client "1.0.0"]
```

[sbt](http://www.scala-sbt.org)

```scala
"com.amazonaws" % "aws-lambda-java-core" % "1.2.1"
"com.amazonaws" % "aws-lambda-java-events" % "3.4.0"
"com.amazonaws" % "aws-lambda-java-events-sdk-transformer" % "2.0.6"
"com.amazonaws" % "aws-lambda-java-events" % "3.6.0"
"com.amazonaws" % "aws-lambda-java-events-sdk-transformer" % "2.0.8"
"com.amazonaws" % "aws-lambda-java-log4j2" % "1.2.0"
"com.amazonaws" % "aws-lambda-java-runtime-interface-client" % "1.0.0"
```

# Using aws-lambda-java-core
Expand All @@ -95,3 +105,12 @@ See the [documentation](aws-lambda-java-events-sdk-transformer/README.md) for mo

This package defines the Lambda adapter to use with log4j version 2.
See the [README](aws-lambda-java-log4j2/README.md) or the [official documentation](http://docs.aws.amazon.com/lambda/latest/dg/java-logging.html#java-wt-logging-using-log4j) for information on how to use the adapter.

# Using aws-lambda-java-runtime-interface-client

This package defines the Lambda Java Runtime Interface Client package, a Lambda Runtime component that starts the runtime and interacts with the Runtime API - i.e., it calls the API for invocation events, starts the function code, calls the API to return the response.
The purpose of this package is to allow developers to deploy their applications in Lambda under the form of Container Images. See the [README](aws-lambda-java-runtime-interface-client/README.md) for information on how to use the library.

# Using aws-lambda-java-serialization

This package defines the Lambda serialization logic using in the aws-lambda-java-runtime-client library. It has no current standalone usage.
1 change: 1 addition & 0 deletions aws-lambda-java-runtime-interface-client/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
compile-flags.txt
44 changes: 44 additions & 0 deletions aws-lambda-java-runtime-interface-client/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
.PHONY: target
target:
$(info ${HELP_MESSAGE})
@exit 0

.PHONY: test
test:
mvn test

.PHONY: setup-codebuild-agent
setup-codebuild-agent:
docker build -t codebuild-agent - < test/integration/codebuild-local/Dockerfile.agent

.PHONY: test-smoke
test-smoke: setup-codebuild-agent
CODEBUILD_IMAGE_TAG=codebuild-agent test/integration/codebuild-local/test_one.sh test/integration/codebuild/buildspec.os.alpine.yml alpine 3.12 corretto11

.PHONY: test-integ
test-integ: setup-codebuild-agent
CODEBUILD_IMAGE_TAG=codebuild-agent test/integration/codebuild-local/test_all.sh test/integration/codebuild

# Command to run everytime you make changes to verify everything works
.PHONY: dev
dev: test

# Verifications to run before sending a pull request
.PHONY: pr
pr: test test-smoke

.PHONY: build
build:
mvn clean install

define HELP_MESSAGE

Usage: $ make [TARGETS]

TARGETS
build Builds the package.
dev Run all development tests after a change.
pr Perform all checks before submitting a Pull Request.
test Run the Unit tests.

endef
131 changes: 131 additions & 0 deletions aws-lambda-java-runtime-interface-client/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
## AWS Lambda Java Runtime Interface Client

We have open-sourced a set of software packages, Runtime Interface Clients (RIC), that implement the Lambda
[Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html), 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.

You can include this package in your preferred base image to make that base image Lambda compatible.

## Usage

### Creating a Docker Image for Lambda with the Runtime Interface Client

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:

* built for x86_64
* contains Java >= 8
* contains glibc >= 2.12 or musl

### Example

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!

Dockerfile
```dockerfile
# we'll use Amazon Linux 2 + Corretto 11 as our base
FROM amazoncorretto:11 as base

# configure the build environment
FROM base as build
RUN yum install -y maven
WORKDIR /src

# cache and copy dependencies
ADD pom.xml .
RUN mvn dependency:go-offline dependency:copy-dependencies

# compile the function
ADD . .
RUN mvn package

# copy the function artifact and dependencies onto a clean base
FROM base
WORKDIR /function

COPY --from=build /src/target/dependency/*.jar ./
COPY --from=build /src/target/*.jar ./

# configure the runtime startup as main
ENTRYPOINT [ "java", "-cp", "./*", "com.amazonaws.services.lambda.runtime.api.client.AWSLambda" ]
# pass the name of the function handler as an argument to the runtime
CMD [ "example.App::sayHello" ]
```
pom.xml
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>example</groupId>
<artifactId>hello-lambda</artifactId>
<packaging>jar</packaging>
<version>1.0-SNAPSHOT</version>
<name>hello-lambda</name>
<url>http://maven.apache.org</url>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-lambda-java-runtime-interface-client</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</project>
```
src/main/java/example/App.java
```java
package example;

public class App {
public static String sayHello() {
return "Hello λ!";
}
}
```

### 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](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.

*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.

```shell script
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
```
2) Run your Lambda image function using the docker run command.

```shell script
docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \
--entrypoint /aws-lambda/aws-lambda-rie \
myfunction:latest \
java -cp ./* com.amazonaws.services.lambda.runtime.api.client.AWSLambda example.App::sayHello
```

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

3) Post an event to the following endpoint using a curl command:

```shell script
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](https://docs.aws.amazon.com/lambda/latest/dg/images-test.html#images-test-alternative).*


## Security

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.

## License

This project is licensed under the Apache-2.0 License.

3 changes: 3 additions & 0 deletions aws-lambda-java-runtime-interface-client/RELEASE.CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### December 01, 2020
`1.0.0`:
- Initial release of AWS Lambda Java Runtime Interface Client
Loading