docs/scf/deployment.md
When you deploy with the Serverless Container Framework (SCF), an entire architecture is deployed, including your containers, to deliver a fully-fledged, production-ready API.
You can mix compute types within your architecture - for example, using Lambda for lightweight API endpoints and Fargate for data-intensive operations.
SCF also makes it easy to switch containers between compute types with zero-downtime.
By default, SCF will detect what changed since your last deployment, and only redeploy the containers that have changed.
Here is everything you need to know about deploying with SCF.
To deploy all of your containers, run the following command:
serverless deploy
--stageBy default, the project will deploy all containers in the dev stage. You can target a different stage by using the --stage flag: serverless deploy --stage prod.
--forceSCF checks for changes in your config or code. If only one container changed, for instance, it will only redeploy that container. This can significantly speed up deployments. However, you can also force a full deployment by using this flag.
--debugThis flag will enable debug logging. If you encounter an issue, please enable debug logging and provide the logs to the Serverless team.
SCF requires AWS credentials to deploy your containerized architecture. Configure your AWS credentials using one of these methods:
# Option 1: AWS CLI (recommended)
aws configure
# Option 2: Environment variables
export AWS_ACCESS_KEY_ID=your-key-id
export AWS_SECRET_ACCESS_KEY=your-access-key
export AWS_SESSION_TOKEN=your-session-token
SCF requires Docker to build your container images.
Before deploying, ensure you have the relevant configuration in your serverless.containers.yml file. Key fields typically include:
namespace: The "namespace" and "stage" → used to generate unique resource names, track state, and separate multiple environments. All resources will be prefixed with the namespace and stage.
provider: This project is designed to work with multiple cloud providers. The provider field is used to specify the cloud provider and region. Initially, the project supports AWS.
containers: At minimum, each container should specify its src code directory and compute type.
When you deploy with SCF using the [email protected] deployment type, the following AWS resources are automatically provisioned to create a production-ready API architecture:
awsLambda compute type. Deployed with an AWS Lambda function URL.All resources are automatically configured with security best practices and are optimized for the specific compute types you choose for your containers.
When you run the deploy command, SCF orchestrates several steps. This includes:
SCF will fetch and resolve AWS credentials automatically if properly configured. AWS credentials are required to use SCF. It resolves AWS credentials through AWS profiles or AWS environment variables.
Any Serverless Framework Variables within your configuration are resolved (e.g., environment variables or references to secrets on AWS SSM, Hashicorp Terraform state outputs, Vault, etc.). This can include stage-specific overrides or dynamic references.
SCF requires Docker to build your container images.
The system checks that all required fields (e.g., namespace, stage, AWS region, etc.) are in place and have valid values.
By default, SCF attempts to detect what needs updating. If only one container changed, for instance, it will only redeploy that container. This can significantly speed up deployments. You can also force a full deployment by using the --force flag. Code and configuration changes are detected by comparing the current state of your project with the last deployed state.
If you do not have a Dockerfile within your container's src directory, SCF will attempt to auto-containerize your code using Cloud Native Buildpacks. Buildpacks, originally developed by Heroku and now maintained by Google and other CNCF members, automatically detect your application's language and dependencies to create optimized container images. They work by:
When deploying to AWS Lambda, SCF automatically includes essential Lambda components:
These Lambda-specific components are only included when deploying to AWS Lambda compute type. When deploying to AWS Fargate, SCF creates standard container images without the Lambda layers, as they are not needed and would only add unnecessary overhead. The same application code can run on either compute type, as SCF handles the appropriate containerization for each target platform.
When using a custom Dockerfile, SCF will use it as-is without modification.
For AWS Fargate ECS deployments, SCF will use the Dockerfile as-is. No additional components are required. However, AWS Lambda requires a custom Dockerfile to be compatible. In this initial release of SCF, SCF does not automatically add essential AWS Lambda components to your container (coming soon).
In this case, your Dockerfile must include specific components to be Lambda-compatible:
FROM public.ecr.aws/lambda/nodejs:20
AWS provides official base images for all supported Lambda runtimes in their public ECR repository. You can browse all available images at: https://gallery.ecr.aws/lambda
# Add Lambda Runtime Interface Emulator (RIE)
COPY --from=public.ecr.aws/lambda/nodejs:20 /usr/local/bin/aws-lambda-rie /aws-lambda-rie
# Add Lambda Web Adapter as an extension
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 /lambda-adapter /opt/extensions/lambda-adapter
# Configure proper entrypoint for Lambda
ENTRYPOINT [ "/aws-lambda-rie" ]
CMD [ "app.handler" ]
For examples of Lambda-compatible Dockerfiles, see the AWS documentation: https://docs.aws.amazon.com/lambda/latest/dg/images-create.html
SCF will build the container images.
A build error on any container will halt the deployment. Build logs are shown only if there is an error or if the --debug flag is used.
You are able to pass build arguments to the build using the args configuration in the container's build configuration. Check out the configuration documentation for specifics.
The deployment process uses AWS APIs (Cloudfront, ECS, Lambda, ALB, VPC, etc.) to do the following, depending on your configuration. CloudFormation or other infrastructure-as-code tools are not used. Given SCF seeks to only deploy a specific architecture, rather than deploy every architecture like other IaC tools, SCF can better optimize the deployment process for speed and safety. For example, solutions to common pitfalls of cloud services are built into SCF, and advanced deployment patterns like compute type switching are supported.
This includes but is not limited to:
When deploying to AWS Fargate ECS, our strategy uses a rolling deployment model. During an update, new tasks are launched alongside the existing ones by registering an updated task definition. The service continuously runs both old and new revisions until the new tasks pass all health checks before the old tasks are terminated.
We explicitly configure ECS with a deployment circuit breaker where both enable and rollback are set to true. This configuration actively monitors the deployment by tracking task health via AWS ALB health checks. If the system detects any failures (for example, if tasks do not return a 200 status on the designated health check path), the deployment is automatically rolled back to the previous stable version. These health checks target the ALB health check path specified in the container's routing configuration.
ALB listener rules are adjusted during the deployment to control traffic routing. By dynamically managing these rules based on the health check results, the system ensures that only tasks passing the health checks receive production traffic.
After provisioning, the project saves state data that helps with incremental deployments and resource tracking.
Finally, you'll see logs or notices about the resources created or updated, along with any relevant URLs (ALB endpoints, etc.).
SCF enables seamless, zero-downtime transitions between compute types for live applications through a sophisticated orchestration process:
Parallel Deployment
Traffic Management
Safety Mechanisms
Completion