カスタムリソース - AWS CloudFormation

カスタムリソース

注記

CloudFormation レジストリには、カスタムリソースに比べて以下のようないくつかの利点があります。

  • サードパーティー製アプリケーションリソースのモデリング、プロビジョニング、および管理をサポート

  • CreateReadUpdateDelete、および List (CRUDL) 操作をサポート

  • プライベートおよびサードパーティーのリソースタイプでドリフト検出をサポート

カスタムリソースとは異なり、レジストリベースのリソースは、CRUDL 操作を実行するために Amazon SNS トピックや Lambda 関数を関連付ける必要がありません。CloudFormation レジストリの詳細については、「AWS CloudFormation レジストリの使用」を参照してください。

カスタムリソースを使用すると、テンプレートにカスタムのプロビジョニングロジックを記述し、ユーザーがスタックを作成、更新(カスタムリソースを変更した場合)、削除するたびに AWS CloudFormation がそれを実行します。たとえば、AWS CloudFormation のリソースタイプとして使用できないリソースを含める必要があるとします。それらのリソースは、カスタム リソースを使用して含めることができます。この方法により、すべての関連リソースを 1 つのスタックで管理できます。

AWS::CloudFormation::CustomResource または Custom::MyCustomResourceTypeName のリソースタイプを使用して、テンプレートにカスタムリソースを定義します。カスタムリソースにはサービストークンを示す 1 つのプロパティが必要です。このプロパティは、AWS CloudFormation がリクエストを送信する宛先 (Amazon SNS トピックなど) を指定します。

注記

VPC エンドポイント機能を使用する場合は、VPC のカスタムリソースには AWS CloudFormation 固有の S3 バケットへのアクセス権が必要です。カスタムリソースは、署名付き Amazon S3 URL に応答を送信する必要があります。Amazon S3 に応答を送信できない場合、AWS CloudFormation は応答を受信せず、スタックオペレーションは失敗となります。詳細については、「AWS CloudFormation の VPC エンドポイントの設定」を参照してください。

カスタムリソースのしくみ

カスタムリソースで実行されるアクションには、3 者が関係します。

template developer

カスタムリソースタイプを含むテンプレートを作成します。template developer はサービストークンとすべての入力データをテンプレートに指定します。

custom resource provider

カスタムリソースを所有し、AWS CloudFormation からの要求に対する処理と応答の方法を決定します。custom resource provider は template developer が使用するサービストークンを提供する必要があります。

AWS CloudFormation

スタックオペレーション中に、テンプレートで指定された要求をサービストークンに送信し、スタックオペレーションを進める前に応答を待機します。

template developer と custom resource provider は同じ個人や企業である場合がありますが、プロセスは同じです。次の手順はその一般的なプロセスを示したものです。

  1. template developer は対象のテンプレートのカスタムリソースを定義します。テンプレートにはサービストークンとすべての入力データのパラメータが含まれます。カスタムリソースによっては、入力データが必要な場合があります。ただし、サービストークンはいつでも必要です。

    サービストークンは AWS CloudFormation がリクエストを送信する宛先 (Amazon SNS トピックの ARNまたは AWS Lambda 関数の ARN など) を指定します。詳細については、「AWS::CloudFormation::CustomResource」を参照してください。サービストークンや入力データの構造は custom resource provider によって定義されます。

  2. テンプレートを使用してカスタムリソースを作成、更新、削除するたびに、AWS CloudFormation は指定のサービストークンに要求を送信します。このサービストークンは、スタックを作成するリージョンと同じリージョンにある必要があります。

    このリクエストには、AWS CloudFormation にリクエストタイプやカスタムリソースが応答を送信する宛先の Amazon Simple Storage Service の署名付き URL などの情報が含まれています。リクエストに含まれている情報の詳細については、「カスタムリソースリクエストオブジェクト」を参照してください。

    次のサンプルデータは、ある要求の AWS CloudFormation に含まれている情報を示します。

    { "RequestType" : "Create", "ResponseURL" : "http://pre-signed-S3-url-for-response", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "unique id for this create request", "ResourceType" : "Custom::TestResource", "LogicalResourceId" : "MyTestResource", "ResourceProperties" : { "Name" : "Value", "List" : [ "1", "2", "3" ] } }
    注記

    この例では、ResourceProperties は AWS CloudFormation が Lambda 関数へ送信するカスタムペイロードの作成を許可します。

  3. カスタムリソースプロバイダーは AWS CloudFormation のリクエストを処理し、SUCCESS または FAILED の応答を署名付き URL に返します。custom resource provider は、応答を JSON 形式のファイルで提供し、それを署名付き S3 URL にアップロードします。詳細については、「Amazon Simple Storage Service ユーザーガイド」の「Uploading objects using pre-signed URLs」(署名付き URL を使用したオブジェクトのアップロード) を参照してください。

    その応答について、custom resource provider には template developer がアクセスできる名前と値のペアも含まれている場合があります。たとえば、応答には要求が成功した場合は出力データ、要求が失敗した場合はエラーメッセージが含まれることがあります。応答の詳細については、「カスタムリソースの応答オブジェクト」を参照してください。

    重要

    名前と値のペアに機密情報が含まれている場合は、NoEcho フィールドを使用して、カスタムリソースの出力をマスクします。それ以外の場合は、プロパティ値 (DescribeStackEvents など) を表示する API を通じて値が表示されます。

    NoEcho を使用して機密情報をマスクする方法の詳細については、「テンプレートに認証情報を埋め込まない」ベストプラクティスを参照してください。

    custom resource provider には要求をリッスンして応答する責任があります。例えば、Amazon SNS 通知の場合、カスタムリソースプロバイダーは指定のトピックの ARN に送信された通知をリッスンして応答する必要があります。AWS CloudFormation は署名付き URL の場所で応答を待機してリッスンします。

    次のサンプルデータは、カスタムリソースの応答に含まれる可能性がある情報を示します。

    { "Status" : "SUCCESS", "PhysicalResourceId" : "TestResource1", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "unique id for this create request", "LogicalResourceId" : "MyTestResource", "Data" : { "OutputName1" : "Value1", "OutputName2" : "Value2", } }
  4. SUCCESS 応答を取得した後、AWS CloudFormation はスタック操作を続けます。FAILED 応答が返されるか、応答が返されない場合、操作は失敗します。カスタムリソースからの出力データは署名付き URL の場所に保存されます。template developer は Fn::GetAtt 関数を使用してそのデータを取得できます。