Lambda 拡張機能 API を使用した拡張機能の作成

Lambda 関数の作成者は、拡張機能を使用して、Lambda を、モニタリング、可観測性、セキュリティ、およびガバナンスのための任意のツールと統合します。関数作成者は、AWS、AWS パートナー、およびオープンソースプロジェクトの拡張機能を使用できます。拡張機能の使用の詳細については、AWS Lambda コンピューティングブログの AWS 拡張機能の紹介を参照してください。このセクションでは、Lambda Extensions API、Lambda 実行環境ライフサイクル、および Lambda Extensions API リファレンスを使用する方法を説明します。

拡張機能の作成者は、Lambda Extensions API を使用して Lambda 実行環境に深く統合することができます。拡張機能は、関数および実行環境のライフサイクルイベントに登録できます。これらのイベントに対応して、新しいプロセスを開始し、ロジックを実行し、Lambda ライフサイクルのすべてのフェーズ (初期化、呼び出し、およびシャットダウン) を制御し、これらに参加することができます。さらに、Runtime Logs API を使用して、ログのストリームを受信できます。

拡張機能は、実行環境で独立したプロセスとして実行され、関数の呼び出しが完全に処理された後も引き続き実行できます。拡張機能はプロセスとして実行されるため、関数とは異なる言語で記述できます。コンパイルされた言語を使用して拡張機能を実装することをお勧めします。この場合、拡張機能は、サポートされているランタイムと互換性のある自己完結型のバイナリです。すべての Lambda ランタイム は拡張機能をサポートします。コンパイルされていない言語を使用する場合は、必ず互換性のあるランタイムを拡張機能に含めてください。

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

関数に拡張機能を追加するには、次の 2 つの方法があります。.zip ファイルアーカイブとしてデプロイされた関数では、拡張機能をレイヤーとしてデプロイします。コンテナイメージとして定義された関数の場合は、コンテナイメージに拡張機能を追加します。

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

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

各フェーズは、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 リクエストを送信することで完了を示します。

呼び出しフェーズ

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

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

ランタイムから関数応答を受信した後、拡張機能がまだ実行中であっても、Lambda はクライアントに応答を返します。

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 は PostRuntimeExtensionsDuration メトリクスを出力します。このメトリクスでは、ランタイム Next API リクエストから最後の拡張機能の Next API リクエストまでの累積時間が測定されます。使用されるメモリの増加を測定するには、MaxMemoryUsed メトリクスを使用します。関数のメトリクスの詳細については、「Lambda 関数のメトリクスを表示する」を参照してください。

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

シャットダウンフェーズ

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

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

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

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

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

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

{ 
  "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) ロールとセキュリティコンテキストが使用されます。

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

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

障害処理

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

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

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

前示の図の詳細については、「呼び出しフェーズ中の失敗」を参照してください。

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

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

拡張機能 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

リクエストヘッダー

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

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

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

次へ

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

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

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

パス – /extension/event/next

メソッド - GET

初期化エラー

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

パス – /extension/init/error

メソッド - POST

このフィールドは、次の構造を持つ JSON オブジェクトです。

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda は、errorType として任意の値を受け入れることに注意してください。

次の例は、呼び出しで指定されたイベントデータを関数で解析できなかった Lambda 関数のエラーメッセージを示しています。

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

終了エラー

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

パス – /extension/exit/error

メソッド - POST

このフィールドは、次の構造を持つ JSON オブジェクトです。

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Lambda は、errorType として任意の値を受け入れることに注意してください。

次の例は、呼び出しで指定されたイベントデータを関数で解析できなかった Lambda 関数のエラーメッセージを示しています。

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}