Skip to content

Latest commit

 

History

History
2898 lines (1824 loc) · 92.6 KB

API.md

File metadata and controls

2898 lines (1824 loc) · 92.6 KB

API Reference

Structs

BootstrapOptions

Options to use with cdk bootstrap.

Initializer 

import { BootstrapOptions } from '@aws-cdk/cli-lib-alpha'

const bootstrapOptions: BootstrapOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
bootstrapBucketName string The name of the CDK toolkit bucket;
bootstrapCustomerKey string Create a Customer Master Key (CMK) for the bootstrap bucket (you will be charged but can customize permissions, modern bootstrapping only).
bootstrapKmsKeyId string AWS KMS master key ID used for the SSE-KMS encryption.
cfnExecutionPolicy string The Managed Policy ARNs that should be attached to the role performing deployments into this environment (may be repeated, modern bootstrapping only).
customPermissionsBoundary string Use the permissions boundary specified by name.
environments string[] The target AWS environments to deploy the bootstrap stack to.
examplePermissionsBoundary boolean Use the example permissions boundary.
execute boolean Whether to execute ChangeSet (--no-execute will NOT execute the ChangeSet).
force boolean Always bootstrap even if it would downgrade template version.
publicAccessBlockConfiguration string Block public access configuration on CDK toolkit bucket (enabled by default).
qualifier string String which must be unique for each bootstrap stack.
showTemplate boolean Instead of actual bootstrapping, print the current CLI's bootstrapping template to stdout for customization.
template string Use the template from the given file instead of the built-in one (use --show-template to obtain an example).
terminationProtection boolean Toggle CloudFormation termination protection on the bootstrap stacks.
toolkitStackName string The name of the CDK toolkit stack to create.
trust string The AWS account IDs that should be trusted to perform deployments into this environment (may be repeated, modern bootstrapping only).
trustForLookup string The AWS account IDs that should be trusted to look up values in this environment (may be repeated, modern bootstrapping only).
usePreviousParameters boolean Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled).
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

bootstrapBucketNameOptional 
public readonly bootstrapBucketName: string;
  • Type: string
  • Default: auto-generated CloudFormation name

The name of the CDK toolkit bucket;

bucket will be created and must not exist

bootstrapCustomerKeyOptional 
public readonly bootstrapCustomerKey: string;
  • Type: string
  • Default: undefined

Create a Customer Master Key (CMK) for the bootstrap bucket (you will be charged but can customize permissions, modern bootstrapping only).

bootstrapKmsKeyIdOptional 
public readonly bootstrapKmsKeyId: string;
  • Type: string
  • Default: undefined

AWS KMS master key ID used for the SSE-KMS encryption.

cfnExecutionPolicyOptional 
public readonly cfnExecutionPolicy: string;
  • Type: string
  • Default: none

The Managed Policy ARNs that should be attached to the role performing deployments into this environment (may be repeated, modern bootstrapping only).

customPermissionsBoundaryOptional 
public readonly customPermissionsBoundary: string;
  • Type: string
  • Default: undefined

Use the permissions boundary specified by name.

environmentsOptional 
public readonly environments: string[];
  • Type: string[]
  • Default: Bootstrap all environments referenced in the CDK app or determine an environment from local configuration.

The target AWS environments to deploy the bootstrap stack to.

Uses the following format: aws://<account-id>/<region>

Example

"aws://123456789012/us-east-1"
examplePermissionsBoundaryOptional 
public readonly examplePermissionsBoundary: boolean;
  • Type: boolean
  • Default: undefined

Use the example permissions boundary.

executeOptional 
public readonly execute: boolean;
  • Type: boolean
  • Default: true

Whether to execute ChangeSet (--no-execute will NOT execute the ChangeSet).

forceOptional 
public readonly force: boolean;
  • Type: boolean
  • Default: false

Always bootstrap even if it would downgrade template version.

publicAccessBlockConfigurationOptional 
public readonly publicAccessBlockConfiguration: string;
  • Type: string
  • Default: undefined

Block public access configuration on CDK toolkit bucket (enabled by default).

qualifierOptional 
public readonly qualifier: string;
  • Type: string
  • Default: undefined

String which must be unique for each bootstrap stack.

You must configure it on your CDK app if you change this from the default.

showTemplateOptional 
public readonly showTemplate: boolean;
  • Type: boolean
  • Default: false

Instead of actual bootstrapping, print the current CLI's bootstrapping template to stdout for customization.

templateOptional 
public readonly template: string;
  • Type: string

Use the template from the given file instead of the built-in one (use --show-template to obtain an example).

terminationProtectionOptional 
public readonly terminationProtection: boolean;
  • Type: boolean
  • Default: false

Toggle CloudFormation termination protection on the bootstrap stacks.

toolkitStackNameOptional 
public readonly toolkitStackName: string;
  • Type: string

The name of the CDK toolkit stack to create.

trustOptional 
public readonly trust: string;
  • Type: string
  • Default: undefined

The AWS account IDs that should be trusted to perform deployments into this environment (may be repeated, modern bootstrapping only).

trustForLookupOptional 
public readonly trustForLookup: string;
  • Type: string
  • Default: undefined

The AWS account IDs that should be trusted to look up values in this environment (may be repeated, modern bootstrapping only).

usePreviousParametersOptional 
public readonly usePreviousParameters: boolean;
  • Type: boolean
  • Default: true

Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled).

CdkAppDirectoryProps

Configuration for creating a CLI from an AWS CDK App directory.

Initializer 

import { CdkAppDirectoryProps } from '@aws-cdk/cli-lib-alpha'

const cdkAppDirectoryProps: CdkAppDirectoryProps = { ... }

Properties

Name Type Description
app string Command-line for executing your app or a cloud assembly directory e.g. "node bin/my-app.js" or "cdk.out".
output string Emits the synthesized cloud assembly into a directory.
appOptional 
public readonly app: string;
  • Type: string
  • Default: read from cdk.json

Command-line for executing your app or a cloud assembly directory e.g. "node bin/my-app.js" or "cdk.out".

outputOptional 
public readonly output: string;
  • Type: string
  • Default: cdk.out

Emits the synthesized cloud assembly into a directory.

DeployOptions

Options to use with cdk deploy.

Initializer 

import { DeployOptions } from '@aws-cdk/cli-lib-alpha'

const deployOptions: DeployOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
assetParallelism boolean Whether to build/publish assets in parallel.
assetPrebuild boolean Whether to build all assets before deploying the first stack (useful for failing Docker builds).
changeSetName string Optional name to use for the CloudFormation change set.
ci boolean Whether we are on a CI system.
concurrency number Maximum number of simultaneous deployments (dependency permitting) to execute.
exclusively boolean Only perform action on the given stack.
execute boolean Whether to execute the ChangeSet Not providing execute parameter will result in execution of ChangeSet.
force boolean Always deploy, even if templates are identical.
hotswap HotswapMode No description.
notificationArns string[] ARNs of SNS topics that CloudFormation will notify with stack related events.
outputsFile string Path to file where stack outputs will be written after a successful deploy as JSON.
parameters {[ key: string ]: string} Additional parameters for CloudFormation at deploy time.
progress StackActivityProgress Display mode for stack activity events.
requireApproval RequireApproval What kind of security changes require approval.
reuseAssets string[] Reuse the assets with the given asset IDs.
rollback boolean Rollback failed deployments.
toolkitStackName string Name of the toolkit stack to use/deploy.
usePreviousParameters boolean Use previous values for unspecified parameters.
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

assetParallelismOptional 
public readonly assetParallelism: boolean;
  • Type: boolean
  • Default: false

Whether to build/publish assets in parallel.

assetPrebuildOptional 
public readonly assetPrebuild: boolean;
  • Type: boolean
  • Default: true

Whether to build all assets before deploying the first stack (useful for failing Docker builds).

changeSetNameOptional 
public readonly changeSetName: string;
  • Type: string
  • Default: auto generate a name

Optional name to use for the CloudFormation change set.

If not provided, a name will be generated automatically.

ciOptional 
public readonly ci: boolean;
  • Type: boolean
  • Default: false unless the environment variable CI is set

Whether we are on a CI system.

concurrencyOptional 
public readonly concurrency: number;
  • Type: number
  • Default: 1

Maximum number of simultaneous deployments (dependency permitting) to execute.

exclusivelyOptional 
public readonly exclusively: boolean;
  • Type: boolean
  • Default: false

Only perform action on the given stack.

executeOptional 
public readonly execute: boolean;
  • Type: boolean
  • Default: true

Whether to execute the ChangeSet Not providing execute parameter will result in execution of ChangeSet.

forceOptional 
public readonly force: boolean;
  • Type: boolean
  • Default: false

Always deploy, even if templates are identical.

hotswapOptional 
public readonly hotswap: HotswapMode;
notificationArnsOptional 
public readonly notificationArns: string[];
  • Type: string[]
  • Default: no notifications

ARNs of SNS topics that CloudFormation will notify with stack related events.

outputsFileOptional 
public readonly outputsFile: string;
  • Type: string
  • Default: Outputs are not written to any file

Path to file where stack outputs will be written after a successful deploy as JSON.

parametersOptional 
public readonly parameters: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: {}

Additional parameters for CloudFormation at deploy time.

progressOptional 
public readonly progress: StackActivityProgress;

Display mode for stack activity events.

The default in the CLI is StackActivityProgress.BAR. But since this is an API it makes more sense to set the default to StackActivityProgress.EVENTS

requireApprovalOptional 
public readonly requireApproval: RequireApproval;

What kind of security changes require approval.

reuseAssetsOptional 
public readonly reuseAssets: string[];
  • Type: string[]
  • Default: do not reuse assets

Reuse the assets with the given asset IDs.

rollbackOptional 
public readonly rollback: boolean;
  • Type: boolean
  • Default: true

Rollback failed deployments.

toolkitStackNameOptional 
public readonly toolkitStackName: string;
  • Type: string
  • Default: CDKToolkit

Name of the toolkit stack to use/deploy.

usePreviousParametersOptional 
public readonly usePreviousParameters: boolean;
  • Type: boolean
  • Default: true

Use previous values for unspecified parameters.

If not set, all parameters must be specified for every deployment.

DestroyOptions

Options to use with cdk destroy.

Initializer 

import { DestroyOptions } from '@aws-cdk/cli-lib-alpha'

const destroyOptions: DestroyOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
exclusively boolean Only destroy the given stack.
requireApproval boolean Should the script prompt for approval before destroying stacks.
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

exclusivelyOptional 
public readonly exclusively: boolean;
  • Type: boolean
  • Default: false

Only destroy the given stack.

requireApprovalOptional 
public readonly requireApproval: boolean;
  • Type: boolean
  • Default: false

Should the script prompt for approval before destroying stacks.

ListOptions

Options for cdk list.

Initializer 

import { ListOptions } from '@aws-cdk/cli-lib-alpha'

const listOptions: ListOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
long boolean Display environment information for each stack.
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

longOptional 
public readonly long: boolean;
  • Type: boolean
  • Default: false

Display environment information for each stack.

SharedOptions

AWS CDK CLI options that apply to all commands.

Initializer 

import { SharedOptions } from '@aws-cdk/cli-lib-alpha'

const sharedOptions: SharedOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

SynthOptions

Options to use with cdk synth.

Initializer 

import { SynthOptions } from '@aws-cdk/cli-lib-alpha'

const synthOptions: SynthOptions = { ... }

Properties

Name Type Description
assetMetadata boolean Include "aws:asset:*" CloudFormation metadata for resources that use assets.
caBundlePath string Path to CA certificate to use when validating HTTPS requests.
color boolean Show colors and other style from console output.
context {[ key: string ]: string} Additional context.
debug boolean enable emission of additional debugging information, such as creation stack traces of tokens.
ec2Creds boolean Force trying to fetch EC2 instance credentials.
ignoreErrors boolean Ignores synthesis errors, which will likely produce an invalid output.
json boolean Use JSON output instead of YAML when templates are printed to STDOUT.
lookups boolean Perform context lookups.
notices boolean Show relevant notices.
pathMetadata boolean Include "aws:cdk:path" CloudFormation metadata for each resource.
profile string Use the indicated AWS profile as the default environment.
proxy string Use the indicated proxy.
roleArn string Role to pass to CloudFormation for deployment.
stacks string[] List of stacks to deploy.
staging boolean Copy assets to the output directory.
strict boolean Do not construct stacks with warnings.
trace boolean Print trace for stack warnings.
verbose boolean show debug logs.
versionReporting boolean Include "AWS::CDK::Metadata" resource in synthesized templates.
exclusively boolean Only synthesize the given stack.
quiet boolean Do not output CloudFormation Template to stdout.
validation boolean After synthesis, validate stacks with the "validateOnSynth" attribute set (can also be controlled with CDK_VALIDATION).
assetMetadataOptional 
public readonly assetMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:asset:*" CloudFormation metadata for resources that use assets.

caBundlePathOptional 
public readonly caBundlePath: string;
  • Type: string
  • Default: read from AWS_CA_BUNDLE environment variable

Path to CA certificate to use when validating HTTPS requests.

colorOptional 
public readonly color: boolean;
  • Type: boolean
  • Default: true unless the environment variable NO_COLOR is set

Show colors and other style from console output.

contextOptional 
public readonly context: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no additional context

Additional context.

debugOptional 
public readonly debug: boolean;
  • Type: boolean
  • Default: false

enable emission of additional debugging information, such as creation stack traces of tokens.

ec2CredsOptional 
public readonly ec2Creds: boolean;
  • Type: boolean
  • Default: guess EC2 instance status

Force trying to fetch EC2 instance credentials.

ignoreErrorsOptional 
public readonly ignoreErrors: boolean;
  • Type: boolean
  • Default: false

Ignores synthesis errors, which will likely produce an invalid output.

jsonOptional 
public readonly json: boolean;
  • Type: boolean
  • Default: false

Use JSON output instead of YAML when templates are printed to STDOUT.

lookupsOptional 
public readonly lookups: boolean;
  • Type: boolean
  • Default: true

Perform context lookups.

Synthesis fails if this is disabled and context lookups need to be performed

noticesOptional 
public readonly notices: boolean;
  • Type: boolean
  • Default: true

Show relevant notices.

pathMetadataOptional 
public readonly pathMetadata: boolean;
  • Type: boolean
  • Default: true

Include "aws:cdk:path" CloudFormation metadata for each resource.

profileOptional 
public readonly profile: string;
  • Type: string
  • Default: no profile is used

Use the indicated AWS profile as the default environment.

proxyOptional 
public readonly proxy: string;
  • Type: string
  • Default: no proxy

Use the indicated proxy.

Will read from HTTPS_PROXY environment if specified

roleArnOptional 
public readonly roleArn: string;
  • Type: string
  • Default: use the bootstrap cfn-exec role

Role to pass to CloudFormation for deployment.

stacksOptional 
public readonly stacks: string[];
  • Type: string[]
  • Default: all stacks

List of stacks to deploy.

stagingOptional 
public readonly staging: boolean;
  • Type: boolean
  • Default: false

Copy assets to the output directory.

Needed for local debugging the source files with SAM CLI

strictOptional 
public readonly strict: boolean;
  • Type: boolean
  • Default: false

Do not construct stacks with warnings.

traceOptional 
public readonly trace: boolean;
  • Type: boolean
  • Default: false

Print trace for stack warnings.

verboseOptional 
public readonly verbose: boolean;
  • Type: boolean
  • Default: false

show debug logs.

versionReportingOptional 
public readonly versionReporting: boolean;
  • Type: boolean
  • Default: true

Include "AWS::CDK::Metadata" resource in synthesized templates.

exclusivelyOptional 
public readonly exclusively: boolean;
  • Type: boolean
  • Default: false

Only synthesize the given stack.

quietOptional 
public readonly quiet: boolean;
  • Type: boolean
  • Default: false;

Do not output CloudFormation Template to stdout.

validationOptional 
public readonly validation: boolean;
  • Type: boolean
  • Default: true;

After synthesis, validate stacks with the "validateOnSynth" attribute set (can also be controlled with CDK_VALIDATION).

Classes

AwsCdkCli

Provides a programmatic interface for interacting with the AWS CDK CLI.

Methods

Name Description
bootstrap cdk bootstrap.
deploy cdk deploy.
destroy cdk destroy.
list cdk list.
synth cdk synth.
bootstrap 
public bootstrap(options?: BootstrapOptions): void

cdk bootstrap.

optionsOptional
deploy 
public deploy(options?: DeployOptions): void

cdk deploy.

optionsOptional
destroy 
public destroy(options?: DestroyOptions): void

cdk destroy.

optionsOptional
list 
public list(options?: ListOptions): void

cdk list.

optionsOptional
synth 
public synth(options?: SynthOptions): void

cdk synth.

optionsOptional

Static Functions

Name Description
fromCdkAppDirectory Create the CLI from a directory containing an AWS CDK app.
fromCloudAssemblyDirectoryProducer Create the CLI from a CloudAssemblyDirectoryProducer.
fromCdkAppDirectory 
import { AwsCdkCli } from '@aws-cdk/cli-lib-alpha'

AwsCdkCli.fromCdkAppDirectory(directory?: string, props?: CdkAppDirectoryProps)

Create the CLI from a directory containing an AWS CDK app.

directoryOptional
  • Type: string

the directory of the AWS CDK app.

Defaults to the current working directory.

propsOptional

additional configuration properties.

fromCloudAssemblyDirectoryProducer 
import { AwsCdkCli } from '@aws-cdk/cli-lib-alpha'

AwsCdkCli.fromCloudAssemblyDirectoryProducer(producer: ICloudAssemblyDirectoryProducer)

Create the CLI from a CloudAssemblyDirectoryProducer.

producerRequired

Protocols

IAwsCdkCli

AWS CDK CLI operations.

Methods

Name Description
bootstrap cdk bootstrap.
deploy cdk deploy.
destroy cdk destroy.
list cdk list.
synth cdk synth.
bootstrap 
public bootstrap(options?: BootstrapOptions): void

cdk bootstrap.

optionsOptional
deploy 
public deploy(options?: DeployOptions): void

cdk deploy.

optionsOptional
destroy 
public destroy(options?: DestroyOptions): void

cdk destroy.

optionsOptional
list 
public list(options?: ListOptions): void

cdk list.

optionsOptional
synth 
public synth(options?: SynthOptions): void

cdk synth.

optionsOptional

ICloudAssemblyDirectoryProducer

A class returning the path to a Cloud Assembly Directory when its produce method is invoked with the current context AWS CDK apps might need to be synthesized multiple times with additional context values before they are ready.

When running the CLI from inside a directory, this is implemented by invoking the app multiple times. Here the produce() method provides this multi-pass ability.

Methods

Name Description
produce Synthesize a Cloud Assembly directory for a given context.
produce 
public produce(context: {[ key: string ]: any}): string

Synthesize a Cloud Assembly directory for a given context.

For all features to work correctly, cdk.App() must be instantiated with the received context values in the method body. Usually obtained similar to this:

class MyProducer implements ICloudAssemblyDirectoryProducer {
  async produce(context: Record<string, any>) {
    const app = new cdk.App({ context });
    // create stacks here
    return app.synth().directory;
  }
}
contextRequired
  • Type: {[ key: string ]: any}

Properties

Name Type Description
workingDirectory string The working directory used to run the Cloud Assembly from.
workingDirectoryOptional 
public readonly workingDirectory: string;
  • Type: string
  • Default: current working directory

The working directory used to run the Cloud Assembly from.

This is were a cdk.context.json files will be written.

Enums

HotswapMode

Members

Name Description
FALL_BACK Will fall back to CloudFormation when a non-hotswappable change is detected.
HOTSWAP_ONLY Will not fall back to CloudFormation when a non-hotswappable change is detected.
FULL_DEPLOYMENT Will not attempt to hotswap anything and instead go straight to CloudFormation.
FALL_BACK

Will fall back to CloudFormation when a non-hotswappable change is detected.

HOTSWAP_ONLY

Will not fall back to CloudFormation when a non-hotswappable change is detected.

FULL_DEPLOYMENT

Will not attempt to hotswap anything and instead go straight to CloudFormation.

RequireApproval

In what scenarios should the CLI ask for approval.

Members

Name Description
NEVER Never ask for approval.
ANYCHANGE Prompt for approval for any type of change to the stack.
BROADENING Only prompt for approval if there are security related changes.
NEVER

Never ask for approval.

ANYCHANGE

Prompt for approval for any type of change to the stack.

BROADENING

Only prompt for approval if there are security related changes.

StackActivityProgress

Supported display modes for stack deployment activity.

Members

Name Description
BAR Displays a progress bar with only the events for the resource currently being deployed.
EVENTS Displays complete history with all CloudFormation stack events.
BAR

Displays a progress bar with only the events for the resource currently being deployed.

EVENTS

Displays complete history with all CloudFormation stack events.