Funqy AWS Lambdaバインディング
プレビューこのガイドでは、Funqy関数を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.6
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、 適切に設定していること
-
Funqy の基礎 を読んで下さい。 これは短い読み物です！
-
AWS SAM CLI 、ローカルテスト用
| Funqy AWS Lambdaは、 QuarkusのAWS Lambdaサポート をベースに構築されています。 |
AWS ビットのインストール
AWSのすべてのツールをインストールすることは、おそらくこのガイドでは最も難しいことです。AWS CLIをインストールするためのすべての手順に従っていることを確認してください。
クイックスタート
Gitレポジトリをクローンするか git clone -b 3.8 https://github.com/quarkusio/quarkus-quickstarts.git 、 アーカイブ をダウンロードします。
ソリューションは funqy-amazon-lambda-quickstart ディレクトリ にあります。
コード
コードに特別なものはなく、さらに重要なのはAWSに特化したものはないということです。Funqy関数は多くの環境にデプロイでき、AWS Lambdaもその1つです。Javaコードは実は funqy-http-quickstart と全く同じコードです。
functionの選択
1つのAWS Lambdaデプロイメントにつき、Funqy関数を1つだけエクスポートできます。プロジェクト内に複数の関数が定義されている場合は、Quarkus application.properties で関数を選択する必要があります：
quarkus.funqy.export=greetクイックスタートが自身の application.properties 内でどのようにそれを行っているか見ることができます。
あるいは、 aws cli を使って AWS Lambda を作成する際に、 QUARKUS_FUNQY_EXPORT 環境変数を設定することもできます。
AWS Lambda Java Runtime へのデプロイ
Funqy 関数を AWS Lambda 上で動作させるには、いくつかのステップがあります。quickstart maven プロジェクトは、純粋な Java とネイティブデプロイメント用の関数を作成、更新、削除、呼び出すための便利なスクリプトを生成します。このスクリプトはビルド時に生成されます。
ビルドとデプロイ
maven を使用してプロジェクトをビルドします。
quarkus build./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.jsonfunctionの更新
お好きなように Java コードを更新することができます。リビルドしたら、 update コマンドを実行することで、関数を再配備できます。
sh target/manage.sh updateAWS Lambda カスタム (ネイティブ) ランタイムへのデプロイ
Funqy関数のメモリフットプリントを小さくし、初期化時間を短縮したい場合は、Javaコードをネイティブ実行可能ファイルにコンパイルすることができます。 -Dnative スイッチを使ってプロジェクトを再ビルドしてください。
Linuxホストの場合は以下を実行します。
quarkus build --native./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../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のサポートは、Quarkus AWS Lambdaテストフレームワークを活用しており、Funqy関数をユニットテストできます。 これはJVMモードとネイティブモードの両方に当てはまります。このテストフレームワークは、Dockerのオーバーヘッドなしに、SAM CLIと同様の機能を提供します。
FunqyTest.java を開くと、テストがAWSの実行環境を複製していることがわかります。
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.jsonfunction.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 を生成します。
