Hello Apache Unomi community members,As I mentioned a few times previously,
I have been interested in working on multi-tenancy support for Apache
Unomi.I started prototyping last week and this quickly turned into much
more than a prototype so I wanted to update you on my progress so far.I put
together quickly (yes AI was used sorry :)) this summary for why, and how
much of the work was done so far, and what remains to be done. If you have
any questions please don't hesitate.Implementation Strategy & Rationale:
- Target Use Case:
- Designed specifically to support hundreds or thousands of small tenants
efficiently
- Optimized for scenarios where many small organizations need their own
isolated space
- Cost-effective solution for small to medium-sized tenants
- Large enterprise tenants can (still) be deployed on dedicated
Elasticsearch/OpenSearch clusters
- Document-Level Multi-tenancy:
- Instead of creating separate indices per tenant, I implemented a
shared-index approach:
- Added tenantId field to all documents
- Prefixed document IDs with tenant identifiers ({tenantId}_{originalId})
- All queries automatically include tenant filtering
- System tenant (default) data can be inherited by other tenants, to avoid
replicating for each tenant data that can be shared instead (such as JSON
files deployed by plugins, or the Geonames database)
- Tenant Inheritance Model:The "inheritance" is actually quite basic, it
just means that the object can be defined in the "system" tenant, and all
the sub-systems that implement the inheritance will be able to access
those. Each tenant may override a system object. The following objects
support inheritance from the system tenant:
- Rules
- Value types
- Condition Types
- Action Types
- Geonames Entry
- PropertyType
- Persona
- JSONSchemaWrapperThis allows tenants to leverage common values while
maintaining the ability to override or extend them.
- Scalability Benefits:
- Significantly reduces index overhead:
- Traditional approach: Each tenant requires its own set of indices
- Our approach: All small tenants share the same set of indices
- Efficient resource utilization:
- Reduced memory footprint for index management
- Better utilization of Elasticsearch/OpenSearch heap space
- Shared segment files and caches across tenants
- Optimized for cloud deployments:
- Lower hosting costs for small tenant deployments
- More predictable resource usage
- Easier capacity planningCompleted Changes:
- Core Multi-tenancy Infrastructure:
- Implemented TenantService interface and core implementation
- Added tenant data isolation in persistence layer
(Elasticsearch/OpenSearch)
- Created tenant-aware service base class (AbstractTenantAwareService)
- Added tenant context management with ThreadLocal storage
- Authentication & Security:
- Implemented API key-based authentication system:
- Public API endpoints using public API keys (context.json,
eventcollector.json now require a tenant public API key, they will reject
requests that don't include a valid public API key for a tenant). The old
third party code was replaced by tenant specific authorization, for example
the protection events such as login and event properties now require a
tenant private key.
- Private endpoints requiring tenant ID + private API key. This removes the
single karaf/karaf basic authentication need for accessing the Unomi
management APIs (actually the JAAS login is still available but tenants
should never use it).
- Added Basic Auth support for tenant credentials
- Implemented tenant isolation in data access
- Added security validation and tenant operation checks
- API & Management:
- Created REST endpoints for tenant management (CRUD operations)
- Implemented API key generation and management
- Added tenant migration tools for existing data
- Added resource quota management per tenant (data model only for the
moment, quota management is not implemented, and might not be implemented
in first version)4. Testing Infrastructure:
- Added new unit tests to test services without having to use integration
tests: for example we can now test the RulesService, DefinitionsService and
ProfileService without needing to start Elasticsearch or OpenSearch.
- New InMemoryPersistenceService implementation is now available for unit
tests, providing the basic method implementations to run most service unit
tests. We will see if at some point it makes any sense to move this
implementation into a real persistence backend but for the moment it is not
fully implemented and reserved for tests.
- Added integration tests for tenant functionality
- Modified existing integration tests to add support for multi-tenancy,
including adding public and private key authentication where needed.
- Created security-specific test suites
- Added tenant isolation testsRemaining Tasks:1. Testing & Quality
Assurance:
- Expand test coverage for tenant inheritance scenarios
- Create test utilities and documentation for tenant-aware testing
- Infrastructure Updates:
- Upgrade to the latest version of Karaf
- Update dependencies and configurations for Karaf compatibility
- Review and update OSGi configurations
- Ensure all services work correctly with the new Karaf version
- Remove Hazelcast and cluster code ? (This is a proposal)3. Tenant
Inheritance Implementation:
- Expand tenant inheritance to additional object types if identified/needed
- Improve inheritance behavior configuration
- Add inheritance override mechanisms
- Create clear documentation for inheritance patterns
- Add test coverage for inheritance scenarios4. Resource Management:
- Implement real-time quota monitoring
- Add quota enforcement mechanisms
- Create alerting system for quota limits
- Documentation:
- Complete API documentation for tenant endpoints
- Add migration guides for existing deployments
- Document best practices for multi-tenant deployments
- Document tenant inheritance patterns and best practices
- Future Enhancements (Lower Priority):
- OAuth2 integration for tenant authentication
- Additional authentication methods
- Advanced tenant-specific rate limitingNext Steps:
- Begin systematic review and update of integration tests to support
multi-tenancy
- Start the Karaf upgrade process and dependency updates
- Map out additional areas for tenant inheritance implementation
- Create test utilities to simplify tenant-aware testing
- Start documentation efforts in parallel, focusing on inheritance patternsThis
implementation strategy allows us to:
- Offer competitive pricing for small organizations
- Scale efficiently to support many tenants
- Maintain flexibility for enterprise deployments
- Optimize infrastructure costs
- Provide robust tenant isolation while sharing resources
Please let me know if you need any clarification or have questions about
specific aspects.Best regards, Serge Huber.
