Skip to content

Commit

Permalink
feat(custom-resource): AwsCustomResource supports AWS SDK for JavaScr…
Browse files Browse the repository at this point in the history
…ipt v3 (#25406)

## What changes
Add support of AWS SDK for JavaScript v3 to `AwsCustomResource`. It also continues to works with runtimes that use the AWS SDK for JavaScript v2 (e.g Node.js 16.x).
**⚠️ This PR only add support, doesn' change custom resource default runtime version**

## Why need this change?
Because AWS SDK for JavaScript v2 enters into maintenance mode in 2023.
At least, we must upgrade Node.js runtime to 18 or higher version that using AWS SDK for JavaScript v3 in 2023. If not upgrade, when customers possibly can't use new AWS Service's APIs.

※ reference from [Document for AWS SDK for JavaScript v2](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/)
> ### Version 2.x Support
> We are formalizing our plans to enter AWS SDK for JavaScript v2 into maintenance mode in 2023.
 [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) is the latest and recommended version, which has been GA since December 2020. Here is [why and how you should use AWS SDK for JavaScript v3](https://aws.amazon.com/blogs/developer/why-and-how-you-should-use-aws-sdk-for-javascript-v3-on-node-js-18/). You can try our experimental migration scripts in [aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod) to migrate your application from v2 to v3.
To get help with your migration, please follow our general guidelines to [open an issue](https://github.com/aws/aws-sdk-js/issues/new/choose) and choose [guidance](https://github.com/aws/aws-sdk-js/issues/new?assignees=&labels=guidance%2C+needs-triage&template=---questions---help.md&title=). To give feedback on and report issues in the v3 repo, please refer to [Giving feedback and contributing](https://github.com/aws/aws-sdk-js-v3#giving-feedback-and-contributing).
Watch this README and the [AWS Developer Tools Blog](https://aws.amazon.com/blogs/developer/) for updates and announcements regarding the maintenance plans and timelines. Please refer to the [AWS SDKs and Tools maintenance policy](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html) for further details.

## Why don't change default runtime version?
AWS Lambda uses AWS SDK for JavaScript v3 since Node.js 18.x runtime. This is major update so I think it has breaking changes. This is reason. So I plan this.
1. Add experimentally support AWS SDK for JavaScript v3 (this PR)
2. Announce experimentally support Node.js 18.x runtime for customers who wish to update
3. Change `AwsCustomResource`'s default runtime to Node.js 18.x in 2023 or Node.js 16.x EOL

This plan allows time for transition before changing the default runtime for `AwsCustomResource`.

## Are there any changes to the props?
Yes. The specification method for the AWS SDK for JavaScript v3 will now be supported.
In AWS SDK for JavaScript v3, packages are installed for each service. Therefore, specify the package name for `service`. Also, `action` specifies the XxxClient operations provided in the package.

Example of [SSM.getParameter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/preview/client/ssm/):
```ts
new AwsCustomResource(this, 'GetParameter', {
  resourceType: 'Custom::SSMParameter',
  onUpdate: {
    service: '@aws-sdk/client-ssm', // 'SSM' in v2
    action: 'GetParameterCommand', // 'getParameter' in v2
    parameters: {
      Name: 'foo',
      WithDecryption: true,
    },
    physicalResourceId: PhysicalResourceId.fromResponse('Parameter.ARN'),
  },
});
```

## What actions do customers need to take when migrating?
Nothing to do. To maintain backward compatibility, when customers provides AWS SDK for JavaScript v2 style parameters, then `AwsCustomResource`  automatically convert the parameters to AWS SDK for JavaScript v3 style and handle it in lambda runtime code. Next example will be allowed.
```ts
new AwsCustomResource(this, 'CostUsageReportDefinitions', {
  resourceType: 'Custom::CostUsageReportDefinitions',
  onUpdate: {
    service: 'CUR', // will convert to '@aws-sdk/client-cost-and-usage-report-service'
    action: 'describeReportDefinitions', // will convert to 'DescribeReportDefinitionsCommand'
    parameters: {
      MaxResults: 5,
    },
    physicalResourceId: PhysicalResourceId.of('xxx'),
  },
});
```

## How can I use it before the default runtime changes?
On hold. Considering overriding with [`regioninfo.Fact.register`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.region_info-readme.html#overriding-incorrect-information) or rewriting it like `addPropertyOverride` by customers. There are currently no plans to provide dedicated functions.

## Others
- I added 3 packages for testing
  - @aws-sdk/client-s3
  - @aws-sdk/credential-providers
  - aws-sdk-client-mock
- I'm referring to part of the code at [aws-sdk-js-codemod](https://github.com/awslabs/aws-sdk-js-codemod). The license is from the same organization, so I don't think there's a problem, but I'll write it down for confirmation.



----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
WinterYukky committed Jun 6, 2023
1 parent 8633c5d commit 60699f4
Show file tree
Hide file tree
Showing 36 changed files with 5,386 additions and 946 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// @ts-ignore
import { S3Client } from '@aws-sdk/client-s3'; // eslint-disable-line import/no-extraneous-dependencies, import/no-unresolved

const s3 = new S3Client();
const s3 = new S3Client({});

export async function handler() {
console.log(s3);
Expand Down

Large diffs are not rendered by default.

Large diffs are not rendered by default.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Large diffs are not rendered by default.

Large diffs are not rendered by default.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 60699f4

Please sign in to comment.