AWS AWSCloudFormation documentation change
Summary
Comprehensive rewrite of custom resource documentation including detailed request/response object specifications, workflow explanation, timeout handling, and security guidance for sensitive data masking
Security assessment
Added documentation about the 'NoEcho' response field to mask sensitive output and explicit warnings about credential exposure prevention. While this improves security awareness, there's no evidence it addresses a specific active vulnerability.
Diff
diff --git a/AWSCloudFormation/latest/UserGuide/crpg-ref.md b/AWSCloudFormation/latest/UserGuide/crpg-ref.md index dbd55e47e..c459bcf42 100644 --- a//AWSCloudFormation/latest/UserGuide/crpg-ref.md +++ b//AWSCloudFormation/latest/UserGuide/crpg-ref.md @@ -5 +5 @@ -# Custom resource reference +Template setupRequest objectResponse object @@ -7 +7 @@ -For an introduction to custom resources and how they work, see [Create custom provisioning logic with custom resources](./template-custom-resources.html). +# CloudFormation custom resource request and response reference @@ -9 +9 @@ For an introduction to custom resources and how they work, see [Create custom pr -This section provides detail about: +CloudFormation manages custom resources through a request-response protocol that communicates with your custom resource provider. Each request includes a request type (`Create`, `Update`, or `Delete`) and follows this high-level workflow: @@ -11 +11 @@ This section provides detail about: - * The JSON request and response fields that are used in messages sent to and from CloudFormation when providing a custom resource. + 1. A template developer defines a custom resource with a `ServiceToken` and `ServiceTimeout` in the template and initiates a stack operation. @@ -13 +13 @@ This section provides detail about: - * Expected fields for requests to, and responses to, the custom resource provider in response to stack creation, stack updates, and stack deletion. + 2. CloudFormation sends a JSON request to the custom resource provider through SNS or Lambda. @@ -14,0 +15 @@ This section provides detail about: + 3. The custom resource provider processes the request and returns a JSON response to a presigned Amazon S3 bucket URL before the timeout period expires. @@ -15,0 +17 @@ This section provides detail about: + 4. CloudFormation reads the response and proceeds with the stack operation. If no response is received before the timeout period ends, the request is considered unsuccessful, and the stack operation fails. @@ -18 +19,0 @@ This section provides detail about: -###### Topics @@ -20 +20,0 @@ This section provides detail about: - * [Custom resource request objects](./crpg-ref-requests.html) @@ -22 +22 @@ This section provides detail about: - * [Custom resource response objects](./crpg-ref-responses.html) +For more information, see [How custom resources work](./template-custom-resources.html#how-custom-resources-work). @@ -24 +24 @@ This section provides detail about: - * [Custom resource request types](./crpg-ref-requesttypes.html) +This section describes the structure, parameters, and expected responses for each request type. @@ -25,0 +26 @@ This section provides detail about: +###### Note @@ -26,0 +28 @@ This section provides detail about: +The total size of the response body can't exceed 4096 bytes. @@ -27,0 +30,461 @@ This section provides detail about: +## Template setup + +When defining a custom resource in a template, the template developer uses [AWS::CloudFormation::CustomResource](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html) with the following properties: + +`ServiceToken` + + +An Amazon SNS topic ARN or Lambda function ARN from the same Region as the stack. + +_Required_ : Yes + +_Type_ : String + +`ServiceTimeout` + + +The maximum time, in seconds, before a custom resource operation times out. It must be a value between 1 and 3600. Default: 3600 seconds (1 hour). + +_Required_ : No + +_Type_ : String + +Additional resource properties are supported. Resource properties will be included as `ResourceProperties` in the request. The custom resource provider must determine which properties are valid and their acceptable values. + +## Request object + +Create + + +When the template developer creates a stack containing a custom resource, CloudFormation sends a request with `RequestType` set to `Create`. + +Create requests contain the following fields: + +`RequestType` + + +`Create`. + +_Required_ : Yes + +_Type_ : String + +`RequestId` + + +A unique ID for the request. + +Combining the `StackId` with the `RequestId` forms a value that you can use to uniquely identify a request on a particular custom resource. + +_Required_ : Yes + +_Type_ : String + +`StackId` + + +The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource. + +Combining the `StackId` with the `RequestId` forms a value that you can use to uniquely identify a request on a particular custom resource. + +_Required_ : Yes + +_Type_ : String + +`ResponseURL` + + +The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to CloudFormation. + +_Required_ : Yes + +_Type_ : String + +`ResourceType` + + +The template developer-chosen resource type of the custom resource in the CloudFormation template. Custom resource type names can be up to 60 characters long and can include alphanumeric and the following characters: `_@-`. + +_Required_ : Yes + +_Type_ : String + +`LogicalResourceId` + + +The template developer-chosen name (logical ID) of the custom resource in the CloudFormation template. + +_Required_ : Yes + +_Type_ : String + +`ResourceProperties` + + +This field contains the contents of the `Properties` object sent by the template developer. Its contents are defined by the custom resource provider. + +_Required_ : No + +_Type_ : JSON object + +### Example + + + { + "RequestType" : "Create", + "RequestId" : "unique-request-id", + "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id", + "ResponseURL" : "pre-signed-url-for-create-response", + "ResourceType" : "Custom::MyCustomResourceType", + "LogicalResourceId" : "resource-logical-id", + "ResourceProperties" : { + "key1" : "string", + "key2" : [ "list" ], + "key3" : { "key4" : "map" } + } + } + +Update + + +When the template developer makes changes to the properties of a custom resource within the template and updates the stack, CloudFormation sends a request to the custom resource provider with `RequestType` set to `Update`. This means that your custom resource code doesn't have to detect changes in resources because it knows that its properties have changed when the request type is `Update`. + +Update requests contain the following fields: + +`RequestType` + + +`Update`. + +_Required_ : Yes + +_Type_ : String + +`RequestId` + + +A unique ID for the request. + +Combining the `StackId` with the `RequestId` forms a value that you can use to uniquely identify a request on a particular custom resource. + +_Required_ : Yes + +_Type_ : String + +`StackId` + + +The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource. + +Combining the `StackId` with the `RequestId` forms a value that you can use to uniquely identify a request on a particular custom resource. + +_Required_ : Yes + +_Type_ : String + +`ResponseURL` + + +The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to CloudFormation. + +_Required_ : Yes +