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

Funqy Amazon Lambda バインディング

このガイドでは、Funqy関数をAmazon Lambdaにデプロイする方法をクイックスタートコードで説明しています。

Funqy関数はAWS Lambda Java Runtimeを使ってデプロイすることもできますし、より少ないメモリーフットプリントとより高速なコールドブート起動時間が必要な場合は、ネイティブ実行可能ファイルをビルドしてLambda Custom Runtimeを使うこともできます。

この技術は、previewと考えられています。

preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックは メーリングリストGitHub の課題管理 で受け付けています。

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

前提条件

このガイドを完成させるには、以下が必要です:

  • ざっと 30 minutes

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

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

  • Amazon AWSのアカウント

  • AWS CLI

  • AWS SAM CLI 、ローカルテスト用

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

AWS bitsのインストール

AWSのすべてのツールをインストールすることは、おそらくこのガイドでは最も難しいことです。AWS CLIをインストールするためのすべての手順に従っていることを確認してください。

クイックスタート

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは funqy-amazon-lambda-quickstart ディレクトリ にあります。

コード

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.

functionの選択

Amazon LambdaデプロイメントごとにエクスポートできるFunqy関数は1つだけです。プロジェクト内で複数の関数を定義している場合は、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 Amazon Lambda using the aws cli.

AWS Lambda Javaランタイムへのデプロイ

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 clean package

これでコードがコンパイルされ、パッケージ化されます。

実行ロールの作成

AWS CLIを使った Lambda のデプロイ方法については、 Getting Started Guide を参照してください。具体的には、 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デプロイメントファイル

  • manage.sh - awsのlambda cliの呼び出しのラッパー

  • bootstrap-example.sh - ネイティブデプロイメント用のブートストラップスクリプトの例

  • 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 は、 create , delete , update , invoke の 4 つの操作をサポートしています。

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.

usage を参照したり、AWS の設定を検証するためには次のようにします。

sh target/manage.sh

次のコマンドを使って、 Function を create します。

sh target/manage.sh create

または、このシェルで既に 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.

Function の作成に問題がある場合は、 delete で Function を削除してから create コマンドを再実行する必要があります。

sh target/manage.sh delete

コマンドはスタックすることもできます。

sh target/manage.sh delete create

関数の呼出

関数を呼び出すには 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

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

Deploy to 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 -Pnative switch.

Linuxホストの場合は以下を実行します。

CLI
quarkus build --native
Maven
./mvnw package -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 package -Dnative -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.

ここでの説明は上記と全く同じですが、1つ変更点があります: manage.sh スクリプトの最初のパラメーターとして native を追加する必要があります。

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.

ネイティブ用のcreateコマンドについて注意すべき点は、 aws lambda create-function 呼び出しで特定の環境変数を設定しなければならないということです。

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

Examine the 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.

統合テスト

Funqy Amazon 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 を生成します。