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.15
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、 適切に設定していること
-
Funqy の基礎 を読んでください。短時間で読めます!
-
AWS SAM CLI (ローカルテスト用)
| Funqy AWS Lambda は、Quarkus AWS Lambda サポート を基盤としています。 |
AWS ツールのインストール
すべての AWS ツールをインストールすることが、おそらくこのガイドで最も難しい点です。AWS CLI のインストールに関するすべての手順に従っていることを確認してください。
クイックスタート
Git リポジトリをクローン: git clone https://github.com/quarkusio/quarkus-quickstarts.git 、または アーカイブ をダウンロードしてください。
ソリューションは funqy-amazon-lambda-quickstart ディレクトリー にあります。
コード
このコードに特別な点はなく、さらに重要なこととして AWS に固有の点もありません。Funqy 関数は多くの環境にデプロイでき、AWS Lambda もその一つです。この Java コードは、実際には funqy-http-quickstart と全く同じコードです。
関数の選択
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 で実行するにはいくつかの手順があります。クイックスタートの 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次のコマンドを使用して、関数を 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 の統合ポイントです。
|
関数の作成に問題がある場合は、create コマンドを再実行する前に、delete コマンドで削除する必要があります。
sh target/manage.sh deleteコマンドはスタックすることもできます:
sh target/manage.sh delete create関数を呼び出す
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 ディレクトリーを作成します。純粋な Java を使用する場合は zip.jvm/ を作成します。ネイティブデプロイメントを行う場合は zip.native/ を作成します。
zip ディレクトリーの下に作成したファイルやディレクトリーは、すべて function.zip に含まれます。
カスタム bootstrap スクリプト
Lambda がネイティブ Funqy デプロイメントを呼び出す際に、特定のシステムプロパティーやその他の引数を設定したい場合があります。zip.native 内に bootstrap スクリプトファイルを含めると、Funqy エクステンションは自動的に実行可能ファイルを function.zip 内で runner に名前変更し、bootstrap スクリプトの Unix モードを実行可能に設定します。
カスタム bootstrap スクリプトを含む場合は、ネイティブ実行可能ファイルを runner として参照する必要があります。
|
このエクステンションは、サンプルのスクリプト target/bootstrap-example.sh を生成します。
