Organizations are moving to the SaaS (Software-as-a-service) delivery model to achieve optimized cost, operational efficiency and overall agility in their software business. SaaS helps to onboard their customers (tenants) into a centrally hosted version of the solution, and manage them via a single pane of glass. These SaaS solutions allow the underneath infrastructure components to be shared across tenants, while demanding mechanisms that can implement the multi-tenancy in the architecture to preserve overall security, performance and other non-functional requirements demanded by the use-case. Often, these strategies and their implementation heavily depend on the underneath technologies and AWS managed services that are being used.
This github solution provides code samples, configurations and best practices that help to implement multi-tenant SaaS reference architecture leveraging Amazon Elastic Container Service (ECS).
The objective here is to dive deeper into design principals and implementation details in building ECS SaaS reference solution covering necessary technical aspects. We will discuss SaaS control plane functionalities with shared services such as tenant onboarding, user management, admin portals, along with the SaaS application plane capabilities such as ECS compute isolation strategies, request routing at scale, service discovery, storage isolation patterns, API throttling and usage plans, and different ways to ensure security and scalability.
The following diagram shows the high-level architecture of the solution that outlines the core components of ECS SaaS. It is a tier-based SaaS, and the three tiers represent three different tenant isolation strategies using Amazon ECS. This would help SaaS providers to have a wide range of technical options to model their SaaS solution based on their tiering requirements.
- Basic Tier: Shared ECS Services across all the tenants (Pool model)
- Advanced Tier : Shared ECS Cluster, dedicated ECS services per tenant (Silo model)
- Premium Tier: Dedicated ECS Cluster per tenant (Silo model)
Fig 1: ECS SaaS - High-level infrastructure
This reference architecture adopts the latest AWS SaaS Builder Toolkit (SBT) that AWS SaaS Factory has developed. SBT helps to extend the SaaS control plane services such as tenant onboarding, off-boarding, tenant and user management, billing, etc seamlessly into the solution. It also provides an event-based integration to the ECS application plane that enables bi-directional communication for SaaS operations. Read more about AWS SBT here.
This solution can be deployed via your local environment which is connected with your AWS account.
In your local environment, it needs some free storage for artifacts of CDK built.
- This reference architecture uses Python. Ensure you have Python 3.11 or newer installed.
- Ensure you have AWS CLI v2 installed (latest version recommended).
- Ensure you have a Docker compatible runtime running (e.g., Docker Desktop, Colima, or Rancher Desktop).
- Ensure you have the latest version of AWS CDK CLI installed. Using an outdated version may cause deployment issues.
- Ensure that you have Node.js 22 (LTS) or newer.
- Ensure that you have Git installed.
To deploy this ECS SaaS reference solution, you can run the below commands. Replace the <admin_email> with a real email address that will be used to create an admin user in the solution, and to share the admin credentials that allow to perform administrative tasks such as onboarding new tenants.
git clone this_repo_url
cd saas-reference-architecture-ecs/scripts
./build-application.sh
./init-install.sh
./sbt-install.sh <admin_email>Builds Docker container images for the sample SaaS application microservices (order, product, user) and pushes them to Amazon ECR.
Deploys the core infrastructure and tenant templates:
1. Provision Source Setup
- Creates an S3 bucket to store the reference solution code
- Uploads source code used for dynamic tenant provisioning (Advanced/Premium tiers)
2. CDK Stack: shared-infra-stack (SharedInfraStack)
- Amazon VPC with 3 Availability Zones
- Application Load Balancers (ALB)
- API Gateway for tenant routing
- CloudFront distributions for admin and application sites
- DynamoDB table for tenant mapping
- S3 buckets for access logs
3. CDK Stack: tenant-template-stack-basic (TenantTemplateStack)
- ECS Cluster for Basic tier (pooled model)
- Amazon Cognito User Pool for tenant authentication
- Cloud Map namespace for service discovery
- DynamoDB tenant mapping entry
4. CDK Stack: tenant-template-stack-advanced (TenantTemplateStack)
- ECS Cluster for Advanced tier (silo model) with
CDK_ADV_CLUSTER=INACTIVE - Cluster only - services are provisioned dynamically during tenant onboarding
5. CDK Stack: tenant-service-stack-basic (TenantServiceStack)
- ECS Services: order, product, user microservices with Nginx reverse proxy
- DynamoDB tables for order and product data
- ALB listener rules and target groups for tenant routing
- IAM task roles with tenant-scoped access policies
Deploys the SaaS control plane and application plane:
1. CDK Stack: controlplane-stack (ControlPlaneStack)
- AWS SaaS Builder Toolkit (SBT) control plane components
- Amazon Cognito for admin authentication
- EventBridge for tenant lifecycle events
- API Gateway for tenant management APIs
- Admin web UI deployment
2. CDK Stack: core-appplane-stack (CoreAppPlaneStack)
- SBT core application plane components
- AWS CodeBuild projects for tenant onboarding/offboarding
- EventBridge rules to trigger provisioning workflows
- Application web UI deployment
- Integration with control plane via EventBridge events
Run the following script to clean up reference solution resources from your AWS account. Please make sure that jq JSON processor installed in your environment before invoking below script.
cd scripts
./cleanup/cleanup.shThis library is licensed under the MIT-0 License. See the LICENSE file.
See CONTRIBUTING for more information.