feat(codepipeline-actions): native Amazon EC2 deployment support #33604

Tietew · 2025-02-27T08:57:52Z

Issue # (if applicable)

Reason for this change

AWS CodePipeline introduces a new action to deploy to Amazon Elastic Compute Cloud (EC2).
https://aws.amazon.com/about-aws/whats-new/2025/02/aws-codepipeline-native-ec2-deployment-support/

Description of changes

Added the Ec2DeployAction action class and corresponding helpers.

Ec2InstanceType - specify instance type: EC2 or SSM_MANAGED_NODE
Ec2DeploySpecification - choose deploy specification: inline or DeploySpec (not yet included)
Ec2MaxInstances - specify maxBatch and maxError configuration

Usage

new cpactions.Ec2DeployAction({
  actionName: 'EC2',
  input: buildOutput,
  // specify instance type
  instanceType: cpactions.Ec2InstanceType.EC2,  // REQUIRED
  // specify tag key and value, not ec2.IInstance
  instanceTagKey: 'Target',                     // REQUIRED
  instanceTagValue: 'DeployTarget',
  // deploy specifications
  deploySpecifications: cpactions.Ec2DeploySpecifications.inline({
    targetDirectory: '/home/ec2-user/deploy',   // REQUIRED
    preScript: 'hooks/pre-script',
    postScript: 'hooks/post-script',            // REQUIRED
  }),
  // the action will detach and attach instances from/to target groups
  targetGroups: [myTargetGroup],
  // the number or percentage of instances that can deploy in parallel
  maxBatch: cpactions.Ec2MaxInstances.target(2),
  maxError: cpactions.Ec2MaxInstances.percent(50),
});

Describe any new or updated permissions being added

Ec2DeployAction adds permissions based on CodePipeline documentation:
https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-EC2Deploy.html#action-reference-EC2Deploy-permissions-action

For details of actions, resource, and condition keys, see the Service Authorization Reference: EC2, ELBv2, SSM

Description of how you validated changes

Unit tests and an integ test.
The integ test also asserts pipeline execution.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

...ages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/assets/artifact.zip

codecov · 2025-02-27T09:06:59Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.98%. Comparing base (994e952) to head (ea61e43).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #33604   +/-   ##
=======================================
  Coverage   83.98%   83.98%           
=======================================
  Files         120      120           
  Lines        6976     6976           
  Branches     1178     1178           
=======================================
  Hits         5859     5859           
  Misses       1005     1005           
  Partials      112      112

Flag	Coverage Δ
suite.unit	`83.98% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
packages/aws-cdk	`∅ <ø> (∅)`
packages/aws-cdk-lib/core	`83.98% <ø> (ø)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Tietew · 2025-02-27T09:08:20Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+  /**
+   * Max number of instances.
+   *
+   * Valid range: from 1 to number of your instances


Validation based on AWS console:

Tietew · 2025-02-27T09:08:50Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+  /**
+   * Max percentage of instances.
+   *
+   * Valid range: from 1 to 99


Validation based on AWS console:

I've succeeded to deploy with maxBatch: '100%'. The note of the AWS console seems inaccurate.

I've updated max allowed percentage to 100%.

Tietew · 2025-02-27T09:18:54Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+        TargetDirectory: this.props.targetDirectory,
+        MaxBatch: this.props.maxBatch?.value,
+        MaxError: this.props.maxError?.value,
+        TargetGroupNameList: this.props.targetGroups?.length ? this.props.targetGroups.map((tg) => tg.targetGroupName).join(',') : undefined,


From AWS console, TargetGroupListName is a comma-separated string instead of a JSON array.

Result of GetPipeline: (pipeline created by console)

Tietew · 2025-02-27T09:19:27Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+    if (!Token.isUnresolved(percentage) && !(percentage >= 1 && percentage <= 99 && Number.isInteger(percentage))) {
+      throw new UnscopedValidationError(`percentage must be a positive integer between 1 and 99. got ${percentage}`);
+    }
+    return { value: `${Tokenization.stringifyNumber(percentage)}%` };


From AWS console, percentage is represented as "NN%"

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

Tietew · 2025-03-17T07:22:24Z

snapshot change is caused by #33742

Tietew · 2025-05-21T05:43:45Z

AWS CodePipeline now supports Deploy Spec file
https://aws.amazon.com/about-aws/whats-new/2025/05/aws-codepipeline-deploy-spec-file-ec2-deploy-action/

kumvprat

Left some comments on the PR

...-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-ec2-deploy.ts

packages/aws-cdk-lib/aws-codepipeline-actions/README.md

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

kumvprat · 2025-05-21T14:04:03Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+        'ec2:DescribeInstances',
+        'elasticloadbalancing:DescribeTargetGroupAttributes',
+        'elasticloadbalancing:DescribeTargetGroups',
+        'elasticloadbalancing:DescribeTargetHealth',


The ssm:CancelCommand may need to be scoped down, similar to ssm:SendCommand, assuming it can cancel the post/pre-scripts running on the specific instance.

Hmmm, looks like ssm:CancelCommand has been added as part of the deploy spec support...
I'll reflect it anyway.

Sorry, I misunderstood your comment.

These policy statements are described in Amazon EC2 action reference.

The ssm:CancelCommand has no related resource types and resources field must be [*].
See https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssystemsmanager.html

Thanks for investigating this
We could add this link : https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssystemsmanager.html and for the related elasticloadbalancing to the PR description/README

Would be nice for users to know about IAM actions

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

kumvprat

Overall the PR looks good, except for a few remaining changes.

Is there a specific reason for clubbing the deploy spec support in this PR ?
Releasing it as a follow-up PR would also work

kumvprat · 2025-05-23T13:22:44Z

...-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-ec2-deploy.ts

+integ.assertions
+  .awsApiCall('codepipeline', 'GetPipelineExecution', { pipelineName: ssmPipeline.pipelineName, pipelineExecutionId: ssmPipelineExecutionId })
+  .waitForAssertions({ interval: cdk.Duration.seconds(30) })
+  .expect(ExpectedResult.objectLike({ pipelineExecution: { status: 'Succeeded' } }));


Why not add the same checks for SSM_MANAGED_NODES and EC2 one ?
Is there some difference between the usages of the two instance types ? If so maybe we need to update the README example to reflect this

These checks seem to be missing from SSM_MANAGED_NODE types :

waitPipelieneSuccess.next(
integ.assertions
.httpApiCall(http://${alb.loadBalancerDnsName}/LB/index.html)
.expect(ExpectedResult.objectLike({ status: 200 })),
);
instances.NoLB.forEach((instance) => waitPipelieneSuccess.next(
integ.assertions
.httpApiCall(http://${instance.instancePublicDnsName}/NoLB/index.html)
.expect(ExpectedResult.objectLike({ status: 200 })),
));

As far as I know, SSM_MANAGED_NODES are on-premise instances outside of AWS.
These instances cannot be created in integ test.
(please correct me if wrong.)

The EC2 deploy action will succeed if no instances match.
So I only verify whether the pipeline succeeds.

I noticed that SSM_MANAGED_NODE matches EC2 instances.
I've made separate 2 integ tests with EC2 and SSM_MANAGED_NODE.

kumvprat · 2025-05-23T13:32:24Z

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts

+        'ec2:DescribeInstances',
+        'elasticloadbalancing:DescribeTargetGroupAttributes',
+        'elasticloadbalancing:DescribeTargetGroups',
+        'elasticloadbalancing:DescribeTargetHealth',


Thanks for investigating this
We could add this link : https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssystemsmanager.html and for the related elasticloadbalancing to the PR description/README

Would be nice for users to know about IAM actions

Tietew · 2025-05-27T04:02:13Z

Is there a specific reason for clubbing the deploy spec support in this PR ?

DeploySpec support will introduce the "choice" which deployment style are used.
At least I want to supply bind()-style integration class.
https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md#unions

I'll drop deploySpec support in this PR if needed.

Tietew · 2025-05-29T07:07:54Z

I could not succeed to deploy with deployspec.yml currently.
Therefore, I'll drop DeploySpec support in this PR...

Tietew · 2025-05-29T07:35:42Z

@kumvprat
Thanks for review!

I've pushed updates and marked as ready.
The DeploySpec support will be a separate PR.

We could add this link : https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssystemsmanager.html and for the related elasticloadbalancing to the PR description/README

I've added refs in PR description and code comments.
But I didn't add to README because it doesn't explain any IAM permissions CDK will grant.

kumvprat

LGTM

mergify · 2025-06-05T15:05:41Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-06-05T15:09:28Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

aws-cdk-automation · 2025-06-05T16:02:59Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
Commit ID: 558af95
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

mergify · 2025-06-05T16:03:25Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2025-06-05T16:03:45Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

Tietew added 2 commits February 27, 2025 17:42

CodePipeline EC2 deployment support

76b324e

integ test

9ff2442

github-actions bot added effort/medium Medium work item – several days of effort feature-request A feature should be added or improved. p2 labels Feb 27, 2025

aws-cdk-automation requested a review from a team February 27, 2025 08:58

github-actions bot added the star-contributor [Pilot] contributed between 25-49 PRs to the CDK label Feb 27, 2025

Tietew commented Feb 27, 2025

View reviewed changes

...ages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/assets/artifact.zip Outdated Show resolved Hide resolved

Tietew commented Feb 27, 2025

View reviewed changes

Tietew added 2 commits February 27, 2025 18:32

fix README

e97afd5

remove redundant docs

6773a05

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Feb 27, 2025

Tietew commented Feb 27, 2025

View reviewed changes

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts Outdated Show resolved Hide resolved

github-actions bot mentioned this pull request Mar 1, 2025

Monthly PR metrics report #33661

Closed

Tietew added 4 commits March 17, 2025 13:01

Merge branch 'main' into codepipeline-ec2deploy

f0e9a53

remove validations to ensure maxError < maxBatch

30a6d9b

update max percentage to 100%

c2ee1ee

update snapshot

afdd585

Tietew added 5 commits March 21, 2025 09:48

Merge branch 'main' into codepipeline-ec2deploy

cb99304

Merge branch 'main' into codepipeline-ec2deploy

5fec3f4

move artifact.zip to prevent unexpected snapshot changes

ea61e43

Merge branch 'main' into codepipeline-ec2deploy

bc14580

update snapshot (nodejs22)

b7c4153

Tietew marked this pull request as draft May 21, 2025 07:34

kumvprat reviewed May 21, 2025

View reviewed changes

kumsmrit reviewed May 21, 2025

View reviewed changes

packages/aws-cdk-lib/aws-codepipeline-actions/lib/ec2/deploy-action.ts Outdated Show resolved Hide resolved

aws deleted a comment from kumvprat May 21, 2025

Tietew added 6 commits May 23, 2025 14:54

Merge branch 'main' into codepipeline-ec2deploy

a2a2b59

fix typo

abf0f32

optional instanceTagValue

3445b48

mandatory instanceType

3d1d443

add SSM_MANAGED_NODE to integ test

249f396

wip - deploy spec support

c5f36ec

kumvprat reviewed May 23, 2025

View reviewed changes

Tietew added 2 commits May 29, 2025 15:29

separate integ test EC2 and SSM_MANAGED_NODE

c948add

drop deployspec support

8287df1

Tietew marked this pull request as ready for review May 29, 2025 07:08

Add comments on permissions

3692710

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label May 29, 2025

kumvprat self-assigned this Jun 4, 2025

kumvprat approved these changes Jun 5, 2025

View reviewed changes

aws-cdk-automation removed the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Jun 5, 2025

Merge branch 'main' into codepipeline-ec2deploy

558af95

mergify bot merged commit 9d39db7 into aws:main Jun 5, 2025
16 checks passed

github-actions bot locked as resolved and limited conversation to collaborators Jun 5, 2025

Tietew deleted the codepipeline-ec2deploy branch June 5, 2025 22:46

feat(codepipeline-actions): native Amazon EC2 deployment support #33604

feat(codepipeline-actions): native Amazon EC2 deployment support #33604

Uh oh!

Conversation

Tietew commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Usage

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

Uh oh!

codecov bot commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tietew Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Tietew commented Mar 17, 2025

Uh oh!

Tietew commented May 21, 2025

Uh oh!

kumvprat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tietew May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tietew May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kumvprat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tietew May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tietew commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tietew commented May 29, 2025

Uh oh!

Tietew commented May 29, 2025

Uh oh!

kumvprat left a comment

Choose a reason for hiding this comment

Uh oh!

Tietew commented Feb 27, 2025 •

edited

Loading

codecov bot commented Feb 27, 2025 •

edited

Loading

Tietew Feb 27, 2025 •

edited

Loading

Tietew May 22, 2025 •

edited

Loading

Tietew May 23, 2025 •

edited

Loading

Tietew May 27, 2025 •

edited

Loading

Tietew commented May 27, 2025 •

edited

Loading