Amazon Simple Notification Service 支持的自定义资源 - Amazon CloudFormation
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

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

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

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

步骤 1:堆栈创建

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

    自定义资源类型是使用服务令牌、可选提供商特定属性以及由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"] } } } }
    注意

    在提供商响应 Amazon CloudFormation 期间,自定义资源提供商会返回使用 Fn::GetAtt 访问的数据的名称和值。如果custom resource provider是第三方,则template developer必须从custom resource provider获取这些返回值的名称。

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

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

    以下示例显示一个自定义资源 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 请求是否已成功。然后,资源提供者使用 Amazon CloudFormation 发送的 S3 URL 来发送 SUCCESSFAILED 响应。

    根据响应类型,Amazon 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", } }

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

  4. Amazon 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:堆栈更新

要更新现有堆栈,您必须提交一个指定了堆栈资源属性更新的模板,如下面的示例所示。Amazon CloudFormation 只更新模板中指定了更改的资源。有关更新堆栈的详细信息,请参阅 Amazon CloudFormation 堆栈更新

您可以更新需要替换基础物理资源的自定义资源。在 Amazon CloudFormation 模板中更新自定义资源时,Amazon CloudFormation 会向相应的自定义资源发送更新请求。如果需要替换自定义资源,新的自定义资源必须使用新的物理 ID 发送响应。Amazon CloudFormation 收到响应时,会比较新旧自定义资源的 PhysicalResourceId。如果不同,Amazon CloudFormation 会将更新识别为替换并向旧资源发送删除请求,如 步骤 3:堆栈删除 中所示。

注意

如果您没有对自定义资源进行更改,Amazon 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. Amazon 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. 自定义资源提供商处理由 Amazon CloudFormation 发送的数据。自定义资源执行更新并向 S3 URL 发送 SUCCESSFAILED 响应。然后 Amazon CloudFormation 比较新旧自定义资源的 PhysicalResourceIDs。如果不同,Amazon 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. Amazon CloudFormation 将堆栈状态声明为 UPDATE_COMPLETEUPDATE_FAILED。如果更新失败,堆栈将回滚。如果堆栈更新成功,template developer可以使用 Fn::GetAtt 访问已创建自定义资源的任何新输出值。

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

步骤 3:堆栈删除

  1. 模板开发人员将删除包含自定义资源的堆栈。Amazon CloudFormation 将获取堆栈模板中指定的当前属性及 SNS 主题,并准备向自定义资源提供商发出请求。

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

    只要您删除堆栈或进行自定义资源的删除或替换更新,Amazon CloudFormation 都会比较新旧自定义资源的 PhysicalResourceId。如果不同,Amazon 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. 自定义资源提供商处理 Amazon CloudFormation 发送的数据,并确定 Delete 请求是否已成功。然后,资源提供者使用 Amazon 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. Amazon CloudFormation 将堆栈状态声明为 DELETE_COMPLETEDELETE_FAILED

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

另请参阅