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/app-delivery

Continuous Integration / Continuous Delivery for CDK Applications

This library includes a CodePipeline composite 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({
  actionName: 'GitHub',
  /* ... */
});
pipeline.addStage({
  name: 'source',
  actions: [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 buildAction = project.toCodePipelineBuildAction({
  actionName: 'CodeBuild',
  inputArtifact: source.outputArtifact,
});
pipeline.addStage({
  name: 'build',
  actions: [buildAction],
});
const synthesizedApp = buildAction.outputArtifact;

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

// Now add our service stacks
const deployStage = pipeline.addStage({ name: 'Deploy' });
const serviceStackA = new MyServiceStackA(app, 'ServiceStackA', { /* ... */ });
// 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 serviceStackB = new MyServiceStackB(app, 'ServiceStackB', { /* ... */ });
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>.

Reference

View in Nuget

csproj:

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

dotnet:

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

packages.config:

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

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:cdk-app-delivery:jar:0.25.3'

Apache Ivy:

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

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>cdk-app-delivery</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:cdk-app-delivery:0.25.3'

Groovy Grape:

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

View in NPM

npm:

$ npm i @aws-cdk/app-delivery@0.25.3

package.json:

{
  "@aws-cdk/app-delivery": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/app-delivery@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/app-delivery@0.25.3

package.json:

{
  "@aws-cdk/app-delivery": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/app-delivery@0.25.3

PipelineDeployStackAction

class @aws-cdk/app-delivery.PipelineDeployStackAction(scope, id, props)

Language-specific names:

using Amazon.CDK.AppDelivery;
import software.amazon.awscdk.appdelivery.PipelineDeployStackAction;
const { PipelineDeployStackAction } = require('@aws-cdk/app-delivery');
import { PipelineDeployStackAction } from '@aws-cdk/app-delivery';

A Construct to deploy a stack that is part of a CDK App, using CodePipeline.

This composite Action takes care of preparing and executing a CloudFormation ChangeSet.

It currently does not support stacks that make use of ``Asset``s, and

requires the deployed stack is in the same account and region where the

CodePipeline is hosted.

Extends:

@aws-cdk/cdk.Construct

Parameters:
addToDeploymentRolePolicy(statement)

Add policy statements to the role deploying the stack.

This role is passed to CloudFormation and must have the IAM permissions

necessary to deploy the stack or you can grant this role adminPermissions

by using that option during creation. If you do not grant

adminPermissions you need to identify the proper statements to add to

this role based on the CloudFormation Resources in your stack.

Parameters:statement (@aws-cdk/aws-iam.PolicyStatement) –
validate() → string[]

Overrides @aws-cdk/cdk.Construct.validate()

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

Return type:string[]
deploymentRole

The role used by CloudFormation for the deploy action

Type:@aws-cdk/aws-iam.IRole (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
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)

PipelineDeployStackActionProps (interface)

class @aws-cdk/app-delivery.PipelineDeployStackActionProps

Language-specific names:

using Amazon.CDK.AppDelivery;
import software.amazon.awscdk.appdelivery.PipelineDeployStackActionProps;
// PipelineDeployStackActionProps is an interface
import { PipelineDeployStackActionProps } from '@aws-cdk/app-delivery';
adminPermissions

Whether to grant admin permissions to CloudFormation while deploying this template.

Setting this to true affects the defaults for role and capabilities, if you

don’t specify any alternatives.

The default role that will be created for you will have admin (i.e., *)

permissions on all resources, and the deployment will have named IAM

capabilities (i.e., able to create all IAM resources).

This is a shorthand that you can use if you fully trust the templates that

are deployed in this pipeline. If you want more fine-grained permissions,

use addToRolePolicy and capabilities to control what the CloudFormation

deployment is allowed to do.

Type:boolean
inputArtifact

The CodePipeline artifact that holds the synthesized app, which is the

contents of the <directory> when running cdk synth -o <directory>.

Type:@aws-cdk/aws-codepipeline-api.Artifact
stack

The CDK stack to be deployed.

Type:@aws-cdk/cdk.Stack
stage

The CodePipeline stage in which to perform the deployment.

Type:@aws-cdk/aws-codepipeline-api.IStage
capabilities

Acknowledge certain changes made as part of deployment

For stacks that contain certain resources, explicit acknowledgement that AWS CloudFormation

might create or update those resources. For example, you must specify AnonymousIAM if your

stack template contains AWS Identity and Access Management (IAM) resources. For more

information

Type:@aws-cdk/aws-cloudformation.CloudFormationCapabilities (optional)
Default:AnonymousIAM, unless adminPermissions is true
changeSetName

The name to use when creating a ChangeSet for the stack.

Type:string (optional)
Default:CDK-CodePipeline-ChangeSet
createChangeSetRunOrder

The runOrder for the CodePipeline action creating the ChangeSet.

Type:number (optional)
Default:1
executeChangeSetRunOrder

The runOrder for the CodePipeline action executing the ChangeSet.

Type:number (optional)
Default:createChangeSetRunOrder + 1
role

IAM role to assume when deploying changes.

If not specified, a fresh role is created. The role is created with zero

permissions unless adminPermissions is true, in which case the role will have

admin permissions.

Type:@aws-cdk/aws-iam.IRole (optional)
Default:A fresh role with admin or no permissions (depending on the value of adminPermissions).