docs/scf/upgrading.md
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.
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 [email protected]. 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.
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.
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.
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']
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
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
SCF v2 provides improved AWS IAM role management with more flexible policy definitions. For details, see the AWS IAM Configuration section.
The deploymentType of [email protected] has been replaced with [email protected]. 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 [email protected] deployment type and re-deploying a new stack with the new deployment type.
Follow the steps below to learn how to safely upgrade.
We recommend deploying the new SCF deployment type ([email protected]) in parallel with your existing [email protected] setup. This allows for testing before decommissioning your current infrastructure.
cp serverless.containers.yml serverless.containers.yml.backup
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: [email protected]
to:
deployment:
type: [email protected]
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.
The new deployment routes all traffic through a CloudFront Function. This introduces:
serverless deploy
Once verified, clean up:
Warning: This will delete all associated AWS resources.
serverless remove --all --force
If you encounter issues during migration create a new Github Issue.