appdelivery

package
v1.168.0-devpreview Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2022 License: Apache-2.0 Imports: 9 Imported by: 0

README

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.

This library has been deprecated. We recommend you use the @aws-cdk/pipelines module instead.

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
// Example automatically generated from non-compiling source. May contain errors.
import codebuild "github.com/aws/aws-cdk-go/awscdk"
import codepipeline "github.com/aws/aws-cdk-go/awscdk"
import codepipeline_actions "github.com/aws/aws-cdk-go/awscdk"
import cdk "github.com/aws/aws-cdk-go/awscdk"
import cicd "github.com/aws/aws-cdk-go/awscdk"
import iam "github.com/aws/aws-cdk-go/awscdk"


type myServiceStackA struct {
	stack
}
type myServiceStackB struct {
	stack
}

app := cdk.NewApp()

// We define a stack that contains the CodePipeline
pipelineStack := cdk.NewStack(app, jsii.String("PipelineStack"))
pipeline := codepipeline.NewPipeline(pipelineStack, jsii.String("CodePipeline"), &pipelineProps{
	// 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: jsii.Boolean(true),
})

// Configure the CodePipeline source - where your CDK App's source code is hosted
sourceOutput := codepipeline.NewArtifact()
source := codepipeline_actions.NewGitHubSourceAction(&gitHubSourceActionProps{
	actionName: jsii.String("GitHub"),
	output: sourceOutput,
	owner: jsii.String("myName"),
	repo: jsii.String("myRepo"),
	oauthToken: cdk.secretValue.unsafePlainText(jsii.String("secret")),
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("source"),
	actions: []iAction{
		source,
	},
})

project := codebuild.NewPipelineProject(pipelineStack, jsii.String("CodeBuild"), &pipelineProjectProps{
})
synthesizedApp := codepipeline.NewArtifact()
buildAction := codepipeline_actions.NewCodeBuildAction(&codeBuildActionProps{
	actionName: jsii.String("CodeBuild"),
	project: project,
	input: sourceOutput,
	outputs: []artifact{
		synthesizedApp,
	},
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("build"),
	actions: []*iAction{
		buildAction,
	},
})

// Optionally, self-update the pipeline stack
selfUpdateStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("SelfUpdate"),
})
selfUpdateStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: pipelineStack,
	input: synthesizedApp,
	adminPermissions: jsii.Boolean(true),
}))

// Now add our service stacks
deployStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("Deploy"),
})
serviceStackA := NewMyServiceStackA(app, jsii.String("ServiceStackA"), &stackProps{
})
// Add actions to deploy the stacks in the deploy stage:
deployServiceAAction := cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackA,
	input: synthesizedApp,
	// See the note below for details about this option.
	adminPermissions: jsii.Boolean(false),
})
deployStage.addAction(deployServiceAAction)
// 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.
myResourceArn := "arn:partition:service:region:account-id:resource-id"
deployServiceAAction.addToDeploymentRolePolicy(iam.NewPolicyStatement(&policyStatementProps{
	actions: []*string{
		jsii.String("service:SomeAction"),
	},
	resources: []*string{
		myResourceArn,
	},
}))

serviceStackB := NewMyServiceStackB(app, jsii.String("ServiceStackB"), &stackProps{
})
deployStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackB,
	input: synthesizedApp,
	createChangeSetRunOrder: jsii.Number(998),
	adminPermissions: jsii.Boolean(true),
}))
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 input to contain the result of synthesizing a CDK App using the cdk synth -o <directory>.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewPipelineDeployStackAction_Override 

func NewPipelineDeployStackAction_Override(p PipelineDeployStackAction, props *PipelineDeployStackActionProps)

Experimental.

Types

type PipelineDeployStackAction 

type PipelineDeployStackAction interface {
	awscodepipeline.IAction
	// The simple properties of the Action, like its Owner, name, etc.
	//
	// Note that this accessor will be called before the {@link bind} callback.
	// Experimental.
	ActionProperties() *awscodepipeline.ActionProperties
	// Experimental.
	DeploymentRole() awsiam.IRole
	// 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.
	// Experimental.
	AddToDeploymentRolePolicy(statement awsiam.PolicyStatement)
	// The callback invoked when this Action is added to a Pipeline.
	// Experimental.
	Bind(scope awscdk.Construct, stage awscodepipeline.IStage, options *awscodepipeline.ActionBindOptions) *awscodepipeline.ActionConfig
	// Creates an Event that will be triggered whenever the state of this Action changes.
	// Experimental.
	OnStateChange(name *string, target awsevents.IRuleTarget, options *awsevents.RuleProps) awsevents.Rule
}

A class 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.

Example: 

// Example automatically generated from non-compiling source. May contain errors.
import codebuild "github.com/aws/aws-cdk-go/awscdk"
import codepipeline "github.com/aws/aws-cdk-go/awscdk"
import codepipeline_actions "github.com/aws/aws-cdk-go/awscdk"
import cdk "github.com/aws/aws-cdk-go/awscdk"
import cicd "github.com/aws/aws-cdk-go/awscdk"
import iam "github.com/aws/aws-cdk-go/awscdk"

type myServiceStackA struct {
	stack
}
type myServiceStackB struct {
	stack
}

app := cdk.NewApp()

// We define a stack that contains the CodePipeline
pipelineStack := cdk.NewStack(app, jsii.String("PipelineStack"))
pipeline := codepipeline.NewPipeline(pipelineStack, jsii.String("CodePipeline"), &pipelineProps{
	// 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: jsii.Boolean(true),
})

// Configure the CodePipeline source - where your CDK App's source code is hosted
sourceOutput := codepipeline.NewArtifact()
source := codepipeline_actions.NewGitHubSourceAction(&gitHubSourceActionProps{
	actionName: jsii.String("GitHub"),
	output: sourceOutput,
	owner: jsii.String("myName"),
	repo: jsii.String("myRepo"),
	oauthToken: cdk.secretValue.unsafePlainText(jsii.String("secret")),
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("source"),
	actions: []iAction{
		source,
	},
})

project := codebuild.NewPipelineProject(pipelineStack, jsii.String("CodeBuild"), &pipelineProjectProps{
})
synthesizedApp := codepipeline.NewArtifact()
buildAction := codepipeline_actions.NewCodeBuildAction(&codeBuildActionProps{
	actionName: jsii.String("CodeBuild"),
	project: project,
	input: sourceOutput,
	outputs: []artifact{
		synthesizedApp,
	},
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("build"),
	actions: []*iAction{
		buildAction,
	},
})

// Optionally, self-update the pipeline stack
selfUpdateStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("SelfUpdate"),
})
selfUpdateStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: pipelineStack,
	input: synthesizedApp,
	adminPermissions: jsii.Boolean(true),
}))

// Now add our service stacks
deployStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("Deploy"),
})
serviceStackA := NewMyServiceStackA(app, jsii.String("ServiceStackA"), &stackProps{
})
// Add actions to deploy the stacks in the deploy stage:
deployServiceAAction := cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackA,
	input: synthesizedApp,
	// See the note below for details about this option.
	adminPermissions: jsii.Boolean(false),
})
deployStage.addAction(deployServiceAAction)
// 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.
myResourceArn := "arn:partition:service:region:account-id:resource-id"
deployServiceAAction.addToDeploymentRolePolicy(iam.NewPolicyStatement(&policyStatementProps{
	actions: []*string{
		jsii.String("service:SomeAction"),
	},
	resources: []*string{
		myResourceArn,
	},
}))

serviceStackB := NewMyServiceStackB(app, jsii.String("ServiceStackB"), &stackProps{
})
deployStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackB,
	input: synthesizedApp,
	createChangeSetRunOrder: jsii.Number(998),
	adminPermissions: jsii.Boolean(true),
}))

Experimental.

func NewPipelineDeployStackAction 

func NewPipelineDeployStackAction(props *PipelineDeployStackActionProps) PipelineDeployStackAction

Experimental.

type PipelineDeployStackActionProps 

type PipelineDeployStackActionProps struct {
	// 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.
	// Experimental.
	AdminPermissions *bool `field:"required" json:"adminPermissions" yaml:"adminPermissions"`
	// The CodePipeline artifact that holds the synthesized app, which is the contents of the “<directory>“ when running “cdk synth -o <directory>“.
	// Experimental.
	Input awscodepipeline.Artifact `field:"required" json:"input" yaml:"input"`
	// The CDK stack to be deployed.
	// Experimental.
	Stack awscdk.Stack `field:"required" json:"stack" yaml:"stack"`
	// 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.
	// See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities
	//
	// Experimental.
	Capabilities *[]awscloudformation.CloudFormationCapabilities `field:"optional" json:"capabilities" yaml:"capabilities"`
	// The name to use when creating a ChangeSet for the stack.
	// Experimental.
	ChangeSetName *string `field:"optional" json:"changeSetName" yaml:"changeSetName"`
	// The name of the CodePipeline action creating the ChangeSet.
	// Experimental.
	CreateChangeSetActionName *string `field:"optional" json:"createChangeSetActionName" yaml:"createChangeSetActionName"`
	// The runOrder for the CodePipeline action creating the ChangeSet.
	// Experimental.
	CreateChangeSetRunOrder *float64 `field:"optional" json:"createChangeSetRunOrder" yaml:"createChangeSetRunOrder"`
	// The name of the CodePipeline action creating the ChangeSet.
	// Experimental.
	ExecuteChangeSetActionName *string `field:"optional" json:"executeChangeSetActionName" yaml:"executeChangeSetActionName"`
	// The runOrder for the CodePipeline action executing the ChangeSet.
	// Experimental.
	ExecuteChangeSetRunOrder *float64 `field:"optional" json:"executeChangeSetRunOrder" yaml:"executeChangeSetRunOrder"`
	// 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.
	// Experimental.
	Role awsiam.IRole `field:"optional" json:"role" yaml:"role"`
}

Example: 

// Example automatically generated from non-compiling source. May contain errors.
import codebuild "github.com/aws/aws-cdk-go/awscdk"
import codepipeline "github.com/aws/aws-cdk-go/awscdk"
import codepipeline_actions "github.com/aws/aws-cdk-go/awscdk"
import cdk "github.com/aws/aws-cdk-go/awscdk"
import cicd "github.com/aws/aws-cdk-go/awscdk"
import iam "github.com/aws/aws-cdk-go/awscdk"

type myServiceStackA struct {
	stack
}
type myServiceStackB struct {
	stack
}

app := cdk.NewApp()

// We define a stack that contains the CodePipeline
pipelineStack := cdk.NewStack(app, jsii.String("PipelineStack"))
pipeline := codepipeline.NewPipeline(pipelineStack, jsii.String("CodePipeline"), &pipelineProps{
	// 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: jsii.Boolean(true),
})

// Configure the CodePipeline source - where your CDK App's source code is hosted
sourceOutput := codepipeline.NewArtifact()
source := codepipeline_actions.NewGitHubSourceAction(&gitHubSourceActionProps{
	actionName: jsii.String("GitHub"),
	output: sourceOutput,
	owner: jsii.String("myName"),
	repo: jsii.String("myRepo"),
	oauthToken: cdk.secretValue.unsafePlainText(jsii.String("secret")),
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("source"),
	actions: []iAction{
		source,
	},
})

project := codebuild.NewPipelineProject(pipelineStack, jsii.String("CodeBuild"), &pipelineProjectProps{
})
synthesizedApp := codepipeline.NewArtifact()
buildAction := codepipeline_actions.NewCodeBuildAction(&codeBuildActionProps{
	actionName: jsii.String("CodeBuild"),
	project: project,
	input: sourceOutput,
	outputs: []artifact{
		synthesizedApp,
	},
})
pipeline.addStage(&stageOptions{
	stageName: jsii.String("build"),
	actions: []*iAction{
		buildAction,
	},
})

// Optionally, self-update the pipeline stack
selfUpdateStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("SelfUpdate"),
})
selfUpdateStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: pipelineStack,
	input: synthesizedApp,
	adminPermissions: jsii.Boolean(true),
}))

// Now add our service stacks
deployStage := pipeline.addStage(&stageOptions{
	stageName: jsii.String("Deploy"),
})
serviceStackA := NewMyServiceStackA(app, jsii.String("ServiceStackA"), &stackProps{
})
// Add actions to deploy the stacks in the deploy stage:
deployServiceAAction := cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackA,
	input: synthesizedApp,
	// See the note below for details about this option.
	adminPermissions: jsii.Boolean(false),
})
deployStage.addAction(deployServiceAAction)
// 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.
myResourceArn := "arn:partition:service:region:account-id:resource-id"
deployServiceAAction.addToDeploymentRolePolicy(iam.NewPolicyStatement(&policyStatementProps{
	actions: []*string{
		jsii.String("service:SomeAction"),
	},
	resources: []*string{
		myResourceArn,
	},
}))

serviceStackB := NewMyServiceStackB(app, jsii.String("ServiceStackB"), &stackProps{
})
deployStage.addAction(cicd.NewPipelineDeployStackAction(&pipelineDeployStackActionProps{
	stack: serviceStackB,
	input: synthesizedApp,
	createChangeSetRunOrder: jsii.Number(998),
	adminPermissions: jsii.Boolean(true),
}))

Experimental.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.