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 Tools

Command-line Toolkit (cdk)

cdk (the AWS CDK Toolkit) is the main tool you use to interact with your |*CDK App*|. It executes the CDK app you have written and compiled, interrogates the application model you have defined, and produces and deploys the AWS CloudFormation templates generated by the AWS CDK.

There are two ways that you can tell cdk what command to use to run your CDK app. The first way is to include an explicit --app option whenever you use a cdk command:

cdk --app 'node bin/main.js' synth

The second way is to add the following entry to the file cdk.json:

{
   "app": "node bin/main.js"
}

Here are the actions you can take on your CDK app (this is the output of the cdk --help command):

Usage: cdk -a <cdk-app> COMMAND

Commands:
  list                        Lists all stacks in the app          [aliases: ls]
  synthesize [STACKS..]       Synthesizes and prints the CloudFormation template
                              for this stack                    [aliases: synth]
  bootstrap [ENVIRONMENTS..]  Deploys the CDK toolkit stack into an AWS
                              environment
  deploy [STACKS..]           Deploys the stack(s) named STACKS into your AWS
                              account
  destroy [STACKS..]          Destroy the stack(s) named STACKS
  diff [STACK]                Compares the specified stack with the deployed
                              stack or a local template file
  metadata [STACK]            Returns all metadata associated with this stack
  init [TEMPLATE]             Create a new, empty CDK project from a template.
                              Invoked without TEMPLATE, the app template will be
                              used.
  docs                        Opens the documentation in a browser[aliases: doc]
  doctor                      Check your set-up for potential problems

Options:
  --app, -a            REQUIRED: Command-line for executing your CDK app (e.g.
                       "node bin/my-app.js")                            [string]
  --context, -c        Add contextual string parameter.                  [array]
  --plugin, -p         Name or path of a node package that extend the CDK
                       features. Can be specified multiple times         [array]
  --rename             Rename stack name if different from the one defined in
                       the cloud executable                             [string]
  --trace              Print trace for stack warnings                  [boolean]
  --strict             Do not construct stacks with warnings           [boolean]
  --ignore-errors      Ignores synthesis errors, which will likely produce an
                       invalid output                 [boolean] [default: false]
  --json, -j           Use JSON output instead of YAML                 [boolean]
  --verbose, -v        Show debug logs                                 [boolean]
  --profile            Use the indicated AWS profile as the default environment
                                                                        [string]
  --proxy              Use the indicated proxy. Will read from HTTPS_PROXY
                       environment variable if not specified.           [string]
  --ec2creds, -i       Force trying to fetch EC2 instance credentials. Default:
                       guess EC2 instance status.                      [boolean]
  --version-reporting  Disable insersion of the CDKMetadata resource in
                       synthesized templates                           [boolean]
  --role-arn, -r       ARN of Role to use when invoking CloudFormation  [string]
  --version            Show version number                             [boolean]
  --help               Show help                                       [boolean]

If your app has a single stack, there is no need to specify the stack name

If one of cdk.json or ~/.cdk.json exists, options specified there will be used
as defaults. Settings in cdk.json take precedence.

Configuration

The CDK toolkit resolves its configuration by reading files in the following order:

  1. ~/.cdk.json: user-level configuration file
  2. cdk.json: project configuration file
  3. Command line arguments

The following options are supported in cdk.json:

  • app (string): the command-line to use in order to invoke your CDK app.
  • browser (string): the command to use to open the browser, using %u as a placeholder for the path of the file to open
  • context (hash): key-value pairs of context values which can later be read by Construct.getContext(key)
  • language (string): programming langauge to use for cdk-init
  • pathMetadata (boolean): Include “aws:cdk:path” CloudFormation metadata for each resource (enabled by default)
  • plugin (array): Name or path of a node package that extend the CDK features
  • requireApproval (string): what security-sensitive changes need manual approval (choices: “never”, “any-change”, “broadening”)
  • toolkitStackName (string): the name of the CDK toolkit stack
  • versionReporting (boolean): Include the “AWS::CDK::Metadata” resource in synthesized templates

Version Reporting

In order to gain insights in how the AWS CDK is used, the versions of libraries used by AWS CDK applications are collected and reported using a resource identified as AWS::CDK::Metadata that is added to CloudFormation templates, and can easily be reviewed. This information may also be used to identify stacks using a package with known serious security or reliability issues and contact their users with important information.

The AWS CDK reports the name and version of npm modules that are loaded into the application at synthesis time, unless their package.json file contains the "private": true attribute.

The AWS::CDK::Metadata resource looks like the following:

CDKMetadata:
  Type: "AWS::CDK::Metadata"
  Properties:
    Modules: "@aws-cdk/core=0.7.2-beta,@aws-cdk/s3=0.7.2-beta,lodash=4.17.10"

Opting-out from Version Reporting

To out-out, use one of the following methods:

  • Use the --no-version-reporting in cdk invocations:

    cdk --no-version-reporting synth
    
  • Set versionReporting to false in ./cdk.json or ~/cdk.json:

    {
      "app": "...",
      "versionReporting": false
    }
    

Plugins

The AWS CDK toolkit provides extension points that enable users to augment the features provided by the toolkit. There is currently only one extension point, allowing users to define custom AWS credential providers, but other extension points may be added in the future as the needs arise.

Loading Plugins

Plugins can be loaded by providing the Node module name (or path) to the CDK toolkit:

  1. Using the --plugin command line option (which can be specified multiple times):

    $ cdk list --plugin=module
    $ cdk deploy --plugin=module_1 --plugin=module_2
    
  2. Adding entries to the ~/.cdk.json or cdk.json file:

    {
      // ...
      "plugin": [
          "module_1",
          "module_2"
      ],
      // ...
    }
    

Authoring Plugins

Plugins must be authored in TypeScript or Javascript, and are defined by implementing a Node module that implements the following protocol, and using PluginHost() methods:

import cdk = require('aws-cdk');

export = {
    version: '1', // Version of the plugin infrastructure (currently always '1')
    init(host: cdk.PluginHost): void {
        // Your plugin initialization hook.
        // Use methods of ``host`` to register custom code with the CDK toolkit
    }
};
export = {
    version: '1', // Version of the plugin infrastructure (currently always '1')
    init(host) {
        // Your plugin initialization hook.
        // Use methods of ``host`` to register custom code with the CDK toolkit
    }
};

Credential Provider Plugins

Custom credential providers are classes implementing the CredentialProviderSource() interface, and registered to the toolkit using the registerCredentialProviderSource() method.

import cdk = require('aws-cdk');
import aws = require('aws-sdk');

class CustomCredentialProviderSource implements cdk.CredentialProviderSource {
  public async isAvailable(): Promise<boolean> {
    // Return ``false`` if the plugin could determine it cannot be used (for example,
    // if it depends on files that are not present on this host).
    return true;
  }

  public async canProvideCredentials(accountId: string): Promise<boolean> {
    // Return ``false`` if the plugin is unable to provide credentials for the
    // requested account (for example if it's not managed by the credentials
    // system that this plugin adds support for).
    return true;
  }

  public async getProvider(accountId: string, mode: cdk.Mode): Promise<aws.Credentials> {
    let credentials: aws.Credentials;
    // Somehow obtain credentials in ``credentials``, and return those.
    return credentials;
  }
}

export = {
  version = '1',
  init(host: cdk.PluginHost): void {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};
class CustomCredentialProviderSource {
  async isAvailable() {
    // Return ``false`` if the plugin could determine it cannot be used (for example,
    // if it depends on files that are not present on this host).
    return true;
  }

  async canProvideCredentials(accountId) {
    // Return ``false`` if the plugin is unable to provide credentials for the
    // requested account (for example if it's not managed by the credentials
    // system that this plugin adds support for).
    return true;
  }

  async getProvider(accountId, mode) {
    let credentials;
    // Somehow obtain credentials in ``credentials``, and return those.
    return credentials;
  }
}

export = {
  version = '1',
  init(host) {
    // Register the credential provider to the PluginHost.
    host.registerCredentialProviderSource(new CustomCredentialProviderSource());
  }
};

Note that the credentials obtained from the providers for a given account and mode will be cached, and as a consequence it is strongly advised that the credentials objects returned are self-refreshing, as descibed in the AWS SDK for Javascript documentation.

Reference

CredentialProviderSource (interface)

class aws-cdk.CredentialProviderSource()
CredentialProviderSource.name

A friendly name for the provider, which will be used in error messages, for example.

Type:string
CredentialProviderSource.isAvailable()

Whether the credential provider is even online. Guaranteed to be called before any of the other functions are called.

Returns:Promise<boolean>
CredentialProviderSource.canProvideCredentials(accountId)

Whether the credential provider can provide credentials for the given account.

Arguments:
  • accountId (string) – the account ID for which credentials are needed.
Returns:

Promise<boolean>

CredentialProviderSource.getProvider(accountId, mode)

Construct a credential provider for the given account and the given access mode. Guaranteed to be called only if canProvideCredentails() returned true at some point.

Arguments:
  • accountId (string) – the account ID for which credentials are needed.
  • mode (aws-cdk.Mode) – the kind of operations the credentials are intended to perform.
Returns:

Promise<aws.Credentials>

Mode (enum)

class aws-cdk.Mode()
Mode.ForReading

Credentials are inteded to be used for read-only scenarios.

Mode.ForWriting

Credentials are intended to be used for read-write scenarios.

Plugin (interface)

class aws-cdk.Plugin()
Plugin.version

The version of the plug-in interface used by the plug-in. This will be used by the plug-in host to handle version changes. Currently, the only valid value for this attribute is '1'.

Type:string
Plugin.init(host)

When defined, this function is invoked right after the plug-in has been loaded, so that the plug-in is able to initialize itself. It may call methods of the PluginHost() instance it receives to register new CredentialProviderSource() instances.

Arguments:
Returns:

void

PluginHost

class aws-cdk.PluginHost()
PluginHost.instance
Type:PluginHost()
PluginHost.load(moduleSpec)

Loads a plug-in into this PluginHost.

Arguments:
  • moduleSpec (string) – the specification (path or name) of the plug-in module to be loaded.
Throws:

Error – if the provided moduleSpec cannot be loaded or is not a valid Plugin().

Returns:

void

PluginHost.registerCredentialProviderSource(source)

Allows plug-ins to register new CredentialProviderSources().

Arguments:
  • source (aws-cdk.CredentialProviderSources) – a new CredentialProviderSource to register.
Returns:

void