Lambda 拡張機能 API - AWS Lambda

Lambda 拡張機能 API

拡張機能の作成には、Lambda 拡張機能 API を使用します。拡張機能では、モニタリング、セキュリティ、その他のツールを Lambda 実行環境 と統合するための新しい方法を利用できます。詳細については、AWS コンピューティングブログの「 AWS Lambda 拡張機能の紹介 」を参照してください。

拡張機能 API は、既存のランタイム API に基づいて構築され、Lambda から呼び出しイベントを受信するカスタムランタイム用の HTTP API を提供します。拡張機能の作成者は、拡張機能 API を使用して、関数および実行環境のライフサイクルイベントに登録できます。これらのイベントに応じて、新しいプロセスを開始したり、ロジックを実行したりできます。

Lambda は、内部拡張機能と外部拡張機能をサポートしています。内部拡張機能を使用すると、ランタイム環境を設定したり、ランタイムプロセスの起動を変更したりできます。内部拡張機能は、言語固有の 環境変数とラッパースクリプト を使用し、ランタイムプロセス内で起動およびシャットダウンします。内部拡張機能は、ランタイムプロセス内で個別のスレッドとして実行され、それらを開始および停止します。

外部拡張機能は、実行環境で独立したプロセスとして実行され、関数呼び出しが完全に処理された後も引き続き実行されます。外部拡張機能は Shutdown イベントに登録する必要があります。これにより、拡張機能はシャットダウンされます。外部拡張機能はプロセスとして実行されるため、関数とは異なる言語で書くことができます。

次の Lambda ランタイムは、外部拡張機能をサポートしています。

  • .NET Core 3.1 (C#/PowerShell) (dotnetcore3.1)

  • カスタムランタイム (provided)

  • Amazon Linux 2 (provided.al2)のカスタムランタイム

  • Java 11 (Corretto) (java11)

  • Java 8 (Corretto) (java8.al2)

  • Node.js 14.x (nodejs14.x)

  • Node.js 12.x (nodejs12.x)

  • Node.js 10.x (nodejs10.x)

  • Python 3.8 (python3.8)

  • Python 3.7 (python3.7)

  • Ruby 2.7 (ruby2.7)

  • Ruby 2.5 (ruby2.5)

コンパイルされた言語を使用して外部拡張機能を実装することをお勧めします。この場合、拡張機能は、サポートされているすべてのランタイムと互換性のある自己完結型のバイナリです。コンパイルされていない言語を使用する場合は、必ず互換性のあるランタイムを拡張機能に含めてください。

拡張機能を Lambda レイヤーとして共有し、組織内または Lambda デベロッパーのコミュニティ全体で使用できるようにします。関数のデベロッパーは、レイヤーを介して拡張機能を検索、管理、インストールできます。

Lambda コンソール、(AWS Command Line Interface) AWS CLI、または Infrastructure as Code (IaC) サービスおよびツール (AWS CloudFormation、AWS サーバーレスアプリケーションモデル (AWS SAM)、Terraform など) を使用して、拡張機能をインストールおよび管理できます。

注記

拡張機能とラッパースクリプトの例については、AWS サンプル GitHub リポジトリの AWS Lambda 拡張 を参照してください。

Lambda 実行環境のライフサイクル

実行環境のライフサイクルには、次のフェーズが含まれています。

  • Init: このフェーズでは、Lambda は、設定されたリソースでの実行環境の作成またはフリーズ解除、関数とすべてのレイヤー用のコードのダウンロード、拡張機能の初期化、ランタイムの初期化を行い、関数の初期化コード (メインハンドラー外のコード) を実行します。Init フェーズは、最初の呼び出し中に発生するか、プロビジョニングされた同時実行を有効にしている場合は、関数呼び出しの前に発生します。

    Init フェーズは、Extension initRuntime initFunction init の 3 つのサブフェーズに分割されます。これらのサブフェーズにより、関数コードが実行される前に、すべての拡張機能とランタイムでセットアップタスクが完了されます。

  • Invoke: このフェーズでは、Lambda は関数ハンドラーを呼び出します。関数の実行が完了すると、Lambda は別の関数呼び出しを処理する準備をします。

  • Shutdown: このフェーズは、Lambda 関数が一定期間呼び出しを受け取らなかった場合に、トリガーされます。Shutdown フェーズでは、Lambda はランタイムを終了し、拡張機能に警告してクリーンに停止させ、その後に環境を削除します。Lambda は、各拡張機能に Shutdown イベントを送信し、環境が間もなくシャットダウンされることを拡張機能に通知します。

各フェーズは、Lambda サービスからランタイム、および登録されたすべての拡張機能へのイベントから始まります。ランタイムと各拡張機能は、Next API リクエストを送信することによって完了を示します。Lambda は、各プロセスが完了して保留中のイベントがなくなると、実行環境をフリーズします。

初期化フェーズ

Extension init フェーズでは、イベントを受信するために、各拡張機能を Lambda に登録する必要があります。Lambda は、拡張機能の完全なファイル名を使用して、拡張機能がブートストラップシーケンスを完了したことを検証します。したがって、各 Register API コールには、拡張機能の完全なファイル名を持つ Lambda-Extension-Name ヘッダーを含める必要があります。

1 つの関数に最大 10 個の拡張機能を登録できます。この制限は、Register API コールを通じて適用されます。

各拡張機能が登録されると、 Lambda がフェーズ Runtime init を開始します。ランタイムプロセスは functionInit を呼び出してフェーズ Function init を開始します。

Init フェーズはランタイム後に完了します。登録された各拡張機能は、Next API リクエストを送信することで完了を示します。

注記

拡張機能は、Init フェーズの任意の時点で初期化を完了できます。

呼び出しフェーズ

Next API リクエストに応答して Lambda 関数が呼び出されると、Lambda は、ランタイムおよび Invoke イベントに登録されている各拡張機能に Invoke イベントを送信します。

呼び出し中、外部拡張機能は関数と並行して実行されます。また、関数が完了した後も、引き続き実行されます。これにより、診断情報をキャプチャしたり、ログ、メトリクス、トレースを任意の場所に送信したりできます。

Invoke フェーズはランタイム後に終了します。すべての拡張機能は、Next API リクエストを送信することによって完了を示します。

イベントペイロード :ランタイムに送信されるイベント(および 関数 Lambda )はリクエスト、ヘッダー ( RequestId など)およびペイロード全体を保持します。各拡張機能に送信されるイベントには、イベントの内容を説明するメタデータが含まれます。このライフサイクルイベントには、イベントのタイプ、関数がタイムアウトした時間(deadlineMs)、requestId、呼び出された関数の Amazon リソースネーム(ARN)、およびトレースヘッダーが含まれます。

関数イベント本体にアクセスする拡張機能は、その拡張機能と通信するインランタイム SDK を使用できます。関数のデベロッパーは、関数が呼び出されたときにインランタイム SDK を使用して、拡張機能にペイロードを送信します。

ペイロードの例を次に示します。

{ "eventType": "INVOKE", "deadlineMs": 676051, "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895", "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest", "tracing": { "type": "X-Amzn-Trace-Id", "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1" } }

所要時間の制限: 関数のタイムアウト設定では、Invoke フェーズ全体の所要時間を制限します。例えば、関数のタイムアウトを 360 秒に設定した場合、関数とすべての拡張機能は 360 秒以内に完了する必要があります。独立した呼び出し後フェーズはないことに注意してください。所要時間は、すべての呼び出し時間 (ランタイム + 拡張機能) の合計であり、関数とすべての拡張機能の実行が終了するまで計算されません。

パフォーマンスの影響と拡張機能のオーバーヘッド: 拡張機能は、関数のパフォーマンスに影響を与える可能性があります。拡張機能の作成者は、拡張機能のパフォーマンスへの影響を制御する必要があります。例えば、拡張機能でコンピューティング負荷の高い操作を実行した場合、拡張機能と関数コードで同じ CPU リソースを共有するため、関数の実行時間が長くなります。さらに、関数呼び出しの完了後に拡張機能が広範な操作を実行する場合、すべての拡張機能が完了を示すまで Invoke フェーズが継続するため、関数の実行時間が長くなります。

Invoke フェーズで拡張機能によって発生したパフォーマンスへの影響を確認できるように、Lambda は PostRuntimeExecutionDuration メトリクスを出力します。このメトリクスでは、ランタイム Next API リクエストから最後の拡張機能の Next API リクエストまでの累積時間が測定されます。使用されるメモリの増加を測定するには、MaxMemoryUsed メトリクスを使用します。関数のメトリクスの詳細については、「AWS Lambda 関数メトリクスの使用」を参照してください。

関数のデベロッパーは、異なるバージョンの関数を並行して実行して、特定の拡張機能の影響を把握することができます。拡張機能の作成者は、関数のデベロッパーが適切な拡張機能を選択しやすくするために、予想されるリソース消費を公開することをお勧めします。

シャットダウンフェーズ

Lambda は、ランタイムを終了しようとする際に、ランタイムに Shutdown イベントを送信してから、登録された各外部拡張機能にイベントを送信します。拡張機能は、この時間を最終的なクリーンアップタスクに使用できます。Shutdown イベントは Next API リクエストに応答して送信されます。

所要時間の制限: Shutdown フェーズの最大所要時間は、登録された拡張機能の設定によって異なります。

  • 300 ms – 登録された拡張機能を持たない関数

  • 500 ms – 登録された内部拡張機能を持つ関数

  • 2000 ms – 登録された外部拡張機能を 1 つ以上持つ関数

外部拡張機能を持つ関数の場合、Lambda はランタイムプロセスがグレースフルシャットダウンを実行するために、最大 300 ms (内部拡張機能を持つランタイムでは 500 ms )を予約します。Lambda は、外部拡張機能によるシャットダウンのために、2000 ms の制限のうち残りを割り当てます。

ランタイムまたは拡張機能が制限内で Shutdown イベントに応答しない場合、Lambda は SIGKILL の通知を使用してプロセスを終了します。

イベントペイロード: Shutdown イベントには、シャットダウンの理由と残り時間 (ミリ秒単位) が含まれます。

shutdownReason には次の値が含まれています。

  • SPINDOWN – 正常なシャットダウン

  • TIMEOUT – 所要時間の制限がタイムアウトしました

  • FAILURE – エラー状態 (out-of-memory イベントなど)

{ "eventType": "SHUTDOWN", "shutdownReason": "reason for shutdown", "deadlineMs": "the time and date that the function times out in Unix time milliseconds" }

アクセス許可と設定

拡張機能は、Lambda 関数と同じ実行環境で実行されます。拡張機能は、CPU、メモリ、/tmp ディスクストレージなどのリソースも関数と共有します。さらに、関数と同じ AWS Identity and Access Management (IAM) ロールとセキュリティコンテキストが使用されます。

ファイルシステムとネットワークアクセス許可: 拡張機能は、関数ランタイムと同じファイルシステムおよびネットワーク名の名前空間で実行されます。つまり、拡張機能は関連するオペレーティングシステムと互換性がある必要があります。拡張機能で追加のネットワーク出力ルールが必要な場合は、これらのルールを関数の設定に適用する必要があります。

注記

関数コードディレクトリは読み取り専用であるため、拡張機能は関数コードを変更できません。

環境変数: 拡張機能は、関数の環境変数にアクセスできます。ただし、ランタイムプロセスに固有の次の変数は除きます。

  • AWS_EXECUTION_ENV

  • AWS_LAMBDA_LOG_GROUP_NAME

  • AWS_LAMBDA_LOG_STREAM_NAME

  • AWS_XRAY_CONTEXT_MISSING

  • AWS_XRAY_DAEMON_ADDRESS

  • LAMBDA_RUNTIME_DIR

  • LAMBDA_TASK_ROOT

  • _AWS_XRAY_DAEMON_ADDRESS

  • _AWS_XRAY_DAEMON_PORT

  • _HANDLER

障害処理

初期化の失敗:拡張機能が失敗した場合、Lambda は実行環境を再起動して一貫した動作を適用し、拡張機能のフェイルファストを推奨します。また、お客様によっては、拡張機能が、ログ記録、セキュリティ、ガバナンス、テレメトリ収集などのミッションクリティカルなニーズを満たす必要があります。

呼び出しの失敗(メモリ不足、関数のタイムアウトなど): 拡張機能はランタイムとリソースを共有するため、メモリが消耗した場合に影響を受けます。ランタイムが失敗すると、すべての拡張機能とランタイム自体が Shutdown フェーズに参加します。さらにランタイムは、—現在の呼び出しの一部として、または遅延された再初期化メカニズムを通し、自動的に再起動されます。

Invoke 中に障害が発生した場合 (関数のタイムアウトやランタイムエラーなど)、Lambda サービスはリセットを実行します。リセットは Shutdown イベントのように動作します。まず、Lambda はランタイムをシャットダウンし、登録された各外部拡張機能に Shutdown イベントを送信します。イベントには、シャットダウンの理由が含まれます。この環境が新しい呼び出しに使用される場合、拡張機能とランタイムは次の呼び出しの一部として再初期化されます。

注記

Lambda は、繰り返し失敗する拡張機能を自動的にシャットダウンしません。ただし、関数のデベロッパーや拡張機能の作成者がこのような失敗を理解し、診断できるように、Lambda は Amazon CloudWatch メトリクスとログを通じてこれらのエラーを報告します。

拡張機能のログ: Lambda は、拡張機能のログ出力を CloudWatch Logs に送信します。Lambda は、Init 中に各拡張機能に対して追加のログイベントも生成します。ログイベントは、成功時には名前と登録設定 (event、config) を記録し、失敗時には失敗理由を記録します。

拡張機能のトラブルシューティング

  • Register リクエストが失敗した場合は、Register API コールの Lambda-Extension-Name ヘッダーに拡張機能の完全なファイル名が含まれていることを確認します。

  • 内部拡張機能に対する Register リクエストが失敗した場合は、そのリクエストが Shutdown イベントに登録されていないことを確認します。

コンテナイメージへの拡張機能の追加

コンテナイメージ に拡張機能を追加できます。ENTRYPOINT コンテナイメージ設定 では、コンテナのメインプロセスを指定します。Dockerfile で ENTRYPOINT および CMD 設定を構成するか、関数設定のオーバーライドとして設定します。

コンテナ内で複数のプロセスを実行できます。Lambda は、メインプロセスと追加のプロセスのライフサイクルを管理する組み込みサーバーを提供します。サーバーは、Extensions API を使用して各外部拡張と通信します。

拡張機能 API リファレンス

拡張機能 API バージョン 2020-01-01 の OpenAPI 仕様は、こちらから入手できます: extensions-api.zip

API エンドポイントの値は、AWS_LAMBDA_RUNTIME_API 環境変数から取得できます。Register リクエストを送信するには、各 API パスの前にプレフィックス 2020-01-01/ を使用します。次に例を示します。

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register

登録

Extension init 中にイベントを受信するには、すべての拡張機能を Lambda に登録する必要があります。Lambda は、拡張機能の完全なファイル名を使用して、拡張機能がブートストラップシーケンスを完了したことを検証します。したがって、各 Register API コールには、拡張機能の完全なファイル名を持つ Lambda-Extension-Name ヘッダーを含める必要があります。

内部拡張機能はランタイムプロセスによって開始および停止されるため、Shutdown イベントへの登録は許可されません。

パス/extension/register

メソッドPOST

ヘッダー

Lambda-Extension-Name – 拡張機能の完全なファイル名。必須: はい。タイプ: 文字列。

Body パラメータ

events – 登録するイベントの配列。必須: いいえ。型: 文字列の配列。有効な文字列: INVOKESHUTDOWN

レスポンスヘッダー

  • Lambda-Extension-Identifier – それ以降のすべてのリクエストに必要な、生成された一意のエージェント識別子 (UUID 文字列)。

レスポンスコード

  • 200 – レスポンス本文には、関数名、関数バージョン、およびハンドラー名が含まれます。

  • 400 – Bad Request

  • 403 – Forbidden

  • 500 – コンテナエラー。回復不能な状態。拡張機能はすぐに終了する必要があります。

例 リクエスト本文の例

{ 'events': [ 'INVOKE', 'SHUTDOWN'] }

例 レスポンスの例

{ "functionName": "helloWorld", "functionVersion": "$LATEST", "handler": "lambda_function.lambda_handler" }

拡張機能は Next API リクエストを送信して、次のイベント (Invokeイベントまたは Shutdown イベント) を受信します。レスポンス本文にはペイロードが含まれます。ペイロードは、イベントデータを含む JSON ドキュメントです。

拡張機能は、新しいイベントを受信する準備ができていることを示す Next API リクエストを送信します。これはブロック呼び出しです。

拡張機能は一定期間中断される可能性があるため、返されるイベントが発生するまで、GET 呼び出しにタイムアウトを設定しないでください。

パス/extension/event/next

メソッドGET

パラメータ

Lambda-Extension-Identifier – 拡張機能の一意の識別子 (UUID 文字列)。必須: はい。型: UUID 文字列。

レスポンスヘッダー

  • Lambda-Extension-Identifier – 一意のエージェント識別子 (UUID文字列) 。

レスポンスコード

  • 200 – レスポンスには、次のイベント (EventInvoke または EventShutdown) に関する情報が含まれます。

  • 403 – Forbidden

  • 500 – コンテナエラー。回復不能な状態。拡張機能はすぐに終了する必要があります。

初期化エラー

拡張機能はこのメソッドを使用して、初期化エラーを Lambda に報告します。拡張機能が登録後に初期化に失敗した場合に呼び出します。Lambda がエラーを受信すると、それ以上の API コールは成功しません。拡張機能は終了します。

パス/extension/init/error

メソッドPOST

ヘッダー

Lambda-Extension-Identifier – 拡張機能の一意の識別子。必須: はい。型: UUID 文字列。

Lambda-Extension-Function-Error-Type – エラー列挙型。必須: はい。タイプ:文字列エラー列挙型(例:Fatal.connectFailed など)。

Body パラメータ

ErrorRequest – エラー型、エラーメッセージ、およびスタックトレースを含む JSON オブジェクト。

レスポンス本文

  • Lambda-Extension-Identifier – 一意のエージェント識別子 (UUID文字列) 。

レスポンスコード

  • 202 – Accepted

  • 400 – Bad Request

  • 403 – Forbidden

  • 500 – コンテナエラー。回復不能な状態。拡張機能はすぐに終了する必要があります。

終了エラー

拡張機能は、このメソッドを使用して、終了する前に Lambda にエラーを報告します。予期しない障害が発生したときに呼び出します。Lambda がエラーを受信すると、それ以上の API コールは成功しません。拡張機能は終了します。

パス/extension/exit/error

メソッドPOST

ヘッダー

Lambda-Extension-Identifier – 拡張機能の一意の識別子。必須: はい。型: UUID 文字列。

Lambda-Extension-Function-Error-Type – エラー列挙型。必須: はい。タイプ:文字列エラー列挙型(例:Fatal.connectFailed など)。

Body パラメータ

ErrorRequest – エラー型、エラーメッセージ、およびスタックトレースを含む JSON オブジェクト。

レスポンス本文

  • Lambda-Extension-Identifier – 一意のエージェント識別子 (UUID文字列) 。

レスポンスコード

  • 202 – Accepted

  • 400 – Bad Request

  • 403 – Forbidden

  • 500 – コンテナエラー。回復不能な状態。拡張機能はすぐに終了する必要があります。