The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Funqy AWS Lambda Binding

The guide walks through quickstart code to show you how you can deploy Funqy functions to AWS Lambda.

Funqy functions can be deployed using the AWS Lambda Java Runtime, or you can build a native executable and use Lambda Custom Runtime if you want a smaller memory footprint and faster cold boot startup time.

这项技术被认为是preview。

preview(预览) 中,不保证向后兼容和在生态系统中的存在。具体的改进可能需要改变配置或API,并且正在计划变得 稳定 。欢迎在我们的 邮件列表 中提供反馈,或在我们的 GitHub问题列表 中提出问题。

For a full list of possible statuses, check our FAQ entry.

先决条件

完成这个指南,你需要:

  • 大概30 minutes

  • 编辑器

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9.8

  • 如果你愿意的话,还可以选择使用Quarkus CLI

  • 如果你想构建原生可执行程序,可以选择安装Mandrel或者GraalVM,并正确配置(或者使用Docker在容器中进行构建)

  • Read about Funqy Basics. This is a short read!

  • An Amazon AWS account

  • AWS CLI

  • AWS SAM CLI ,用于本地测试

Funqy AWS Lambdas build off of our Quarkus AWS Lambda support.

安装AWS位

安装所有AWS位可能是本指南中最困难的事情。请确保你遵循安装AWS CLI的所有步骤。

The Quickstart

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git ,或者下载 存档

The solution is located in the funqy-amazon-lambda-quickstart directory.

The Code

There is nothing special about the code and more importantly nothing AWS specific. Funqy functions can be deployed to many environments and AWS Lambda is one of them. The Java code is actually the same exact code as the funqy-http-quickstart.

Choose Your Function

Only one Funqy function can be exported per AWS Lambda deployment. If you have multiple functions defined within your project, then you will need to choose the function within your Quarkus application.properties:

quarkus.funqy.export=greet

You can see how the quickstart has done it within its own application.properties.

Alternatively, you can set the QUARKUS_FUNQY_EXPORT environment variable when you create the AWS Lambda using the aws cli.

部署到AWS Lambda Java Runtime

There are a few steps to get your Funqy function running on AWS Lambda. The quickstart maven project generates a helpful script to create, update, delete, and invoke your functions for pure Java and native deployments. This script is generated at build time.

构建和部署

Build the project using Maven:

CLI
quarkus build
Maven
./mvnw install

这将对你的代码进行编译和打包。

创建一个执行角色

查看使用AWS CLI部署lambda的 入门指南 。具体来说,确保你已经创建了一个 Execution Role 。你需要在你的配置文件或控制台窗口中定义一个 LAMBDA_ROLE_ARN 环境变量,或者,你可以编辑由构建生成的 manage.sh 脚本,并把角色值直接放在那里:

LAMBDA_ROLE_ARN="arn:aws:iam::1234567890:role/lambda-role"

构建额外生成的文件

After you run the build, there are a few extra files generated by the quarkus-funqy-amazon-lambda extension. These files are in the build directory: target/ for maven, build/ for gradle.

  • function.zip - lambda deployment file

  • manage.sh - wrapper around aws lambda cli calls

  • bootstrap-example.sh - 用于原生部署的bootstrap脚本示例

  • sam.jvm.yaml - (可选)用于sam cli和本地测试

  • sam.native.yaml - (可选),用于Sam cli和原生本地测试

创建函数

The target/manage.sh script is for managing your Funqy function using the AWS Lambda Java runtime. This script is provided only for your convenience. Examine the output of the manage.sh script if you want to learn what aws commands are executed to create, delete, and update your functions.

manage.sh 支持四种操作: createdeleteupdateinvoke

To verify your setup, that you have the AWS CLI installed, executed aws configure for the AWS access keys, and set up the LAMBDA_ROLE_ARN environment variable (as described above), please execute manage.sh without any parameters. A usage statement will be printed to guide you accordingly.

要查看 用法 声明,并验证AWS配置:

sh target/manage.sh

你可以使用以下命令 创建 你的函数:

sh target/manage.sh create

或者如果在这个shell中没有定义 LAMBDA_ROLE_ARN

LAMBDA_ROLE_ARN="arn:aws:iam::1234567890:role/lambda-role" sh target/manage.sh create
Do not change the handler switch. This must be hardcoded to io.quarkus.funqy.lambda.FunqyStreamHandler::handleRequest. This special handler is Funqy’s integration point with AWS Lambda.

如果在创建函数时有任何问题,你必须在重新运行 create 命令之前使用 delete 函数来删除它。

sh target/manage.sh delete

命令也可以是叠加的:

sh target/manage.sh delete create

Invoke the function

使用 invoke 命令来调用你的函数。

sh target/manage.sh invoke

The example function takes input passed in via the --payload switch which points to a json file in the root directory of the project.

The function can also be invoked locally with the SAM CLI like this:

sam local invoke --template target/sam.jvm.yaml --event payload.json

如果你正在使用原生镜像构建,只需将模板名称替换为原生版本:

sam local invoke --template target/sam.native.yaml --event payload.json

Update the function

You can update the Java code as you see fit. Once you’ve rebuilt, you can redeploy your function by executing the update command.

sh target/manage.sh update

部署到AWS Lambda Custom (native) Runtime

If you want a lower memory footprint and faster initialization times for your Funqy function, you can compile your Java code to a native executable. Just make sure to rebuild your project with the -Dnative switch.

For Linux hosts execute:

CLI
quarkus build --native
Maven
./mvnw install -Dnative
If you are building on a non-Linux system, you will need to also pass in a property instructing Quarkus to use a Docker build as Amazon Lambda requires Linux binaries. You can do this by passing this property to your build: -Dnative-image.docker-build=true. This requires you to have Docker installed locally, however.
CLI
quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.
Maven
./mvnw install -Dnative -DskipTests -Dquarkus.native.container-build=true

Either of these commands will compile and create a native executable. It also generates a zip file target/function.zip. This zip file contains your native executable image renamed to bootstrap. This is a requirement of the AWS Lambda Custom (Provided) Runtime.

这里的说明与上面的完全一样,但有一个变化:你需要将 native 作为第一个参数添加到 manage.sh 脚本中:

sh target/manage.sh native create

如上所述,命令可以叠加。如果你想使用原生镜像构建,唯一的要求是 native 是第一个参数。该脚本将处理管理你原生镜像功能部署所需的其余细节。

Examine the output of the manage.sh script if you want to learn what aws commands are executed to create, delete, and update your functions.

对于原生的创建命令,需要注意的一点是, aws lambda create-function 调用必须设置一个特定的环境变量:

--environment 'Variables={DISABLE_SIGNAL_HANDLERS=true}'

检查POM

There is nothing special about the POM other than the inclusion of the quarkus-funqy-amazon-lambda extension as a dependency. The extension automatically generates everything you might need for your lambda deployment.

Integration Testing

Funqy AWS Lambda support leverages the Quarkus AWS Lambda test framework so that you can unit tests your Funqy functions. This is true for both JVM and native modes. This test framework provides similar functionality to the SAM CLI, without the overhead of Docker.

If you open up FunqyTest.java you’ll see that the test replicates the AWS execution environment.

package org.acme.funqy;

import io.quarkus.amazon.lambda.test.LambdaClient;
import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;

@QuarkusTest
public class FunqyTest {
    @Test
    public void testSimpleLambdaSuccess() throws Exception {
        Friend friend = new Friend("Bill");
        Greeting out = LambdaClient.invoke(Greeting.class, friend);
        Assertions.assertEquals("Hello Bill", out.getMessage());
    }
}

使用SAM CLI进行测试

The AWS SAM CLI allows you to run your functions locally on your laptop in a simulated Lambda environment. This requires docker to be installed. This is an optional approach should you choose to take advantage of it. Otherwise, the Quarkus JUnit integration should be sufficient for most of your needs.

已经为JVM和原生执行模式生成了一个启动模板。

Run the following SAM CLI command to locally test your function, passing the appropriate SAM template. The event parameter takes any JSON file, in this case the sample payload.json.

sam local invoke --template target/sam.jvm.yaml --event payload.json

本地镜像也可以使用 sam.native.yaml 模板进行本地测试:

sam local invoke --template target/sam.native.yaml --event payload.json

修改 function.zip

There are times when you may have to add additional entries to the function.zip lambda deployment that is generated by the build. To do this, create a zip.jvm or zip.native directory within src/main. Create zip.jvm/ if you are doing a pure Java. zip.native/ if you are doing a native deployment.

你在zip目录下创建的任何文件和目录都将包括在 function.zip

自定义 bootstrap 脚本

There are times you may want to set specific system properties or other arguments when lambda invokes your native Funqy deployment. If you include a bootstrap script file within zip.native, the Funqy extension will automatically rename the executable to runner within function.zip and set the unix mode of the bootstrap script to executable.

如果你包含一个自定义的 bootstrap 脚本,那么本地可执行文件必须被引用为 runner

扩展会在 target/bootstrap-example.sh 中生成了一个示例脚本。

Related content