diff --git a/doc/admin/cep.md b/doc/admin/cep.md index e7c42e83..fdaddfc6 100644 --- a/doc/admin/cep.md +++ b/doc/admin/cep.md @@ -126,6 +126,21 @@ The Cepheus-CEP loads its data on startup and saves back data updates to a singl The default location of the data file is defined by the `data.file` property. This Cepheus-CEP process must have write access rights on this file. +### Multi-Tenancy + +Cepheus-CEP comes with the ```multi-tenancy``` feature by which user can send multiple config file based on different ```tenants```. Cepheus-CEP provide every tenant a dedicated share of the instance including its data, configuration, user management, tenant individual functionality and non-functional properties. + +You can enable ```multi-tenancy``` feature of Cepheus CEP by uncommenting ```spring.profiles.active=multi-tenant``` in: +* the src/main/resources/application.properties file when building from the source or +* an external configuration like /etc/cepheus/cep.properties from the Debian package. + +``` +# Optional multi-tenancy profile +spring.profiles.active=multi-tenant +``` + +**Note**: This feature is ```disabled``` by default and is **not** yet **"production ready"**. + ### Metrics and health You can enable the Spring Boot Actuator `/infos`, `/health` and `/metrics` endpoints with these application properties: diff --git a/doc/cep/multi-tenant.md b/doc/cep/multi-tenant.md new file mode 100644 index 00000000..68b0cceb --- /dev/null +++ b/doc/cep/multi-tenant.md @@ -0,0 +1,75 @@ +# Multi-tenancy + +A tenant is a group of users who share a common access with specific privileges to the software instance. The multi-tenant is an architecture that allow a single instance of a software runs on a server and serves multiple tenants. Multi-tenant ensures that the entities/attributes/subscriptions of one tenant are "invisible" to other tenants. + +Tenant is a ```service``` in FIWARE terminology.A tenant can be composed by multiple child ```subtenants```(subservices/servicePath). + +The way to address tenants are HTTP headers + +``` +Fiware-Service : +Fiware-Servicepath: +``` + +**Note**: ```Subtenant``` must start with the ```/``` character. + +Cepheus-CEP is designed to provide every tenant a dedicated share of the instance including its data, configuration, user management, tenant individual functionality and non-functional properties. + +For Cepheus-CEP to work in ```multi-tenant``` way a user need to enable multi-tenanancy by uncommenting ```spring.profiles.active=multi-tenant``` in application.properties(for build from source)/cep.properties(for Debian package), this feature is disabled by default. + +By enabling this, user can send different configuration for different tenant. Name of file will be obtained by ```cep--``` provided in request Header. + + +![multi-tenancy configuration](multi_01.png) + +The way multi-tenancy is defined in Cepheus-CEP is to have a ```one-to-one``` mapping between Orion and Cepheus-CEP tenants e.g., if tenant ```testservice``` exists on Orion(at servicename field in providers), then it should exist on Cepheus-CEP(at request header as Fiware-Service). + +Sample Config file for Cepheus CEP: + +``` +POST http://localhost:8080/v1/admin/config +Fiware-Service: testservice +Fiware-ServicePath: /testservicepath + +{ + "host":"http://localhost:8080", + "in":[ + ... + "providers":[ + { + "url":"http://localhost:1026", + "serviceName": "testservice", + "servicePath": "/testservicepath" + } + ], + ... + ] + "out":[ + ... + "brokers":[ + { + "url":"http://localhost:1026", + "serviceName": "test", + "servicePath": "/" + } + ] + ] +} +``` + +**Note**: ```serviceName/servicePath``` of orion and ```Fiware-Service/Fiware-ServicePath``` of Cepheus-CEP should be same for processing of events. serviceName/servicePath of the orion and Fiware-Service/Fiware-ServicePath of Cepheus-CEP are mapped at the time of subscription. + +On sending this configuration, Cepheus-CEP saves the configuration as a configuration file locally named as ```cep-testservice-testservicepath```. Then it subscribe to orion for the given serviceName and servicePath(given in provider section). + + +![subscribe to context broker](multi_02.png) + +Whenever Cepheus-CEP receive notifyContext from orion(as In-Event) for any change in value of attributes, it processes Out-Event based on the statement provided in the statements section and generates outgoing Event as an output of the processing. + + +![notification from context broker](multi_03.png) + +### Current Limitation +* The incompatibility between multi-tenancy of Cepheus and serviceName/servicePath defined in providers, i.e., this will not work if we use different tenant in Cepheus CEP and orion. +* The outstanding bugs when using multi tenancy with Orion, mainly [#73](https://github.com/Orange-OpenSource/fiware-cepheus/issues/73) and [#64](https://github.com/Orange-OpenSource/fiware-cepheus/issues/64). +* Not yet "production ready". diff --git a/doc/cep/multi_01.png b/doc/cep/multi_01.png new file mode 100644 index 00000000..3c510a55 Binary files /dev/null and b/doc/cep/multi_01.png differ diff --git a/doc/cep/multi_02.png b/doc/cep/multi_02.png new file mode 100644 index 00000000..3e41d141 Binary files /dev/null and b/doc/cep/multi_02.png differ diff --git a/doc/cep/multi_03.png b/doc/cep/multi_03.png new file mode 100644 index 00000000..d38dc0de Binary files /dev/null and b/doc/cep/multi_03.png differ