feat: re-structure the CodePipeline Construct library API. (#1590)

BREAKING CHANGE: the CodePipeline Stage class is no longer a Construct, and cannot be instantiated directly, only through calling Pipeline#addStage; which now takes an Object argument instead of a String. BREAKING CHANGE: the CodePipeline Actions are no longer Constructs. BREAKING CHANGE: the CodePipeline Action name is now part of the Action props, instead of being a separate parameter. BREAKING CHANGE: the Pipeline#addToPipeline methods in Resources like S3, CodeBuild, CodeCommit etc. have been renamed to `toCodePipelineAction`.
aws · Feb 8, 2019 · 3c3db07 · 3c3db07
1 parent 22fc8b9
commit 3c3db07
Show file tree

Hide file tree

Showing 72 changed files with 1,590 additions and 1,270 deletions.
diff --git a/packages/@aws-cdk/alexa-ask/README.md b/packages/@aws-cdk/alexa-ask/README.md
@@ -10,13 +10,13 @@ You can deploy to Alexa using CodePipeline with the following DeployAction.
 
 ```ts
 // Read the secrets from ParameterStore
-const clientId = new cdk.SecretParameter(stack, 'AlexaClientId', {ssmParameter: '/Alexa/ClientId'});
-const clientSecret = new cdk.SecretParameter(stack, 'AlexaClientSecret', {ssmParameter: '/Alexa/ClientSecret'});
-const refreshToken = new cdk.SecretParameter(stack, 'AlexaRefreshToken', {ssmParameter: '/Alexa/RefreshToken'});
+const clientId = new cdk.SecretParameter(this, 'AlexaClientId', { ssmParameter: '/Alexa/ClientId' });
+const clientSecret = new cdk.SecretParameter(this, 'AlexaClientSecret', { ssmParameter: '/Alexa/ClientSecret' });
+const refreshToken = new cdk.SecretParameter(this, 'AlexaRefreshToken', { ssmParameter: '/Alexa/RefreshToken' });
 
 // Add deploy action
-new alexa.AlexaSkillDeployAction(stack, 'DeploySkill', {
-  stage: deployStage,
+new alexaAsk.AlexaSkillDeployAction({
+  actionName: 'DeploySkill',
   runOrder: 1,
   inputArtifact: sourceAction.outputArtifact,
   clientId: clientId.value,
@@ -26,12 +26,14 @@ new alexa.AlexaSkillDeployAction(stack, 'DeploySkill', {
 });
 ```
 
-If you need manifest overrides you can specify them as `overrideArtifact` in the action.
+If you need manifest overrides you can specify them as `parameterOverridesArtifact` in the action:
 
 ```ts
+const cloudformation = require('@aws-cdk/aws-cloudformation');
+
 // Deploy some CFN change set and store output
-const executeChangeSetAction = new PipelineExecuteChangeSetAction(this, 'ExecuteChangesTest', {
-  stage: deployStage,
+const executeChangeSetAction = new cloudformation.PipelineExecuteChangeSetAction({
+  actionName: 'ExecuteChangesTest',
   runOrder: 2,
   stackName,
   changeSetName,
@@ -40,8 +42,8 @@ const executeChangeSetAction = new PipelineExecuteChangeSetAction(this, 'Execute
 });
 
 // Provide CFN output as manifest overrides
-new AlexaSkillDeployAction(this, 'DeploySkill', {
-  stage: deployStage,
+new alexaAsk.AlexaSkillDeployAction({
+  actionName: 'DeploySkill',
   runOrder: 1,
   inputArtifact: sourceAction.outputArtifact,
   parameterOverridesArtifact: executeChangeSetAction.outputArtifact,
@@ -50,4 +52,4 @@ new AlexaSkillDeployAction(this, 'DeploySkill', {
   refreshToken: refreshToken.value,
   skillId: 'amzn1.ask.skill.12345678-1234-1234-1234-123456789012',
 });
-```
+```
diff --git a/packages/@aws-cdk/alexa-ask/lib/pipeline-actions.ts b/packages/@aws-cdk/alexa-ask/lib/pipeline-actions.ts
@@ -4,9 +4,7 @@ import cdk = require('@aws-cdk/cdk');
 /**
  * Construction properties of the {@link AlexaSkillDeployAction Alexa deploy Action}.
  */
-export interface AlexaSkillDeployActionProps extends codepipeline.CommonActionProps,
-    codepipeline.CommonActionConstructProps {
-
+export interface AlexaSkillDeployActionProps extends codepipeline.CommonActionProps {
   /**
    * The client id of the developer console token
    */
@@ -30,7 +28,7 @@ export interface AlexaSkillDeployActionProps extends codepipeline.CommonActionPr
   /**
    * The source artifact containing the voice model and skill manifest
    */
-  inputArtifact?: codepipeline.Artifact;
+  inputArtifact: codepipeline.Artifact;
 
   /**
    * An optional artifact containing overrides for the skill manifest
@@ -42,8 +40,8 @@ export interface AlexaSkillDeployActionProps extends codepipeline.CommonActionPr
  * Deploys the skill to Alexa
  */
 export class AlexaSkillDeployAction extends codepipeline.DeployAction {
-  constructor(scope: cdk.Construct, id: string, props: AlexaSkillDeployActionProps) {
-    super(scope, id, {
+  constructor(props: AlexaSkillDeployActionProps) {
+    super({
       ...props,
       artifactBounds: {
         minInputs: 1,
@@ -60,8 +58,13 @@ export class AlexaSkillDeployAction extends codepipeline.DeployAction {
         SkillId: props.skillId,
       },
     });
+
     if (props.parameterOverridesArtifact) {
       this.addInputArtifact(props.parameterOverridesArtifact);
     }
   }
+
+  protected bind(_stage: codepipeline.IStage, _scope: cdk.Construct): void {
+    // nothing to do
+  }
 }
diff --git a/packages/@aws-cdk/app-delivery/README.md b/packages/@aws-cdk/app-delivery/README.md
@@ -1,5 +1,5 @@
 ## Continuous Integration / Continuous Delivery for CDK Applications
-This library includes a *CodePipeline* action for deploying AWS CDK Applications.
+This library includes a *CodePipeline* composite Action for deploying AWS CDK Applications.
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
 
@@ -29,7 +29,7 @@ The example below defines a *CDK App* that contains 3 stacks:
 ```
 
 #### `index.ts`
-```ts
+```typescript
 import codebuild = require('@aws-cdk/aws-codebuild');
 import codepipeline = require('@aws-cdk/aws-codepipeline');
 import cdk = require('@aws-cdk/cdk');
@@ -46,36 +46,48 @@ const pipeline = new codepipeline.Pipeline(pipelineStack, 'CodePipeline', {
   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 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
+  * 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,
+  *   buildImage: codebuild.LinuxBuildImage.UBUNTU_14_04_NODEJS_10_1_0,
   * },
   */
 });
-const buildStage = pipeline.addStage('build');
-const buildAction = project.addToPipeline(buildStage, 'CodeBuild');
+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('SelfUpdate');
+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('Deploy');
+const deployStage = pipeline.addStage({ name: '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,
@@ -84,7 +96,6 @@ const deployServiceAAction = new cicd.PipelineDeployStackAction(pipelineStack, '
   // 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, 
@@ -95,7 +106,9 @@ deployServiceAAction.addToRolePolicy(
     .addResource(myResource.myResourceArn)
     // add more Action(s) and/or Resource(s) here, as needed
 );
-const deployServiceBAction = new cicd.PipelineDeployStackAction(pipelineStack, 'DeployServiceStackB', {
+
+const serviceStackB = new MyServiceStackB(app, 'ServiceStackB', { /* ... */ });
+new cicd.PipelineDeployStackAction(pipelineStack, 'DeployServiceStackB', {
   stage: deployStage,
   stack: serviceStackB,
   inputArtifact: synthesizedApp,

diff --git a/packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts b/packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts
@@ -85,8 +85,8 @@ export interface PipelineDeployStackActionProps {
 }
 
 /**
- * A CodePipeline action to deploy a stack that is part of a CDK App. This
- * action takes care of preparing and executing a CloudFormation ChangeSet.
+ * 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
@@ -120,24 +120,25 @@ export class PipelineDeployStackAction extends cdk.Construct {
     const changeSetName = props.changeSetName || 'CDK-CodePipeline-ChangeSet';
 
     const capabilities = cfnCapabilities(props.adminPermissions, props.capabilities);
-    const changeSetAction = new cfn.PipelineCreateReplaceChangeSetAction(this, 'ChangeSet', {
+    const changeSetAction = new cfn.PipelineCreateReplaceChangeSetAction({
+      actionName: 'ChangeSet',
       changeSetName,
       runOrder: createChangeSetRunOrder,
       stackName: props.stack.name,
-      stage: props.stage,
       templatePath: props.inputArtifact.atPath(`${props.stack.name}.template.yaml`),
       adminPermissions: props.adminPermissions,
       deploymentRole: props.role,
       capabilities,
     });
-    this.deploymentRole = changeSetAction.deploymentRole;
-
-    new cfn.PipelineExecuteChangeSetAction(this, 'Execute', {
+    props.stage.addAction(changeSetAction);
+    props.stage.addAction(new cfn.PipelineExecuteChangeSetAction({
+      actionName: 'Execute',
       changeSetName,
       runOrder: executeChangeSetRunOrder,
       stackName: props.stack.name,
-      stage: props.stage,
-    });
+    }));
+
+    this.deploymentRole = changeSetAction.deploymentRole;
   }
 
   /**

diff --git a/packages/@aws-cdk/app-delivery/test/integ.cicd.expected.json b/packages/@aws-cdk/app-delivery/test/integ.cicd.expected.json
@@ -63,7 +63,7 @@
               "Effect": "Allow",
               "Resource": {
                 "Fn::GetAtt": [
-                  "DeployStackChangeSetRole4923A126",
+                  "CodePipelineDeployChangeSetRoleF9F2B343",
                   "Arn"
                 ]
               }
@@ -202,7 +202,7 @@
                   "TemplatePath": "Artifact_CICDGitHubF8BA7ADD::CICD.template.yaml",
                   "RoleArn": {
                     "Fn::GetAtt": [
-                      "DeployStackChangeSetRole4923A126",
+                      "CodePipelineDeployChangeSetRoleF9F2B343",
                       "Arn"
                     ]
                   }
@@ -243,7 +243,7 @@
         "CodePipelineRoleB3A660B4"
       ]
     },
-    "DeployStackChangeSetRole4923A126": {
+    "CodePipelineDeployChangeSetRoleF9F2B343": {
       "Type": "AWS::IAM::Role",
       "Properties": {
         "AssumeRolePolicyDocument": {

diff --git a/packages/@aws-cdk/app-delivery/test/integ.cicd.ts b/packages/@aws-cdk/app-delivery/test/integ.cicd.ts
@@ -12,14 +12,19 @@ const pipeline = new code.Pipeline(stack, 'CodePipeline', {
     removalPolicy: cdk.RemovalPolicy.Destroy
   })
 });
-const source = new code.GitHubSourceAction(stack, 'GitHub', {
-  stage: pipeline.addStage('Source'),
+const source = new code.GitHubSourceAction({
+  actionName: 'GitHub',
   owner: 'awslabs',
   repo: 'aws-cdk',
   oauthToken: new cdk.Secret('DummyToken'),
   pollForSourceChanges: true,
+  outputArtifactName: 'Artifact_CICDGitHubF8BA7ADD',
 });
-const stage = pipeline.addStage('Deploy');
+pipeline.addStage({
+  name: 'Source',
+  actions: [source],
+});
+const stage = pipeline.addStage({ name: 'Deploy' });
 new cicd.PipelineDeployStackAction(stack, 'DeployStack', {
   stage,
   stack,