This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
Parameters
Parameters are custom values that are supplied at deployment time. Parameters are a feature of AWS CloudFormation. Since the AWS Cloud Development Kit (AWS CDK) synthesizes AWS CloudFormation templates, it also offers support for deployment-time parameters.
About parameters
Using the AWS CDK, you can define parameters, which can then be used in the properties of constructs you create. You can also deploy stacks that contain parameters.
When deploying the AWS CloudFormation template using the AWS CDK Toolkit, you provide the parameter values on the command line. If you deploy the template through the AWS CloudFormation console, you are prompted for the parameter values.
In general, we recommend against using AWS CloudFormation parameters with the AWS CDK. The usual ways to pass values into AWS CDK apps are context values and environment variables. Because they are not available at synthesis time, parameter values cannot be easily used for flow control and other purposes in your CDK app.
Note
To do control flow with parameters, you can use CfnCondition
constructs, although
this is awkward compared to native if
statements.
Using parameters requires you to be mindful of how the code you're writing behaves at deployment time, and also at synthesis time. This makes it harder to understand and reason about your AWS CDK application, in many cases for little benefit.
Generally, it's better to have your CDK app accept necessary information in a well-defined way and use it directly to declare constructs in your CDK app. An ideal AWS CDK–generated AWS CloudFormation template is concrete, with no values remaining to be specified at deployment time.
There are, however, use cases to which AWS CloudFormation parameters are uniquely suited. If you have separate teams defining and deploying infrastructure, for example, you can use parameters to make the generated templates more widely useful. Also, because the AWS CDK supports AWS CloudFormation parameters, you can use the AWS CDK with AWS services that use AWS CloudFormation templates (such as Service Catalog). These AWS services use parameters to configure the template that's being deployed.
Defining parameters
Use the CfnParameter
class to define a parameter. You'll want to specify at least a type and a
description for most parameters, though both are technically optional. The description appears when the user is
prompted to enter the parameter's value in the AWS CloudFormation console. For more information on the available types, see Types.
Note
You can define parameters in any scope. However, we recommend defining parameters at the stack level so that their logical ID doesn't change when you refactor your code.
Using parameters
A CfnParameter
instance exposes its value to your AWS CDK app via a token.
Like all tokens, the parameter's token is resolved at synthesis time. But it resolves to a reference to the parameter
defined in the AWS CloudFormation template (which will be resolved at deploy time), rather than to a concrete value.
You can retrieve the token as an instance of the Token
class, or in string, string list, or numeric
encoding. Your choice depends on the kind of value required by the class or method that you want to use the parameter
with.
For example, to use a parameter in a Bucket
definition:
Deploying with parameters
When you deploy a generated AWS CloudFormation template through the AWS CloudFormation console, you will be prompted to provide the values for each parameter.
You can also provide parameter values using the CDK CLI cdk deploy
command, or by specifying
parameter values in your CDK project’s stack file.
Providing parameter values with cdk deploy
When you deploy using the CDK CLI cdk deploy
command, you can provide parameter values at
deployment with the --parameters
option.
The following is an example of the cdk deploy
command structure:
$
cdk deploy
stack-logical-id
--parametersstack-name
:parameter-name
=parameter-value
If your CDK app contains a single stack, you don’t have to provide the stack logical ID argument or the
value in the stack-name
--parameters
option. The
CDK CLI will automatically find and provide these values. The following is an example that specifies an
uploadbucket
value for the uploadBucketName
parameter of the single stack in our
CDK app:
$
cdk deploy --parameters
uploadBucketName
=uploadbucket
Providing parameter values with cdk deploy for multi-stack applications
The following is an example CDK application in TypeScript that contains two CDK stacks. Each stack contains an Amazon S3 bucket instance and a parameter to set the Amazon S3 bucket name:
import * as cdk from 'aws-cdk-lib'; import { Construct } from 'constructs'; import * as s3 from 'aws-cdk-lib/aws-s3'; // Define the CDK app const app = new cdk.App(); // First stack export class MyFirstStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Set a default parameter name const bucketNameParam = new cdk.CfnParameter(this, 'bucketNameParam', { type: 'String', default: 'myfirststackdefaultbucketname' }); // Define an S3 bucket new s3.Bucket(this, 'MyFirstBucket', { bucketName: bucketNameParam.valueAsString }); } } // Second stack export class MySecondStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Set a default parameter name const bucketNameParam = new cdk.CfnParameter(this, 'bucketNameParam', { type: 'String', default: 'mysecondstackdefaultbucketname' }); // Define an S3 bucket new s3.Bucket(this, 'MySecondBucket', { bucketName: bucketNameParam.valueAsString }); } } // Instantiate the stacks new MyFirstStack(app, 'MyFirstStack', { stackName: 'MyFirstDeployedStack', }); new MySecondStack(app, 'MySecondStack', { stackName: 'MySecondDeployedStack', });
For CDK apps that contain multiple stacks, you can do the following:
-
Deploy one stack with parameters – To deploy a single stack from a multi-stack application, provide the stack logical ID as an argument.
The following is an example that deploys
MySecondStack
withmynewbucketname
as the parameter value forbucketNameParam
:$
cdk deploy
MySecondStack
--parametersbucketNameParam
='mynewbucketname'
-
Deploy all stacks and specify parameter values for each stack – Provide the
'*'
wildcard or the--all
option to deploy all stacks. Provide the--parameters
option multiple times in a single command to specify parameter values for each stack. The following is an example:$
cdk deploy
'*'
--parametersMyFirstDeployedStack
:bucketNameParam
='mynewfirststackbucketname'
--parametersMySecondDeployedStack
:bucketNameParam
='mynewsecondstackbucketname'
-
Deploy all stacks and specify parameter values for a single stack – Provide the
'*'
wildcard or the--all
option to deploy all stacks. Then, specify the stack to define the parameter for in the--parameters
option. The following are examples that deploys all stacks in a CDK app and specifies a parameter value for theMySecondDeployedStack
AWS CloudFormation stack. All other stacks will deploy and use the default parameter value:$
cdk deploy
'*'
--parametersMySecondDeployedStack
:bucketNameParam
='mynewbucketname'
$
cdk deploy
--all
--parametersMySecondDeployedStack
:bucketNameParam
='mynewbucketname'
Providing parameter values with cdk deploy for applications with nested stacks
The CDK CLI behavior when working with applications containing nested stacks is similar to multi-stack
applications. The main difference is, if you want to deploy all nested stacks, use the '**'
wildcard.
The '*'
wildcard deploys all stacks but will not deploy nested stacks. The '**'
wildcard
deploys all stacks, including nested stacks.
The following is an example that deploys nested stacks while specifying the parameter value for one nested stack:
$
cdk deploy
'**'
--parametersMultiStackCdkApp/SecondStack
:bucketNameParam
='mysecondstackbucketname'
For more information on cdk deploy
command options, see cdk deploy.