メニュー
AWS CloudFormation
ユーザーガイド (API Version 2010-05-15)

Amazon Simple Notification Service-backed カスタムリソース

Amazon SNS トピックをカスタムリソースに関連付けた場合、Amazon SNS 通知を使用してカスタムプロビジョニングをトリガーします。カスタムリソースと Amazon SNS を使用すると、新しいリソースのスタックへの追加、スタックへの動的データの挿入などのシナリオが可能になりす。たとえば、スタックを作成するときに、AWS CloudFormation によって、Amazon Elastic Compute Cloud インスタンスで実行しているアプリケーションが監視するトピックに create リクエストを送信できます。Amazon SNS 通知は、追加のプロビジョニングタスク (ホワイトリストに含まれた Elastic IP のプールの取得など) を実行するようにアプリケーションをトリガーします。完了すると、アプリケーションは、AWS CloudFormation にスタックオペレーションの続行を通知するレスポンス (および該当する場合は出力データ) を送信します。

演習: Amazon Simple Notification Service を使用してカスタムリソースを作成する

このウォークスルーでは、カスタムリソースのプロセスを順に説明します。イベントの発生順序や、カスタムリソーススタックの作成、更新、削除の結果として送受信されるメッセージについて説明しています。

ステップ 1: スタックの作成

  1. template developerが、カスタムリソースを含んだ AWS CloudFormation スタックを作成します。以下のテンプレート例では、カスタムリソース MySeleniumTest に対し、Custom::SeleniumTester という名前のカスタムリソースタイプを使用しています。

    カスタムリソースのタイプとともに、custom resource providerによって定義された情報として、サービストークン、オプションのプロバイダー固有のプロパティ、オプションの Fn::GetAtt 属性が宣言されています。これらのプロパティと属性を使用して、template developerからcustom resource providerへ、またはcustom resource providerからtemplate developerへ情報を受け渡しすることができます。カスタムリソースタイプの名前は、英数字で 60 文字までの長さにする必要があります。

    以下に示したのは、カスタムプロパティと出力属性の両方を持つテンプレートの例です。

    Copy
    { "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : { "MySeleniumTest" : { "Type": "Custom::SeleniumTester", "Version" : "1.0", "Properties" : { "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest", "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } } }, "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } } }

    注記

    Fn::GetAtt を使ってアクセスしたデータの名前と値は、プロバイダーから AWS CloudFormation へのレスポンス中にcustom resource providerから返されます。custom resource providerがサードパーティである場合、template developerは、それらの戻り値の名前をcustom resource providerから入手する必要があります。

  2. AWS CloudFormation が Amazon SNS 通知をリソースプロバイダーに送信します。送信には、スタックに関する情報、スタックテンプレートに基づくカスタムリソースのプロパティ、レスポンスに使用する S3 の URL を含んだ "RequestType" : "Create" が使用されます。

    通知を送信する際に使用する SNS トピックは、テンプレートの ServiceToken プロパティに埋め込まれます。値をハードコーディングすることを避けるためには、テンプレートパラメーターを使用します。スタックの起動時に値を入力することができます。

    次の例は、カスタムリソースの Create リクエストを示します。LogicalResourceIdMySeleniumTester として作成されたカスタムリソースタイプの名前 (Custom::SeleniumTester) が含まれています。

    Copy
    { "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::SeleniumTester", "LogicalResourceId" : "MySeleniumTester", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } }
  3. custom resource providerは、template developerから送信されたデータを処理し、Create リクエストが成功したかどうかを判断します。リソースプロバイダーは、AWS CloudFormation から送信された S3 の URL を使用して、SUCCESS または FAILED のレスポンスを送信します。

    AWS CloudFormation に返されるレスポンスフィールドは、レスポンスのタイプによって異なります。処理対象の RequestType に該当するリファレンストピックの「レスポンス」のセクションを参照してください。

    custom resource providerは、作成リクエストまたは更新リクエストへの応答として、レスポンスの データ フィールドでデータ要素を返すことができます。これらは名前/値ペアであり、"名前" は、スタックテンプレートのカスタムリソースで使用されている Fn::GetAtt 属性に対応します。"" は、template developerが、リソースから属性名を使って Fn::GetAtt を呼び出したときに返されるデータです。

    次に、カスタムリソースのレスポンスの例を示します。

    Copy
    { "Status" : "SUCCESS", "PhysicalResourceId" : "Tester1", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "unique id for this create request", "LogicalResourceId" : "MySeleniumTester", "Data" : { "resultsPage" : "http://www.myexampledomain/test-results/guid", "lastUpdate" : "2012-11-14T03:30Z", } }

    StackIdRequestId、および LogicalResourceId フィールドをリクエストからそのままコピーする必要があります。

  4. AWS CloudFormation は、スタックのステータスを CREATE_COMPLETE または CREATE_FAILED として宣言します。スタックが正常に作成された場合、template developerは、作成したカスタムリソースの出力値に Fn::GetAtt でアクセスし、使用することができます。

    たとえば、先ほど例示したカスタムリソーステンプレートでは、Fn::GetAtt を使用してリソースの出力をスタック出力にコピーしています。

    Copy
    "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } }

Create リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、カスタムリソースリファレンスの「作成」を参照してください。

ステップ 2: スタックの更新

既存のスタックを更新するには、以下の例に示したように、スタック内リソースのプロパティについて、その更新を指定するテンプレートを送信する必要があります。AWS CloudFormation は、テンプレートで指定されている変更があるリソースのみを更新します。スタックの更新の詳細については、「AWS CloudFormation スタックの更新」を参照してください。

カスタムリソースの更新には、基になる物理リソースの置き換えが伴うことがあります。AWS CloudFormation テンプレートでカスタムリソースを更新すると、AWS CloudFormation が、そのカスタムリソースに更新リクエストを送信します。カスタムリソースを置き換えることが必要になった場合には、新しいカスタムリソースから新しい物理 ID を含むレスポンスを送信する必要があります。AWS CloudFormation は、そのレスポンスを受け取ると、古いカスタムリソースと新しいカスタムリソースの PhysicalResourceId を比較します。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソースに削除リクエストを送信します (「ステップ 3: スタックの削除」を参照)。

注記

カスタムリソースに変更を行なわない場合、AWS CloudFormation はスタック更新中にリクエストを送信しません。

  1. template developerが、カスタムリソースを含んだスタックの更新を開始します。更新時、template developerは、新しいプロパティをスタックテンプレートで指定できます。

    カスタムリソースタイプを使用したスタックテンプレートに対する Update の例を以下に示します。

    Copy
    { "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : { "MySeleniumTest" : { "Type": "Custom::SeleniumTester", "Version" : "1.0", "Properties" : { "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest", "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] } } }, "Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } } }
  2. AWS CloudFormation が、Amazon SNS 通知をリソースプロバイダーに送信します。送信には、Create 呼び出しと同様の情報を含んだ "RequestType" : "Update" が使用されます。ただし、OldResourceProperties フィールドには古いリソースプロパティが、ResourceProperties には新しい (存在する場合) リソースプロパティが格納されます。

    次は、Update リクエストの例です。

    Copy
    { "RequestType" : "Update", "ResponseURL" : "http://pre-signed-S3-url-for-response", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "uniqueid for this update request", "LogicalResourceId" : "MySeleniumTester", "ResourceType" : "Custom::SeleniumTester" "PhysicalResourceId" : "Tester1", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] } "OldResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4" ] } }
  3. AWS CloudFormation から送信されたデータをcustom resource providerが処理します。カスタムリソースが更新を実行し、SUCCESS または FAILED のレスポンスを S3 の URL に送信します。その後 AWS CloudFormation は、新旧のカスタムリソースの PhysicalResourceIDs を比較します。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソースに削除リクエストを送信します。以下に示したのは、Update リクエストに対するcustom resource providerのレスポンスの例です。

    Copy
    { "Status" : "SUCCESS", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "uniqueid for this update request", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester2" }

    StackIdRequestId、および LogicalResourceId フィールドをリクエストからそのままコピーする必要があります。

  4. AWS CloudFormation は、スタックのステータスを UPDATE_COMPLETE または UPDATE_FAILED として宣言します。更新に失敗すると、スタックはロールバックされます。スタックが正常に更新された場合、template developerは、作成したカスタムリソースの新しい出力値に Fn::GetAtt でアクセスすることができます。

Update リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、カスタムリソースリファレンスの「更新」を参照してください。

ステップ 3: スタックの削除

  1. template developerが、カスタムリソースを含んだスタックを削除します。AWS CloudFormation は、スタックテンプレートに指定された現在のプロパティと SNS トピックを取得し、custom resource providerへのリクエストに備えます。

  2. AWS CloudFormation が Amazon SNS 通知をリソースプロバイダーに送信します。送信には、スタックに関する最新の情報、スタックテンプレートに基づくカスタムリソースのプロパティ、レスポンスに使用する S3 の URL を含んだ "RequestType" : "Delete" が使用されます。

    スタックを削除したり、カスタムリソースの削除や置き換えを伴う更新を行ったりした場合は必ず、AWS CloudFormation によって、新旧のカスタムリソース間で PhysicalResourceId が比較されます。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソース (OldPhysicalResource) の削除リクエストを送信します (以下の Delete リクエストの例を参照)。

    Copy
    { "RequestType" : "Delete", "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 delete request", "ResourceType" : "Custom::SeleniumTester", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1", "ResourceProperties" : { "seleniumTester" : "SeleniumTest()", "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com", "http://mynewsite.com" ], "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ] } }

    ユーザー定義の名前が指定されている場合、DescribeStackResourceDescribeStackResourcesListStackResources で表示できます。

  3. custom resource providerは、AWS CloudFormation から送信されたデータを処理し、Delete リクエストが成功したかどうかを判断します。リソースプロバイダーは、AWS CloudFormation から送信された S3 の URL を使用して、SUCCESS または FAILED のレスポンスを送信します。カスタムリソースを持つスタックを正常に削除するには、削除リクエストに対して custom resource provider が適切に応答する必要があります。

    以下に示したのは、Delete リクエストに対するcustom resource providerのレスポンスの例です。

    Copy
    { "Status" : "SUCCESS", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "unique id for this delete request", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester1" }

    StackIdRequestId、および LogicalResourceId フィールドをリクエストからそのままコピーする必要があります。

  4. AWS CloudFormation は、スタックのステータスを DELETE_COMPLETE または DELETE_FAILED として宣言します。

Delete リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、カスタムリソースリファレンスの「削除」を参照してください。

以下の資料も参照してください。