This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

@aws-cdk/runtime-values

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:

  1. Make the current stack name available as an environment variable to your runtime code. The convention is to use RTV_STACK_NAME.
  2. 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/runtime-values'

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

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.RuntimeValues" Version="0.25.3" />

dotnet:

dotnet add package Amazon.CDK.RuntimeValues --version 0.25.3

packages.config:

<package id="Amazon.CDK.RuntimeValues" version="0.25.3" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:cdk-runtime-values:jar:0.25.3'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="cdk-runtime-values" rev="0.25.3"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>cdk-runtime-values</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:cdk-runtime-values:0.25.3'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='cdk-runtime-values', version='0.25.3')
)

View in NPM

npm:

$ npm i @aws-cdk/runtime-values@0.25.3

package.json:

{
  "@aws-cdk/runtime-values": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/runtime-values@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/runtime-values@0.25.3

package.json:

{
  "@aws-cdk/runtime-values": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/runtime-values@0.25.3

RuntimeValue

class @aws-cdk/runtime-values.RuntimeValue(scope, id, props)

Language-specific names:

using Amazon.CDK.RuntimeValues;
import software.amazon.awscdk.runtimevalues.RuntimeValue;
const { RuntimeValue } = require('@aws-cdk/runtime-values');
import { RuntimeValue } from '@aws-cdk/runtime-values';

Defines a value published from construction code which needs to be accessible

by runtime code.

Extends:

@aws-cdk/cdk.Construct

Parameters:
grantRead([principal])

Grants a principal read permissions on this runtime value.

Parameters:principal (@aws-cdk/aws-iam.IPrincipal (optional)) – 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)
envValue

The value to assign to the RTV_STACK_NAME environment variable.

Type:string (readonly)
parameterArn

The ARN fo the SSM parameter used for this runtime value.

Type:string (readonly)
parameterName

The name of the runtime parameter.

Type:string (readonly)
prepare()

Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

RuntimeValueProps (interface)

class @aws-cdk/runtime-values.RuntimeValueProps

Language-specific names:

using Amazon.CDK.RuntimeValues;
import software.amazon.awscdk.runtimevalues.RuntimeValueProps;
// RuntimeValueProps is an interface
import { RuntimeValueProps } from '@aws-cdk/runtime-values';
package

A namespace for the runtime value.

It is recommended to use the name of the library/package that advertises this value.

Type:string
value

The value to advertise. Can be either a primitive value or a token.

Type:any