class CfnInclude (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.CloudFormation.Include.CfnInclude |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/cloudformationinclude#CfnInclude |
![]() | software.amazon.awscdk.cloudformation.include.CfnInclude |
![]() | aws_cdk.cloudformation_include.CfnInclude |
![]() | aws-cdk-lib » cloudformation_include » CfnInclude |
Implements
IConstruct
, IDependable
Construct to import an existing CloudFormation template file into a CDK application.
All resources defined in the template file can be retrieved by calling the getResource
method.
Any modifications made on the returned resource objects will be reflected in the resulting CDK template.
Example
const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
templateFile: 'my-template.json',
});
Initializer
new CfnInclude(scope: Construct, id: string, props: CfnIncludeProps)
Parameters
- scope
Construct
- id
string
- props
Cfn
Include Props
Construct Props
Name | Type | Description |
---|---|---|
template | string | Path to the template file. |
allow | boolean | Specifies whether to allow cyclical references, effectively disregarding safeguards meant to avoid undeployable templates. |
dehydrated | string[] | Specifies a list of LogicalIDs for resources that will be included in the CDK Stack, but will not be parsed and converted to CDK types. |
load | { [string]: Cfn } | Specifies the template files that define nested stacks that should be included. |
parameters? | { [string]: any } | Specifies parameters to be replaced by the values in this mapping. |
preserve | boolean | Whether the resources should have the same logical IDs in the resulting CDK template as they did in the original CloudFormation template file. |
templateFile
Type:
string
Path to the template file.
Both JSON and YAML template formats are supported.
allowCyclicalReferences?
Type:
boolean
(optional, default: will throw an error on detecting any cyclical references)
Specifies whether to allow cyclical references, effectively disregarding safeguards meant to avoid undeployable templates.
This should only be set to true in the case of templates utilizing cloud transforms (e.g. SAM) that after processing the transform will no longer contain any circular references.
dehydratedResources?
Type:
string[]
(optional, default: All resources are hydrated)
Specifies a list of LogicalIDs for resources that will be included in the CDK Stack, but will not be parsed and converted to CDK types.
This allows you to use CFN templates
that rely on Intrinsic placement that cfn-include
would otherwise reject, such as non-primitive values in resource update policies.
loadNestedStacks?
Type:
{ [string]:
Cfn
}
(optional, default: no nested stacks will be included)
Specifies the template files that define nested stacks that should be included.
If your template specifies a stack that isn't included here, it won't be created as a NestedStack
resource, and it won't be accessible from the CfnInclude.getNestedStack
method
(but will still be accessible from the CfnInclude.getResource
method).
If you include a stack here with an ID that isn't in the template, or is in the template but is not a nested stack, template creation will fail and an error will be thrown.
parameters?
Type:
{ [string]: any }
(optional, default: parameters will retain their original definitions)
Specifies parameters to be replaced by the values in this mapping.
Any parameters in the template that aren't specified here will be left unmodified. If you include a parameter here with an ID that isn't in the template, template creation will fail and an error will be thrown.
If you are importing a parameter from a live stack, we cannot know the value of that parameter. You will need to supply a value for your parameters, else the default value will be used.
preserveLogicalIds?
Type:
boolean
(optional, default: true)
Whether the resources should have the same logical IDs in the resulting CDK template as they did in the original CloudFormation template file.
If you're vending a Construct using an existing CloudFormation template,
make sure to pass this as false
.
Note: regardless of whether this option is true or false,
the CfnInclude.getResource
and related methods always uses the original logical ID of the resource/element,
as specified in the template file.
Properties
Name | Type | Description |
---|---|---|
creation | string[] | |
logical | string | The logical ID for this CloudFormation stack element. |
node | Node | The tree node. |
stack | Stack | The stack in which this element is defined. |
creationStack
Type:
string[]
logicalId
Type:
string
The logical ID for this CloudFormation stack element.
The logical ID of the element is calculated from the path of the resource node in the construct tree.
To override this value, use overrideLogicalId(newLogicalId)
.
node
Type:
Node
The tree node.
stack
Type:
Stack
The stack in which this element is defined.
CfnElements must be defined within a stack scope (directly or indirectly).
Methods
Name | Description |
---|---|
get | Returns the CfnCondition object from the 'Conditions' section of the CloudFormation template with the given name. |
get | Returns the CfnHook object from the 'Hooks' section of the included CloudFormation template with the given logical ID. |
get | Returns the CfnMapping object from the 'Mappings' section of the included template. |
get | Returns a loaded NestedStack with name logicalId. |
get | Returns the CfnOutput object from the 'Outputs' section of the included template. |
get | Returns the CfnParameter object from the 'Parameters' section of the included template. |
get | Returns the low-level CfnResource from the template with the given logical ID. |
get | Returns the CfnRule object from the 'Rules' section of the CloudFormation template with the given name. |
load | Includes a template for a child stack inside of this parent template. |
override | Overrides the auto-generated logical ID with a specific ID. |
to | Returns a string representation of this construct. |
getCondition(conditionName)
public getCondition(conditionName: string): CfnCondition
Parameters
- conditionName
string
— the name of the Condition in the CloudFormation template file.
Returns
Returns the CfnCondition object from the 'Conditions' section of the CloudFormation template with the given name.
Any modifications performed on that object will be reflected in the resulting CDK template.
If a Condition with the given name is not present in the template, throws an exception.
getHook(hookLogicalId)
public getHook(hookLogicalId: string): CfnHook
Parameters
- hookLogicalId
string
— the logical ID of the Hook in the included CloudFormation template's 'Hooks' section.
Returns
Returns the CfnHook object from the 'Hooks' section of the included CloudFormation template with the given logical ID.
Any modifications performed on the returned object will be reflected in the resulting CDK template.
If a Hook with the given logical ID is not present in the template, an exception will be thrown.
getMapping(mappingName)
public getMapping(mappingName: string): CfnMapping
Parameters
- mappingName
string
— the name of the Mapping in the template to retrieve.
Returns
Returns the CfnMapping object from the 'Mappings' section of the included template.
Any modifications performed on that object will be reflected in the resulting CDK template.
If a Mapping with the given name is not present in the template, an exception will be thrown.
getNestedStack(logicalId)
public getNestedStack(logicalId: string): IncludedNestedStack
Parameters
- logicalId
string
— the ID of the stack to retrieve, as it appears in the template.
Returns
Returns a loaded NestedStack with name logicalId.
For a nested stack to be returned by this method,
it must be specified either in the CfnIncludeProps.loadNestedStacks
property,
or through the loadNestedStack
method.
getOutput(logicalId)
public getOutput(logicalId: string): CfnOutput
Parameters
- logicalId
string
— the name of the output to retrieve.
Returns
Returns the CfnOutput object from the 'Outputs' section of the included template.
Any modifications performed on that object will be reflected in the resulting CDK template.
If an Output with the given name is not present in the template, throws an exception.
getParameter(parameterName)
public getParameter(parameterName: string): CfnParameter
Parameters
- parameterName
string
— the name of the parameter to retrieve.
Returns
Returns the CfnParameter object from the 'Parameters' section of the included template.
Any modifications performed on that object will be reflected in the resulting CDK template.
If a Parameter with the given name is not present in the template, throws an exception.
getResource(logicalId)
public getResource(logicalId: string): CfnResource
Parameters
- logicalId
string
— the logical ID of the resource in the CloudFormation template file.
Returns
Returns the low-level CfnResource from the template with the given logical ID.
Any modifications performed on that resource will be reflected in the resulting CDK template.
The returned object will be of the proper underlying class; you can always cast it to the correct type in your code:
// assume the template contains an AWS::S3::Bucket with logical ID 'Bucket'
const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
// cfnBucket is of type s3.CfnBucket
If the template does not contain a resource with the given logical ID, an exception will be thrown.
getRule(ruleName)
public getRule(ruleName: string): CfnRule
Parameters
- ruleName
string
— the name of the Rule in the CloudFormation template.
Returns
Returns the CfnRule object from the 'Rules' section of the CloudFormation template with the given name.
Any modifications performed on that object will be reflected in the resulting CDK template.
If a Rule with the given name is not present in the template, an exception will be thrown.
loadNestedStack(logicalId, nestedStackProps)
public loadNestedStack(logicalId: string, nestedStackProps: CfnIncludeProps): IncludedNestedStack
Parameters
- logicalId
string
— the ID of the stack to retrieve, as it appears in the template. - nestedStackProps
Cfn
— the properties of the included child Stack.Include Props
Returns
Includes a template for a child stack inside of this parent template.
A child with this logical ID must exist in the template,
and be of type AWS::CloudFormation::Stack.
This is equivalent to specifying the value in the CfnIncludeProps.loadNestedStacks
property on object construction.
overrideLogicalId(newLogicalId)
public overrideLogicalId(newLogicalId: string): void
Parameters
- newLogicalId
string
— The new logical ID to use for this stack element.
Overrides the auto-generated logical ID with a specific ID.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.