pub enum CfnRequest<P>where
P: Clone,{
Create {
request_id: String,
response_url: String,
resource_type: String,
logical_resource_id: String,
stack_id: String,
resource_properties: P,
},
Delete {
request_id: String,
response_url: String,
resource_type: String,
logical_resource_id: String,
stack_id: String,
physical_resource_id: String,
resource_properties: P,
},
Update {
request_id: String,
response_url: String,
resource_type: String,
logical_resource_id: String,
stack_id: String,
physical_resource_id: String,
resource_properties: P,
old_resource_properties: P,
},
}
Expand description
On stack modification, AWS CloudFormation sends out a request for custom resources. This enum can represent such a request, encapsulating the three request variants:
- Creation of a custom resource.
- Update of a custom resource.
- Deletion of a custom resource.
(For more information on AWS CloudFormation custom resource requests, see docs.aws.amazon.com.)
When creating/updating a custom resource, AWS CloudFormation forwards any additional key-value
pairs the template designer provided with the request. To enable strict typing on this data,
CfnRequest
has the generic type parameter P
which the caller provides. This has to be a
deserializable type.
Example
The following is an example on how one can create a type that is deserializable through Serde, such that the untyped JSON map object provided by AWS CloudFormation can be converted into a strongly typed struct. (If the JSON is not compatible with the struct, deserialization and thus modification of the custom resource fails.)
#[derive(Debug, PartialEq, Clone, Deserialize)]
struct MyResourceProperties {
parameter1: String,
parameter2: Vec<String>,
}
let actual = serde_json::from_value(json!(
{
"parameter1": "example for the first parameter",
"parameter2": ["list", "of", "values"]
}
)).unwrap();
let expected = MyResourceProperties {
parameter1: "example for the first parameter".to_owned(),
parameter2: vec!["list".to_owned(), "of".to_owned(), "values".to_owned()],
};
assert_eq!(expected, actual);
Required presence of resource properties
If you have read the AWS CloudFormation documentation on custom resource requests, you might
have seen that the ResourceProperties
field on a request sent by AWS CloudFormation can be
optional, whereas all variants in this enum seem to require the field to be present.
The reason for the field being optional is (presumably) that AWS CloudFormation wants to support custom resources that do not require additional parameters besides the ones automatically sent by AWS CloudFormation, i.e. a custom resource might be just fine with only the stack ID.
Where this reasoning falls short, and where the documentation contradicts itself, is when it
comes to updating resources. For update requests it is documented that the
OldResourceProperties
field is mandatory. Now, what happens if you update a resource that
previously didn’t have any properties? Will the OldResourceProperties
field be present as the
documentation requires it to be, although it cannot have any (reasonable) content?
For this reason, and for the sake of simplicity in usage and implementation, the user of this library can decide whether they want all property fields to be required or optional. You have at least four options:
-
If your custom resource requires additional properties to function correctly, simply provide your type
T
as-is. -
If you want your resource to support custom resource properties, but not to depend on them, you can provide an
Option<T>
instead. -
Should you not need custom resource properties at all, but want the deserialization of the request to fail if any are provided, you can specify
Option<()>
. -
If you don’t need custom resource properties and don’t want to fail should they have been provided, you can specify
Ignored
as the type. This is a custom struct included in this library that deserializes any and no data into itself. This means that any data provided by AWS CloudFormation will be discarded, but it will also not fail if no data was present.
License attribution
The documentation for the CfnRequest
enum-variants and their fields has been taken unmodified
from the AWS CloudFormation Custom Resource Reference, which is licensed under CC BY-SA 4.0.
Variants§
Create
Fields
response_url: String
The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.
resource_type: String
The template developer-chosen resource type of the custom resource in the AWS
CloudFormation template. Custom resource type names can be up to 60 characters long and
can include alphanumeric and the following characters: _@-
.
logical_resource_id: String
The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.
stack_id: String
The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.
resource_properties: P
This field contains the contents of the Properties
object sent by the template
developer. Its contents are defined by the custom resource provider.
Custom resource provider requests with RequestType
set to “Create
” are sent when the
template developer creates a stack that contains a custom resource. See
docs.aws.amazon.com for more information.
Delete
Fields
response_url: String
The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.
resource_type: String
The template developer-chosen resource type of the custom resource in the AWS
CloudFormation template. Custom resource type names can be up to 60 characters long and
can include alphanumeric and the following characters: _@-
.
logical_resource_id: String
The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.
stack_id: String
The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.
physical_resource_id: String
A required custom resource provider-defined physical ID that is unique for that provider.
resource_properties: P
This field contains the contents of the Properties
object sent by the template
developer. Its contents are defined by the custom resource provider.
Custom resource provider requests with RequestType
set to “Delete
” are sent when the
template developer deletes a stack that contains a custom resource. To successfully delete a
stack with a custom resource, the custom resource provider must respond successfully to a
delete request. See docs.aws.amazon.com for more information.
Update
Fields
response_url: String
The response URL identifies a presigned S3 bucket that receives responses from the custom resource provider to AWS CloudFormation.
resource_type: String
The template developer-chosen resource type of the custom resource in the AWS
CloudFormation template. Custom resource type names can be up to 60 characters long and
can include alphanumeric and the following characters: _@-
.
logical_resource_id: String
The template developer-chosen name (logical ID) of the custom resource in the AWS CloudFormation template.
stack_id: String
The Amazon Resource Name (ARN) that identifies the stack that contains the custom resource.
physical_resource_id: String
A required custom resource provider-defined physical ID that is unique for that provider.
resource_properties: P
This field contains the contents of the Properties
object sent by the template
developer. Its contents are defined by the custom resource provider.
old_resource_properties: P
The resource property values that were previously declared by the template developer in the AWS CloudFormation template.
Custom resource provider requests with RequestType
set to “Update
” are sent when there’s
any change to the properties of the custom resource within the template. Therefore, custom
resource code doesn’t have to detect changes because it knows that its properties have
changed when Update is being called. See docs.aws.amazon.com for more information.
Implementations§
source§impl<P> CfnRequest<P>where
P: PhysicalResourceIdSuffixProvider + Clone,
impl<P> CfnRequest<P>where
P: PhysicalResourceIdSuffixProvider + Clone,
sourcepub fn request_id(&self) -> String
pub fn request_id(&self) -> String
The request ID field exists for all variants of the CfnRequest
enum. This is a helper
method to access this field without requiring you to match for the variant yourself.
sourcepub fn response_url(&self) -> String
pub fn response_url(&self) -> String
The response URL field exists for all variants of the CfnRequest
enum. This is a helper
method to access this field without requiring you to match for the variant yourself.
sourcepub fn resource_type(&self) -> String
pub fn resource_type(&self) -> String
The resource type field exists for all variants of the CfnRequest
enum. This is a helper
method to access this field without requiring you to match for the variant yourself.
sourcepub fn logical_resource_id(&self) -> String
pub fn logical_resource_id(&self) -> String
The logical resource ID field exists for all variants of the CfnRequest
enum. This is a
helper method to access this field without requiring you to match for the variant yourself.
sourcepub fn stack_id(&self) -> String
pub fn stack_id(&self) -> String
The stack ID field exists for all variants of the CfnRequest
enum. This is a helper
method to access this field without requiring you to match for the variant yourself.
sourcepub fn physical_resource_id(&self) -> String
pub fn physical_resource_id(&self) -> String
The physical resource ID field either exists or has to be (re)generated for all variants of
the CfnRequest
enum. This is a helper method to access this field without requiring you
to match for the variant yourself, while always getting the correct and up-to-date physical
resource ID.
sourcepub fn resource_properties(&self) -> &P
pub fn resource_properties(&self) -> &P
The resource properties field exists for all variants of the CfnRequest
enum. This is a
helper method to access this field without requiring you to match for the variant yourself.
sourcepub fn into_response<S>(self, result: &Result<Option<S>, Error>) -> CfnResponsewhere
S: Serialize,
pub fn into_response<S>(self, result: &Result<Option<S>, Error>) -> CfnResponsewhere
S: Serialize,
This method turns a CfnRequest
into a CfnResponse
, choosing one of the Success
or
Failed
variants based on a Result
. A CfnResponse
should always be created through
this method to ensure that all the relevant response-fields that AWS CloudFormation requires
are populated correctly.
Trait Implementations§
source§impl<P> Clone for CfnRequest<P>where
P: Clone + Clone,
impl<P> Clone for CfnRequest<P>where
P: Clone + Clone,
source§fn clone(&self) -> CfnRequest<P>
fn clone(&self) -> CfnRequest<P>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more