Upgrade to AWS SDK V3

[tazorax]

First of all, thanks a lot for this serverless V3 revival.

Is there any plan to use aws-sdk v3 package? The v2 will be end of support in september 2025.

[mnapoli]

Eventually yes, but I think this is a major effort unfortunately.

[rageycomma]

I think this does fall under the “major features” — plus the way the CLI is structured it relies on the v2 sdk exporting all the methods in one big export whereas in v3 the libs function differently.

Agree this is huge effort but eventually v2 is going to stop working.

[GrahamCampbell]

Not to mention breaking a lot of plugins.

[GrahamCampbell]

That is to say that changing the SDK version will do that.

[mato-gallardo]

Any updates on this? How can I contribute to the migration?

[adamsea]

+1 here -- happy to help contribute if we want to break it down into subtasks

[GrahamCampbell]

The problem is we'll break all plugins that are using:

const awsSdk = this.serverless.getProvider('aws').sdk;

As this is the v2 SDK. At this point, it's probably not too hard to get claude to do the upgrade to v3, but it's not super clear if we actually want this, at the expense of breaking plugins when the old sdk still works just fine.

[GrahamCampbell]

Detailed AWS SDK v2 to v3 Migration Plan (from Claude 4 Sonnet)

Based on my comprehensive analysis of the serverless codebase, here's a detailed migration plan:

Current State Summary

Hybrid State Detected:

• AWS SDK v2: Used in ~60+ files via centralized lib/aws/request.js wrapper
• AWS SDK v3: Already implemented in 7 custom resource files
• Dual Dependencies: Both "aws-sdk": "^2.1404.0" and 6 @aws-sdk/client-* packages present

Phase 1: Foundation & Infrastructure (Days 1-3)

1.1 Package Dependencies Update

// Add to package.json dependencies:
"@aws-sdk/client-cloudformation": "^3.588.0",
"@aws-sdk/client-cloudwatch": "^3.588.0",
"@aws-sdk/client-cloudwatch-logs": "^3.588.0",
"@aws-sdk/client-ecr": "^3.588.0",
"@aws-sdk/client-apigatewayv2": "^3.588.0",
"@aws-sdk/client-ssm": "^3.588.0",
"@aws-sdk/credential-providers": "^3.588.0"

1.2 Create AWS SDK v3 Infrastructure

New Files to Create:

• lib/aws/sdk-v3.js - Centralized v3 client factory
• lib/aws/request-v3.js - New request wrapper for v3 pattern
• lib/aws/clients.js - Shared client instances with configuration

1.3 Migration Utilities

Helper Functions:

• V2 to V3 parameter transformation utilities
• Error handling adapters
• Pagination helpers for v3 pattern

Phase 2: Core Request Layer Migration (Days 4-7)

2.1 Create V3 Request Wrapper

File: lib/aws/request-v3.js

• Implement v3 equivalent of current lib/aws/request.js
• Handle service client instantiation
• Maintain compatibility with existing provider.request() interface
• Implement retry logic, proxy support, timeout handling

2.2 Update Provider Class

File: lib/plugins/aws/provider.js

• Add parallel v3 request method alongside existing v2
• Gradual migration of service calls
• Maintain backward compatibility during transition

Phase 3: Service-by-Service Migration (Days 8-20)

Priority Order (by usage frequency and complexity):

3.1 CloudFormation Service (HIGH PRIORITY - Days 8-10)

Files Affected: ~15 files
Methods to Migrate:

• createStack, createChangeSet, deleteChangeSet, executeChangeSet
• updateStack, deleteStack, describeStacks, validateTemplate
• setStackPolicy, getTemplate, listStackResources

Key Changes:
// V2 Pattern
await this.provider.request('CloudFormation', 'createStack', params);

// V3 Pattern
await this.provider.requestV3('CloudFormation', 'CreateStackCommand', params);

3.2 S3 Service (HIGH PRIORITY - Days 11-12)

Files Affected: ~10 files
Methods to Migrate:

• listObjectsV2, listObjectVersions, deleteObjects
• headObject, upload, getObject, getBucketLocation

Complexity: Medium (some files already use v3, need to consolidate)

3.3 Lambda Service (HIGH PRIORITY - Days 13-14)

Files Affected: ~8 files
Methods to Migrate:

• getFunction, updateFunctionConfiguration, updateFunctionCode
• invoke, listVersionsByFunction, getLayerVersion

3.4 API Gateway Services (MEDIUM PRIORITY - Days 15-16)

Files Affected: ~6 files
Services: Both APIGateway and ApiGatewayV2
Methods: getApiKey, createStage, tagResource, updateStage, etc.

3.5 CloudWatch & Logging (MEDIUM PRIORITY - Days 17-18)

Files Affected: ~4 files
Services: CloudWatch, CloudWatchLogs
Methods: getMetricStatistics, describeLogStreams, filterLogEvents

3.6 IAM & ECR (LOW PRIORITY - Days 19-20)

Files Affected: ~3 files
Services: IAM, ECR
Methods: getRole, deleteRepository, describeRepositories

Phase 4: Variable Resolution & SSM (Days 21-22)

4.1 SSM Parameter Resolution

File: lib/configuration/variables/sources/instance-dependent/get-ssm.js

• Migrate from v2 new AWS.SSM() to v3 SSMClient
• Update getParameter method calls

4.2 CloudFormation Value Resolution

Files: CF and S3 value resolution utilities

• Update variable resolution that uses AWS services

Phase 5: Test Migration (Days 23-25)

5.1 Test Utilities Update

Files Affected: ~15 test utility files in /test/utils/

• test/utils/cloudformation.js
• test/utils/s3.js
• test/utils/api-gateway.js
• etc.

5.2 Mock Updates

Test Pattern Changes:
// V2 Mocking
const AWS = require('aws-sdk');
AWS.CloudFormation.prototype.createStack = sinon.stub();

// V3 Mocking
const { CloudFormationClient } = require('@aws-sdk/client-cloudformation');
sinon.stub(CloudFormationClient.prototype, 'send');

Phase 6: Integration & Cleanup (Days 26-30)

6.1 Integration Testing

• Run full test suite with v3 implementation
• Test real AWS operations with integration tests
• Performance comparison between v2 and v3

6.2 Final Migration Steps

• Switch default provider.request() to use v3
• Remove v2 fallbacks
• Remove aws-sdk v2 dependency
• Update lib/aws/sdk-v2.js → lib/aws/sdk-v3.js

6.3 Documentation Updates

• Update any internal documentation
• Update contribution guidelines if applicable

Critical Implementation Details

Error Handling Transformation

// V2 Error Pattern
catch (error) {
if (error.code === 'ValidationError') // handle
}

// V3 Error Pattern
catch (error) {
if (error.name === 'ValidationException') // handle
}

Pagination Pattern Changes

// V2 Pagination
const result = await service.listObjects({ ContinuationToken: token }).promise();

// V3 Pagination
import { paginateListObjectsV2 } from '@aws-sdk/client-s3';
for await (const page of paginateListObjectsV2({ client: s3 }, params)) {
// handle page
}

Configuration Migration

// V2 Configuration
new AWS.S3({ region: 'us-east-1', maxRetries: 3 });

// V3 Configuration
new S3Client({
region: 'us-east-1',
maxAttempts: 3,
retryMode: 'adaptive'
});

Risk Mitigation

1. Parallel Implementation: Keep both v2 and v3 implementations running during migration
2. Feature Flags: Environment variable to switch between v2/v3 for testing
3. Gradual Rollout: Service-by-service migration allows for incremental testing
4. Fallback Strategy: Ability to rollback to v2 if critical issues arise

Expected Benefits Post-Migration

1. Bundle Size: ~70% reduction in AWS SDK bundle size
2. Performance: Faster cold starts, tree-shaking benefits
3. Type Safety: Better TypeScript support
4. Maintenance: Single SDK version, consistent patterns
5. Future-Proof: AWS SDK v2 is in maintenance mode

Effort Estimation

• Total Duration: 30 working days
• Risk Level: Medium-High (due to scope)
• Testing Required: Extensive integration testing
• Rollback Plan: Maintain v2 capability until full validation

This migration affects the core of the serverless framework's AWS integration and should be approached
methodically with extensive testing at each phase.

[GrahamCampbell]

Feel free to give this a try. #65

[mnapoli]

Hey everyone, we've released a new version (v3.52.0) that lets you switch to the SDK v3 via a feature flag:

export SLS_AWS_SDK_V3=1
serverless deploy

Please help us validate that everything works fine with the SDK v3 so that we can make it the default in a future version 🙏

Edit: please report bugs in separate issues, that will make it easier to follow overall progress here.

[mnapoli]

@sunaoka can you open bug reports in separate issues? That will help keep this thread to update on overall progress.

Thanks!

[sunaoka]

@mnapoli Oh, I'm sorry. I posted the issue here. #74