You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[custom resource responses](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html), and
15
-
sends them to the custom resources. Subclasses implement the provisioning logic and configure certain properties of
16
-
these response objects.
11
+
Powertools-cloudformation makes it easy to write Lambda functions in Java that are used as CloudFormation custom resources.
12
+
The utility reads incoming CloudFormation events, calls your custom code depending on the operation (CREATE, UPDATE or DELETE) and sends responses back to CloudFormation.
13
+
By using this library you do not need to write code to integrate with CloudFormation, and you only focus on writing the custom provisioning logic inside the Lambda function.
17
14
18
15
## Install
19
16
@@ -40,57 +37,90 @@ To install this utility, add the following dependency to your project.
40
37
41
38
## Usage
42
39
43
-
Create a new `AbstractCustomResourceHandler` subclass and implement the `create`, `update`, and `delete` methods with
44
-
provisioning logic in the appropriate methods(s).
40
+
To utilise the feature, extend the `AbstractCustomResourceHandler` class in your Lambda handler class.
41
+
Next, implement and override the following 3 methods: `create`, `update` and `delete`. The `AbstractCustomResourceHandler` invokes the right method according to the CloudFormation [custom resource request event](
42
+
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requests.html) it receives.
43
+
Inside the methods, implement your custom provisioning logic, and return a `Response`. The `AbstractCustomResourceHandler` takes your `Response`, builds a
44
+
[custom resource responses](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-responses.html) and sends it to CloudFormation automatically.
45
45
46
-
As an example, if a Lambda function only needs to provision something when a stack is created, put the provisioning
47
-
logic exclusively within the `create` method; the other methods can just return `null`.
46
+
Custom resources notify cloudformation either of `SUCCESS` or `FAILED` status. You have 2 utility methods to represent these responses: `Response.success(physicalResourceId)` and `Response.failed(physicalResourceId)`.
47
+
The `physicalResourceId` is an identifier that is used during the lifecycle operations of the Custom Resource.
48
+
You should generate a `physicalResourceId` during the `CREATE` operation, CloudFormation stores the `physicalResourceId` and includes it in `UPDATE` and `DELETE` events.
48
49
49
-
```java hl_lines="8 9 10 11"
50
+
Here an example of how to implement a Custom Resource using the powertools-cloudformation library:
if(deleteResult.isSuccessful()){ //check if the delete operations were successful
87
+
returnResponse.success(physicalResourceId);
88
+
}else{
89
+
returnResponse.failed(physicalResourceId);
90
+
}
71
91
}
72
92
}
73
93
```
74
94
75
-
### Signaling Provisioning Failures
95
+
### Missing `Response` and exception handling
76
96
77
-
If provisioning fails, the stack creation/modification/deletion as a whole can be failed by either throwing a
78
-
`RuntimeException` or by explicitly returning a `Response` with a failed status, e.g. `Response.failure()`.
97
+
If a `Response` is not returned by your code, `AbstractCustomResourceHandler` defaults the response to `SUCCESS`.
98
+
If your code raises an exception (which is not handled), the `AbstractCustomResourceHandler` defaults the response to `FAILED`.
79
99
80
-
### Configuring Response Objects
100
+
In both of the scenarios, powertools-java will return the `physicalResourceId` to CloudFormation based on the following logic:
101
+
- For CREATE operations, the `LogStreamName` from the Lambda context is used.
102
+
- For UPDATE and DELETE operations, the `physicalResourceId` provided in the `CloudFormationCustomResourceEvent` is used.
81
103
82
-
When provisioning results in data to be shared with other parts of the stack, include this data within the returned
83
-
`Response` instance.
104
+
#### Why do you need a physicalResourceId?
84
105
85
-
This Lambda function creates a [Chime AppInstance](https://docs.aws.amazon.com/chime/latest/dg/create-app-instance.html)
106
+
It is recommended that you always explicitly provide a `physicalResourceId` in your response rather than letting powertools generate if for you because `physicalResourceId` has a crucial role in the lifecycle of a CloudFormation custom resource.
107
+
If the `physicalResourceId` changes between calls from Cloudformation, for instance in response to an `Update` event, Cloudformation [treats the resource update as a replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html).
108
+
109
+
### Customising a response
110
+
111
+
As well as the `Response.success(physicalResourceId)` and `Response.failed(physicalResourceId)`, you can customise the `Response` by using the `Response.builder()`.
112
+
You customise the responses when you need additional attributes to be shared with other parts of the CloudFormation stack.
113
+
114
+
In the example below, the Lambda function creates a [Chime AppInstance](https://docs.aws.amazon.com/chime/latest/dg/create-app-instance.html)
86
115
and maps the returned ARN to a "ChimeAppInstanceArn" attribute.
### Understanding the CloudFormation custom resource lifecycle
222
+
223
+
While the library provides an easy-to-use interface, we recommend that you understand the lifecycle of CloudFormation custom resources before using them in production.
224
+
225
+
#### Creating a custom resource
226
+
When CloudFormation issues a CREATE on a custom resource, there are 2 possible states: `CREATE_COMPLETE` and `CREATE_FAILED`
227
+
```mermaid
228
+
stateDiagram
229
+
direction LR
230
+
createState: Create custom resource
231
+
[*] --> createState
232
+
createState --> CREATE_COMPLETE
233
+
createState --> CREATE_FAILED
234
+
```
235
+
236
+
If the resource is created successfully, the `physicalResourceId` is stored by CloudFormation for future operations.
237
+
If the resource failed to create, CloudFormation triggers a rollback operation by default (rollback can be disabled, see [stack failure options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html))
238
+
239
+
#### Updating a custom resource
240
+
CloudFormation issues an UPDATE operation on a custom resource only when one or more custom resource properties change.
241
+
During the update, the custom resource may update successfully, or may fail the update.
242
+
```mermaid
243
+
stateDiagram
244
+
direction LR
245
+
updateState: Update custom resource
246
+
[*] --> updateState
247
+
updateState --> UPDATE_COMPLETE
248
+
updateState --> UPDATE_FAILED
249
+
```
250
+
251
+
In both of these scenarios, the custom resource can return the same `physicalResourceId` it received in the CloudFormation event, or a different `physicalResourceId`.
252
+
Semantically an `UPDATE_COMPLETE` that returns the same `physicalResourceId` it received indicates that the existing resource was updated successfully.
253
+
Instead, an `UPDATE_COMPLETE` with a different `physicalResourceId` means that a new physical resource was created successfully.
254
+
```mermaid
255
+
flowchart BT
256
+
id1(Logical resource)
257
+
id2(Previous physical Resource)
258
+
id3(New physical Resource)
259
+
id2 --> id1
260
+
id3 --> id1
261
+
```
262
+
Therefore, after the custom resource update completed or failed, there may be other cleanup operations by Cloudformation during the rollback, as described in the diagram below:
263
+
```mermaid
264
+
stateDiagram
265
+
state if_state <<choice>>
266
+
updateState: Update custom resource
267
+
deletePrev: DELETE resource with previous physicalResourceId
268
+
updatePrev: Rollback - UPDATE resource with previous properties
269
+
noOp: No further operations
270
+
[*] --> updateState
271
+
updateState --> UPDATE_COMPLETE
272
+
UPDATE_COMPLETE --> if_state
273
+
if_state --> noOp : Same physicalResourceId
274
+
if_state --> deletePrev : Different physicalResourceId
275
+
updateState --> UPDATE_FAILED
276
+
UPDATE_FAILED --> updatePrev
277
+
```
278
+
279
+
#### Deleting a custom resource
280
+
281
+
CloudFormation issues a DELETE on a custom resource when:
282
+
- the CloudFormation stack is being deleted
283
+
- a new `physicalResourceId` was received during an update, and CloudFormation proceeds to rollback(DELETE) the custom resource with the previous `physicalResourceId`.
0 commit comments