The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
このページを編集

Funqy AWS Lambdaバインディング

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

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

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

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

とりうるステータスの完全なリストについては、 FAQの項目 を参照してください。

前提条件

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

  • ざっと 30 minutes

  • IDE

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

  • Apache Maven 3.9.8

  • 使用したい場合は、 Quarkus CLI

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

  • Funqy の基礎 を読む。短時間で読めます!

  • An Amazon AWS account

  • AWS CLI

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

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

AWS ビットのインストール

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

クイックスタート

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

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

コード

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の選択

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 へのデプロイ

Funqy 関数を AWS Lambda 上で動作させるには、いくつかのステップがあります。quickstart maven プロジェクトは、純粋な Java とネイティブデプロイメント用の関数を作成、更新、削除、呼び出すための便利なスクリプトを生成します。このスクリプトはビルド時に生成されます。

ビルドとデプロイ

maven を使用してプロジェクトをビルドします。

コマンドラインインタフェース
quarkus build
Maven
./mvnw install

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

実行ロールの作成

AWS CLIを使った Lambda のデプロイ方法については、 Getting Started Guide を参照してください。具体的には、 Execution Role を作成していることを確認してください。プロファイルやコンソールウィンドウで LAMBDA_ROLE_ARN 環境変数を定義する必要があります。また、ビルドで生成される manage.sh スクリプトを編集して、そこに直接ロール値を置くこともできます。

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

ビルド時に追加生成されるファイル

ビルドを実行すると、quarkus-funqy-amazon-lambda のエクステンションで生成されるいくつかの追加ファイルがあります。これらのファイルはビルドディレクトリーにあります: maven なら target/、gradleなら build/

  • function.zip - Lambda デプロイファイル

  • manage.sh - aws Lambda CLI の呼び出しのラッパー

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

  • sam.jvm.yaml - (オプション) SAM CLI やローカル・テスト用

  • sam.native.yaml - (オプション) SAM CLI やネイティブ・ローカル・テスト用(オプション)

関数を作成する

target/manage.sh スクリプトは、AWS Lambda Java ランタイムを使用して Funqy 関数を管理するためのものです。このスクリプトは利便性のためだけに提供されています。関数の作成、削除、更新のためにどのような aws コマンドが実行されるかを知りたい場合は、manage.sh スクリプトの出力を確認してください。

manage.sh は、 create , delete , update , invoke の 4 つの操作をサポートしています。

AWS CLIがインストールされていること、AWSアクセスキーのためのaws configureを実行していること、 LAMBDA_ROLE_ARN 環境変数を設定していること(上記の通り)を確認するには、 manage.sh をパラメーターなしで実行してください。それに応じて利用方法のガイドが表示されます。

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
ハンドラースイッチを変更しないでください。これは io.quarkus.funqy.lambda.FunqyStreamHandler::handleRequest にハードコードされている必要があります。この特別なハンドラーは、Funqy と AWS Lambda の統合ポイントです。

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

sh target/manage.sh delete

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

sh target/manage.sh delete create

関数の呼出

Function を呼び出すには invoke コマンドを使用します。

sh target/manage.sh invoke

サンプルの関数は、プロジェクトのルートディレクトリーにある json ファイルを指す --payload スイッチを介して渡された入力を受け取ります。

この関数は、以下のようにSAM CLI によってローカルで呼び出すこともできます。

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

ネイティブイメージのビルドで作業している場合は、テンプレート名をネイティブバージョンに置き換えてください。

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

functionの更新

お好きなように Java コードを更新することができます。リビルドしたら、 update コマンドを実行することで、関数を再配備できます。

sh target/manage.sh update

AWS Lambda カスタム (ネイティブ) ランタイムへのデプロイ

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.

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

コマンドラインインタフェース
quarkus build --native
Maven
./mvnw install -Dnative
Linux 以外のシステムでビルドしている場合は、Amazon Lambda が Linux バイナリーを必要とするため、Docker ビルドを使用するように Quarkus に指示するプロパティーも渡す必要があります。これを行うには、-Dnative-image.docker-build=true プロパティーをビルドに渡します。ただし、これには Docker をローカルにインストールする必要があります。
コマンドラインインタフェース
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

これらのコマンドのいずれかがコンパイルされ、ネイティブの実行可能ファイルが作成されます。また、zip ファイル target/function.zip も生成されます。このzipファイルには、 bootstrap にリネームされたネイティブ実行イメージが含まれています。これはAWS Lambda Custom (Provided) Runtimeの要件です。

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

sh target/manage.sh native create

上記のように、コマンドはスタックすることができます。唯一の要件は、ネイティブイメージビルドで作業したい場合、最初のパラメーターとして native を指定することです。このスクリプトは、ネイティブイメージ Function のデプロイメントを管理するために必要な残りの詳細を処理します。

関数を作成、削除、更新するためにどのようなawsコマンドが実行されるかを知りたい場合は、 manage.sh スクリプトの出力を調べてください。

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

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

POM を検証する

POM には quarkus-funqy-amazon-lambda エクステンションが依存関係として含まれている以外に特別なことは何もありません。このエクステンションは Lambda のデプロイに必要なものをすべて自動的に生成します。

統合テスト

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 を使用したテスト

AWS SAM CLI を利用すると、Lambda をシミュレートした環境でラップトップ上のローカルで関数を実行することができます。これには docker のインストールが必要です。これは、利用することを選択した場合のオプションのアプローチです。それ以外の場合は、Quarkus JUnitの統合でほとんどのニーズを満たすことができるはずです。

JVMとネイティブ実行モードの両方に対応したスターターテンプレートが生成されています。

以下の SAM CLI コマンドを実行して、適切な SAM template を渡して関数をローカルでテストします。 event パラメーターには任意の JSON ファイルを指定します。この場合はサンプル 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 の修正

ビルドによって生成された function.zip Lambda デプロイメントに追加のエントリーを加えなければならない場合があります。これを行うには、 src/main 内に zip.jvm または zip.native ディレクトリーを作成します。Pure Java を実行している場合は zip.jvm/ を、ネイティブディプロイメントを実行している場合は zip.native/ を作成します。

zipディレクトリーの下に作成したファイルやディレクトリーは、すべて function.zip に含まれます。

カスタム bootstrap スクリプト

ラムダがネイティブの Funqy デプロイメントを起動する際に、特定のシステムプロパティーやその他の引数を設定したい場合があるかもしれません。 zip.native 内に bootstrap スクリプトファイルを含めると、Funqy エクステンションは自動的に実行ファイルの名前を function.zip 内の runner に変更し、 bootstrap スクリプトの unix モードを実行ファイルに設定します。

カスタム bootstrap スクリプトを含む場合は、ネイティブ実行可能ファイルを runner として参照する必要があります。

このエクステンションは、サンプルのスクリプト target/bootstrap-example.sh を生成します。

関連コンテンツ