Implementing Multi‑Tenant Architecture with Spring Boot and Spring Cloud

Overview

Multi‑tenant architecture allows multiple tenants to share a single application while keeping their resources and data completely isolated. It enables personalized tenant requirements, reduces operational and development costs, and improves scalability.

Advantages

Better fulfillment of individual tenant needs.

Lower operational costs and reduced infrastructure investment.

Reduced development effort through code reuse.

Enhanced scalability and horizontal expansion.

Technical Choices

The most important factor is a correct architectural mindset; however, choosing the right technologies accelerates implementation.

Design Approach

Architecture Selection

For Java‑based multi‑tenant applications, Spring Boot and Spring Cloud are recommended. Spring Boot simplifies project setup and auto‑configures common libraries, while Spring Cloud provides tools for micro‑service architectures.

Spring Boot

Spring Boot streamlines project creation and reduces developer workload.

@RestController
public class TenantController {
    @GetMapping("/hello")
    public String hello(@RequestHeader("tenant-id") String tenantId) {
        return "Hello, " + tenantId;
    }
}

Spring Cloud

Spring Cloud offers solutions such as Eureka, Zookeeper, and Consul for service discovery and load balancing.

Database Design

Two common approaches ensure data isolation:

Shared database with a tenant_id column in each table.

Separate database per tenant with identical schemas.

Application Deployment

Key considerations include application isolation (e.g., containers or VMs) and tenant‑specific configuration (ports, SSL certificates, etc.). Docker is a popular isolation technology.

Tenant Management

Manage tenant data and permissions. Typical operations include create, update, delete, and query tenant information.

CREATE TABLE tenant (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) NOT NULL UNIQUE,
    description VARCHAR(255),
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Permission control ensures tenants cannot access each other's resources.

@EnableGlobalMethodSecurity(prePostEnabled = true)
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/api/tenant/**").hasRole("ADMIN")
            .anyRequest().authenticated()
            .and()
            .formLogin();
    }
    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userDetailsService())
            .passwordEncoder(new BCryptPasswordEncoder())
            .and()
            .inMemoryAuthentication()
            .withUser("admin")
            .password(new BCryptPasswordEncoder().encode("123456"))
            .roles("ADMIN");
    }
}

Technical Implementation

Spring Boot Multi‑Tenant Implementation

Multiple data sources are configured, each representing a tenant.

@Configuration
public class DataSourceConfig {
    @Bean(name = "dataSourceA")
    @ConfigurationProperties(prefix = "spring.datasource.a")
    public DataSource dataSourceA() { return DataSourceBuilder.create().build(); }

    @Bean(name = "dataSourceB")
    @ConfigurationProperties(prefix = "spring.datasource.b")
    public DataSource dataSourceB() { return DataSourceBuilder.create().build(); }

    @Bean(name = "dataSourceC")
    @ConfigurationProperties(prefix = "spring.datasource.c")
    public DataSource dataSourceC() { return DataSourceBuilder.create().build(); }
}

Dynamic routing selects the appropriate data source at runtime.

public class DynamicDataSource extends AbstractRoutingDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        return TenantContextHolder.getTenantId();
    }
}

@Configuration
public class DataSourceConfig {
    @Bean(name = "dataSource")
    @ConfigurationProperties(prefix = "spring.datasource")
    public DataSource dataSource() {
        return DataSourceBuilder.create().type(DynamicDataSource.class).build();
    }
}

Spring Cloud Multi‑Tenant Implementation

Service registration (Eureka), configuration center, and Ribbon load balancing are used to separate tenant traffic.

Application Scenarios

Private‑cloud environments for internal enterprise use.

Public‑cloud SaaS platforms offering isolated tenant instances.

Enterprise‑grade applications such as ERP, CRM, and OA systems.

Implementation Steps

1. Set Up Spring Boot and Spring Cloud

org.springframework.boot
spring-boot-starter-web
org.springframework.cloud
spring-cloud-dependencies
2020.0.3
pom
import

Configure the application properties (datasource URL, server port, Eureka URL, etc.) in application.yml .

2. Modify Database Design

Add a tenant identifier column or create separate databases per tenant.

3. Implement Multi‑Tenant Deployment

Instantiate tenant‑specific Spring beans and route requests based on the tenant ID.

@Configuration
public class MultiTenantConfig {
    // Provide tenant‑specific DataSource
    @Bean
    public DataSource dataSource(TenantRegistry tenantRegistry) {
        return new TenantAwareDataSource(tenantRegistry);
    }
    // Configure MyBatis SqlSessionFactory
    @Bean(name = "sqlSessionFactory")
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        return sessionFactory.getObject();
    }
    // Dynamic tenant interceptor
    @Bean
    public MultiTenantInterceptor multiTenantInterceptor(TenantResolver tenantResolver) {
        MultiTenantInterceptor interceptor = new MultiTenantInterceptor();
        interceptor.setTenantResolver(tenantResolver);
        return interceptor;
    }
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(multiTenantInterceptor());
    }
    @Bean
    public TenantRegistry tenantRegistry() { return new TenantRegistryImpl(); }
    @Bean
    public TenantResolver tenantResolver() { return new HeaderTenantResolver(); }
}

4. Implement Tenant Management

Use Eureka to register each tenant instance and provide an independent database for data isolation.

Conclusion

The article demonstrates how to build a multi‑tenant SaaS application with Spring Boot and Spring Cloud, covering environment setup, database design, deployment, and tenant management. While multi‑tenant architecture improves scalability and maintainability, it also adds deployment and operational complexity, suggesting future work on automation and reduced manual intervention.