AWS CloudFormation
User Guide (API Version 2010-05-15)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

Amazon Simple Notification Service 支持的自定义资源

在将 Amazon SNS 主题与自定义资源关联时,可使用 Amazon SNS 通知来触发自定义配置逻辑。通过自定义资源和 Amazon SNS,您可以启用方案,例如向堆栈添加新资源和向堆栈注入动态数据。例如,在创建堆栈时,AWS CloudFormation 可以向由运行在 Amazon Elastic Compute Cloud 实例上的应用程序监控的主题发送 create 请求。Amazon SNS 通知触发应用程序以执行其他配置任务,如检索列在白名单中的弹性 IP 池。完成后,应用程序发送响应(和任何输出数据),通知 AWS CloudFormation 继续执行堆栈操作。

演练:使用 Amazon Simple Notification Service 创建自定义资源

此演练将逐步执行自定义资源过程,并对由于自定义资源堆栈创建、更新和删除而发送和接收的事件和消息序列进行说明。

步骤 1:堆栈创建

  1. template developer创建包含自定义资源的 AWS CloudFormation 堆栈;在下面的模板示例中,我们对自定义资源 Custom::SeleniumTester 使用自定义资源类型名称 MySeleniumTest

    自定义资源类型是使用服务令牌、可选提供商特定属性以及由custom resource provider定义的可选 Fn::GetAtt 属性声明的。使用这些属性和特性可以将信息从template developer传递给custom resource provider,反之亦然。自定义资源类型名称必须是字母数字字符,最大长度为 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会返回使用 Fn::GetAtt 访问的数据的名称和值。如果custom resource provider是第三方,则template developer必须从custom resource provider获取这些返回值的名称。

  2. AWS CloudFormation 使用 "RequestType" : "Create" 向资源提供者发送一条 Amazon SNS 通知,其中包含有关堆栈的信息、堆栈模板中的自定义资源属性和用于响应的 S3 URL。

    用于发送通知的 SNS 主题嵌入在模板的 ServiceToken 属性中。要避免使用硬编码值,template developer可以使用模板参数,以便在启动堆栈时输入值。

    下面的示例所示为一个自定义资源 Create 请求,其中包含一个用 Custom::SeleniumTesterLogicalResourceId 创建的自定义资源类型名称 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" ] } }
  3. custom resource provider处理template developer发送的数据,并确定 Create 请求是否已成功。然后,资源提供者使用 AWS CloudFormation 发送的 S3 URL 来发送 SUCCESSFAILED 响应。

    根据响应类型,AWS CloudFormation 将需要不同的响应字段。请参阅参考主题中的“响应”部分,了解要处理的 RequestType。

    在响应创建或更新请求时,custom resource provider可以在响应的 Data 字段中返回数据元素。这些是名称/值对,名称对应于用于堆栈模板中的自定义资源的 Fn::GetAtt 属性。该是 template developer 对具有此属性名称的资源调用 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", } }

    StackIdRequestIdLogicalResourceId 字段必须从请求中逐字复制。

  4. AWS CloudFormation 将堆栈状态声明为 CREATE_COMPLETECREATE_FAILED。如果堆栈已成功创建,template developer通过 Fn::GetAtt 访问已创建的自定义资源的输出值,从而使用这些值。

    例如,用于举例说明的自定义资源模板使用 Fn::GetAtt 将资源输出复制到堆栈输出:

    "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。如果不同,AWS CloudFormation 将更新识别为替换内容并向旧资源发送删除请求,如步骤 3:堆栈删除中所示。

注意

如果您没有对自定义资源进行更改,AWS CloudFormation 在堆栈更新过程中不会向资源发送请求。

  1. 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"] } } } }
  2. AWS CloudFormation 会使用 "RequestType" : "Update" 向资源提供者发送一条 Amazon SNS 通知,其中包含与 Create 调用类似的信息,不同的是,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" ] } }
  3. custom resource provider处理由 AWS CloudFormation 发送的数据。自定义资源执行更新并向 S3 URL 发送 SUCCESSFAILED 响应。然后 AWS CloudFormation 将新旧自定义资源的 PhysicalResourceIDs 进行比较。如果不同,AWS CloudFormation 将认为更新要求是替换并向旧资源发送删除请求。下面的示例说明custom resource provider对 Update 请求的响应。

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

    StackIdRequestIdLogicalResourceId 字段必须从请求中逐字复制。

  4. AWS CloudFormation 将堆栈状态声明为 UPDATE_COMPLETEUPDATE_FAILED。如果更新失败,堆栈将回滚。如果堆栈更新成功,template developer可以使用 Fn::GetAtt 访问已创建自定义资源的任何新输出值。

有关 Update 请求中涉及的请求和响应对象的详细信息,请参阅自定义资源参考中的更新

步骤 3:堆栈删除

  1. template developer会删除包含自定义资源的堆栈。AWS CloudFormation 获取堆栈模板中指定的当前属性及 SNS 主题,并准备向custom resource provider发出请求。

  2. AWS CloudFormation 使用 "RequestType" : "Delete" 向资源提供者发送一条 Amazon SNS 通知,其中包含有关堆栈的当前信息、堆栈模板中的自定义资源属性和用于响应的 S3 URL。

    只要您删除堆栈或进行自定义资源的删除或替换更新,AWS CloudFormation 都会比较新旧自定义资源的 PhysicalResourceId。如果不同,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" ] } }

    DescribeStackResourceDescribeStackResourcesListStackResources 显示用户定义的名称(如果已指定)。

  3. custom resource provider处理由 AWS CloudFormation 发送的数据并确定 Delete 请求是否成功。然后,资源提供者使用 AWS CloudFormation 发送的 S3 URL 来发送 SUCCESSFAILED 响应。要成功删除带自定义资源的堆栈,custom resource provider 必须成功响应删除请求。

    以下是custom resource provider响应 Delete 请求的示例:

    { "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" }

    StackIdRequestIdLogicalResourceId 字段必须从请求中逐字复制。

  4. AWS CloudFormation 将堆栈状态声明为 DELETE_COMPLETEDELETE_FAILED

有关 Delete 请求中涉及的请求和响应对象的详细信息,请参阅中的删除自定义资源参考

另请参阅