Bases: AwsCustomResource
CDK construct for reading SSM parameters from different AWS regions using custom resources.
This construct extends AWS CDK's AwsCustomResource to enable cross-region SSM parameter
access during CloudFormation deployment. It's particularly useful when your stack needs
to reference parameters that exist in a different region than where the stack is deployed.
The construct uses AWS SDK calls within a Lambda function to fetch parameter values
at deployment time, making them available as CloudFormation tokens within your stack.
This enables infrastructure that depends on configuration stored in centralized regions
or cross-region resource references.
Key Features:
- Cross-region SSM parameter access during deployment
- CloudFormation token integration for seamless parameter usage
- Automatic IAM policy creation for SSM access
- Timestamp-based physical resource ID for update handling
Inherits from
cr.AwsCustomResource: AWS CDK custom resource for SDK calls
Source code in mare_aws_common_lib/helpers/ssm_parameter_cross_region_reader.py
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109 | class SSMParameterCrossRegionReader(cr.AwsCustomResource):
"""
CDK construct for reading SSM parameters from different AWS regions using custom resources.
This construct extends AWS CDK's AwsCustomResource to enable cross-region SSM parameter
access during CloudFormation deployment. It's particularly useful when your stack needs
to reference parameters that exist in a different region than where the stack is deployed.
The construct uses AWS SDK calls within a Lambda function to fetch parameter values
at deployment time, making them available as CloudFormation tokens within your stack.
This enables infrastructure that depends on configuration stored in centralized regions
or cross-region resource references.
Key Features:
- Cross-region SSM parameter access during deployment
- CloudFormation token integration for seamless parameter usage
- Automatic IAM policy creation for SSM access
- Timestamp-based physical resource ID for update handling
Inherits from:
cr.AwsCustomResource: AWS CDK custom resource for SDK calls
"""
def __init__(self, scope: Construct, id: str, *, parameter_name: str, region: str):
"""
Initialize the cross-region SSM parameter reader construct.
Creates a custom resource that uses AWS SDK calls to retrieve an SSM parameter
from a specified region during CloudFormation deployment. The construct automatically
configures the necessary IAM permissions and SDK call parameters.
Args:
scope (Construct): CDK construct scope (typically a Stack or parent construct)
id (str): Unique identifier for this construct within the scope
parameter_name (str): Full name/path of the SSM parameter to retrieve.
Should include the complete parameter path (e.g., "/app/prod/database-url")
region (str): AWS region where the SSM parameter is located. Can be different
from the region where this stack is being deployed.
Notes:
- The construct creates a Lambda function that executes during deployment
- IAM permissions are automatically granted for SSM parameter access
- The physical resource ID uses a timestamp to ensure updates are triggered
- The parameter value is retrieved fresh on each stack update
- Works across regions within the same AWS account
IAM Permissions:
The construct automatically creates an IAM policy granting:
- ssm:GetParameter on all resources (*)
Limitations:
- Requires the parameter to exist at deployment time
- Cannot access parameters from different AWS accounts
- Subject to Lambda execution time limits for very large parameters
- The calling region must have SSM service availability
"""
current_timestamp_str = str(int(datetime.now(timezone.utc).timestamp()))
ssm_aws_sdk_call = cr.AwsSdkCall(
service="SSM",
action="getParameter",
parameters={
"Name": parameter_name
},
region=region,
physical_resource_id=cr.PhysicalResourceId.of(current_timestamp_str)
)
policy = cr.AwsCustomResourcePolicy.from_statements([
iam.PolicyStatement(
actions=["ssm:GetParameter"],
resources=["*"],
effect=iam.Effect.ALLOW
)
])
super().__init__(scope, id, on_update=ssm_aws_sdk_call, policy=policy)
def get_parameter_value(self) -> str:
"""
Retrieve the SSM parameter value as a CloudFormation token.
Returns the parameter value that was fetched from the specified region during
deployment. The returned value is a CloudFormation token that will be resolved
during stack deployment and can be used in other CDK constructs.
Returns:
str: CloudFormation token representing the parameter value. This token
will resolve to the actual parameter value during deployment.
Note:
- This method returns a token, not the actual parameter value
- The token will be resolved by CloudFormation during deployment
- The value cannot be used for synthesis-time logic or conditions
- Each call to this method returns the same token reference
- The parameter must exist and be accessible at deployment time
Raises:
RuntimeError: If called before the custom resource has been properly initialized
or if the parameter cannot be retrieved during deployment
"""
return self.get_response_field("Parameter.Value")
|
Functions
__init__(scope, id, *, parameter_name, region)
Initialize the cross-region SSM parameter reader construct.
Creates a custom resource that uses AWS SDK calls to retrieve an SSM parameter
from a specified region during CloudFormation deployment. The construct automatically
configures the necessary IAM permissions and SDK call parameters.
Parameters:
| Name |
Type |
Description |
Default |
scope
|
Construct
|
CDK construct scope (typically a Stack or parent construct)
|
required
|
id
|
str
|
Unique identifier for this construct within the scope
|
required
|
parameter_name
|
str
|
Full name/path of the SSM parameter to retrieve.
Should include the complete parameter path (e.g., "/app/prod/database-url")
|
required
|
region
|
str
|
AWS region where the SSM parameter is located. Can be different
from the region where this stack is being deployed.
|
required
|
Notes
- The construct creates a Lambda function that executes during deployment
- IAM permissions are automatically granted for SSM parameter access
- The physical resource ID uses a timestamp to ensure updates are triggered
- The parameter value is retrieved fresh on each stack update
- Works across regions within the same AWS account
IAM Permissions
The construct automatically creates an IAM policy granting:
- ssm:GetParameter on all resources (*)
Limitations
- Requires the parameter to exist at deployment time
- Cannot access parameters from different AWS accounts
- Subject to Lambda execution time limits for very large parameters
- The calling region must have SSM service availability
Source code in mare_aws_common_lib/helpers/ssm_parameter_cross_region_reader.py
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84 | def __init__(self, scope: Construct, id: str, *, parameter_name: str, region: str):
"""
Initialize the cross-region SSM parameter reader construct.
Creates a custom resource that uses AWS SDK calls to retrieve an SSM parameter
from a specified region during CloudFormation deployment. The construct automatically
configures the necessary IAM permissions and SDK call parameters.
Args:
scope (Construct): CDK construct scope (typically a Stack or parent construct)
id (str): Unique identifier for this construct within the scope
parameter_name (str): Full name/path of the SSM parameter to retrieve.
Should include the complete parameter path (e.g., "/app/prod/database-url")
region (str): AWS region where the SSM parameter is located. Can be different
from the region where this stack is being deployed.
Notes:
- The construct creates a Lambda function that executes during deployment
- IAM permissions are automatically granted for SSM parameter access
- The physical resource ID uses a timestamp to ensure updates are triggered
- The parameter value is retrieved fresh on each stack update
- Works across regions within the same AWS account
IAM Permissions:
The construct automatically creates an IAM policy granting:
- ssm:GetParameter on all resources (*)
Limitations:
- Requires the parameter to exist at deployment time
- Cannot access parameters from different AWS accounts
- Subject to Lambda execution time limits for very large parameters
- The calling region must have SSM service availability
"""
current_timestamp_str = str(int(datetime.now(timezone.utc).timestamp()))
ssm_aws_sdk_call = cr.AwsSdkCall(
service="SSM",
action="getParameter",
parameters={
"Name": parameter_name
},
region=region,
physical_resource_id=cr.PhysicalResourceId.of(current_timestamp_str)
)
policy = cr.AwsCustomResourcePolicy.from_statements([
iam.PolicyStatement(
actions=["ssm:GetParameter"],
resources=["*"],
effect=iam.Effect.ALLOW
)
])
super().__init__(scope, id, on_update=ssm_aws_sdk_call, policy=policy)
|
get_parameter_value()
Retrieve the SSM parameter value as a CloudFormation token.
Returns the parameter value that was fetched from the specified region during
deployment. The returned value is a CloudFormation token that will be resolved
during stack deployment and can be used in other CDK constructs.
Returns:
| Name | Type |
Description |
str |
str
|
CloudFormation token representing the parameter value. This token
will resolve to the actual parameter value during deployment.
|
Note
- This method returns a token, not the actual parameter value
- The token will be resolved by CloudFormation during deployment
- The value cannot be used for synthesis-time logic or conditions
- Each call to this method returns the same token reference
- The parameter must exist and be accessible at deployment time
Raises:
| Type |
Description |
RuntimeError
|
If called before the custom resource has been properly initialized
or if the parameter cannot be retrieved during deployment
|
Source code in mare_aws_common_lib/helpers/ssm_parameter_cross_region_reader.py
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109 | def get_parameter_value(self) -> str:
"""
Retrieve the SSM parameter value as a CloudFormation token.
Returns the parameter value that was fetched from the specified region during
deployment. The returned value is a CloudFormation token that will be resolved
during stack deployment and can be used in other CDK constructs.
Returns:
str: CloudFormation token representing the parameter value. This token
will resolve to the actual parameter value during deployment.
Note:
- This method returns a token, not the actual parameter value
- The token will be resolved by CloudFormation during deployment
- The value cannot be used for synthesis-time logic or conditions
- Each call to this method returns the same token reference
- The parameter must exist and be accessible at deployment time
Raises:
RuntimeError: If called before the custom resource has been properly initialized
or if the parameter cannot be retrieved during deployment
"""
return self.get_response_field("Parameter.Value")
|