@aws-cdk/rtv¶
Runtime Values¶
The CDK allows apps to advertise values from construction time to runtime code. For example, consider code in a Lambda function which needs to know the URL of the SQS queue created as part of your CDK app.
Runtime values are advertised as textual SSM parameters with the following key:
/rtv/<stack-name>/<package>/<name>
Therefore, in order to advertise a value you will need to:
- Make the current stack name available as an environment variable to your
runtime code. The convention is to use
RTV_STACK_NAME
. - Use the
RuntimeValue
construct in order to create the SSM parameter and specify least-privilege permissions.
For example, say we want to publish a queue’s URL to a lambda function.
Construction Code¶
import { RuntimeValue } from '@aws-cdk/rtv'
const queue = new Queue(this, 'MyQueue', { /* props.... */ });
const fn = new Lambda(this, 'MyFunction', { /* props... */ });
const fleet = new Fleet(this, 'MyFleet', { /* props... */ });
// this line defines an AWS::SSM::Parameter resource with the
// key "/rtv/<stack-name>/com.myorg/MyQueueURL" and the actual queue URL as value
const queueUrlRtv = new RuntimeValue(this, 'QueueRTV', {
package: 'com.myorg',
name: 'MyQueueURL',
value: queue.queueUrl
});
// this line adds read permissions for this SSM parameter to the policies associated with
// the IAM roles of the Lambda function and the EC2 fleet
queueUrlRtv.grantRead(fn.role);
queueUrlRtv.grantRead(fleet.role);
// adds the `RTV_STACK_NAME` to the environment of the lambda function
// and the fleet (via user-data)
fn.env(RuntimeValue.ENV_NAME, RuntimeValue.ENV_VALUE);
fleet.env(RuntimeValue.ENV_NAME, RuntimeValue.ENV_VALUE);
Runtime Code¶
Then, your runtime code will need to use the SSM Parameter Store AWS SDK in order to format the SSM parameter key and read the value. In future releases, we will provide runtime libraries to make this easy.
Reference¶
ParameterName¶
RuntimeValue¶
-
class
_aws-cdk_rtv.
RuntimeValue
(parent, name, props)¶ Defines a value published from construction code which needs to be accessible by runtime code.
Extends: Construct
Parameters: - parent (
Construct
) – - name (string) –
- props (
RuntimeValueProps
) –
-
grantRead
([principal])¶ Grants a principal read permissions on this runtime value.
Parameters: principal ( IIdentityResource
or None) – The principal (e.g. Role, User, Group)
-
ENV_NAME
¶ The recommended name of the environment variable to use to set the stack name from which the runtime value is published.
Type: string (readonly) (static)
-
ENV_VALUE
¶ The value to assign to the RTV_STACK_NAME environment variable.
Type: AwsStackName
(readonly) (static)
-
parameterName
¶ The name of the runtime parameter.
Type: ParameterName
(readonly)
-
parameterArn
¶ The ARN fo the SSM parameter used for this runtime value.
Type: Arn
(readonly)
- parent (