6.8 KiB
| title | short_title | description | keywords | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Serverless Container Framework - Upgrading Guide | Upgrading Guide | Complete guide to upgrading from Serverless Container Framework v1 to v2. Learn about breaking changes, new features, and step-by-step migration instructions including deployment type updates and new integrations. |
|
Upgrading from SCF v1 to v2
This guide will help you upgrade your Serverless Container Framework (SCF) projects from v1 to v2. SCF v2 introduces several new features and some breaking changes that require configuration updates and a specific migration process.
Overview of Changes
A Single, Powerful Architecture
In SCF v1, we introduced deploymentType to specify both the target cloud and the container architecture (e.g., an API on AWS or an event handler). Since then, we've found that a single architecture can support a wide range of use cases—such as synchronous request/response workflows and asynchronous event handling. As a result, we're simplifying deploymentType to only specify the target cloud with a new simplified deployment type aws@1.0. This change streamlines the deployment process and better positions us for future multi-cloud support.
However, this is a breaking change. awsApi1.0 will still be supported, but all new features listed here and going forward will be in aws1.0. Follow the steps below to learn how to upgrade.
Caching & Routing At The Edge
We've introduced routing via AWS CloudFront Functions for faster performance and greater flexibility in directing traffic to AWS ECS, Lambda, and more. This approach resolves key limitations of AWS Application Load Balancer—like lack of streaming support and the 1MB request/response header cap—by routing directly to Lambda via function URLs.
Further, switching workloads between compute services is now instantaneous, unlike the slower reconfiguration required with ALB. Additionally, with CloudFront as a first-class component, caching is built-in by default—making your deployments more production-ready out of the box.
New Use Cases & Integrations
We've added a new integrations property to make it easier to connect your app with external services.
For complete integration configuration examples and options, see the Container Integrations Configuration section.
AWS EventBridge Integration
You can now receive events from AWS EventBridge and define routing logic for them. SCF handles all the setup for subscriptions automatically.
integrations:
event-processor:
type: awsEventBridge
webhookPath: '/integrations/event-processor/eventbridge' # Optional; defaults to /integrations/<name>/eventbridge
pattern: # Required: Event filtering criteria
source: ['myapp.orders', 'myapp.users'] # Required
detail-type: ['Order Created', 'User Registered'] # Optional
detail: # Optional: Match specific fields in the event payload
status: ['pending', 'processing']
Scheduled Tasks
Run scheduled jobs using the schedule integration. Ideal for periodic tasks like cleanups or data syncs.
integrations:
daily-cleanup:
type: schedule
webhookPath: '/integrations/daily-cleanup/schedule' # Optional; defaults to /integrations/<name>/schedule
schedule: 'rate(1 day)' # Required: Schedule expression
Slack Integration
You can now connect SCF to Slack—useful for internal tools and AI agents. SCF supports both standard and socket mode.
integrations:
slack-notifications:
type: slack
name: 'API Notifications' # Required: Display name for the Slack app
socketMode: false # Optional; defaults to false
webhookPath: '/integrations/slack-notifications/slack' # Optional; defaults to /integrations/<name>/slack
credentials: # Optional: Slack app credentials
signingSecret: ${env:SLACK_SIGNING_SECRET} # Required
botToken: ${env:SLACK_BOT_TOKEN} # Required
appToken: ${env:SLACK_APP_TOKEN} # Required if socketMode is true
Enhanced IAM Configuration
SCF v2 provides improved AWS IAM role management with more flexible policy definitions. For details, see the AWS IAM Configuration section.
Breaking Changes
The deploymentType of awsApi@1.0 has been replaced with aws@1.0. All new features listed here and going forward will be in the new aws1.0 deployment type. Unfortunately, this will require decommissioning your current infrastructure using the awsApi@1.0 deployment type and re-deploying a new stack with the new deployment type.
Follow the steps below to learn how to safely upgrade.
Migration
We recommend deploying the new SCF deployment type (aws@1.0) in parallel with your existing awsApi@1.0 setup. This allows for testing before decommissioning your current infrastructure.
Backup Your Current Configuration
cp serverless.containers.yml serverless.containers.yml.backup
Update Your Configuration
In your serverless.containers.yml, change the name property to create an entirely seperate stack of new infrastructure that does not have names that collide with existing infrastructure (in the case of testing on the same AWS account).
Next, change the deployment type:
deployment:
type: awsApi@1.0
to:
deployment:
type: aws@1.0
Be sure to remove any custom domains in the new config to avoid traffic redirection. SCF will give you a CloudFront domain by default for safe testing. You can reintroduce custom domains once you're confident in the new setup.
Refer to the Configuration Guide for changes or new features you may want to adopt. You can always add new features in future deployments, after you've tested and migrated.
Note on Architecture Changes
The new deployment routes all traffic through a CloudFront Function. This introduces:
- Better flexibility across compute types and clouds.
- Performance and cost implications. Test accordingly.
- Future support for editing the routing function.
Deploy the New Stack
serverless deploy
Final Cutover
Once verified, clean up:
- Swap filenames.
- Remove the old stack:
Warning: This will delete all associated AWS resources.
serverless remove --all --force
Additional Resources
Support
If you encounter issues during migration create a new Github Issue.