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: スタックの作成
-
テンプレート開発者が、カスタムリソースを含んだ AWS CloudFormation スタックを作成します。以下のテンプレート例では、カスタムリソース
MySeleniumTest
に対し、Custom::SeleniumTester
という名前のカスタムリソースタイプを使用しています。カスタムリソースのタイプとともに、custom resource provider によって定義された情報として、サービストークン、オプションのプロバイダー固有のプロパティ、オプションの Fn::GetAtt 属性が宣言されています。これらのプロパティと属性を使用して、template developer から custom resource provider へ、または custom resource provider から template developer へ情報を受け渡しすることができます。カスタムリソースタイプの名前は、英数字で 60 文字までの長さにする必要があります。
以下に示したのは、カスタムプロパティと出力属性の両方を持つテンプレートの例です。
{ "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"] } } } }
注記
を使ってアクセスしたデータの名前と値は、プロバイダーから AWS CloudFormation へのレスポンス中にカスタムリソースプロバイダーから返されます。custom resource provider がサードパーティーである場合、template developer は、それらの戻り値の名前を custom resource provider から入手する必要があります。Fn::GetAtt
-
AWS CloudFormation が Amazon SNS 通知をリソースプロバイダーに送信します。送信には、スタックに関する情報、スタックテンプレートに基づくカスタムリソースのプロパティ、レスポンスに使用する S3 URL を含んだ
"RequestType" : "Create"
が使用されます。通知を送信する際に使用する SNS トピックは、テンプレートの
ServiceToken
プロパティに埋め込まれます。値をハードコーディングすることを避けるために、テンプレート開発者はテンプレートパラメータを使用します。スタックの起動時に値を入力することができます。次の例は、カスタムリソースの
Create
リクエストを示します。Custom::SeleniumTester
をLogicalResourceId
として作成されたカスタムリソースタイプの名前 (MySeleniumTester
) が含まれています。{ "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" ] } }
-
custom resource provider は、template developer から送信されたデータを処理し、
Create
リクエストが成功したかどうかを判断します。リソースプロバイダーは、AWS CloudFormation から送信された S3 URL を使用して、SUCCESS
またはFAILED
のレスポンスを送信します。AWS CloudFormation に返されるレスポンスフィールドは、レスポンスのタイプによって異なります。処理対象の RequestType に該当するリファレンストピックの「レスポンス」のセクションを参照してください。
custom resource provider は、作成リクエストまたは更新リクエストへの応答として、レスポンスの [データ] フィールドでデータ要素を返すことができます。これらは名前/値ペアであり、名前は、スタックテンプレートのカスタムリソースで使用されている
属性に対応します。値は、テンプレート開発者が、リソースから属性名を使ってFn::GetAtt
を呼び出したときに返されるデータです。Fn::GetAtt
次に、カスタムリソースのレスポンスの例を示します。
{ "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", } }
StackId
、RequestId
、およびLogicalResourceId
フィールドはリクエストからそのままコピーする必要があります。 -
AWS CloudFormation は、スタックのステータスを
CREATE_COMPLETE
またはCREATE_FAILED
として宣言します。スタックが正常に作成された場合、template developer は、作成したカスタムリソースの出力値に Fn::GetAtt でアクセスすることで使用できます。たとえば、先ほど例示したカスタムリソーステンプレートでは、
を使用してリソースの出力をスタック出力にコピーしています。Fn::GetAtt
"Outputs" : { "topItem" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] } }, "numRespondents" : { "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] } } }
Create
リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、「Custom Resource Reference」(カスタムリソースリファレンス) の「Create」(作成) を参照してください。
ステップ 2: スタックの更新
既存のスタックを更新するには、以下の例に示したように、スタック内リソースのプロパティについて、その更新を指定するテンプレートを送信する必要があります。AWS CloudFormation は、テンプレートで指定されている変更があるリソースのみを更新します。スタックの更新の詳細については、「AWS CloudFormation スタックの更新」を参照してください。
カスタムリソースの更新には、基になる物理リソースの置き換えが伴うことがあります。AWS CloudFormation テンプレートでカスタムリソースを更新すると、AWS CloudFormation が、そのカスタムリソースに更新リクエストを送信します。カスタムリソースを置き換えることが必要になった場合には、新しいカスタムリソースから新しい物理 ID を含むレスポンスを送信する必要があります。AWS CloudFormation は、そのレスポンスを受け取ると、古いカスタムリソースと新しいカスタムリソースの PhysicalResourceId
を比較します。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソースに削除リクエストを送信します (「ステップ 3: スタックの削除」を参照)。
注記
カスタムリソースに変更を行なわない場合、AWS CloudFormation はスタック更新中にリクエストを送信しません。
-
template developerが、カスタムリソースを含んだスタックの更新を開始します。更新時、template developerは、新しいプロパティをスタックテンプレートで指定できます。
カスタムリソースタイプを使用したスタックテンプレートに対する
Update
の例を以下に示します。{ "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"] } } } }
-
AWS CloudFormation が、Amazon SNS 通知をリソースプロバイダーに送信します。送信には、
Create
呼び出しと同様の情報を含んだ"RequestType" : "Update"
が使用されます。ただし、OldResourceProperties
フィールドには古いリソースプロパティが、ResourceProperties には新しい (存在する場合) リソースプロパティが格納されます。次は、
Update
リクエストの例です。{ "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" ] } }
-
AWS CloudFormation から送信されたデータをカスタムリソースプロバイダーが処理します。カスタムリソースが更新を実行し、
SUCCESS
またはFAILED
のレスポンスを S3 URL に送信します。その後 AWS CloudFormation は、新旧のカスタムリソースのPhysicalResourceIDs
を比較します。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソースに削除リクエストを送信します。以下に示したのは、Update
リクエストに対するcustom resource providerのレスポンスの例です。{ "Status" : "SUCCESS", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "uniqueid for this update request", "LogicalResourceId" : "MySeleniumTester", "PhysicalResourceId" : "Tester2" }
StackId
、RequestId
、およびLogicalResourceId
フィールドはリクエストからそのままコピーする必要があります。 -
AWS CloudFormation は、スタックのステータスを
UPDATE_COMPLETE
またはUPDATE_FAILED
として宣言します。更新に失敗すると、スタックはロールバックされます。スタックが正常に更新された場合、template developer は、作成したカスタムリソースの新しい出力値に
でアクセスすることができます。Fn::GetAtt
Update
リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、「Custom Resource Reference」(カスタムリソースリファレンス) の「Update」(更新) を参照してください。
ステップ 3: スタックの削除
-
テンプレート開発者が、カスタムリソースを含んだスタックを削除します。AWS CloudFormation は、スタックテンプレートに指定された現在のプロパティと SNS トピックを取得し、カスタムリソースプロバイダーへのリクエストに備えます。
-
AWS CloudFormation が Amazon SNS 通知をリソースプロバイダーに送信します。送信には、スタックに関する現在の情報、スタックテンプレートに基づくカスタムリソースのプロパティ、レスポンスに使用する S3 URL を含んだ
"RequestType" : "Delete"
が使用されます。スタックを削除したり、カスタムリソースの削除や置き換えを伴う更新を行ったりした場合は必ず、AWS CloudFormation によって、新旧のカスタムリソース間で
PhysicalResourceId
が比較されます。この 2 つが異なる場合には、AWS CloudFormation は置き換えが必要な更新と認識し、古いリソース (OldPhysicalResource
) の削除リクエストを送信します (以下のDelete
リクエストの例を参照)。{ "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" ] } }
ユーザー定義の名前が指定されている場合、
DescribeStackResource
、DescribeStackResources
、ListStackResources
で表示できます。 -
カスタムリソースプロバイダーは、AWS CloudFormation から送信されたデータを処理し、
Delete
リクエストが成功したかどうかを判断します。リソースプロバイダーは、AWS CloudFormation から送信された S3 URL を使用して、SUCCESS
またはFAILED
のレスポンスを送信します。カスタムリソースを持つスタックを正常に削除するには、削除リクエストに対して custom resource provider が適切に応答する必要があります。以下に示したのは、
Delete
リクエストに対する custom resource provider のレスポンスの例です。{ "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" }
StackId
、RequestId
、およびLogicalResourceId
フィールドはリクエストからそのままコピーする必要があります。 -
AWS CloudFormation は、スタックのステータスを
DELETE_COMPLETE
またはDELETE_FAILED
として宣言します。
Delete
リクエストに関係するリクエストオブジェクトとレスポンスオブジェクトの詳細については、「カスタムリソースリファレンス」の「削除」を参照してください。