@aws-cdk/app-delivery

Continuous Integration / Continuous Delivery for CDK Applications

This library includes a CodePipeline action for deploying AWS CDK Applications.

This module is part of the AWS Cloud Development Kit project.

Limitations

The construct library in it's current form has the following limitations:

1. It can only deploy stacks that are hosted in the same AWS account and region as the CodePipeline is.
2. Stacks that make use of Assets cannot be deployed successfully.

Getting Started

In order to add the PipelineDeployStackAction to your CodePipeline, you need to have a CodePipeline artifact that contains the result of invoking cdk synth -o <dir> on your CDK App. You can for example achieve this using a CodeBuild project.

The example below defines a CDK App that contains 3 stacks:

• CodePipelineStack manages the CodePipeline resources, and self-updates before deploying any other stack
• ServiceStackA and ServiceStackB are service infrastructure stacks, and need to be deployed in this order

  ┏━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  ┃     Source     ┃  ┃     Build      ┃  ┃  Self-Update    ┃  ┃             Deploy              ┃
  ┃                ┃  ┃                ┃  ┃                 ┃  ┃                                 ┃
  ┃ ┌────────────┐ ┃  ┃ ┌────────────┐ ┃  ┃ ┌─────────────┐ ┃  ┃ ┌─────────────┐ ┌─────────────┐ ┃
  ┃ │   GitHub   ┣━╋━━╋━▶ CodeBuild  ┣━╋━━╋━▶Deploy Stack ┣━╋━━╋━▶Deploy Stack ┣━▶Deploy Stack │ ┃
  ┃ │            │ ┃  ┃ │            │ ┃  ┃ │PipelineStack│ ┃  ┃ │ServiceStackA│ │ServiceStackB│ ┃
  ┃ └────────────┘ ┃  ┃ └────────────┘ ┃  ┃ └─────────────┘ ┃  ┃ └─────────────┘ └─────────────┘ ┃
  ┗━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

index.ts

import codebuild = require('@aws-cdk/aws-codebuild');
import codepipeline = require('@aws-cdk/aws-codepipeline');
import cdk = require('@aws-cdk/cdk');
import cicd = require('@aws-cdk/cicd');

const app = new cdk.App();

// We define a stack that contains the CodePipeline
const pipelineStack = new cdk.Stack(app, 'PipelineStack');
const pipeline = new codepipeline.Pipeline(pipelineStack, 'CodePipeline', {
  // Mutating a CodePipeline can cause the currently propagating state to be
  // "lost". Ensure we re-run the latest change through the pipeline after it's
  // been mutated so we're sure the latest state is fully deployed through.
  restartExecutionOnUpdate: true,
  /* ... */
});
// Configure the CodePipeline source - where your CDK App's source code is hosted
const source = new codepipeline.GitHubSourceAction(pipelineStack, 'GitHub', {
  stage: pipeline.addStage('source'),
  /* ... */
});
const project = new codebuild.PipelineProject(pipelineStack, 'CodeBuild', {
  /** 
  * Choose an environment configuration that meets your use case. For NodeJS
  * this might be
  * environment: {
  *  buildImage: codebuild.LinuxBuildImage.UBUNTU_14_04_NODEJS_10_1_0,
  * },
  */
});
const buildStage = pipeline.addStage('build');
const buildAction = project.addToPipeline(buildStage, 'CodeBuild');
const synthesizedApp = buildAction.outputArtifact;

// Optionally, self-update the pipeline stack
const selfUpdateStage = pipeline.addStage('SelfUpdate');
new cicd.PipelineDeployStackAction(pipelineStack, 'SelfUpdatePipeline', {
  stage: selfUpdateStage,
  stack: pipelineStack,
  inputArtifact: synthesizedApp,
});

// Now add our service stacks
const deployStage = pipeline.addStage('Deploy');
const serviceStackA = new MyServiceStackA(app, 'ServiceStackA', { /* ... */ });
const serviceStackB = new MyServiceStackB(app, 'ServiceStackB', { /* ... */ });
// Add actions to deploy the stacks in the deploy stage:
const deployServiceAAction = new cicd.PipelineDeployStackAction(pipelineStack, 'DeployServiceStackA', {
  stage: deployStage,
  stack: serviceStackA,
  inputArtifact: synthesizedApp,
  // See the note below for details about this option.
  adminPermissions: false, 
});

// Add the necessary permissions for you service deploy action. This role is
// is passed to CloudFormation and needs the permissions necessary to deploy
// stack. Alternatively you can enable [Administrator](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html#jf_administrator) permissions above, 
// users should understand the privileged nature of this role.
deployServiceAAction.addToRolePolicy(
  new iam.PolicyStatement()
    .addAction('service:SomeAction')
    .addResource(myResource.myResourceArn)
    // add more Action(s) and/or Resource(s) here, as needed
);
const deployServiceBAction = new cicd.PipelineDeployStackAction(pipelineStack, 'DeployServiceStackB', {
  stage: deployStage,
  stack: serviceStackB,
  inputArtifact: synthesizedApp,
  createChangeSetRunOrder: 998,
  adminPermissions: true, // no need to modify the role with admin
}); 

buildspec.yml

The repository can contain a file at the root level named buildspec.yml, or you can in-line the buildspec. Note that buildspec.yaml is not compatible.

For example, a TypeScript or Javascript CDK App can add the following buildspec.yml at the root of the repository:

version: 0.2
phases:
  install:
    commands:
      # Installs the npm dependencies as defined by the `package.json` file
      # present in the root directory of the package
      # (`cdk init app --language=typescript` would have created one for you)
      - npm install
  build:
    commands:
      # Builds the CDK App so it can be synthesized
      - npm run build
      # Synthesizes the CDK App and puts the resulting artifacts into `dist`
      - npm run cdk synth -- -o dist
artifacts:
  # The output artifact is all the files in the `dist` directory
  base-directory: dist
  files: '**/*'

The PipelineDeployStackAction expects it's inputArtifact to contain the result of synthesizing a CDK App using the cdk synth -o <directory>.

Changelog

0.22.0 (2019-01-10)

This is a major release with multiple breaking changes in the core layers. Please consult the breaking changes section below for details.

We are focusing these days on finalizing the common patterns and APIs of the CDK framework and the AWS Construct Library, which is why you are seeing all these breaking changes. Expect a few more releases with changes of that nature as we stabilize these APIs, so you might want to hold off with upgrading. We will communicate when this foundational work is complete.

Bug Fixes

• core: automatic cross-stack refs for CFN resources (#1510) (ca5ee35)
• ecs: correct typo and other minor mistakes in ecs readme (#1448) (9c91b20)
• elbv2: unable to specify load balancer name (#1486) (5b24583), closes #973 #1481
• lambda: use IRole instead of Role to allow imports (#1509) (b909dcd)
• toolkit: fix typo in --rename option description (#1438) (1dd56d4)
• toolkit: support multiple toolkit stacks in the same environment (#1427) (095da14), closes #1416

Features

• apigateway: add tracingEnabled property to APIGW Stage (#1482) (fefa764)
• assets: enable local tooling scenarios such as lambda debugging (#1433) (0d2b633), closes #1432
• aws-cdk: better stack dependency handling (#1511) (b4bbaf0), closes #1508 #1505
• aws-codepipeline: jenkins build and test actions (#1216) (471e8eb)
• aws-codepipeline: support notifications on the ManualApprovalAction (#1368) (068fa46), closes #1222
• aws-ecs: add support Amazon Linux 2 (#1484) (82ec0ff), closes #1483
• aws-kms: allow tagging kms keys (#1485) (f43b4d4)
• aws-lambda: add input and output artifacts to the CodePipeline action (#1390) (fbd7728), closes #1384
• cdk: transparently use constructs from another stack (d7371f0), closes #1324
• cli: allow specifying options using env vars (#1447) (7cd84a0)
• aws resource api linting (breaking changes) (#1434) (8c17ca7), closes #742 #1428
• core: cloudformation condition chaining (#1494) (2169015), closes #1457
• diff: better diff of arbitrary json objects (#1488) (607f997)
• route53: support cname records (#1487) (17eddd1), closes #1420
• step-functions: support parameters option (#1492) (935054a), closes #1480
• core: construct base class changes (breaking) (#1444) (fb22a32), closes #1431 #1441 #189 #1441 #1431
• core: idiomize cloudformation intrinsics functions (#1428) (04217a5), closes #202
• cloudformation: no more generated attribute types in CFN layer (L1) (#1489) (4d6d5ca), closes #1455 #1406
• cloudformation: stop generating legacy cloudformation resources (#1493) (81b4174)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• Cross-stack references: if you are using export() and import() to share constructs between stacks, you can stop doing that, instead of FooImportProps accept an IFoo directly on the consuming stack, and use that object as usual.
• ArnUtils.fromComponents() and ArnUtils.parse() have been moved onto Stack.
• All CloudFormation pseudo-parameter (such as AWS::AccountId etc) are now also accessible via Stack, as stack.accountId etc.
• All CloudFormation intrinsic functions are now represented as static methods under the Fn class (e.g. Fn.join(...) instead of new FnJoin(...).toString())
• resolve() has been moved to this.node.resolve().
• CloudFormationJSON.stringify() has been moved to this.node.stringifyJson(). validate() now should be protected.
• The deprecated cloudformation.XxxResource classes have been removed. Use the CfnXxx classes instead.
• Any CfnXxx resource attributes that represented a list of strings are now typed as string[]s (via #1144). Attributes that represent strings, are still typed as string (#712) and all other attribute types are represented as cdk.Token.
• route53: The route53.TXTRecord class was renamed to route53.TxtRecord.
• route53: record classes now require a zone when created (not assuming zone is the parent construct).
• lambda: the static "metric" methods moved from lambda.FunctionRef to lambda.Function.
• Many AWS resource classes have been changed to conform to API guidelines:
  • XxxRef abstract classes are now IXxx interfaces
  • XxxRefProps are now XxxImportProps
  • XxxRef.import(...) are now Xxx.import(...) accept XxxImportProps and return IXxx
  • export(): XxxImportProps is now defined in IXxx and implemented by imported resources